Priism's IP Framework

Overview

The IP framework is intended to allow rapid development of image processing applications for Priism; it is especially useful for applications which do 2D processing on each section. The framework provides the basics of a user interface (a graphical user interface is always provided; a non-interactive batch interface and text-mode interface are optional) and a processing loop (verification of parameters; setup of inputs and outputs; looping through the data).

The basics of writing an application with the framework are covered in the Writing section; the example code should also be helpful. For more information about the order of operations performed by the framework, consult the Details section.

Topics

Overview | Writing | Compiling and linking | Examples | Details | Release Notes | Reference | Dialog Elements

Writing an Application with IP

An IP application has 3 parts: the first is the body of the application which is already written for you; the second is the IPAppSpecifics routine which defines what parts of the IP framework you want to customize; the third consists of the routines that were registered (using calls to IPSetCustRoutine in IPAppSpecifics) to perform certain customizations.

The IPAppSpecifics routine performs a series of calls to IP library routines to define the application's behavior. The handling of input/output, user interaction, and image processing can all be customized. A brief description of the most commonly used customizations is given below.

IPAddInput and IPAddOutput are the most used calls for customizing input/output. For each input image file that you want the IP framework to handle for your application, you call IPAddInput from IPAppSpecifics. This call will create the elements at the top of the dialog so the user can specify the input file or window and initializes the framework to handle an additional input image. IPAddOutput functions similarly.

Custom dialog elements are added by registering a function using IPSetCustRoutine with the CUS_MENU option. The registered function then makes the WM calls to create the widgets. The placement of the application dialog and the title that appears on the dialog's frame are usually customized with calls to IPSetMenuLoc and IPSetMenuTitle.

For processing, a typical application registers a PROC_FUNC routine with IPSetCustRoutine and uses a PROC_FUNC routine (and, if necessary, CHECK_PARAMS, INIT_PROC, or AFTER_DO_IT routines as well). A stereotypical 2D processing application using this approach defines a routine which processes a single section and registers that routine with the PROC_FUNC option to IPSetCustRoutine. The prototype for the registered routine, in C, is 

     void routine_name(int nxyz[3], float dmms[3], int argu);

and, in Fortran, is 

     subroutine routine_name(nxyz, dmms, argu)
     integer nxyz(3), argu
     real dmms(3)

nxyz holds the dimensions of the region being processed. The elements of dmms should be set to the minimum, maximum, and sum of the pixel values in the result of processing the section. argu is the parameter passed when the function was registered. Within the processing function, call IPGetDataPtr to get pointers to the input and output arrays.

3D and 4D processing can be performed similarly. The prototype for the PROC_FUNC routine is different: 

     void routine_name(int argu);

in C and, in Fortran, 

    subroutine routine_name(argu)
    integer argu

Also, when 3D or 4D processing is done, the application must handle reading and writing of the image data, rearranging the extended header, if any, and computing and setting the statistics values for each wavelength in the outputs (using IPSetFirstWaveMMM or IPSetFirstWaveMMMExt for the first wavelength and IMAlWavMM for the others). As in the 2D case, the framework allocates buffers for the inputs and outputs, but because of the size of 3D or 4D data, it is likely that the application will do its own allocation and completely or partially disable what the framework normally does by calling IPSetNoAutoIO.

Topics

Overview | Writing | Compiling and linking | Examples | Details | Release Notes | Reference | Dialog Elements

Compiling and Linking IP Applications

C/C++ programs which make calls to the IP library should include ip.h to define constants and function prototypes. Fortran programs may want to include ip.inc which defines parameters for the different types of processing (two-, three-, or four- dimensional) and the different classes of functions that may be registered with IPSetCustRoutine.

When linking your application, link against libProcFunc.a or libProcFunc.so (libProcFunc.dylib on Mac OS X) if the IPAppSpecifics routine for your application is written in C or C++. Link against libFProcFunc.a or libFProcFunc.so (libFProcFunc.dylib on Mac OS X) if the IPAppSpecifics routine for your application is written in Fortran. If you use one of the archive versions of the library (libProcFunc.a or libFProcFunc.a), you will also have to explicitly link against libSelectRegion.a, the IW library (libIWL.so (.dylib for Mac OS X) or libIWL.a), WM library (libWM.so (.dylib for MacOS X) or libWM.a), and libIVE (libive.so (libive.dylib for Mac OS X) or libive.a).

Platform Specifics

IRIX

In IVE versions since 3.3, the IP libraries are in the n32 object format. Therefore, you will need to compile and link your application so that it is in the n32 format as well. Supplying the -n32 option to the compiler and linker is one way to do this; see the pe_environ (5) man page for others.

ip.h and ip.inc are located in the IRIX/INCLUDE directory and the libraries in the IRIX/LIB directory of the Priism distribution.

For Fortran programs, the name mangling of the libraries is compatible with the default name mangling done by the MIPS Pro Fortran compiler. The library also includes alternate entry points which are compatible with the default name mangling done by g77.

x86 Linux

The requirements for the x86 Linux version of the library are the combined requirements for the IW and WM libraries.

The headers are located in the Linux/x86/INCLUDE directory of the Priism distribution. For C/C++ programs, include ip.h has the side effect of including X headers; if the path to those headers is not in the default search path then it will be necessary to include it in the search path (in most cases adding 

    -I/usr/X11R6/include

to the compilation options will do this).

The libraries are located in the Linux/x86/LIB directory of the Priism distribution. If you use one of the shared libraries (libProcFunc.so or libFProcFunc.so) it is necessary to instruct the linker to search Linux/x86/LIB for additional libraries that are used internally. If you invoke the linker directly, this can be done by adding 

    -rpath-link install_dir/Linux/x86/LIB

to the linker options (replace install_dir with the path to the Priism distribution). If the compiler is used to invoke the linker, then you will need to determine how to instruct the compiler to pass the above option to the linker; for most compilers it can be done with 

    -Wl,-rpath-link,install_dir/Linux/x86/LIB

The shared libraries also depend, indirectly, on the Motif (or LessTif), X, and OpenGL libraries; if the paths to those libraries are not in the directory search path, it will be necessary to supply additional -rpath-link options.

For Fortran programs, the name mangling of the libraries is compatible with the default mangling done by the Portland Group Fortran compiler. The library include alternate entry points which are compatible with the default name mangling done by g77.

x86_64 Linux

The requirements for the x86_64 Linux version of the library are the combined requirements for the IW and WM libraries.

The headers are located in the Linux/x86_64/INCLUDE directory of the Priism distribution. For C/C++ programs, include ip.h has the side effect of including X headers; if the path to those headers is not in the default search path then it will be necessary to include it in the search path (in most cases adding 

    -I/usr/X11R6/include

to the compilation options will do this).

The libraries are located in the Linux/x86_64/LIB directory of the Priism distribution. If you use one of the shared libraries (libProcFunc.so or libFProcFunc.so) it is necessary to instruct the linker to search Linux/x86_64/LIB for additional libraries that are used internally. If you invoke the linker directly, this can be done by adding 

    -rpath-link install_dir/Linux/x86_64/LIB

to the linker options (replace install_dir with the path to the Priism distribution). If the compiler is used to invoke the linker, then you will need to determine how to instruct the compiler to pass the above option to the linker; for most compilers it can be done with 

    -Wl,-rpath-link,install_dir/Linux/x86_64/LIB

The shared libraries also depend, indirectly, on the Motif (or LessTif), X, and OpenGL libraries; if the paths to those libraries are not in the directory search path, it will be necessary to supply additional -rpath-link options.

For Fortran programs, the name mangling of the libraries is compatible with the default mangling done by the Intel Fortran compiler. The library include alternate entry points which are compatible with the default name mangling done by g77.

Mac OS X

The requirements for the Mac OS X version of the library are the combined requirements for the IW and WM libraries.

The headers are located in the Darwin/INCLUDE directory of the Priism distribution. For C/C++ programs, include ip.h has the side effect of including X headers; if the path to those headers is not in the default search path then it will be necessary to include it in the search path (in most cases adding 

    -I/usr/X11R6/include

to the compilation options will do this).

The libraries are located in the Darwin/LIB directory of the Priism distribution. If you link against one of the shared libraries ( libProcFunc.dylib or libFProcFunc.dylib) it is also necessary to link against libWM, libIWL, libive, libGLw, and libXm, i.e. add 

    -lWM -lIWL -live -lGLw -lXm

the link options. Except for the Motif/LessTif library, libXm, these libraries are in the same directory as the IP shared libraries.

For Fortran programs, the name mangling of the libraries is compatible with typical Unix behavior (names converted to all lowercase with an underscore appended). When using the Absoft Fortran compiler, the options 

     -N15 -f

are necessary to force that style of name mangling.

Topics

Overview | Writing | Compiling and Linking | Examples | Details | Release Notes | Reference | Dialog Elements

IP Examples

Some Priism Applications which use the IP Framework

FindBorder
Uses the basic IP dialog with just one additional widget, an input for the threshold to use.
Threshold
Adds more widgets for the thresholds to apply, the form of the output, and to specify an optional non-image output file.
NewConvolution
Includes the IP option for processing a single section.
Image Arith
Combines two input image files to form one output.

Sample Source Code

Select.c
Copies a subset of the input to the output performing any necessary real/complex conversions.
FindBorder.c
Creates an image file where borders (determined from a single threshold) are marked with 1's and the rest of the image is 0's.
FindBorderF.f
Has the same functionality as FindBorder.c above but is written in Fortran.
interpo.c and gettransmatrix.f
Resamples a data stack to a new grid in two dimensions; it is functionally equivalent to Priism's Resample2D,

Topics

Overview | Writing | Compiling and Linking | Examples | Details | Release Notes | Reference | Dialog Elements

Details

When an application based on the IP framework is run, it initializes the framework and calls IPAppSpecifics. Certain customizations can only be performed from within IPAppSpecifics, namely IPSetCustRoutine for the CUS_MENU, OPT_MENU, CMD_LINE_FUNC, USAGE_FUNC, WRITE_CMD, and PROMPT_FUNC routines (as you will see below, these routines, if called at all, are called just after IPAppSpecifics returns so any later modifications have no effect), IPAddInput, and IPAddOutput.

When IPAppSpecifics returns, the framework makes a decision about which interface to present to the user. If there is only one command-line argument and that argument is -prompt, the text-mode interactive interface is started. If the text-mode interface is started but the application has not registered a PROMPT_FUNC routine with IPSetCustRoutine, the application will exit with a message that the text-mode interface is not handled. If there are any command-line arguments, the non-interactive interface is started. When the application is started with no command-line arguments the graphical user interface is started.

In the graphical user interface, the framework does the following:

  1. If not already set (via a command-line which included the -menu option), names for the output data sets are initialized to available image window numbers.
  2. The framework creates the main dialog and adds the input and output controls to it.
  3. The framework calls the CUS_MENU routine registered with IPSetCustRoutine to add the application-specific controls to the main dialog.
  4. The framework completes the main dialog. If IPEnableDoSec or the application has registered a WRITE_CMD routine with IPSetCustRoutine, then the main dialog contains an "Options" menu with entries for controlling trial runs (only enabled if IPEnableDoSec has been called) and an entry to create a command file (only enabled if a WRITE_CMD routine has been registered).
  5. The framework calls the OPT_MENU routine registered with IPSetCustRoutine.
  6. The framework enters a loop waiting for user input. If the user presses the "DoIt" button, processing is started; the steps in processing are described separately below. When the user presses the "Quit" button or asks the window manager to close the application, the loop terminates and the framework performs a set of cleanup actions described below. The application then exits with a exit code of zero.

In the command-line interface, the framework does the following:

  1. If the application has not registered a CMD_LINE_FUNC routine with IPSetCustRoutine, the application exits after displaying a message that the application does not support a command-line interface.
  2. Scans the command-line argument for the input and output data stack names and any command-line arguments handled by the framework. These are stripped from the command-line. The framework opens any input stack whose name was set, reads its header, and calls the callback for the input registered with IPAddInput and the OPEN_FILE routine from IPSetCustRoutine. The parameters for the input region and output file modes are set and the related routines (the NEW_REGION, WAVE_FUNC, and CHANGE_MODE routines set with IPSetCustRoutine are called.
  3. Call the CMD_LINE_FUNC routine the application has registered with IPSetCustRoutine
  4. If the -menu option was specified on the command-line, the application proceeds to execute with a graphical interface (see the description above for what happens). Otherwise, the application starts processing; the processing stages are described separately below. When processing completes, the cleanup actions, also described below, are performed and then the application exits. The exit code is 0 if the processing ran to completion without an interrupt or a detected fatal error and 1 otherwise.

In the text-mode interface, the application enters a loop which, until terminated by the user, does the following:

  1. Prompts the user for the parameters handled by the framework: names of input and output files, size of the selected region, pixel format for output, etc.
  2. Calls the PROMPT_FUNC routine registered with IPSetCustRoutine to ask the user for the parameters specific to the application.
  3. With the given parameters, starts processing. The stages involved in processing are described separately below.

When the user asks to terminate the text-mode loop, the cleanup actions described below are called and the application exits with an exit code of 0.

The cleanup actions performed in any of the three forms of user interaction are:

  1. The framework calls the CLEAN_UP_PROC routine which was registered with IPSetCustRoutine.
  2. The framework closes any open input added with IPAddInput. In the process any graphics or window event handlers added by the framework are removed.

Processing is proceeded by a couple of steps to check the input parameters and set up the handling of interrupts and is followed by a couple of steps to wrap things up. Those steps are:

  1. If the application is not running with a graphical interface, the framework installs signal handlers for SIGHUP, SIGINT, and SIGTERM which cause those signals to set a flag that processing should be interrupted (the application can check this flag with IPCheckInterrupt.
  2. The framework calls the CHECK_PARAMS routine registered with IPSetCustRoutine.
  3. If the application or framework has not detected an error or problem in the input parameters, then the actual data processing is started. This is described in detail separately. If there is an error or problem in the input parameters and the application is running with the command-line interface, the framework prints a summary of the allowed command-line parameters and calls the DISPLAY_USAGE routine registered with IPSetCustRoutine to display a summary of the application-specific command-line parameters. To flag an error in the inputs, the application would call IPDesist from within the CHECK_PARAMS routine or, if the application is running with a command-line interface, from within the CMD_LINE_FUNC routine.
  4. The framework calls the UNDO_CHECK routine registered with IPSetCustRoutine.
  5. If the application is running without a graphical interface and processing was interrupted, the INTERRUPT routine registered with IPSetCustRoutine is called at this point. When run with a graphical interface, the INTERRUPT routine is called when the interrupt is detected; usually this would be from within a call to IPCheckInterrupt.
  6. If the application is not running with a graphical interface, the application restores the prior signal handlers for SIGHUP, SIGINT, and SIGTERM.

The actual processing is done in one of two ways. If the application has registered a CUST_DOIT routine with IPSetCustRoutine, then, as far as the framework is concerned, processing is only a matter of calling the CUST_DOIT routine. The more common approach which forces the framework to do more of the work is to not register a CUST_DOIT routine. Then the processing proceeds as follows:

  1. The framework computes the size of the input region based on the selected region for the first input.
  2. For each output from IPAddOutput that has a name specified, the framework calls the callback registered with IPSetComputeSize to determine the size of the data to be generated; if a callback is not registered, the framework assumes that the size of data generated for that output will be the same as the input size.
  3. The framework determines which outputs have names which already exist and whether to append or overwrite those that do.
  4. The framework opens all the outputs from IPAddOutput and sets up or adjusts the headers as appropriate. If a callback was registered with IPAddOutput, that callback is invoked after the output is open and the headers are set.
  5. If it was not possible to open a required output or IPDesist was called from one or more of the IPSetComputeSize or IPAddOutput callbacks, processing does not proceed any further.
  6. If IPSetNoAutoIO has not been called, buffers for each input and output are allocated (some buffers may be shared; see IPSetIncoreProc and IPSetIncoreProcExt for details). If allocation fails, processing is halted at this point and the opened outputs are closed. If IPSetNoAutoIO was called the pointers to the buffers are all initialized to be NULL. Applications can access the pointers to the buffers with IPGetDataPtr and IPSetDataPtr.
  7. The framework calls the INIT_PROC routine registered with IPSetCustRoutine. If the routine calls IPDesist, processing is halted when the routine is returned: the buffers are deallocated and open outputs from IPAddOutput are closed.
  8. The framework loops over the input region making calls to the PROC_FUNC routine. The form of this loop is described below and depends upon which processing type was set with IPSetProcType (the default type is 2D).
  9. The framework calls the AFTER_DO_IT routine registered with IPSetCustRoutine.
  10. The framework deallocates all the buffers and closes the outputs from IPAddOutput. Prior to closing each, the header is updated with the final statistics for the first wavelength and new labels.

The loop in which PROC_FUNC is called has the following structure for 2D processing (the TWO_D option to IPSetProcType):

  1. Loop over the wavelengths to process or until interrupted. If run from the graphical interface, the order of the wavelengths is from the lowest to highest index in the inputs; if run from the command-line it is possible for the user to specify a different ordering. Use IPGetWaveOrder to determine the order in which wavelengths are drawn from a particular input.
    1. Set the output's initial scaling for the current wavelength (see IPSetSclParam for details).
    2. Loop over time points for lowest index to highest index or until interrupted.
      1. Loop over z from lowest to highest section number or until interrupted.
        1. For each open input from IPAddInput, position the input at the appropriate section, and if the input has an associated buffer (it will if IPSetNoAutoIO has not been called or IPSetDataPtr has been used to set the pointer to the buffer to a non-NULL value), read in the data for the section.
        2. For each open output from IPAddOutput, position the output at the appropriate section.
        3. Call the PROC_FUNC routine registered with IPSetCustRoutine.
        4. For each open output from IPAddOutput update the cumulative statistics, the statistics for the section, and the image scaling (only if writing to an image window). The extended header corresponding to the processed section from the first output is transferred, if possible. If the output has an associated buffer (it will if IPSetNoAutoIO has not been called or IPSetDataPtr has been used to set the pointer to the buffer to a non-NULL value), then the contents of that buffer are written to the output file.
    3. For each output, adjust the wavelength's statistics in the header.
  2. If processing terminated early, attempt to fix the header of the output file to accurately reflect what was completed.

The 3D and 4D processing loops are similar, but there is no reading and writing of the image data done by the framework nor handling of the extended header. For 3D processing (the THREE_D option to IPSetProcType), the loop structure is:

  1. Loop over the wavelengths to process or until interrupted. If run from the graphical interface, the order of the wavelengths is from the lowest to highest index in the inputs; if run from the command-line it is possible for the user to specify a different ordering. Use IPGetWaveOrder to determine the order in which wavelengths are drawn from a particular input.
    1. Set each output's initial scaling for the current wavelength (see IPSetSclParam for details).
    2. Loop over time points for lowest index to highest index or until interrupted.
      1. Call the PROC_FUNC routine registered with IPSetCustRoutine.
  2. If processing terminated early, attempt to fixup the header of the output file to accurately reflect what was completed.

For the alternative 3D processing loop where time is used as the third dimension (the THREE_D_XYT option to IPSetProcType), the loop structure is:

  1. Loop over the wavelengths to process or until interrupted. If run from the graphical interface, the order of the wavelengths is from the lowest to highest index in the inputs; if run from the command-line it is possible for the user to specify a different ordering. Use IPGetWaveOrder to determine the order in which wavelengths are drawn from a particular input.
    1. Set each output's initial scaling for the current wavelength (see IPSetSclParam for details).
    2. Loop over z from lowest to highest section number or until interrupted.
      1. Call the PROC_FUNC routine registered with IPSetCustRoutine.
  2. If processing terminated early, attempt to fixup the header of the output file to accurately reflect what was completed.

For 4D processing (the FOUR_D option to IPSetProcType), the loop structure is:

  1. Loop over the wavelengths to process or until interrupted. If run from the graphical interface, the order of the wavelengths is from the lowest to highest index in the inputs; if run from the command-line it is possible for the user to specify a different ordering. Use IPGetWaveOrder to determine the order in which wavelengths are drawn from a particular input.
    1. Set each open output's initial scaling for the current wavelength (see IPSetSclParam for details).
    2. Call the PROC_FUNC routine registered with IPSetCustRoutine.
  2. If processing terminated early, attempt to fixup the header of the output file to accurately reflect what was completed.

An alternative 4D processing loop (the FOUR_D_WAVE option to IPSetProcType) has this loop structure:

  1. For each open output from IPAddOutput, loop over the wavelengths to generate for that output and set the initial scaling for the wavelengths (see IPSetSclParam for details).
  2. Loop over time points for lowest index to highest index or until interrupted.
    1. Call the PROC_FUNC routine registered with IPSetCustRoutine.
  3. If processing terminated early, attempt to fixup the header of the output file to accurately reflect what was completed.

Topics

Overview | Writing | Compiling and Linking | Examples | Details | Release Notes | Reference | Dialog Elements

Release Notes

In IVE 4.2.2, added the following features that were not available in previous versions:

In IVE 4.2.3, introduced the constant THREE_D_XYT; that constant is not present in previous implementations of the library.

The following changes made between IVE 3.3 and IVE 4 break backward source or makefile compatibility:

In IVE 4.0.7, the value of the constant, SAME_AS_FIRST_INPUT, was changed in to avoid a clash with the value of IW_COMPLEX_SHORT. This breaks backward binary compatibility with previous versions. Executables linked against the IP shared libraries or object files which used this constant (or its equivalent integer value) should be recompiled to operate correctly with the IP library.

The following changes made between IVE 4.0 and IVE 4.1 break backward source or makefile compatibility:

Topics

Overview | Writing | Compiling and Linking | Examples | Details | Release Notes | Reference | Dialog Elements

IP Function Reference

Functions by Category:

Functions by Name:

Topics

Overview | Writing | Compiling and Linking | Examples | Details | Release Notes | Reference | Dialog Elements

IPAddInput

Overview

Adds an input image file that will be automatically handled by the IP framework (automatic handling can be overridden with IPSetNoAutoIO or doing processing with a CUST_DOIT function). IPAddInput should be called from within IPAppSpecifics. In the graphical user interface, each input image file will have a button to open a file selection dialog and a text entry field to display and edit the file selected. These user interface elements appear at the top of the dialog, immediately below the user interface elements added by any previous calls to IPAddInput.

C Prototype

#include "ip.h"
void IPAddInput(int in_stream, char* str, int req_flag, int win_only, IPCallback file_open_hdl, int argu);

Fortran Prototype

subroutine IPAddInput(in_stream, str, req_flag, win_only, file_open_hdl, argu)
integer in_stream, req_flag, win_only, argu
character*(*) str
external file_open_hdl

Parameters

in_stream
(in) in_stream is the IM stream number to use for the file. in_stream must be a valid IM stream number (i.e. greater than zero).
str
(in) str is used as the label for the button to open the file selection dialog.
req_flag
(in) If req_flag is nonzero, the file must be present before processing proceeds.
window_only
(in) If window_only is nonzero, the input must be from a window; otherwise the input may come from a window or file.
file_open_hdl
(in) Specifies the routine that is called after instr is opened and its header is read. If IPAddInput is called from C/C++, file_open_hdl should be a NULL or a function which does not return a value and takes a single integer argument; the value of in_stream is passed as this argument. If called from Fortran, file_open_hdl should be a subroutine which has one integer argument; a temporary copy of in_stream will be passed as this argument.
argu
(in) Is currently not used.

Return to function list

IPAddOutput

Overview

Adds an output image file that will be automatically handled by the IP framework (automatic handling can be overridden with IPSetNoAutoIO. IPAddOutput should be called from within IPAppSpecifics. In the graphical user interface, the output image file will have a button to open a file selection dialog, a text entry field to display and edit the file selected, and a pulldown menu to control the format of data values. These controls will appear immediately below the controls added previous calls to IPAddOutput or, if there were no previous calls to IPAddOutput, all the controls for the input data stacks.

C Prototype

#include "ip.h"
void IPAddOutput(int out_stream, char* str, int req_flag, int win_only, IPCallback file_open_hdl, int argu);

Fortran Prototype

subroutine IPAddOutput(out_stream, str, req_flag, win_only, file_open_hdl, argu)
integer out_stream, req_flag, win_only, argu
character*(*) str
external file_open_hdl

Parameters

out_stream
(in) out_steam is the IM stream number to use for the file. out_stream must be a valid IM stream number (greater than zero).
str
(in) str is used as the label for the button to open the file selection dialog.
req_flag
(in) If req_flag is nonzero, the file must be present before processing proceeds.
window_only
(in) If window_only is nonzero, the input must be from a window; otherwise the input may come from a window or file.
file_open_hdl
(in) If a CUST_DOIT routine has not been registered with IPSetCustRoutine, file_open_hdr specifies the routine that is called after instr is opened and its header is set. If called from C/C++, file_open_hdl should be a NULL or a function which does not return a value and takes a single integer argument; the value of in_stream is passed as this argument. If called from Fortran, file_open_hdl should be a subroutine which has one integer argument; a temporary copy of out_stream will be passed as this argument.
argu
(in) Is currently not used.

Return to function list

IPAllowMode

Overview

For one of the outputs registered with IPAddOutput, adds or removes a pixel format from the set of choices available to the user. If you want to have the pixel format for an output be completely under control of the application (via IPSetDefOutPutMode or IPSetDefOutPutModeExt), use IPAllowModeChange instead.

When using this function to remove a choice from the set, the application should check what the current choice is (via IPGetDefOutPutMode or IPGetDefOutPutModeExt) and, if it matches the choice be removed, set the current choice to one of the allowed choices.

C Prototype

#include "ip.h"
void IPAllowMode(int out_stream, int mode, int yesno);

Fortran Prototype

subroutine IPAllowMode(out_stream, mode, yesno)
integer out_stream, mode, yesno

Parameters

out_stream
(in) Is the IM stream number of the output to modify.
mode
(in) Is either SAME_AS_FIRST_INPUT or the IM pixel type code that is to be added or removed from the set of available choices.
yesno
(in) If zero, mode is removed from the set of available choices; otherwise, mode is added to the set of available choices.

Return to function list

IPAllowModeChange

Overview

Use this function to enable or disable the user's control over the format of an output.

C Prototype

#include "ip.h"
void IPAllowModeChange(int out_stream, int yesno);

Fortran Prototype

subroutine IPAllowMode(out_stream, yesno)
integer out_stream, yesno

Parameters

out_stream
(in) Is the IM stream number of the output to modify.
yesno
(in) If zero, the user can not set the format for out_stream and the format is completely under the application's control. If one, the user can change the format for out_stream.

Return to function list

IPAppendCommand

Overview

Appends the given text to the command file currently being generated. The appended text will be separated from what was previously written by at least a space character. This function only has an effect when a command file is being generated (i.e. a WRITE_CMD callback, registered with IPSetCustRoutine, is in progress).

C Prototype

#include "ip.h"
void IPAppendCommand(const char* text);

Fortran Prototype

subroutine IPAppendCommand(text)
character*(*) text

Parameters

text
(in) Is the text to be appended to the command file. Since the text is included as part of a command line for the shell, care should be taken that characters with special meaning to the shell (for example spaces, newlines, dollar signs...) are quoted when necessary.

Return to function list

IPAppSpecifics

Overview

The IP framework calls the user-provided routine IPAppSpecifics at startup. Any calls to the following functions should be made from within IPAppSpecifics to have the intended effect (these calls add user interface elements or control what parameters are expected in the command-line or text interfaces):

The following functions are frequently called from within IPAppSpecifics:

C Prototype

int IPAppSpecifics(void);

Fortran Prototype

subroutine IPAppSpecifics()

Return Value

The value returned by IPAppSpecifics in C is not used.

Return to function list

IPCheckInterrupt

Overview

If the application does extensive processing within one of the functions registered with IPSetCustRoutine (typically PROC_FUNC or CUST_DOIT), periodic calls to IPCheckInterrupt should be made to check if the user has requested for processing to halt. If a halt has been requested, the application should return from the registered function promptly.

For standard processing, the framework checks for a user-requested halt between each call to the PROC_FUNC routine (i.e. for each section in 2D processing or for each volume in 3D processing). That may be sufficient, depending on the application, to maintain adequate responsiveness without additional calls to IPCheckInterrupt.

C Prototype

#include "ip.h"
int IPCheckInterrupt(void);

Fortran Prototype

integer function IPCheckInterrupt()

Return Value

Returns one if the user has requested that processing be interrupted and zero if not.

Return to function list

IPDesist

Overview

If IPDesist is called from within a routine while the application is processing data or parsing the command line, the application will then stop processing when the callback returns, invoke any cleanup actions, and then either resume prompting for input parameters in the interactive case or exit in the non-interactive case. To be specific, IPDesist will have the above effect when called from within one of the following routines: the INIT_PROC, PROC_FUNC, CHECK_PARAMS, CMD_LINE_FUNC, or PROMPT_FUNC routines registered with IPSetCustRoutine or callbacks registered with IPSetComputeSize, IPAddOutput, or IPSetDisChgHandler (for IPSetDisChgHandler callbacks, the effect will only happen if the callback occurs during processing). IPDesist will also halt processing if the application is running non-interactively and IPDesist is called from one of the following callbacks: the OPEN_FILE, NEW_REGION, WAVE_FUNC, CHANGE_MODE, or NEW_RES routines registered with IPSetCustRoutine or a callback registered with IPAddInput.

If IPDesist is called from a WRITE_CMD routine registered with IPSetCustRoutine, the framework will try to complete writing the script when the callback returns. However, it will not take any further actions (running it locally or submitting it to a batch queue) that the user had requested.

In all other cases IPDesist has no effect.

C Prototype

#include "ip.h"
void IPDesist(void);

Fortran Prototype

subroutine IPDesist()

Return to function list

IPDisplayMessage

Overview

Displays a message for the user in a manner that is consistent with the mode (interactive with a graphical interface, interactive with a text interface, or non-interactive) that the application is running in.

C Prototype

#include "ip.h"
void IPDisplayMessage(const char* msg, int priority);

Fortran Prototype

subroutine IPDisplayMessage(msg, priority)
character*(*) msg
integer priority

Parameters

msg
(in) Is the message to be displayed.
priority
(out) The priority affects the formatting of the message. priority is also used to filter and tag messages. Valid values for priority, in order of decreasing priority level, are (these constants defined in ip.h for C/C++ and ip.inc for Fortran):
IP_LOG_ERROR
Use for messages about conditions which prevent further processing. When running with a graphical user interface, messages with this priority are displayed in dialogs like those created by WMConfirmError. When running interactively in text-mode or running non-interactively, messages with this priority are written to standard error.
IP_LOG_WARN
Use for messages about conditions which may be serious but which do not prevent further processing. When running with a graphical user interface, messages with this priority are displayed in dialogs like those created by WMConfirmError. When running interactively in text-mode or running non-interactively, messages with this priority are written to standard error.
IP_LOG_INFO
Use for useful informational messages. When running with a graphical user interface, messages with this priority are displayed in dialogs like those created by WMPostInfo. When running interactively in text-mode or running non-interactively, messages with this priority are written to standard output.
IP_LOG_PROGRESS
Use for messages which indicate the progress of processing. When running with a graphical user interface, messages with this priority are written to the status field. This field can only display twenty characters; messages longer than that are truncated. When running interactively in text-mode or running non-interactively, messages with this priority are not displayed by default.
IP_LOG_DEBUG
Use for messages which are only of interest when by debugging. Messages with this priority are written to standard output and, by default, are not displayed.

Return to function list

IPEnableDoSec

Overview

The documentation for the user interface common to all IP-based applications describes a trial run mode to make it easier for the user to iteratively adjust processing parameters to achieve the desired output. Calling IPEnableDoSec from within IPAppSpecifics, tells the library to offer the user the choice of whether or not to perform processing in a trial run mode. The application does not need to do anything else for the trial run mode as the other details are handled internally by the IP framework.

C Prototype

#include "ip.h"
void IPEnableDoSec(void);

Fortran Prototype

subroutine IPEnableDoSec()

Return to function list

IPEnableRegionSelection

Overview

If an application has multiple inputs registered with IPAddInput, the user is allowed to select the region to process from the first input, and the same region is used for all the other inputs. The application can choose to allow the user to independently select a region for the one or more of the other inputs by calling IPEnableRegionSelection for each of the inputs that should allow region selection. To have the desired effect, IPEnableRegionSelection must be called from within IPAppSpecifics.

If region selection is allowed for multiple inputs, the framework still imposes the restriction that the regions have the same sizes in all dimensions.

C Prototype

#include "ip.h"
void IPEnableRegionSelection(int in_stream);

Fortran Prototype

subroutine IPEnableRegionSelection(in_stream)
integer in_stream

Parameters

in_stream
(in) Is the IM stream number of the input for which region selection should be allowed.

Return to function list

IPEnableResolutionSelection

Overview

By default, IP-based applications process the highest resolution data set present in a file. If you want to allow the user to select which resolution to process, call IPEnableResolutionSelection from within IPAppSpecifics. Your application can then use IPGetCurRes to determine the resolution the user has selected. To have a callback function invoked when the user changes the resolution, call IPSetCustRoutine with the NEW_RES option.

C Prototype

#include "ip.h"
void IPEnableResolutionSelection(void);

Fortran Prototype

subroutine IPEnableResolutionSelection()

Return to function list

IPGetAppendOptions

Overview

When an output registered with IPAddOutput would modify existing data, there are two factors that determine what choices the user has: compatibility between the size of the existing data and the output to be generated and restrictions placed by the application on what sort of operations are permitted. IPGetAppendOptions returns the settings for the latter.

C Prototype

#include "ip.h"
void IPGetAppendOptions(int out_stream, int* in_z, int* in_w, int* in_t, int* replace);

Fortran Prototype

subroutine IPGetAppendOptions(out_stream, in_z, in_w, in_t, replace)
integer out_stream, in_z, in_w, in_t, replace

Parameters

out_stream
(in) Is the IM stream number for the output of interest.
in_z
(out) If *in_z in C or in_z in Fortran is not zero, then the application allows the framework to append to existing data along the z dimension when the sizes and layout of the existing data and the processing results permit it. Otherwise, appending along the z dimension is not allowed.
in_w
(out) If *in_w in C or in_w in Fortran is not zero, then the application allows the framework to append to existing data as additional wavelengths if the sizes and layout of the existing data and the processing results permit it. Otherwise, appending wavelengths is not allowed.
in_t
(out) If *in_t in C or in_t in Fortran is not zero, then the application allows the framework to append to existing data as additional time points when the sizes and layout of the existing data and the processing results permit it. Otherwise, appending additional time points is not allowed.
replace
(out) If *replace in C or replace in Fortran is not zero, then the application allows the framework to replace the contents of an input with an output in the case where an input and output have the same name and the layout and sizes of the existing data and processing results permit the replacement.

Return to function list

IPGetArg

Overview

Returns an application-specific argument from the command-line.

C Prototype

#include "ip.h"
char* IPGetArg(int iarg);

Fortran Prototype

integer IPGetArg(iarg, arg)
integer iarg
character arg(*)

Parameters

iarg
(in) Is the index of the argument to retrieve. A value of zero retrieves the name of the application used on the command line; a value of one retrieves the first application-specific argument.
arg
(out, Fortran only) The argument to be retrieved is copied to arg and either truncated (if arg is shorter than the argument) or padded with spaces (if arg is longer than the argument). If iarg is less than zero or greater than the result of IPGetArgCount, arg is filled with spaces.

Return Value

In C, a pointer to the argument is returned or NULL if iarg is less than zero or greater than the result of IPGetArgCount. In Fortran, the actual length of the argument is returned (i.e. the length before any truncation or padding necessary to fit it into arg) or -1 if iarg was out of bounds.

Return to function list

IPGetArgCount

Overview

Returns the number of application-specific arguments on the command-line.

C Prototype

#include "ip.h"
int IPGetArgCount(void);

Fortran Prototype

integer function IPGetArgCount()

Return to function list

IPGetCurRes

Overview

Returns the resolution selected for a given input. Zero is the highest resolution, one is the next highest resolution, and so on.

C Prototype

#include "ip.h"
int IPGetCurRes(int im_stream);

Fortran Prototype

integer function IPGetCurRes(im_stream)
integer im_stream

Parameters

im_stream
(in) Is the IM stream number for the input of interest.

Return to function list

IPGetCurZWT

Overview

This function has the same affect as the following sequence of calls in C:
int zwt[6];
IPGetCurZWTExt(i_stream, zwt);
IPGetCurZWTExt(o_stream, zwt + 3);
where i_stream is the stream number for the first input registered with IPAddInput and o_stream is the stream number for the first output registered with IPAddOutput.

C Prototype

#include "ip.h"
void IPGetCurZWT(int zwt[6]);

Fortran Prototype

subroutine IPGetCurZWT(zwt)
integer zwt(6)

Parameters

zwt
(out) The first 3 elements of zwt are set to the current z, wavelength, and time indices, respectively, of the first input stack. The fourth through sixth elements of zwt are set to the current z, wavelength, and time indices, respectively, of the first output stack. See the documentation of IPGetCurZWTExt for details.

Return to function list

IPGetCurZWTExt

Overview

If an application does not use a CUST_DOIT routine for processing, it can call IPGetCurZWTExt to determine the z, wavelength, and time indices corresponding to the current stage or processing.

C Prototype

#include "ip.h"
void IPGetCurZWT(int im_stream, int izwt[3]);

Fortran Prototype

subroutine IPGetCurZWT(im_stream, izwt)
integer in_stream, izwt(3)

Parameters

im_stream
(in) Is the IM stream number for the input or output of interest.
izwt
(out) izwt[0] (izwt(1) in Fortran) is the current z index (0-based) for im_stream. izwt[1] (izwt(2) in Fortran) is the current wavlength index (0-based). izwt[2] (izwt(2) in Fortran) is the current time point index (0-index). If called from an application with a CUST_DOIT routine registered or while processing is not in progress, the values returned in izwt are the the indices for the first section to process. For an application which does not use a CUST_DOIT routine but which does three or four dimensional processing, the values in izwt are the indices for the first section in the current three or four dimensional chunk: if three dimensional processing is done via the THREE_D option to IPSetProcType, the first element of izwt is always the starting z index; if three dimensional processing is done via the THREE_D_XYT option to IPSetProcType, the third element of izwt is always the starting time point index; if four dimensional processing is done via the FOUR_D option to IPSetProcType, the first element of of izwt is always the starting z index and the third element is always the starting time point index; if four dimensional processing is done via the FOUR_D_WAVE option to IPSetProcType, the first element of izwt is always the starting z index and the second element of izwt is always the index of the first wavelength. If im_stream is an input stream, the z index (i.e. the first element of izwt) is always with respect to the highest resolution data set in the input.

Return to function list

IPGetDataPtr

Overview

During processing (i.e. in the INIT_PROC, PROC_FUNC, CUST_DOIT, or AFTER_DO_IT routines registered through IPSetCustRoutine), use IPGetDataPtr to return the array that holds the image data for one of the inputs or outputs.

C Prototype

#include "ip.h"
float* IPGetDataPtr(int im_stream);

Fortran Prototype

pointer_type function IPGetDataPtr(im_stream)
integer im_stream

Parameters

im_stream
(in) Is a stream number that had been used in a call to IPAddInput or IPAddOutput.

Return Value

A pointer to the first element in the array is returned. The elements of the array are floating-point values (unless the application has used IMAlCon on the stream). If the input or output associated with im_stream has complex-valued image data, there will be two floating-point values per pixel: the first is the real part and the second is the imaginary part; otherwise there is one floating-point value per pixel.

Return to function list

IPGetDefOutPutMode

Overview

Returns the current selection for the format of each pixel in the first output registered with IPAddOutput. Use IPGetDefOutPutModeExt to get the format selection for other outputs.

C Prototype

#include "ip.h"
int IPGetDefOutPutMode(void);

Fortran Prototype

integer function IPGetDefOutPutMode()

Return Value

If no output has been registered with IPAddOutput this function returns SAME_AS_FIRST_INPUT. Otherwise, the current selection in the mode menu for the first output is returned. It will either be SAME_AS_FIRST_INPUT (defined in ip.h for C/C++ or ip.inc for Fortran) or one of the IM pixel type codes.

Return to function list

IPGetDefOutPutModeExt

Overview

Returns the current selection for the format of each pixel in an output registered with IPAddOutput.

C Prototype

#include "ip.h"
int IPGetDefOutPutModeExt(int out_stream);

Fortran Prototype

integer function IPGetDefOutPutModeExt(out_stream)
integer out_stream

Parameters

out_stream
(in) Is the stream number that was used when registering the output of interest with IPAddOutput.

Return Value

If out_stream does not correspond to an output registered, with IPAddOutput, this function returns SAME_AS_FIRST_INPUT. Otherwise, the current selection in the mode menu for the first output is returned. It will either be SAME_AS_FIRST_INPUT (defined in ip.h for C/C++ or ip.inc for Fortran) or one of the IM pixel type codes.

Return to function list

IPGetFilename

Overview

Returns the file name currently associated with one of the inputs or outputs.

C Prototype

#include "ip.h"
void IPGetFilename(int im_stream, char* file);

Fortran Prototype

subroutine IPGetFilename(im_stream, file)
integer im_stream
character*(*) file

Parameters

im_stream
(in) Is a stream number that had been used in a call to IPAddInput or IPAddOutput.
file
(out) Is filled with the file name associated with im_stream or is set to the empty string if im_stream does not match a stream number used with IPAddInput or IPAddOutput. If called from Fortran, the file name is either padded with blanks or truncated in order to fill file. For IPGetFilename to function reliably when called from C, file must point to space for at least 256 characters (including the terminating null).

Return to function list

IPGetRegionInfo

Overview

Returns the currently selected region for the first input registered with IPAddInput. Use IPGetRegionInfoExt to retrieve the selected region for other inputs (this is only necessary if the application has multiple inputs and has enabled independent region selection, via IPEnableRegionSelection, for one of the inputs other than the first). The x, y, and z indices returned always refer to the highest resolution data set in the first input. Until processing starts, the bounds for an input may be inconsistent with the input's header if the input is not the first input and the input's bounds are derived from the first input's bounds.

C Prototype

#include "ip.h"
void IPGetRegionInfo(int nxyzt[4][3], int iwave[IW_MAX_WAVE]);

Fortran Prototype

subroutine IPGetRegionInfo(nxyzt, iwave)
integer nxyzt(3, 4), iwave(5)

Parameters

nxyzt
(out) Let i be the dimension; where i = 1 is x, i = 2 is y, i = 3 is z, and i = 4 is time. Then nxyzt[i-1][0] (nxyzt(1,i) in Fortran) is the zero-based index for the start of the region in the ith dimension, nxyzt[i-1][1] (nxyzt(2,i) in Fortran) is the zero-based index for the end of the region in the ith dimension, and nxyzt[i-1][2] (nxyzt(3,i) in Fortran) is the index increment between points that are processed in the ith dimension. For the x and y directions, a further constraint is applied, and the returned increment is always one. If processing the highest resolution, it follows that the number of points processed in the ith dimension is (nxyzt[i-1][1] - nxyzt[i-1][0]) / ((nxyzt[i-1][2] != 0) ? nxyzt[i-1][2] : 1) + 1 (or, in Fortran, (nxyzt(2,i) - nxyzt(1,i)) / max(nxyzt(3,i), 1) + 1). If processing a resolution other than the highest, the x and y sizes are decreased by a factor of 2 raised to the j power where j is the resolution index. The z size is (nxyzt[2][1] - nxyzt[2][0]) / zstep + 1 ((nxyzt(2,3) - nxyzt(1,3)) / zstep in Fortran). zstep is the smallest multiple of the z downsampling factor raised to the resolution index power which is greater than or equal to nxyzt[2][2] (nxyzt(3,3) in Fortran).
iwave
(out) If the ith wavelength (i greater than zero and less than 5 (IW_MAX_WAVE)) is to be processed then iwave[i-1] (iwave(i) in Fortran) is 1; otherwise iwave[i-1] is zero. If the application is not running with the graphical user interface, this information is not adequate to describe which wavelengths are processed: the text and non-interactive modes allow reordering and repetition of wavelengths. Use IPGetWaveOrder to get the complete information when running in one of those modes.

Return to function list

IPGetRegionInfoExt

Overview

Returns the currently selected region for an input registered with IPAddInput. The x, y, and z indices returned always refer to the highest resolution data set in the input.

C Prototype

#include "ip.h"
void IPGetRegionInfoExt(int in_stream, int nxyzt[4][3], int iwave[IW_MAX_WAVE]);

Fortran Prototype

subroutine IPGetRegionInfoExt(in_stream, nxyzt, iwave)
integer in_stream, nxyzt(3, 4), iwave(5)

Parameters

in_stream
(in) Is the IM stream number for the input of interest.
nxyzt
(out) Let i be the dimension; where i = 1 is x, i = 2 is y, i = 3 is z, and i = 4 is time. Then nxyzt[i-1][0] (nxyzt(1,i) in Fortran) is the zero-based index for the start of the region in the ith dimension, nxyzt[i-1][1] (nxyzt(2,i) in Fortran) is the zero-based index for the end of the region in the ith dimension, and nxyzt[i-1][2] (nxyzt(3,i) in Fortran) is the index increment between points that are processed in the ith dimension. For the x and y directions, a further constraint is applied, and the returned increment is always one. If processing the highest resolution, it follows that the number of points processed in the ith dimension is (nxyzt[i-1][1] - nxyzt[i-1][0]) / ((nxyzt[i-1][2] != 0) ? nxyzt[i-1] : 1) + 1 (or, in Fortran, (nxyzt(2,i) - nxyzt(1,i)) / max(nxyzt(3,i), 1) + 1). If processing a resolution other than the highest, the x and y sizes are decreased by a factor of 2 raised to the j power where j is the resolution index. The z size is (nxyzt[2][1] - nxyzt[2][0]) / zstep + 1 ((nxyzt(2,3) - nxyzt(1,3)) / zstep in Fortran). zstep is the smallest multiple of the z downsampling factor raised to the resolution index power which is greater than or equal to nxyzt[2][2] (nxyzt(3,3) in Fortran).
iwave
(out) If the ith wavelength (i greater than zero and less than 5 (IW_MAX_WAVE)) is to be processed then iwave[i-1] (iwave(i) in Fortran) is 1; otherwise iwave[i-1] is zero. If the application is not running with the graphical user interface, this information is not adequate to describe which wavelengths are processed: the text and non-interactive modes allow reordering and repetition of wavelengths. Use IPGetWaveOrder to get the complete information when running in one of those modes.

Return to function list

IPGetRegionWidgets

Overview

Returns the IDs of the user interface elements used to control the selection of the input region for the first input. The returned values could be used with the WM library calls to disable or hide the widgets.

C Prototype

#include "ip.h"
void IPGetRegionWidgets(Widget widgets[IW_MAX_WAVE + 3]);

Fortran Prototype

subroutine IPGetRegionWidgets(widgets)
integer widgets(8)

Parameters

widgets
(out) widgets[0] (widgets(1) in Fortran) is the ID of the text field for the x and y bounds of the region. widgets[1] is the ID of the text field for the z bounds and increment. widgets[2] is the ID of the text field for the time bounds and increment. widgets[i+2] (widgets(i+3) in Fortran) is the ID for the toggle button controlling whether or not the ith wavelength is processed (i is greater than zero and less then or equal to 5 (IW_MAX_WAVE)). If the program is not running with the graphical interface or does not have an input registered with IPAddInput, the elements of widgets are set to zero.

Return to function list

IPGetWaveOrder

Overview

Returns the mapping of input wavelengths to output wavelengths.

C Prototype

#include "ip.h"
void IPGetWaveOrder(int in_stream, int* nout, int waves[]);

Fortran Prototype

subroutine IPGetWaveOrder(in_stream, nout, waves)
integer in_stream, nout, waves(*)

Parameters

in_stream
(in) Is the IM stream number of the input of interest.
nout
(out) The number of wavelengths to be processed from in_stream is returned in nout
waves
(out) When IPGetWaveOrder returns, waves[i] (waves(i + 1) in Fortran if one-based indexing is used) is the index of the input wavelength from in_stream used as the source for the ith output wavelength. The behavior is undefined if waves has less than nout elements.

Return to function list

IPHasGUI

Overview

Returns whether or not the application is using a graphical user interface.

C Prototype

#include "ip.h"
int IPHasGUI(void);

Fortran Prototype

integer function IPHasGUI()

Return Value

Returns zero if the application is not running with a graphical interface (it is either running interactively in text-mode or running non-interactively). Returns one if the application s running with a graphical interface.

Return to function list

IPIsAppending

Overview

Checks whether an output registered with IPAddOutput is appending to existing data. IPIsAppending is only useful if the application does not do its processing with a CUST_DOIT function and if IPIsAppending is called after the framework has made the decision to append (this occurs after CHECK_PARAMS is called but before INIT_PROC is called) and before the outputs are closed (this occurs after AFTER_DO_IT is called).

C Prototype

include "ip.h"
int IPIsAppending(int out_stream);

Fortran Prototype

integer function IPIsAppending(out_stream)
integer out_stream

Parameters

out_stream
(in) Is the IM stream number of the output to check.

Return Value

Returns zero if out_stream is not the IM stream of an output registered with IPAddInput or if that output is not appending to existing data. Otherwise, one is returned if the output data is appended along the z dimension, two is returned if the output is appended along the wavelength dimension, or three is returned if the data is appended along the time dimension.

Return to function list

IPIsInteractive

Overview

Returns whether or not the application is running interactively (i.e. it can query the user for input).

C Prototype

#include "ip.h"
int IPIsInteractive(void);

Fortran Prototype

integer function IPIsInteractive()

Return Value

If the application is running interactively (either with a graphical user interface or with a text interface), the function returns one. Otherwise, the function returns zero.

Return to function list

IPIsOpen

Overview

Checks whether an input registered with IPAddInput or an output registered with IPAddOutput is currently open.

C Prototype

include "ip.h"
int IPIsOpen(int im_stream);

Fortran Prototype

integer function IPIsOpen(im_stream)
integer im_stream

Parameters

im_stream
(in) Is the IM stream number to check.

Return Value

Returns one if im_stream is open and corresponds to an input registered with IPAddInput or an output registered with IPAddOutput. Otherwise, returns zero.

Return to function list

IPParseIntArg

Overview

Given a character string, parses it to see if it matches the format, -prefix=integer_1[:integer_2...].

C Prototype

#include ip.h"
int IPParseIntArg(const char* arg, const char* prefix, int max_count, int values[]);

Fortran Prototype

integer function IPParseIntArg(arg, prefix, max_count, values)
character*(*) arg, prefix
integer max_count
integer values(max_count)

Parameters

arg
(in) arg is the string to process. In C, it should be null-terminated. In Fortran, only the portion up to the last printable character which is not a space is considered.
prefix
(in) If the start of arg does not match a '-' followed by the contents of prefix followed by an equals sign, IPParseIntArg returns zero and does not modify the contents of values. In C, prefix should be null-terminated. In Fortran, only the portion up to the last printable character which is not a space is considered.
max_count
(in) max_count is the maximum number of integers expected.
values
(in/out) The parsed integer values from the string are returned in values.

Return Value

The return value indicates the number of integers that was successfully scanned and transfered to values. If n is the value returned then:

Return to function list

IPParseRealArg

Overview

Given a character string, parses it to see if it matches the format, -prefix=real_1[:real_2...].

C Prototype

#include ip.h"
int IPParseRealArg(const char* arg, const char* prefix, int max_count, float values[]);

Fortran Prototype

integer function IPParseRealArg(arg, prefix, max_count, values)
character*(*) arg, prefix
integer max_count
real values(max_count)

Parameters

arg
(in) arg is the string to process. In C, it should be null-terminated. In Fortran, only the portion up to the last printable character which is not a space is considered.
prefix
(in) If the start of arg does not match a '-' followed by the contents of prefix followed by an equals sign, IPParseRealArg returns zero and does not modify the contents of values. In C, prefix should be null-terminated. In Fortran, only the portion up to the last printable character which is not a space is considered.
max_count
(in) max_count is the maximum number of real values expected.
values
(in/out) The parsed real values from the string are returned in values.

Return Value

The return value indicates the number of integers that was successfully scanned and transfered to values. If n is the value returned then:

Return to function list

IPPromptInt

Overview

Prompts the user for one or more integer values.

C Prototype

#include "ip.h"
int IPPromptInt(const char* name, int set_count, int min_count, int max_count, int values[]);

Fortran Prototype

integer function IPPromptInt(name, set_count, min_count, max_count, values)
character*(*) name
integer set_count, min_count, max_count
integer values(count)

Parameters

name
(in) name is used to label the prompt. The prompt has the form "name (default value1 ...)=". In C, name should be null-terminated. In Fortran, only the portion up to the last printable character which is not a space is considered.
set_count
(in) The first set_count of values are printed as the default selection in the prompt; if set_count is less than or equal to zero no default is printed.
min_count
(in) min_count is the minimum number of values that the user is allowed to enter.
max_count
(in) max_count is the maximum number of values that the user is allowed to enter.
values
(in/out) The elements of values when IPPromptInt is called are used as the default values. When IPPromptInt returns, the elements of values are modified to correspond to the user's entries. The results are undefined if values has less than max_count elements.

Return Value

IPPromptInt returns the number of values that the user entered. The returned value will be negative one if a memory allocation error occurred or zero if the user accepted the defaults; otherwise, it will be between min_count and max_count.

Return to function list

IPPromptReal

Overview

Prompts the user for one or more real values.

C Prototype

#include "ip.h"
int IPPromptReal(const char* name, int set_count, int min_count, int max_count, float values[]);

Fortran Prototype

integer function IPPromptReal(name, set_count, min_count, max_count, values)
character*(*) name
integer set_count, min_count, max_count
real values(count)

Parameters

name
(in) name is used to label the prompt. The prompt has the form "name (default value1 ...)=". In C, name should be null-terminated. In Fortran, only the portion up to the last printable character which is not a space is considered.
set_count
(in) The first set_count of values are printed as the default selection in the prompt; if set_count is less than or equal to zero no default is printed.
min_count
(in) min_count is the minimum number of values that the user is allowed to enter.
max_count
(in) max_count is the maximum number of values that the user is allowed to enter.
values
(in/out) The elements of values when IPPromptReal is called are used as the default values. When IPPromptReal returns, the elements of values are modified to correspond to the user's entries. The results are undefined if values has less than max_count elements.

Return Value

IPPromptReal returns the number of values that the user entered. The returned value will be negative one if a memory allocation error occurred or zero if the user accepted the defaults; otherwise, it will be between min_count and max_count.

Return to function list

IPPromptString

Overview

Prompts the user for a string.

C Prototype

#include "ip.h"
int IPPromptString(const char* prompt, char* value, int max_length);

Fortran Prototype

integer function IPPromptString(prompt, value)
character*(*) prompt, value

Parameters

prompt
(in) prompt is printed before waiting for input. In C, prompt should be null-terminated. In Fortran, only the portion up to the last printable character which is not a space is considered.
value
(out) When IPPromptString returns, value holds what the user entered. value will be null-terminated in C. In Fortran, it will be padded, if necessary, with spaces to fill the full size of the string.
max_length
(in) In C, max_length is the maximum number of characters including the terminating null that value can hold.

Return Value

The total number of characters entered by the user is returned. This may exceed the length of value if value was not big enough to hold what was entered.

Return to function list

IPPostInfo

Overview

Is a synonym for IPDisplayMessage(string, IP_LOG_PROGRESS).

C Prototype

#include "ip.h"
void IPPostInfo(const char* string);

Fortran Prototype

subroutine IPPostInfo(string)
character*(*) string

Parameters

string
(in) string holds the message to be displayed. When the application is run with a graphical interface, at most twenty characters are displayed; any contents of string beyond that will not be visible.

Return to function list

IPReportSectionStats

Overview

For applications which do 2D processing via a PROC_FUNC callback, an argument to that callback is used to return that statistics (minimum, maximum, and sum) for the section just processed and written to the first output. If the application has more than one output registered with IPAddOutput, the statistics for the section just processed and written to those outputs are reported with IPReportSectionStats.

C Prototype

#include "ip.h"
void IPReportSectionStats(int out_stream, float smin, float smax, float ssum);

Fortran Prototype

subroutine IPReportSectionStats(out_stream, smin, smax, ssum)
integer out_stream
real smin, smax, ssum

Parameters

out_stream
(in) Is the IM stream number for the output whose section statistics are given.
smin
(in) Is the minimum data value in the section just processed.
smax
(in) Is the maximum data value in the section just processed.
ssum
(in) Is the sum of the data values in the section just processed.

Return to function list

IPSetAppendOptions

Overview

When an output registered with IPAddOutput would modify existing data, there are two factors that determine what choices the user has: compatibility between the size of the existing data and the output to be generated and restrictions placed by the application on what sort of operations are permitted. IPSetAppendOptions modifies the settings for the latter.

C Prototype

#include "ip.h"
void IPSetAppendOptions(int out_stream, int in_z, int in_w, int in_t, int replace);

Fortran Prototype

subroutine IPSetAppendOptions(out_stream, in_z, in_w, in_t, replace)
integer out_stream, in_z, in_w, in_t, replace

Parameters

out_stream
(in) Is the IM stream number for the output of interest.
in_z
(in) If in_z is not zero, then the application allows the framework to append to existing data along the z dimension when the sizes and layout of the existing data and the processing results permit it. Otherwise, appending along the z dimension is not allowed.
in_w
(in) If in_w in C is not zero, then the application allows the framework to append to existing data as additional wavelengths if the sizes and layout of the existing data and the processing results permit it. Otherwise, appending wavelengths is not allowed.
in_t
(in) If in_t is not zero, then the application allows the framework to append to existing data as additional time points when the sizes and layout of the existing data and the processing results permit it. Otherwise, appending additional time points is not allowed.
replace
(in) If replace is not zero, then the application allows the framework to replace the contents of an input with an output in the case where an input and output have the same name and the layout and sizes of the existing data and processing results permit the replacement.

Return to function list

IPSetAutoScale

Overview

If 2D processing is done via a PROC_FUNC callback and the output is an image window, the framework sets the scaling parameters for the image window. By default, these scaling parameters are set so each section in a wavelength is scaled to the same range. The range is the full range of processed data values in the wavelength. Alternatively, the scales may be set so that each section is scaled independently; the scaled range for each section will be the full range of processed data values in that section.

C Prototype

#include "ip.h"
void IPSetAutoScale(int onoff);

Fortran Prototype

subroutine IPSetAutoScale(onoff)
integer onoff

Parameters

onoff
(in) If onoff is zero, the default method for assigning the scaling parameters (scaling each section in a wavelength to the same range) is used. Otherwise, the alternative method of scaling each section separately is used.

Return to function list

IPSetComputeSize

Overview

If the result of processing has a different size than the input region processed, the application can use IPSetComputeSize to register a callback function which the framework will call to determine what the size of the processing result will be. Doing so will allow the framework to correctly identify when it is possible to append to an existing data set. Also, if the application did not notify the framework of the modified size, it might have to free and reallocate the memory that the framework does on behalf of the application (using a combination of IPGetDataPtr and IPSetDataPtr) or disable the framework's memory allocation mechanism entirely with IPSetNoAutoIO.

C Prototype

#include "ip.h"
void IPSetComputeSize(int out_stream, void (*func)(int istrm, int arg, int sizes[5]), int arg);

Fortran Prototype

subroutine IPComputeSize(out_stream, func, arg)
integer out_stream, arg
external func

Parameters

out_stream
(in) Is the IM stream number associated with the output whose size may vary from the dimensions of the input region.
func
(in) Is the routine that the framework will call to determine the size of the processed region. The routine is expected to take three arguments. The first is the IM stream number for the output. The second is the arg passed to IPSetComputeSize. The third is an array of five integers corresponding to the x, y, z, wavelength and time sizes for the processed region. When the func is called the array is filled with the sizes for the input region; func is expected to modify the sizes to correspond to what the size of the processed data will be. func should not return a value.
arg
(in) arg is passed as the second argument to func when it is called.

Return to function list

IPSetCustRoutine

Overview

For a number of operations, an application may register a routine with the IP framework in order to customize how the framework behaves. To register a routine, call IPSetCustRoutine. In most cases the routine takes a single integer argument and has no return value; the exceptions are noted below. The behaviors that can be customized are:

OPEN_FILE
The routine registered for OPEN_FILE is invoked whenever one of the inputs set with IPAddInput is called.
CUS_MENU
The routine registered for CUS_MENU is invoked to insert user interface elements into the main dialog. This occurs after the elements for the input and output files from IPAddInput and IPAddOutput but before the "Title", "Status", "Quit", and "DoIt" controls are added. To have an effect, the CUS_MENU function must be set from within IPAppSpecifics or a routine that IPAppSpecifics calls.
INIT_PROC
The routine registered for INIT_PROC only has an effect if no routine has been registered for CUST_DOIT. It is called during processing after the input files and output files have been opened and memory has been allocated for the input and output arrays and before the loop over the region to process has begun.
PROC_FUNC
The routine registered for PROC_FUNC only has an effect if no routine has been registered for CUST_DOIT. It is called once for every loop over the region to process (see the Details section for more information on this loop). For 2D processing, the routine is passed the x, y, and z dimensions of the region (taking into account resolution changes, if any) as a three element integer array, a three element floating-point array which should be filled with the minimum value, maximum value, and sum of the section processed, and the integer argument registered with IPSetCustRoutine. For the other processing types, it is passed the integer argument registered with IPSetCustRoutine.
CLEAN_UP_PROC
The routine registered for CLEAN_UP_PROC is invoked when the user presses the "Quit" button.
CHECK_PARAMS
The routine registered with CHECK_PARAMS is invoked when processing starts. At that point, any input added by IPAddInput is open unless no name was specified for the input or an error occurred while opening the input, but no memory allocation or opening of output files has been done. If the application calls IPDesist from within the CHECK_PARAMS callback, the framework will not call the processing callbacks (either CUST_DOIT or the combination of INIT_PROC, PROC_FUNC, and AFTER_DO_IT) when the CHECK_PARAMS callback returns: the framework will simply call the UNDO_CHECK callback, if any, and return control to the user.
INTERRUPT
The routine registered for INTERRUPT is invoked if the user chooses to interrupt processing while it is in progress.
NEW_REGION
The routine registered for NEW_REGION is invoked when the user changes the x, y, z, or time bounds of the region. If the first input is from an image window, it is also possible to change the x and y bounds by selecting a region in the window. In that case, the NEW_XYAREA callback is invoked while the region is changed; when the user releases the mouse button, the NEW_REGION callback is invoked. There are two situations (command-line operation and changing whether or not an input uses the first input's bounds) when the spatial and wavelength bounds and selected resolution can change simultaneously. If your application makes use of two or more of the NEW_REGION, NEW_RES, and WAVE_FUNC callback routines, you should write those routines so they handle the case where all three parameters (spatial bounds, wavelengths, and resolution) have changed.
NEW_RES
The routine registered for NEW_RES is invoked when the user changes the resolution selection. There are two situations (command-line operation and changing whether or not an input uses the first input's bounds) when the spatial and wavelength bounds and selected resolution can change simultaneously. If your application makes use of two or more of the NEW_REGION, NEW_RES, and WAVE_FUNC callback routines, you should write those routines so they handle the case where all three parameters (spatial bounds, wavelengths, and resolution) have changed.
OPT_MENU
The routine registered for OPT_MENU is invoked when the framework has completed. The application could use the OPT_MENU to initialize other subdialogs (though this can often be done on the fly) or to add user interface items below the "DoIt" button (though that is not recommended since it could violate the user's expectations for how IP based user interfaces are structured). To have an effect, the OPT_MENU function must be set from within IPAppSpecifics or a routine that IPAppSpecifics calls.
CUST_DOIT
If a routine is registered for CUST_DOIT, the application becomes responsible for many of the tasks that the framework normally handles when the "DoIt" button is pressed. In the normal case, pressing the "DoIt" button causes the framework to check the output file, open it, set up the header, allocate memory for the input and output arrays, invoke the INIT_PROC routine, perform a loop over the input region invoking PROC_FUNC routine once per iteration, invoke the AFTER_DO_IT routine, and then tidy up the header of the output file and close it. None of that happens if a CUST_DOIT routine is registered; the framework simply calls the CUST_DOIT routine. In both cases, the input image sources registered with IPAddInput are open and have had their headers read when the "DoIt" button is pressed.
WAVE_FUNC
The routine registered for WAVE_FUNC is invoked when the user changes the wavelengths that are currently selected for processing. There are two situations (command-line operation and changing whether or not an input uses the first input's bounds) when the spatial and wavelength bounds and selected resolution can change simultaneously. If your application makes use of two or more of the NEW_REGION, NEW_RES, and WAVE_FUNC callback routines, you should write those routines so they handle the case where all three parameters (spatial bounds, wavelengths, and resolution) have changed.
NEW_XYAREA
If the user chooses to select the x and y bounds of the region using the mouse, the routine registered for NEW_XYAREA is invoked when the mouse moves and possibly causes a change to the selected region. Because the application and image window should respond promptly when the mouse is moved, the NEW_XYAREA routine should avoid performing time-consuming operations.
AFTER_DO_IT
The routine registered for AFTER_DO_IT only has an effect if no routine has been registered for CUST_DOIT. It is called after the processing loop has completed and before the final update to the header (with final values for the minimum, maximum, and mean, and additional labels are added) is performed and the output file is closed.
CHANGE_MODE
The routine registered for CHANGE_MODE is invoked when the user changes the data format for each pixel in the output.
UNDO_CHECK
The routine registered with UNDO_CHECK is invoked after processing is complete (or has been skipped because an error was detected in the input parameters). At that point all output files have been closed, but any inputs that were open remain open.
CMD_LINE_FUNC
The function registered with CMD_LINE_FUNC is invoked when the application is invoked with any command-line arguments (the exception is if there is a single command-line argument which is -prompt; then the application will enter an interactive text mode if a PROMPT_FUNC callback has been registered or exit if a PROMPT_FUNC callback has not been registered). The CMD_LINE_FUNC callback is invoked after the framework has read and removed all command-line parameters handled by the framework. Any input registered with IPAddInput will be open at that point unless the no name for that input was supplied or there was an error opening the input. A CMD_LINE_FUNC callback can use IPGetArgCount and IPGetArg to read the command-line arguments.
USAGE_FUNC
If, when processing command-line arguments, the framework detects an error, it will print out a summary of valid command-line parameters and exit. To have the application-specific command-line parameters appear in the printed summary, the application should register a USAGE_FUNC callback with IPSetCustRoutine and from within the callback use a series of IPDisplayMessage calls with a priority of IP_LOG_ERROR to print out information about the application-specific parameters.
WRITE_CMD
If the application registers a WRITE_CMD callback with IPSetCustRoutine, the framework will give the user the option to write a command file from the graphical user interface. If the user chooses to do so, the WRITE_CMD callback is invoked after the framework has opened the command file and written the command-line parameters handled by the framework. From within the callback, the application should add the application-specific parameters which match the current settings in the graphical user interface; the application writes the parameters to the command file via calls to IPAppendCommand.
PROMPT_FUNC
If the application registers a PROMPT_FUNC routine, then the application can be run in an interactive text mode. The framework calls the PROMPT_FUNC routine to prompt the user to enter the values for application-specific input parameters. You may use the IPPromptInt, IPPromptReal, and IPPromptString to prompt the user.

C Prototype

#include "ip.h"
void IPSetCustRoutine(int func_op, IPCallback func, int argu);

Fortran Prototype

subroutine IPSetCustRoutine(func_op, func, argu)
integer func_op, argu
external func

Parameters

func_op(in)
Specifies for which category (OPEN_FILE, ...) the routine is to be registered. Constants with the same names as the categories are defined in ip.h for C/C++ programs or ip.inc for Fortran programs.
func
(in) func is the routine to register. In all cases func is not expected to return a value.