superdsm.pipeline

class superdsm.pipeline.Pipeline

Bases: object

Represents a processing pipeline for image segmentation.

Note that hyperparameters are not set automatically if the process_image() method is used directly. Hyperparameters are only set automatically based on the scale of objects, if the automation module (as in this example) or batch processing are used (as in this example).

append(stage, after=None)

find(stage_name, not_found_dummy=inf)

Returns the position of the stage identified by stage_name.

Returns not_found_dummy if the stage is not found.

init(g_raw, cfg)

Initializes the pipeline for processing the image g_raw.

Parameters:

g_raw – The image which is to be processed by the pipeline.
cfg – The hyperparameters.

The image g_raw is made available as an input to the pipeline stages. However, if cfg['histological'] == True (i.e. the hyperparameter histological is set to True), then g_raw is converted to a brightness-inverse intensity image, and the original image is provided as g_rgb to the stages of the pipeline.

In addition, g_raw is normalized so that the intensities range from 0 to 1.

process_image(g_raw, cfg, first_stage=None, last_stage=None, data=None, out=None, log_root_dir=None)

Performs the segmentation of an image.

First, the image is provided to the stages of the pipeline using the init() method. Then, the process() methods of the stages of the pipeline are executed successively.

Parameters:

g_raw – A numpy.ndarray object corresponding to the image which is to be processed.
cfg – A Config object which represents the hyperparameters.
first_stage – The name of the first stage to be executed.
last_stage – The name of the last stage to be executed.
data – The results of a previous execution.
out – An instance of an Output sub-class, 'muted' if no output should be produced, or None if the default output should be used.
log_root_dir – Path to a directory where log files should be written to.

Returns:

Tuple (data, cfg, timings), where data is the pipeline data object comprising all final and intermediate results, cfg are the finally used hyperparameters, and timings is a dictionary containing the execution time of each individual pipeline stage (in seconds).

The parameter data is used if and only if first_stage is not None. In this case, the outputs produced by the stages of the pipeline which are being skipped must be fed in using the data parameter obtained from a previous execution of this method.

class superdsm.pipeline.ProcessingControl(first_stage=None, last_stage=None)

Bases: object

step(stage)

class superdsm.pipeline.Stage(name, cfgns=None, inputs=[], outputs=[])

Bases: object

A pipeline stage.

Each stage can be controlled by a separate set of hyperparameters. Refer to the documentation of the respective pipeline stages for details. Most hyperparameters reside in namespaces, which are uniquely associated with the corresponding pipeline stages.

Parameters:

name – Readable identifier of this stage.
cfgns – Hyperparameter namespace of this stage. Defaults to name if not specified.
inputs – List of inputs required by this stage.
outputs – List of outputs produced by this stage.

Automation

Hyperparameters can be set automatically using the configure() method based on the scale \(\sigma\) of objects in an image. Hyperparameters are only set automatically based on the scale of objects, if the automation module (as in this example) or batch processing are used (as in this example). Hyperparameters are not set automatically if the process_image() method of the Pipeline class is used directly.

Inputs and outputs

Each stage must declare its required inputs and the outputs it produces. These are used by create_pipeline() to automatically determine the stage order. The input g_raw is provided by the pipeline itself.

add_callback(name, cb)

configure(scale)

Automatically computes the default configuration entries which are dependent on the scale of the objects in an image.

Parameters:: scale – The average scale of objects in the image.
Returns:: See configure_ex().

The parameter scale corresponds to \(\sigma\) in Kostrykin and Rohr (TPAMI 2023). Delegates to the configure_ex() method, using \(\sqrt{2} \cdot \sigma\) for radius and \(\sqrt{8} \cdot \sigma\) for diameter.

>>> import superdsm.globalenergymin
>>> stage = superdsm.globalenergymin.GlobalEnergyMinimization()
>>> stage.configure(40)
{'beta': (1600, 0.66), 'max_seed_distance': (113.13708498984761, inf)}

configure_ex(scale, radius, diameter)

Automatically computes the default configuration entries which are dependent on the scale of the objects in an image, using explicit values for the expected radius and diameter of the objects.

Parameters:

scale – The average scale of objects in the image.
radius – The average radius of objects in the image.
diameter – The average diameter of objects in the image.

Returns:

Dictionary of configuration entries of the form:

{
    'key': (factor, default_user_factor),
}

Each hyperparameter key is associated with a new hyperparameter AF_key. The value of the hyperparameter key will be computed as the product of factor and the value of the AF_key hyperparameter, which defaults to default_user_factor. The value given for factor is usually scale, radius, diameter, or a polynomial thereof. Another dictionary may be provided as a third component of the tuple, which can specify a type, min, and max values.

process(input_data, cfg, out, log_root_dir)

Runs this pipeline stage.

Parameters:

input_data – Dictionary of the inputs declared by this stage.
cfg – The hyperparameters to be used by this stage.
out – An instance of an Output sub-class, 'muted' if no output should be produced, or None if the default output should be used.
log_root_dir – Path of directory where log files will be written, or None if no log files should be written.

Returns:

Dictionary of the outputs declared by this stage.

remove_callback(name, cb)

superdsm.pipeline.create_default_pipeline()

Creates and returns a new pre-configured Pipeline object.

The pipeline consists of the following stages:

Refer to Default pipeline for a comprehensive documentation of the pipeline.

superdsm.pipeline.create_pipeline(stages)

Creates and returns a new Pipeline object configured for the given stages.

The stage order is determined automatically.