superdsm.globalenergymin
- class superdsm.globalenergymin.GlobalEnergyMinimization
Bases:
Stage
Implements the global energy minimization (see Joint segmentation and cluster splitting).
This stage implements Algorithm 1 and Criterion 2 from Kostrykin and Rohr (TPAMI 2023). The stage requires
y
,y_mask
,atoms
,adjacencies
,dsm_cfg
for input and producesy_img
,cover
,objects
,performance
for output. Refer to Inputs and outputs for more information on the available inputs and outputs.For Algorithm 1, there are two behaviours implemented which differ in the definition of the upper bound \(c_{\text{max}}\). In exact pruning mode, the original definition from the paper is used,
\[c_{\text{max}} = \operatorname{MSC}(\mathscr U) - \sum_{u \in U \setminus X} \nu(\{u\}),\]which guarantees that \(\operatorname{MSC}(\mathscr U_{\# U}) = \operatorname{MSC}(\mathbb P(U))\). On the other hand, the isbi24 pruning mode corresponds to the algorithm described in Kostrykin and Rohr (ISBI 2024), which yields a more greedy behaviour. Depending on the data, this can be significantly faster, without degrading the segmentation or cluster splitting performance.
Hyperparameters
The following hyperparameters can be used to control this pipeline stage:
global-energy-minimization/pruning
Mist be either
exact
orisbi24
, as described above. Defaults toexact
.global-energy-minimization/beta
Corresponds to the sparsity parameter \(\beta\) described in Joint segmentation and cluster splitting. Defaults to 0, or to
AF_beta × scale^2
if configured automatically, whereAF_beta
corresponds to \(\beta_\text{factor}\) in Kostrykin and Rohr (TPAMI 2023) and defaults to 0.66. Due to a transmission error, the values reported forAF_beta
in the paper were misstated by a factor of 2 (Section 3.3, Supplemental Material 8).global-energy-minimization/max_iter
The number of iterations to perform for solving the min-weight set-cover (see
solve_minsetcover()
and Algorithm 2 in Kostrykin and Rohr, TPAMI 2023). Iterations use an increasingly conservative merging strategy (i.e. the sparsity parameter \(\beta\) is reduced). Defaults to 5.global-energy-minimization/gamma
The factor used to reduce the sparsity parameter \(\beta\) after the first iteration (this is the parameter \(\gamma\) of Algorithm 2 in Kostrykin and Rohr, TPAMI 2023, where \(0 < \gamma < 1\)). Defaults to 0.8.
global-energy-minimization/max_seed_distance
Maximum distance allowed between two seed points of atomic image regions which are grouped into an image region corresponding to single object (cf. Coarse-to-fine region analysis). This can be used to enforce that the segmented objects will be of a maximum size, and thus to limit the computational cost by using prior knowledge. Defaults to infinity, or to
AF_max_seed_distance × diameter
if configured automatically (andAF_max_seed_distance
defaults to infinity).global-energy-minimization/max_work_amount
Used to recognize a computationally intractable amount of objects due to misconfigured hyperparameters. If the number of objects could exceed this threshold, a
ValueError
is raised. The number of objects is estimated based on the structure of the adjacency graph of the atomic image regions (see Coarse-to-fine region analysis). Defaults to 10e6.
- 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.
- class superdsm.globalenergymin.PerformanceReport(**kwargs)
Bases:
object
Reports the pruning performance of the global energy minimization method.
- Variables:
direct_solution_trial_count – The number of cases in which Criterion 2 was evaluated (see Kostrykin and Rohr, TPAMI 2023).
direct_solution_success_count – The number of cases in which Criterion 2 yielded a closed-form solution (see Kostrykin and Rohr, TPAMI 2023).
iterative_object_count – The number of objects which would be computed if bruteforce was used instead of Algorithm 1.
iterative_computed_object_count – The number of objects computed by Algorithm 1 (see Kostrykin and Rohr, TPAMI 2023).
overall_object_count – The overall number of objects which would be computed if neither Algorithm 1 nor Criterion 2 was used.
overall_computed_object_count – The overall number of computed objects.
nontrivial_object_count – The overall number of objects which would be computed if neither Algorithm 1 nor Criterion 2 was used (except for trivial regions of possibly clustered objects).
nontrivial_computed_object_count – The overall number of computed objects (except for trivial regions of possibly clustered objects).
For regions of possibly clustered objects, for which the cardinality \(\# U\) of the universe \(U\) is 1 or 2, always all possible objects must be computed. Since only 3 objects are possible at most (the region of possbily clustered objects either corresponds to two objects or to a single object), such regions are called trivial.
- attributes = ['direct_solution_trial_count', 'direct_solution_success_count', 'iterative_object_count', 'iterative_computed_object_count', 'overall_object_count', 'overall_computed_object_count', 'nontrivial_object_count', 'nontrivial_computed_object_count']
List of supported keyword arguments and attributes.
- property direct_solution_success
The number of cases in which Criterion 2 yielded a closed-form solution, normalized by the number of cases in which Criterion 2 was evaluated (see Kostrykin and Rohr, TPAMI 2023).
- property iterative_pruning_success
The number of objects pruned by Algorithm 1, normalized by the number of objects which would be computed if bruteforce was used instead of Algorithm 1 (see Kostrykin and Rohr, TPAMI 2023).
- property nontrivial_pruning_success
The number of pruned objects within non-trivial regions of possibly clustered objects, normalized by the number of objects in those regions which would be computed if neither Algorithm 1 nor Criterion 2 was used (see Kostrykin and Rohr, TPAMI 2023).
This is the key performance indicator for the overall pruning performance.
- property overall_pruning_success
The number of pruned objects, normalized by the number of objects which would be computed if neither Algorithm 1 nor Criterion 2 was used (see Kostrykin and Rohr, TPAMI 2023).