Argument Modifications

The above example of showing multiple images, takes only one file name for each execution of the job. What if the job required two file names? For example, one might want to read in the W365B47 image, but then divide it by the MB9401R image. In the “Is” module, you can define a filter to select either one or the other of the two images, but only one name is passed to “exec”. To specify two file names, you need to be able to modify the specified file name.

A modification is specified by two double-quote marks, after the symbol, but within the dollar signs, such as with modification symbol “X”. There are three modification symbols, “F”, “P”, and “S”. They stand for File, Parent, and Substitute. For example, the directory name is an absolute path name. The symbol is the parent directory of the specified directory name. More than one “P” is allowed to specify directories higher up on the chain. For example, the parent of the parent directory is specified by The “F” symbol takes the last name of the absolute path, which is the relative directory name itself. Multiple “F” symbols, therefore, do not make sense and are ignored. Here are some specific examples.

To read the input image from one directory and then write the output image in a different directory, you need to include the name of the destination directory after the directory modification. For example, if the input directory is “Input Images” and the output directory is next to it and is called “Output Images” then the modification would be:

Note that the output directory name is written outside of the $ variables, preceded by a double colon (::) that separates it from the directory before it. Any output directory must exist before this job is run, otherwise a “tile cannot be written” error message will stop the job.

The modifications described so far only change between directories on the same disk drive. To change between directories on two different disk drives requires additional commands. These additional commands are different for Windows and macOS.

For a Mac, you can simply back up to the top of the directory chain using the “Parent” modification, then type in Volumes::Directory Name. In the following example, a file is read from the user's Desktop and written to an external drive: Disk A.

On Windows, you cannot back up the directory chain to a place where you can switch disks, so you need to include the new disk name separately in the specification. For example, the same example on Windows might be:

Note that the disk name is written as in Windows, “D:\”, with the backslash. In general, the use of two colons, “::”, instead of the backslash, “\” is to make the job command easier to exchange between the Windows and Mac systems. In the case of the disk name, there is no equivalent disk designation, so the full disk name with the colon and backslash should be used.

The Substitute modification lets you substitute one character string for another. This modification works for both the directory and the file names. The modification is expressed as “S/target/replacement/”. Say, for example, that we have specified the file name from the “Is” filter as the fluorescence image W365B47 and we would now like to indicate the 940 infrared image MB9401R. The image names are:

The following specification will make the necessary modification:

You can put more than one substitution in a single modification argument. For example, lets say that you have several input file names, but wish to change each one differently. You can do that with one substitution argument, by repeating the “S” command.

The following argument in “exec” will make this change :

$F”S/+MB450RB_04_F /_blue /S/+MB530GN_07_F /_green /S/+MB630RD_11_F /_red /“$

In this modification, there are three substitutions that can be made. At most, only one will be made for each file. The algorithm searches for the target phrase (e.g. + MB450RB 04 F) in the file name. If that phrase is found, the substitution is made (_green) and the search is stopped. If no target phrase is found, then no substitution is made. In this way, a different substitution can be made for each file in the list. Because this argument can get very long, it is reasonable to create the argument in a text editor and paste it into the “exec” argument text.

A variation of this modification is a lower case “s”. This substitution finds its target phrase, makes its substitution, then continues making substitutions. For example, say that you want to change two phrases in the name that are not next to each other. The following modification will accomplish both substitutions:

In summary, you can have multiple searches in one modification argument. If you use an upper case “S”, then if that substitution is successful, the search stops and no more substitutions are tried. If you search with a lower case “s”, then even if the substitution is successful, the search will continue to any other substitutions in that argument.

One last modification is an uppercase “R”, which stands for Remove. This modification applies only to the filename, not the directory name. It assumes that the beginning of the filename starts with the directory name that holds it. The “R” modification removes the directory name from the filename, leaving the remainder of the filename. For example, this modification would be applied in the following way:

The iteration parameter, “$I$”, takes a modification that specifies what numbers to iterate over. For example, if one put the dynamic variable “$band$' into the “bands” argument in Readlmage, then one can use the iteration parameter to specify which bands to show, one at a time, in the dynamic variable in the “exec” arguments.

The specification of which number to iterate over is:

“$l”start#increment#end”$“

For example, the iteration parameter of “$I”0#1#4”$“ would iterate over the numbers from 0 to 4, one at a time, or 5 different values. Only one specification of the values is needed. One might put the iteration modification parameters in the “$bands$' argument of Readlmage, and “$I$”, without any parameters, in the “$title$” argument for Show. In this case, the title of the Show display window would have the iteration number as its title for each display. The “bands” argument of Readlmage would also have each band number, sequentially. The increment can be negative.