superdsm.dsmcfg

class superdsm.dsmcfg.DSM_Config

Bases: Stage

Fetches the hyperparameters from the dsm namespace and provides them as an output.

The purpose of this stage is to provide the hyperparameters from the dsm namespace as the output dsm_cfg, which is a dictionary of the hyperparameters without the leading dsm/ namespace prefix. This enables any stage to access the DSM-related hyperparameters, like the C2F_RegionAnalysis and GlobalEnergyMinimization stages, without having to access the dsm hyperparameter namespace. Refer to Inputs and outputs for more information on the available inputs and outputs.

Hyperparameters

The following hyperparameters are fetched:

dsm/cachesize: The maximum number of entries used for caching during convex programming. This concerns invocations of the callback function F used by the cvxopt solver for nonlinear problems. Defaults to 1.
dsm/cachetest: The test function to be used for cache testing. If None, then numpy.array_equal will be used. Using other functions like numpy.allclose has shown to introduce numerical instabilities. Defaults to None.
dsm/sparsity_tol: Absolute values below this threshold will be treated as zeros during optimization. Defaults to 0.
dsm/init: Either a function or a string. If this is function, then it will be called to determine the initialization, and the dimension of the vector \(\xi\) will be passed as a parameter. If this is a string, then the initialization corresponds to the result of convex programming using elliptical models (if set to elliptical, see Supplemental Material 6 of Kostrykin and Rohr, TPAMI 2023) or a zeros vector of is used (otherwise). Defaults to elliptical.
dsm/smooth_amount: Corresponds to \(\sigma_G\) described in Deformable shape models. Defaults to 10, or to AF_smooth_amount × scale if computed automatically (forced to \(\geq 4\) and AF_smooth_amount defaults to 0.2).
dsm/smooth_subsample: Corresponds to the amount of sub-sampling used to obtain the matrix \(\tilde G_\omega\) in Kostrykin and Rohr (TPAMI 2023, Section 3.3). Defaults to 20, or to AF_smooth_subsample × scale if computed automatically (forced to \(\geq 8\) and AF_smooth_subsample defaults to 0.4).
dsm/epsilon: Corresponds to the constant \(\epsilon\) which is used for the smooth approximation of the regularization term \(\|\xi\|_1 \approx \mathbb 1^\top_\Omega \sqrt{\xi^2 + \epsilon} - \sqrt{\epsilon} \cdot \#\Omega\) (see Supplemental Material 2 of Kostrykin and Rohr, TPAMI 2023). Defaults to 1.
dsm/alpha: Governs the regularization of the deformations and corresponds to \(\alpha\) described in Convex energy minimization. Increasing this value leads to a smoother segmentation result. Defaults to 0.5, or to AF_alpha × scale^2 if computed automatically (where AF_alpha corresponds to \(\alpha_\text{factor}\) in Kostrykin and Rohr, TPAMI 2023, and defaults to 5e-4).
dsm/scale: Fixed factor used during convex programming to slightly improve numerical stabilities. Defaults to 1000.
dsm/gaussian_shape_multiplier: The Gaussian function with standard deviation \(\sigma_G\) used to construct the block Toeplitz matrix \(G_\omega\) is cut off after \(4 \sigma_G\) multiplied by this value (see Deformable shape models). Defaults to 2.
dsm/smooth_mat_dtype: A string indicating the data type used for the matrix \(G_\omega\). Defaults to float32.
dsm/smooth_mat_max_allocations: Maximum number of simultaneous allocation of the matrix \(\tilde G_\omega\) during parallel processing (see Section 3.3 of Kostrykin and Rohr, TPAMI 2023, each allocation might require a considerable amount of system memory).
dsm/background_margin: Governs the amount of image background included in the obtained image region. This is the width of the “stripe” of background retained around each connected foreground region (in pixels). See Supplemental Material 6 of Kostrykin and Rohr (TPAMI 2023) for details, however, due to a transmission error, the threshold \(\sigma_G\) in Eq. (S11) was misstated by a factor of 2 (the correct threshold is \(2\sigma_G\)). Defaults to 20, or to AF_background_margin × scale if computed automatically (forced to \(\geq 8\) and AF_background_margin defaults to 0.4).
dsm/cp_timeout: The maximum run time of convex programming for each object (in seconds). The convex optimization will be interrupted if it takes longer than that (the cvxprog() function will report the status fallback in this case). If this is set to None, the run time is not limited. Defaults to 300 (i.e. 5 minutes).

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.