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 outputdsm_cfg
, which is a dictionary of the hyperparameters without the leadingdsm/
namespace prefix. This enables any stage to access the DSM-related hyperparameters, like theC2F_RegionAnalysis
andGlobalEnergyMinimization
stages, without having to access thedsm
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
, thennumpy.array_equal
will be used. Using other functions likenumpy.allclose
has shown to introduce numerical instabilities. Defaults toNone
.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 toelliptical
.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\) andAF_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\) andAF_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 (whereAF_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\) andAF_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 statusfallback
in this case). If this is set toNone
, 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 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.