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 theautomation
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, ifcfg['histological'] == True
(i.e. the hyperparameterhistological
is set toTrue
), theng_raw
is converted to a brightness-inverse intensity image, and the original image is provided asg_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, theprocess()
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, orNone
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)
, wheredata
is the pipeline data object comprising all final and intermediate results,cfg
are the finally used hyperparameters, andtimings
is a dictionary containing the execution time of each individual pipeline stage (in seconds).
The parameter
data
is used if and only iffirst_stage
is notNone
. In this case, the outputs produced by the stages of the pipeline which are being skipped must be fed in using thedata
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 theautomation
module (as in this example) or batch processing are used (as in this example). Hyperparameters are not set automatically if theprocess_image()
method of thePipeline
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 inputg_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 theconfigure_ex()
method, using \(\sqrt{2} \cdot \sigma\) forradius
and \(\sqrt{8} \cdot \sigma\) fordiameter
.>>> 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 hyperparameterAF_key
. The value of the hyperparameterkey
will be computed as the product offactor
and the value of theAF_key
hyperparameter, which defaults todefault_user_factor
. The value given forfactor
is usuallyscale
,radius
,diameter
, or a polynomial thereof. Another dictionary may be provided as a third component of the tuple, which can specify atype
,min
, andmax
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, orNone
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.