Command line interface

Note: This page describes the command-line interface (CLI) for running filters. The command line parameters to the open_iA GUI executable are described here.

All dataset (image/volume as well as mesh) processing filters available in open_iA can also be run from the command line via the open_iA_cmd executable (open_iA_cmd.exe under Windows). In the following, > denotes the command prompt (don't type this character yourself). On Linux, you'll have to prepend open_iA_cmd with ./ in order to make the shell find the command in the current folder.

Execute open_iA_cmd without parameters to see the available options:

> open_iA_cmd
open_iA command line tool, version 2024.7.x.
Usage:
  > open_iA_cmd command [options]
With command one of:
     list [name|category|fullCategory]
         List available filters, sorted by name (default) or by category
     help FilterName
         Print help on a specific filter
     run FilterName -i Input -o Output -p Parameters [-q] [-c] [-f] [-s n] [-j InParams] [-k OutParams]
         Run the filter given by FilterName with Parameters on given Input, write to Output
           -i   the list of input filenames. If a filename contains one or more spaces, it needs
                to be quoted, e.g. "my input file.mhd"
           -o   the name of the file(s) to which the output of the filter should be written.
                Same as for input files, if the file name contains spaces, it needs to be quoted.
           -p   the parameters of the filter to be run. Use 'parameters' command to determine the
                parameters expected for a given filter.
                If a parameter value contains spaces (for example certain strings in categorical type
                parameters), it needs to be surrounded with quotes.
                Vector type parameters need to be specified as a quoted list separated by commas,
                e.g. "1.0,0.0,0.0" for a vector of 3 double values.
                If the parameter type says 'Text', then a file name is expected here; the file
                content is read from disk and passed to the filter
                For Boolean type parameters, specify 'true', 'on', 'yes' or any uppercase variant
                of these words to signify a value of true; every other value will be taken as
                meaning false.
           -q   quiet - no output except for error messages
           -f   overwrite output if it exists
           -s n separate input starts at nth filename given under -i
                (required for some filters, e.g.Extended Random Walker)
           -v n specify the log level (how verbose output should be).
                Can be DEBUG, INFO , WARN , ERROR, FATAL or a numeric value (1..5)
                between 1 and 5 (1=DEBUG, ...). Default is WARN.
           -j InputParameters for input file formats that require parameters (e.g. raw files)
                Note that -i with all input filenames needs to be specified before -j for the
                program to be able to determine the input parameters necessary for the given files.
                Specify -j once per input file that requires parameters.
                You can check whether a file format requires input parameters through the
                'formatinfo' command (see below).
                The parameters need to be specified analogously to the -p option, see notes there.
           -k OutputParameters for output file formats that take parameters (e.g. compress for .mhd)
                Note that -o with all output filenames needs to be specified before -k for the
                program to be able to determine the input parameters necessary for the given files.
                Specify -k once per filename that requires parameters.
                You can check whether a file format requires input parameters through the
                'formatinfo' command (see below).
                The parameters need to be specified analogously to the -p option, see notes there.
         Note: Only image and mesh output is written to the filename(s) specified after -o,
           filters returning one or more output values write those values to the command line.
     parameters FilterName
         Output the Parameter Descriptor for the given filter (required for sampling).
     formatinfo Extension
         Output information on which parameters a file format with the given extension
         (can be specified with or without leading '.') has for loading/saving.
     formats
         List available file formats for loading and saving files.

As the output above tells you, you can list all available filters via the list command:

> open_iA_cmd list
Available filters:
ASTRA Forward Projection
        Forward Projection with the ASTRA Toolbox

ASTRA Reconstruction
        Reconstruction with the ASTRA Toolbox

Free Beam Intensity
        Convert the intensity values to attenuation values via free beam intensity transform.

...

To run a specific filter, use the run FilterName option. In the list of available filters, the FilterName is always the first, non-indented name specified. If it contains spaces or other special characters, you need to enclose it in quotes in all future commands. Let's say we want to add some Gaussian noise to an image. For this, there is an "Additive Gaussian" filter. Let's first see its description and parameters:

> open_iA_cmd help "Additive Gaussian"
Additive Gaussian:
Adds additive gaussian white noise to an image.
To each pixel intensity, a value from a normal distribution with the given Mean and Standard deviation is added.
For more information, see the Additive Gaussian Noise Filter in the ITK documentation.
Parameters:
    Mean Continuous default=0
    Standard deviation Continuous min=2.22045e-16 default=0.1
Input images:
    Input 0
Output images:
    Additive Gaussian

This shows that the "Additive Gaussian" filter has two parameters: The first is called "Mean", it is a continuous value (i.e. floating point, in contrast to discrete = integer), which has no limitations regarding its range. The parameter "Standard deviation" is also continuous, but it needs to be positive (see the value given for min, which is the minimum positive value a double can represent). Mean's default value is 0, and for the standard deviation, it is 0.1. To run the filter, we need to specify values for both parameters, as well as input and output filename, like this:

> open_iA_cmd run "Additive Gaussian" -i test-in.mhd -o test-out.mhd -p 100 10
Reading input file 'test-in.mhd'
Running filter 'Additive Gaussian' with parameters: 
    Mean=100
    Standard deviation=10
|                                                  |
 ..................................................
Writing output 0 to file: 'test-out.mhd' (compression: off)

You will see a progress bar updating as the filter proceeds, and after the filter is done, its output will be written to the filename given after the -o switch.

You can view the result e.g. in open_iA:

open_iA test-out.mhd