superdsm.postprocess

class superdsm.postprocess.PostprocessedObject(original)

Bases: BaseObject

Each object of this class represents a segmented object after it has been post-processed.

class superdsm.postprocess.Postprocessing

Bases: Stage

Discards spurious objects and refines the segmentation masks as described in Section 3.4 and Supplemental Material 7 of Kostrykin and Rohr (TPAMI 2023).

This stage requires g_raw, cover, y_img`, ``atoms, dsm_cfg for input and produces postprocessed_objects for output. Refer to Inputs and outputs for more information on the available inputs and outputs.

Hyperparameters

The following hyperparameters can be used to control this pipeline stage.

Simple post-processing

postprocess/max_norm_energy: Objects with a normalized energy larger than this value are discarded. Corresponds to max_norm_energy2 in Kostrykin and Rohr (TPAMI 2023, Supplemental Material 8, also incorrectly referred to as min_norm_energy2 in Supplemental Material 7 due to a typo). Defaults to 0.2.
postprocess/discard_image_boundary: Objects located directly on the image border are discarded if this is set to True. Defaults to False.
postprocess/min_object_radius: Objects smaller than a circle of this radius are discarded (in terms of the surface area). Defaults to 0, or to AF_min_object_radius × radius if configured automatically (and AF_min_object_radius defaults to zero).
postprocess/max_object_radius: Objects larger than a circle of this radius are discarded (in terms of the surface area). Defaults to infinity, or to AF_max_object_radius × radius if configured automatically (and AF_max_object_radius defaults to infinity).
postprocess/min_boundary_obj_radius: Overrides postprocess/min_object_radius for objects located directly on the image border. Defaults to the value of the postprocess/min_object_radius hyperparameter.
postprocess/max_eccentricity: Objects with an eccentricity higher than this value are discarded. Defaults to 0.99.
postprocess/max_boundary_eccentricity: Overrides postprocess/max_boundary_eccentricity for objects located directly on the image border. Defaults to the value set for postprocess/max_boundary_eccentricity.

Contrast-based post-processing

A segmented object is discarded if the contrast is too low. The contrast is computed as the ratio of (i) the mean image intensity inside the segmentation mask of the object and (ii) the average image intensity within its exterior neighborhood. The average image intensity within the exterior neighborhood is determined using a weighted mean of the image intensities, where the weight

\[\exp(-\max\{0, \operatorname{dist}_M(x) - \text{exterior_offset}\} / \text{exterior_scale})\]

of an image point \(x\) decays exponentially with the Euclidean distance \(\operatorname{dist}_M(x)\) of that point to the mask \(M\) of the segmented object. Image points corresponding to segmentation masks of segmented objects are weighted by zero.

postprocess/exterior_scale: Scales the thickness of the soft margin of the exterior neighborhood (this is the outer margin, corresponding to image points associated with weights smaller than 1). Increasing this value increases the importance of image points further away of the segmentation mask. Defaults to 5.
postprocess/exterior_offset: Corresponds to the thickness of the inner margin of image points within the exterior neighborhood which are weighted by 1. Increasing this value increases the importance of image points closest to the segmentation mask. Defaults to 5.
postprocess/min_contrast: A segmented object is discarded, if the contrast as defined above is below this threshold. See Supplemental Materials 7 and 8 in Kostrykin and Rohr (TPAMI 2023). Defaults to 1.35.
postprocess/contrast_epsilon: This constant is added to both the nominator and the denominator of the fraction which defines the contrast (see above). Defaults to 1e-4.

Mask-based post-processing

The segmentation masks are refined individually (independently of each other).

postprocess/mask_stdamp: An image point adjacent to the boundary of the original segmentation mask is added to the segmentation mask, if its Gaussian-smoothed intensity is sufficiently similar to the mean intensity of the mask. The image point is removed otherwise. The lower the value set for postprocess/mask_stdamp, the stricter the similarity must be. Defaults to 2.
postprocess/mask_max_distance: Image points within this maximum distance of the boundary of the original segmentation mask are subject to refinement. Image points further away from the boundary are neither added to nor removed from the segmentation mask. Defaults to 1.
postprocess/mask_smoothness: Corresponds to the scale of the Gaussian filter used to smooth the image intensities for refinement of the segmentation mask. Defaults to 3.
postprocess/fill_holes: Morphological holes in the segmentation mask are filled if set to True. Defaults to True.

Autofluorescence glare removal

To decide whether a segmented object is an autofluorescence artifact, we considere its segmentation mask. The object is identified as an autofluorescence artifiact and discarded, if it is sufficiently large and, by default, the top 50% of the Gaussian-smoothed intensity profile of the object mask is approximately pyramid-shaped (i.e. the top 50% intensity-superlevel sets of the object are connected). This is illustrated in the figure below, where the intensity-superlevel sets are shown for 5 different intensity values:

_images/glare_detection.png — Autofluorescence artifact detection method. (a) Original image section (NIH3T3 cells, contrast-enhanced). (b) Ground truth segmentation. (c) Segmentation result of cell nuclei (green contour) and the autofluorescence artifact (red contour). (d) Smoothed image intensities (Gaussian filter) and the corresponding intensity profiles (solid contours) of the detected objects (dashed contours).

postprocess/glare_detection_smoothness: The standard deviation of the Gaussian function used for smoothing the image intensities of the segmented object. Defaults to 3.
postprocess/glare_detection_num_layers: The number of intensity values, for which the connectivity of the intensity-superlevel sets is investigated. Defaults to 5.
postprocess/glare_detection_min_layer: The top fraction of the Gaussian-smoothed intensity profile investigated for connectivity. Defaults to 0.5, i.e. the top 50% of the Gaussian-smoothed intensity profile is investigated.
postprocess/min_glare_radius: The size of a segmented object must correspond to a circle at least of this radius (in terms of the surface area) in order for the object to be possibly recognized as an autofluorescence artifact. Defaults to infinity, or to AF_min_glare_radius × radius if configured automatically (and AF_min_glare_radius defaults to infinity).
postprocess/min_boundary_glare_radius: Overrides postprocess/min_glare_radius for objects located directly on the image border. Defaults to the value of the postprocess/min_glare_radius hyperparameter.

configure(pipeline, input_id, *args, radius, **kwargs)

Returns the rules to adopt hyperparameters based on the input data.

Sometimes it can be necessary to automatically adopt hyperparameters based on the input data. For those cases where linear adoptation is suitable, this method can be overridden to return the rules which specify how to adopt the hyperparameters. The rules are then applied by the repype.pipeline.Pipeline.configure() method.

The rules must be specified by the following structure:

{
    'key': [
        factor,
        default_user_factor,
    ],
}

The rules are resolved by mapping the above structure to the arguments of the repype.pipeline.create_config_entry() function. In this example, two new hyperparameters are created:

The hyperparameter AF_key is created and defaults to the value of default_user_factor.
The hyperparameter key is created and defaults to the value of the hyperparameter AF_key times the value of factor.

In addition, a third element can be added to the list to further constrain the resulting values:

{
    'key': [
        factor,
        default_user_factor,
        {
            type: 'float',
            min: 0.0,
            max: 1.0,
        },
    ],
}

Parameters:

pipeline – The pipeline object that this stage is a part of.
input_id – The identifier of the input data to adopt the hyperparameters for.
*args – Sequential arguments passed to Pipeline.configure.
**kwargs – Keyword arguments passed to Pipeline.configure.

id: str = 'postprocess': The stage identifier.

inputs: Collection[str] = ['cover', 'y_img', 'atoms', 'g_raw', 'dsm_cfg']: List of fields read by this stage.

outputs: Collection[str] = ['postprocessed_objects']: List of fields produced by this stage.

process(cover, y_img, atoms, g_raw, dsm_cfg, pipeline, config, status=None, log_root_dir=None)

Processes the input fields of this stage of the pipeline.

This method implements a stage of the pipeline with the provided inputs and configuration parameters. It then returns the outputs produced by the stage.

Parameters:

pipeline – The pipeline object that this stage is a part of.
config – The hyperparameters to be used for this stage.
status – A status object to report the progress of the computations.
**inputs – The fields of the pipeline read by this stage. Each key-value pair represents an input field and the corresponding value.

Returns:

A dictionary containing the outputs of this stage. Each key-value pair in the dictionary represents an output field and the corresponding value.

Raises:

NotImplementedError – If the method is not implemented by the subclass.