superdsm.c2freganal

class superdsm.c2freganal.C2F_RegionAnalysis

Bases: Stage

Implements the Coarse-to-fine region analysis scheme.

This stage requires y and dsm_cfg for input and produces y_mask, atoms, adjacencies, seeds, clusters 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:

c2f-region-analysis/seed_connectivity

Image points which are adjacent to each other are not to determine the atomic image regions. Adjacency of such image points is determined using either 4-connectivity or 8-connectivity. Must be either 4 or 8. Defaults to 8.

c2f-region-analysis/min_atom_radius

No region determined by the Coarse-to-fine region analysis scheme is smaller than a circle of this radius (in terms of the surface area). Corresponds to min_region_radius in Kostrykin and Rohr (TPAMI 2023, Supplemental Materials 5 and 8). Defaults to 15, or to AF_min_atom_radius × radius if configured automatically (and AF_min_atom_radius defaults to 0.33).

c2f-region-analysis/max_atom_norm_energy

No atomic image region \(\omega\) determined by the Coarse-to-fine region analysis has a normalized energy \(r(\omega)\) smaller than this value. Corresponds to max_norm_energy1 in Kostrykin and Rohr (TPAMI 2023, Supplemental Materials 5 and 8). Defaults to 0.05.

c2f-region-analysis/min_norm_energy_improvement

Each split performed during the computation of the atomic image regions must improve the normalized energy \(r(\omega)\) of an image region \(\omega\) by at least this factor (see Coarse-to-fine region analysis). Given that an image region is split into the sub-regions \(\omega_1, \omega_2\), the improvement of the split is defined by the fraction \(\max\{ r(\omega_1), r(\omega_1) \} / r(\omega_1 \cup \omega_2)\). Lower values of the fraction correspond to better improvements. Defaults to 0.1.

c2f-region-analysis/max_cluster_marker_irregularity

Threshold for the “irregularity” of image regions, which is used to determine the output y_mask. Image regions with an “irregularity” higher than this value are masked as “empty” image regions and discarded from further considerations. This is the threshold for the P/A ratio described in Kostrykin and Rohr (TPAMI 2023, see Section 3.1 and max_pa_ratio in Supplemental Material 8). Defaults to 0.2.

Note

This stage takes the DSM-related hyperparameters as an input. Due to a bug in the original implementation, the value set for the hyperparameter dsm/background_margin was disrespected and a value of 20 was always used instead. However, the impact on the results is only subtle. Having this issue fixed, the results are mostly consistent with those originally reported in Kostrykin and Rohr (TPAMI 2023, the hyperparameter \(\alpha\) is changed from 0.1 to 0.2 for the GOWT1-2 dataset when using SuperDSM*, see the examples/GOWT1-2/default/adapted/task.json file).

ENABLED_BY_DEFAULT = True
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.