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 produces y_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 or isbi24, as described above. Defaults to exact.
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, where AF_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 for AF_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 (and AF_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 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.

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).