commands.txt

These are the script commands that ar available at the interactive
processing window. These are TCL commands, so basic understanding of
Tcl scripting is assumed.

* axes <name>

Return an ordered list of dimensions for the axes of the named
item. For example, a 640x480 grayscale image has the axes dimensions
"640 480". This uses the FITS definition of image axes, so
multi-spectral images put color information in another axis. So an RGB
color image would have axes dimensions "640 480 3".

* bayer_decompose <dst> <src>

Decompose a grayscale image captured by a bayer filtered sensor into
red, green and blue planes of a destination image. The destination
image has the same X-Y dimensions as the source image, but input some
of the pixel values are valid. For each plane where a pixel value is
not valid, mark that pixel blank by setting its alpha mask to zero.

One way to get a source image that has the properties that this
function expects is with the dcraw command, like so:

   dcraw -v -T -D -4 -o 0 -W -r 1.0 1.0 1.0 1.0 foo.NEF

This will produce a file "foo.tiff" that is a 16bit TIFF file. Load that
and use it as a source for the bayer_decompose function.

* bench close <name>...

Close the named items. The items may be images work work folders, but
must be top loevel items. Closing will close an open file or work
folder, or delete a scratch image. Any number of item names can be
included on the command line, and all will be closed.

* bench names

Get a list of the bench tree items that have script names.

* bench display_text <name>

Get the display string for the named item.

* choose_file [-i]

Put up a file selection dialog box and ask the user to select an
existing file (or files). The result is a list of files that the user
selected. The default is to let the user select from any files.

The "-i" option restricts the selection to images.

* choose_one <message> <item>...

Put up a dialog box and ask the user to choose from a list of items.
The <message> is the question that is displayed in the dialog box, and
the remaining arguments are words to be collected into a ComboBox. The
user selects one of the words and pressed OK, and the result from the
command is the word that the user selected.

* copy <work/dst> <src>

Copy the source data array to the named item in the work folder. The
source array can be any data array, the destination is of the form
<folder>/<name>, where <folder> is the script-name for a Work Folder
and the <name> is the name of a page within the folder.

* crop <dst> <axes-list> <src> <start-point>

Crop an array from the source. The destination can have fewer
dimensions then the source array, but must fit entirely within the
source array. Also, the <start-point> dimensions must match the
dimensions of the <src> image.

* define_action <name> <script>

Define a new action in the "Actions" menu. The <name> is the name that
appears in the menu, and the <script> is the tcl script that is
executed when the action is activated. If this command is executed
with no arguments, it pops up a dialog box to ask for them
interactively.

* fill <name> <value>

Fill the named image with a constant value.

* folder <name> images
* folder <name> tables

Operate on folders. The <name> is the script name for the folder, and
the <command> is the command to perform. The "images" command returns
a list of the images in the folder, and the "tables" command returns a
list of the tables in the folder.

* image <name> create <type> <axes>

Create a new image within a work folder. The <name> has the form
<work>/<name>.

* import <name> <path>

Import an image from an image file into the work folder. The <name> is
expected to have the form <work>/<item> where <work> is the name of
the work folder and the <item> is the name to create within the folder.

* scratch new <name> <display-name> <type> <axes-list>

Create a new scratch image with the script name <name>. Use
<display-name> as the name to display, and create an image with the
<axes-list> dimensions.

* minmax <src>

Scan an image to find the minimum and maximum pixel values. The result
is a list of 4 items: The minimum value, the address of the minimum,
the maximum value, and its address.

* normalize <src> <alpha> <target>

Normalize an image by scaling the pixels based on the <alpha> array
values. The idea is to scale the <src> image and <alpha> image
together so that all the bits of the <alpha> image have the same
<target> value. This function is intended to go with the "stack"
function described below.

* phase_correlate <dest> <dst-axes> <src1> <point1> <src2> <point2>

Do a phase correlation of portions of <src1> and <src2> images, and
put the resulting image into <dest>. If <dest> is "-", then the image
is not actually created and the only product from this function is the
correlated offsets.

The destination array will have the data type native double and the
dimensions given by the list <dst-axes>. For example:

     phase_correlate dst {3900 2613} ...

will create a 2D destination array.

The <src1> and <src2> images must have the same type, and at least as
many axes as the destination array. For example, if the destination
array is 2D, then the source image must have at least 2 axes. The
<point1> and <point2> lists give the starting corner where the data
will be pulled from the <src1> and <src2> arrays. The dimensions of
the image to be cropped will come from the size of the destination
array. For example:

     phase_correlate dst {3900 2613} src1 {0 0 1} src2 {0 0 1}

will use the second plane of 3D source arrays as input to the 2D phase
correlation.

This function will create the destination image, but will also output
the coordinates in the destination of the peak, which corresponds to
the relative shift of the two source images.

* pixbin <dst> <src> <bin-list>

Bin pixels from the source image into a reduced destination image. The
<bin-list> is a list of bin amounts in each dimension. This function
accounts for blank pixels by not adding them into the result. The
destination image is scaled by the number of input values per bin, so
that the destination pixels have the same range as the source pixels.

* stack <dst> <alpha> <point> <src>

Add a source image into the destination image. The destination, alpha
and source images must already exist.

The <dst> image is the destination where the source image is added
in. The <point> is where in the <dst> image to add in the origin of
the <src> image. Any samples in the <src> image that do not map onto a
<dst> sample are ignored.

The <alpha> array is incremented at each point where a <src> sample is
added into the <dst> array. If there are no valid <src> points for a
given sample of the <dst> array, the corresponding <alpha> sample is
not incremented. The <alpha> array is used to keep track of which
samples of the <dst> actually have valid results, and also to help
normalize those results later.

* table <name> create <column-info>...
* table <name> cols
* table <name> rows
* table <name> set <row> <col> <value>
* table <name> get <row> <col>

These variants of the "table" command allow for manipulation of
tables. In all cases the first argument is the table to manipulate,
and the second argument is the table-specific command to perform. The
table name is of the form <work>/<name> where <work> is the
script-name for a work folder and <name> is the name of the table.

 - create <column-info>...

This subcommand creates a new table. The named table must not already
exist. Each argument is a <column-info> list that describes the
column. Each column-info item is a list: {<name> <type>}. The <name>
is an ASCII name for the column heading, and the type is the type for
values.

 - cols
 - rows

These subcommands return the number of columns/rows in an existing
table. If the table doesn't exist, they return zero.

 - set <row> <col> <value>

This sets the value in the table at <row> <col> in the able. The <col>
must exist. The <row> must either exist or be exactly 1 past the last
row. In the latter case, a new row is created to accomodate the new
value. This is how new rows are added to the table.