Region Processing Interface

Overview

Many Priism applications share a common layout for their user interface. The shared dialog elements are at the top and bottom of the dialog, and application-specific elements appear in the middle.

At the top of the dialog, there is one line for each input data stack and one line for each output data stack. For each line, the current file or window selection is shown in the text field. You can change the selection by editing the text or using the button next to the field to open a file selection dialog. The line for an output data stack has an additional menu which you may use to select the data type used to store each pixel's intensity. Some applications may not allow the data type to be changed; in that case, the menu will be disabled.

Below the lines for the input and output files, the dimensions of the first input stack and controls for selecting a subset of that input are shown. See the XYZ, W, T, R, and Select Region topics for more about selecting a subset of an input. If the application has more than one input data stack, the application may allow the user to independently select the region used for two or more of the outputs. If that is the case, additional controls will be shown for each input data stack which allows region selection. Input data stacks for which the application does not allow user control of the region will use the same region as the first input data stack.

The portion of the dialog between the wavelength toggles for the last input and the Title button varies from application to application. Consult the application-specific help for more information.

The bottom part of the dialog contains the DoIt button for starting processing. When processing is in progress, the Status field displays how far along the processing is; the Interrupt button (which appears in place of the DoIt button) can be used to stop processing. The Quit button closes the dialog and stops the application. Use the Title field to add descriptive information to the header of the output.

Some applications supply a special mode for performing a trial run of the input parameters on a single section. If the application provides this feature, the application will have an Options menu next to the Quit button, and that menu will have the Toggle trial run and Set scratch depth... options enabled.

Some applications can generate a command file from the currently entered inputs; this command file could then be used to perform the processing in the background or in a batch queue. The command file is also useful as a model when writing a script to run the application non-interactively. Applications which allow generation of a command file have an Options menu next to the Quit button, and that menu will have the Create batch job... option enabled. All the applications that support the option to generate a command file can be run from the command line and not use a graphical user interface. The Command line topic describes the format of the command-line and the common command-line parameters that these applications share.

Topics

XY and Z Range Selection

The first two values in the XY field are the starting x and y indices for the subset of the data to process. The lower left-hand corner of a displayed image corresponds to x and y indices of 0. The second two values are the x and y sizes for the subset. By default, the full XY extent of the input data is processed. You change this by changing the values in this field or using the Select Region button.

The 3 values in the z field are the index of the first section to process, the index of the last section to process, and the index increment.

Regardless of the resolution you select, the sizes and bounds for region selection are in terms of the coordinates for the highest resolution data set. If you do process a lower resolution where the z dimension is also downsampled, the z index increment will be the smallest multiple of the z downsampling factor that is greater than or equal to the z increment you specify.

Topics

Waves Selection

Use these toggles to choose which waves to load.

Topics

Time Selection

This is the time range that will be loaded. The three values in the field are the index of the first time to process, the index of the last time to process, and the index increment.

Topics

Resolution Selection

By default, the application will process the highest resolution data set from each input. Some applications will allow you to select which resolution to process. Those applications will include a menu next to the time field in which you can select the resolution: zero is highest resolution, one is the next highest resolution, and so on.

Topics

Interactive Region Selection

If your input is an image window, you can select the region to load using the mouse. Pushing the Select Region button activates the image window so you can select a region; it remains active until the first time the pointer leaves the window after the left mouse button has been pressed and released in the image window.

While the window is active, you can select a new region by positioning the pointer inside the image window and outside any existing selection region (displayed as a rectangle). Then depress the left mouse button and drag the mouse to select the region. Release the left mouse button to fix the rectangular region at its current size.

Also while the window is active, you can use two ways of editing the selection rectangle with the mouse. By positioning the pointer in the selection rectangle and depressing the left mouse button, you can move the selection rectangle by moving the mouse. Release the left mouse button to fix the rectangle in its current position. By positioning the pointer on an edge or corner of the selection rectangle and depressing the left mouse button, you can resize the rectangle by moving the mouse. Releasing the left mouse button fixes the rectangle at its current size.

If the image window is in matrix mode (displaying several images at once in a tabular arrangement), the selection rectangle will be displayed on all the images, but only the image in the lower left corner of the window should be used for changing the selection rectangle with the mouse.

Topics

Output Data Mode

For each output data stack there is a pulldown menu to control the data format for that stack. The available choices are (note that some applications may not allow the output format to be varied or may only allow a subset of the choices shown below):

Default: Causes the output to have the same format as the first input.
Byte: Causes each pixel to be stored as an integer with a maximum allowable range of 0 to 255, inclusive.
Short: Causes each pixel to be stored as an integer with a maximum allowable range of -32678 to 32767.
Float: Causes each pixel to be stored as a floating-point value which can represent quantities in the range of -1 x 10^38 to 1 x 10^38 (roughly) with approximately 6 significant digits.
Complex: Causes each pixel to be stored as a complex value. The value is represented by two floating-point values: one for the real component and another for the imaginary component.
C. Short: This is similar to the Complex option, but the two components are integers (range -32768 to 32767) rather than floating-point values.
UShort: Causes each pixel to be stored as an integer with a maximum allowable range of 0 to 65535.
Long: Causes each pixel to be stored as an integer with a maximum allowable range of -2147483648 to 2147483647.

When choosing an output format, you should consider the range and accuracy you need for the output. Space and time constraints and compatibility with other applications can also be important.

Some types of calculations (projections for instance) can easily exceed the range of the integer (Byte, Short, UShort, Long) formats. Values which fall outside of the allowed range are generally coerced (a value less than the minimum accepted value is recorded as the minimum accepted value; a value greater than the maximum accepted value is recorded as the maximum accepted value).

If the "true" output would involve non-integral values, use of one of the integer formats will generally cause those values to be rounded to the nearest integer.

For a data stack with the same dimensions, a file which uses the Short or UShort format takes up twice as much space as a file that uses the Byte format and would typically take twice as long to read. A file which uses the Float or Long format takes up four times as much space as a file that uses the Byte format and would typically take four times as long to read.

Complex-valued data, i.e. the Complex and C. Short options, is frequently not handled or is not handled correctly (either as input or output) by many Priism applications. Support for the Complex format is better than for C. Short.

Support for the UShort and Long formats is new in IVE 4. Previous versions of IVE and other applications which use the MRC format will generally not be able to use data written with the UShort or Long formats.

Priism image files use a modified MRC file format. That file format has as standard output types the Byte, Short, Float, Complex, and C. Short options. If you wish to use your data with another application that uses the MRC file format, then you should use one of those output types. The other application may only accept a subset of those standard types (for instance, CCP4 normally only uses the Float and Byte formats).

Topics

Output Title

If this toggle button is on, the text in the adjacent field will be appended to the titles in the header of the output data stacks. No title is appended if the toggle button is not on.

Topics

Processing Status

This field is blank when no processing is being done. When processing is in progress, the current section being processed is displayed.

Topics

Doing a Trial Run

If the application's main dialog has an Options menu next to the Quit button and that menu has the Toggle trial run entry enabled, then the application can be run in a special mode in which the current settings are used to process just one section.

To use this mode, select Toggle trial run from the Options menu at the bottom of the main dialog. Then change the output file to be a window (if the window exists it will be automatically overwritten unless it is a scratch window, in which case it may be possible to append to it). The section that will be processed is the first section if the input is a file or the currently displayed section if the input is a window; so if the input is a window, adjust it to display the section to process. Then press the DoSec button to do the processing.

The result is displayed in a scratch window. If you change the input section or another input parameter and do the processing again, the new result will be displayed as the second section and the previous results will remain in the first section. In general, the scratch window will store the last n results (n defaults to 10 and can be changed by selecting Set scratch size... from the Options menu).

Topics

Scratch Size

The scratch size only affects processing when the special mode for testing input parameters on a single section is used. In that situation, the result of processing a section is added to a scratch window where the last n sections are saved. The value of n can be set selecting Set scratch size... from the Options menu in the main dialog and then entering the desired value of n in the dialog that appears.

Topics

Creating a command file

If the application's main dialog has an Options menu next to the Quit button and that menu has the Create batch job... entry enabled, then the application can generate a command file from the currently entered inputs.

Selecting Create batch job... from the Options menu displays a dialog with the following entries:

Log file: When a command file is executed, it can generate text output. If the Log file field is empty, then this text will not be redirected in any way. Otherwise, the text will be redirected to a file with the name shown in the Log file field. To change the file name shown. you may directly edit it or press the Log file button to open a file browser.
Command file: Enter the name of the command file to use in this field or press the Command file button to select a command file with a file browser.
Queue: This option menu indicates what will be done when the dialog's Do It button is pressed. If the run locally option is selected, pressing the Do It button generates the command file and, if the skip execution toggle button is off, executes it on the current machine. Until execution completes, the Do It button will be labeled Cancel and pressing it will terminate execution. Other entries may appear in the Queue menu. These entries can be customized (consult the Queue topic in BatchRegion.html for details). Commonly, if one of the additional entries is selected, the command file is submitted to a batch queue when the Do It button is pressed and the skip execution toggle button is off.
append to log file: If this toggle button is on, the commands written to the command file will append any text output they generate to the log file rather than overwriting the log file.
skip execution: If this toggle button is off, pressing the Do It button both generates a script and either executes it directly or submits it to a batch queue. If this toggle button is on, pressing the Do It button only generates the script.
Close: Pressing this button dismisses the dialog.
Do It: Pressing this button causes the command file to be updated and, depending on how the Queue menu is set, executed as well. If the command file already exists, you will have the option to either append the new command to it or to overwrite its current contents.

Topics

Command Line

If an application has n input data stacks and m output data stacks (these are the same data stacks which are controlled by the fields at the top of the applications graphical user interface), then the command-line syntax is:

application_name input1_name ... inputn_name \
    output1_name ... outputm_name options

The ordering of the data stack names from right to left on the command line is the same as the top to bottom ordering of the data stack fields in the user interface. Names for all the data stacks must be supplied; if a data stack is optional and you do not want to specify one, use an empty string (i.e. '' or "") for the command-line argument. The options may zero or more of the options described below or options which are specific to the application (for those, consult the application's documentation). Unlike the data stack names, options may appear in any order.

The command-line options shared by all the region processing applications that support a command-line interface are listed below. Options which take arguments have an equals sign between the option name and the arguments, and if there is more than one argument to the option, they are separated by colons. Some options interact. It is not possible to specify more than one of -no_overwrite, -append_z, -append_w, or -append_t for the same output data stack, and specifying -menu will render -no_overwrite, -append_z, -append_w, -append_t, and -logstamp options ineffective.

-x=start:stop

Sets the range of x indices to process from the first input data stack. The first argument is required and is the starting index (zero-based). The second argument is optional and is the end index; if the second argument is omitted, the end index is the same as the starting index. Both arguments must be non-negative and less than the x size of the first data set or processing will stop with an error. If -x (or its synonym, -x1) is not specified, the entire x range of the first input data stack is processed.

-x1=start:stop

This is a synonym for -x.

-y=start:stop

Is similar to -x but controls the range of y indices to process from the first data set.

-y1=start:stop

This is a synonym for -y.

-z=start:stop:step

Sets the z sections processed from the first input data stack. The first argument is required and specifies the index (zero-based) of the first section to process. The first argument must be non-negative and less then the number of z sections in the first data stack. The second and third arguments are optional. The second argument specifies the upper bound on the z section indices processed. If not specified, its value is set to be the same as the first argument; otherwise, it must be greater than or equal to the first argument and less than the number of z sections in the first input data stack. The third argument specifies the index increment between sections processed. If not supplied, its value is set to one; otherwise it must be a positive integer. If -z (or its synonym, -z1) is not supplied, the entire z range of the first input data stack is processed.

-z1=start:stop:step

This is a synonym for -z.

-t=start:stop:step

Is similar to -z but controls the range of time indices processed.

-t1=start:stop:step

This is a synonym for -t.

-res=ires

Selects the resolution to process from the first data set. Zero is the highest resolution, one is the next highest, and so on. An application will only accept this option if the application's graphical user interface also allows selection of the resolution to process. Regardless of which resolution you select, the sizes and bounds for region selection are always in the coordinates of the highest resolution data set.

-res1=ires

This is a synonym for -res.

-w=wv1...

Sets which wavelengths to process from the first input data stack. Supply one argument for each wavelength to process. The argument must either be the index of a wavelength (i.e. a value greater than or equal to zero and less than the number of wavelengths in the first input data stack) or the wavelength value in nanometers stored in the data stack's header (this second option is only possible if the wavelength value is greater than or equal to 200 and less than 1000). The ordering of the arguments from left to right is the order in which the wavelengths will be processed. Wavelengths may be repeated or appear in a different order than in the input data stack. If -w (or its synonym, -w1) is not supplied, then all wavelengths from the first input stack are processed in order.

-w1=wv1...

This is a synonym for -w.

-mode=format

If the application has an output data stack and allows the representation of values in that data stack to be modified, use the -mode1 option to specify the representation of values in the first output. If -mode (or its synonym, -mode1) is not supplied, the representation of values in the output data stack is the same as in the first data stack unless the application has set a different default representation. This option requires one argument and it must be one of the following:

as_first: Store each pixel value using the representation from the first input data stack.
byte: Store each pixel value as an 8-bit unsigned integer.
short: Store each pixel value as a 16-bit signed integer.
float: Store each pixel value as a 32-bit IEEE floating-point value.
complex: Store each pixel value as a complex quantity. The value is represented by two 32-bit IEEE floating-point values: one for the real part and another for the imaginary part.
cshort: Store each pixel value as a complex quantity. The value is represented by two 16-bit signed integers: one for the real part and another for the imaginary part.
ushort: Store each pixel value as a 16-bit unsigned integer.
long: Store each pixel value as a 32-bit signed integer.

-mode1=format

This is a synonym for -mode.

-title=label

Specifies a title that is added to the labels of the output data stacks, if any.

-scratch

If the application supports trial runs, then supplying this option will cause the application to run in that mode.

-scratch=depth

Has the same function as -scratch, but requires one argument to specify the depth of the scratch window used. This depth must be a positive integer.

-no_overwrite

If the name of one of the output data stacks is already in use, the application will, by default, attempt to overwrite the data associated with that name when run from the command-line. You may specify the -no_overwrite so that if the name for the first output data stack is already in use, the application terminates with an error before damaging the existing data.

-no_overwrite=o1...

This option is an alternative to -no_overwrite that is useful if the application has more than one output data stack. The required argument may be all which will cause the application to exit if the names used for any of the output data stacks are already in use. Alternatively, the argument may be a colon separated list of the indices (one-based) for the output data stacks for which overwriting is not to be allowed.

-append_z

If this option is specified, the application will attempt to append to the first output data stack along the z dimension. If there is no output data stack or its name is not already in use, this option has no effect.

-append_z=o1...

This option is an alternative to -append_z that is useful if the application has more than one output data stack. The required argument may be all which will cause the application to attempt to append to all output data stacks along the z dimension. Alternatively, the argument may be a colon separated list of the indices (one-based) for the output data stacks which are to be appended to along the z dimension.

-append_w

If this option is specified, the application will attempt to append to the first output data stack along the wavelength dimension. If there is no output data stack or its name is not already in use, this option has no effect.

-append_w=o1...

This option is similar to -append_z= but specifies the output data stacks which are to be appended to along the wavelength dimension.

-append_t

If this option is specified, the application will attempt to append to the first output data stack along the time dimension. If there is no output data stack or its name is not already in use, this option has no effect.

-append_t=o1...

This option is similar to -append_t= but specifies the output data stacks which are to be appended to along the time dimension.

-logging=level

This option specifies which messages the application will display as it runs. Messages are assigned a priority and all messages at or above the level given will be displayed. Valid values for level, in order of decreasing priority, are:

error: Is for messages which indicate a fatal error: the application is not able to proceed.
warning: Is for messages for conditions that may be serious, but the application is able to proceed.
info: Is for messages which may be useful but are, as far as the application is concerned, not a necessary part of the output. This is the default level when the application does not display a graphical user interface.
progress: Is for messages which would be written to the Status field in the graphical user interface: i.e. messages used to indicate the current stage of processing. This is the default level when the application displays a graphical interface.
debug: Is for messages which would only be of interest when debugging.

-logstamp

If this option is supplied, extra information (date and time, message priority level as an integer, application name, and process ID) will be displayed before each message.

-menu

Normally when command-line options are supplied, the application will read them, perform processing, and then exit. If the -menu is supplied, the application will read the command-line parameters but then proceed to display its graphical interface and function as it normally does when the graphical interface is displayed.

If the application has more than one input data stack and it allows for regions to be specified separately for the different input stacks, the application will accept additional options: -x2, -y2, -z2, -w2, -t2, -res2, and so on. These options are analogous to the -x, -y, -z, -w, -t, -res options but select the region for the additional input stacks. Any bounds that are not set for the additional inputs are the same as those for the first input.

If the application has more than one output data stack and allows the pixel value representation top be changed for those data stacks, the application will accept additional options (-mode2 and so on) that are similar to -mode but set the pixel representation for the additional outputs.

As an example, the following command line would extract a 100 x 100 rectangle from the 450 nm and 640 nm data in.dat (the lower left corner of the rectangle is at (35, 50)), convert the data values to floating-point, and write the result to out.dat:

CopyRegion in.dat out.dat -x=35:134 -y=50:149 -w=450:640 -mode=float

If the 450 nm data is the fifth wavelength in in.dat and the 640 nm data is the second wavelength in in.dat, the command line below is equivalent to the one above:

CopyRegion in.dat out.dat -x=35:134 -y=50:149 -w=4:1 -mode=float

Some applications support an alternate interface that prompts for inputs at the command-line. If supported, this interface can be accessed with:

application_name -prompt

Topics

Overview

Topics

Related Priism Topics

Topics

Topics

Topics

Topics

Topics

Topics

Topics

Topics

Topics

Topics

Topics

Topics