superdsm.c2freganal
- class superdsm.c2freganal.C2F_RegionAnalysis
Bases:
Stage
Implements the Coarse-to-fine region analysis scheme.
This stage requires
y
anddsm_cfg
for input and producesy_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 (andAF_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 theexamples/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 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.