Check the usage guide for a more comprehensive read on the library’s usage and the different parameters.
API
class Dosage
The class is configured once on creation and exposes a single method run to process frames.
Parameters
width: int
Specifies the width of the frames to be processed.
height: int
Specifies the height of the frames to be processed.
method: MethodDosage | MethodFastMBD | MethodHybrid, default: MethodHybrid
Specifies the method to be used.
sigma: float, default: 2.5
Higher values yield smoother results, typically at the expense of accuracy. In most cases the default value is good enough.
boundary_thickness: int | 'auto', default: 'auto'
Specifies the thickness of the sub-rectangles used to represent image boundaries.
foreground_boundary: BoundaryTop | BoundaryRight | BoundaryBottom | BoundaryLeft | BoundaryNone, default: BoundaryNone
Specifies which of the four image boundaries should be marked as a foreground boundary.
n_passes: int, default: 4
Specifies the number of passes to be performed. Higher values yield higher output quality but slow down execution. In most cases the default value is enough.
winsor: int, default: 0
When non-zero, the result is clipped so that all values lie in between the winsor-th and 100 - winsor-th percentile. This can help remove outliers and push (non) salient and very (non) salient areas together. Very aggressive, and slightly slows down execution.
reconstruct: bool, default: True
Specifies whether morphological reconstruction should be performed.
reconstruct_iter: int, default: 10
Specifies the number of iterations for morphological reconstruction. Higher values yield a better approximation but slow down execution.
reconstruct_scale: float, default: 0.5
Specifies the factor by which the input for morphological reconstruction should be scaled down. Smaller values speed up execution and need less iterations to achieve a good approximation, but can yield blurry results.
reconstruct_spread: float, default: 0.025
Specifies the spread factor for morphological reconstruction. Higher values perform a more aggressive reconstruction and can better extract bigger shapes, but require more iterations to achieve a good approximation.
reconstruct_renormalize: bool, default: True
Specifies whether values should be normalized to the range [0, 1] after morphological reconstruction.
deflicker: bool, default: True
Specifies whether to (attempt to) reduce flickering in between frames. Applies only when processing frames in sequence (video).
postprocess: bool, default: True
Specifies whether the result should be post processed via a sigmoid function.
sigmoid_center: float, default: 0.5
Specifies the post processing sigmoid function’s center.
sigmoid_strength: float, default: 10
Specifies the post processing sigmoid function’s strength.
Methods
run(frame: NDArray[np.uint8]) → NDArray[np.float32]:
Processes a frame. The frame’s width and height must match the width and height supplied to the instance on creation. The return value is a map from each pixel to its saliency value. Saliency values are in the range [0, 1].
Parameter Impact
The following table shows which parameters have an effect depending on the selected method.
✔️ = parameter has an effect
✖️ = parameter has no effect
MethodDosage | MethodFastMBD | MethodHybrid | |
|---|---|---|---|
| sigma | ✔️ | ✖️ | ✔️ |
| boundary_thickness | ✔️ | ✖️ | ✔️ |
| foreground_boundary | ✔️ | ✔️ | ✔️ |
| n_passes | ✖️ | ✔️ | ✔️ |