giatools.cli

class giatools.cli.ToolBaseplate(*args, params_required=True, **kwargs)

Bases: object

Baseplate for command-line tools in Galaxy Image Analysis.

Example

The following example implements a simple thresholding tool that reads an input image from a file path and performs thresholding based on the mean pixel value. Only the YX axes are processed jointly. This means that, for multi-channel images, the thresholding is applied independently to each channel. For 3-D images, the thresholding is also applied independently to each z-slice, and for multi-frame images (time series), it is applied independently to each frame. The output is written as a binary image (uint8 with 0/255 labels).

import giatools
if __name__ == '__main__':

    tool = giatools.ToolBaseplate(params_required=False)
    tool.add_input_image('input')
    tool.add_output_image('output')
    for sect in tool.run('YX', output_dtype_hint='binary'):
        sect['output'] = (
            sect['input'].data > sect['input'].data.mean()
        )

This code forges a command-line tool that can cope with different input image formats (including TIFF and Zarr), a variety of different image axes in arbitrary orders, and preserves important image metadata that can be crucial for subsequent analysis steps. The tool can be executed from the command line as follows:

$ python -m examples.cli --help
usage: cli.py [-h] [--params PARAMS] [--verbose] --input INPUT --output OUTPUT

options:
  -h, --help       show this help message and exit
  --params PARAMS
  --verbose
  --input INPUT
  --output OUTPUT

The –params argument is optional in this example, but could be used to provide the path to a JSON file that is generated as configfile from the Galaxy tool wrapper.

$ python -m examples.cli --verbose --input data/input4_uint8.png --output /tmp/output.png
[input] Input image axes: YXC
[input] Input image shape: (10, 10, 3)
[input] Input image dtype: uint8
[output] Output image axes: YXC
[output] Output image shape: (10, 10, 3)
[output] Output image dtype: uint8

add_input_image(key: str, required: bool = True)

Add a named input image argument to the parser.

Raises:

ValueError – If the key is already used.

add_output_image(key: str, required: bool = True)

Add an argument for a path for an output image to the parser.

Raises:

ValueError – If the key is already used.

args: SimpleNamespace | None = None

Command-line arguments parsed from the command line (including the loaded input images).

create_processor() → ImageProcessor

Create a giatools.image_processor.ImageProcessor with the input images parsed from the command line. The giatools.image_processor.ImageProcessor is returned and also made available via the processor attribute.

The command line arguments are obtained via the parse_args() method unless the args attribute is already populated (which has precedence).

input_keys: List[str]

List of input image keys.

output_keys: List[str]

List of output image keys.

parse_args() → SimpleNamespace

Parse the command-line arguments and return a namespace that contains the JSON-encoded parameters, the input images, and the output image file paths. The args attribute is also populated.

processor: ImageProcessor | None = None

The giatools.image_processor.ImageProcessor instantiated latest via the create_processor() method.

run(joint_axes: str, write_output_images: bool = True, **kwargs: str) → Iterator[ProcessorIteration]

Use the create_processor() method to spin up a giatools.image_processor.ImageProcessor with the input images parsed from the command line, and write the output images to the file paths specified via command line arguments (if write_output_images is True).

Note

This method requires Python 3.11 or later.

Raises:

RuntimeError – If Python version is less than 3.11.

write_output_images()

Write the output images to the file paths specified via command line arguments.

The output images are obtained from the giatools.image_processor.ImageProcessor referenced by the processor attribute. The command line arguments must be provided via the args attribute.

Raises:

RuntimeError – If the pre-conditions are not met (args or processor attributes are not populated).