Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Rubick65/dcemapper/llms.txt

Use this file to discover all available pages before exploring further.

The src.roi module provides functions to build and manipulate 3D binary masks used to restrict quantitative analysis to a specific region of interest. All functions accept and return the same full_mask array (shape (X, Y, Z), float values in [0, 1]), making them easy to chain. Each function modifies a single Z slice while leaving other slices untouched, and applies smoothing at slice boundaries to reduce hard-edge artifacts.

​
update_rectangular_mask(roi_coords, full_mask, z_index)

Sets a rectangular region of a single slice to 1.0, then applies a gentle Gaussian blur (sigma=0.5) to smooth the mask edges. The result is combined with the existing mask using an element-wise minimum so that previously excluded voxels cannot be re-included.
​
roi_coords
tuple
required
Bounding box defined as (x1, y1, x2, y2) in pixel coordinates. Values are floored to integers and clipped to the array bounds automatically. The order of x1/x2 and y1/y2 does not matter; the function sorts them internally.
​
full_mask
numpy.ndarray
required
3D float mask array of shape (X, Y, Z) with values in [0, 1]. Pass np.ones((X, Y, Z)) to start with a full-volume mask.
​
z_index
int
required
Index of the axial slice to update.
Returns numpy.ndarray — the updated full_mask (modified in-place and also returned). 
from src.roi.roi_creation import update_rectangular_mask
import numpy as np

mask = np.ones((128, 128, 20))
mask = update_rectangular_mask((30, 40, 80, 90), mask, z_index=5)
# Voxels outside the rectangle on slice 5 are suppressed; interior is 1.0

​
update_elliptical_mask(full_mask, ellipsis_center, radius, z_index)

Paints an elliptical region on a single slice using the analytic ellipse equation, then smooths the mask edge with a Gaussian blur (sigma=1.0). Like the rectangular variant, the result is combined with the existing slice via element-wise minimum.
​
full_mask
numpy.ndarray
required
3D float mask array of shape (X, Y, Z).
​
ellipsis_center
tuple
required
(xc, yc) — pixel coordinates of the ellipse centre.
​
radius
tuple
required
(a, b) — semi-axis lengths in the x and y directions respectively. Values are in pixels.
​
z_index
int
required
Index of the axial slice to update.
Returns numpy.ndarray — the updated full_mask. 
from src.roi.roi_creation import update_elliptical_mask
import numpy as np

mask = np.ones((128, 128, 20))
mask = update_elliptical_mask(mask, ellipsis_center=(64, 64), radius=(20, 15), z_index=5)

​
update_polygon_mask(full_mask, polygon_coords, z_index)

Rasterises an arbitrary polygon onto a single slice using 4× supersampling for antialiasing. The high-resolution binary mask is created with skimage.draw.polygon, then downscaled back to the original slice dimensions using bilinear interpolation (skimage.transform.resize, order=1). The result is combined with the existing slice via element-wise minimum.
​
full_mask
numpy.ndarray
required
3D float mask array of shape (X, Y, Z).
​
polygon_coords
list[tuple]
required
Ordered list of (x, y) vertex coordinates defining the polygon boundary. At least three vertices are required. The polygon is automatically closed.
​
z_index
int
required
Index of the axial slice to update.
Returns numpy.ndarray — the updated full_mask. 
from src.roi.roi_creation import update_polygon_mask
import numpy as np

mask = np.ones((128, 128, 20))
vertices = [(30, 40), (80, 40), (80, 90), (30, 90)]
mask = update_polygon_mask(mask, vertices, z_index=5)

​
restar_mask(full_mask, z_index)

Resets a single slice of the mask back to all 1.0, effectively undoing any ROI drawn on that slice. This is the undo operation exposed in the GUI via Ctrl+Z.
​
full_mask
numpy.ndarray
required
3D float mask array of shape (X, Y, Z).
​
z_index
int
required
Index of the axial slice to reset.
Returns numpy.ndarray — the updated full_mask with full_mask[:, :, z_index] set entirely to 1.0. 
from src.roi.roi_creation import restar_mask
import numpy as np

mask = np.ones((128, 128, 20))
# ... apply some ROIs ...
mask = restar_mask(mask, z_index=5)  # undo ROI on slice 5

​
Chaining mask operations

All four functions share the same interface and return the modified array, so they can be chained naturally: 
import numpy as np
from src.roi.roi_creation import (
    update_rectangular_mask,
    update_elliptical_mask,
    update_polygon_mask,
    restar_mask,
)

mask = np.ones((128, 128, 20), dtype=float)

# Draw a rectangle on slice 3
mask = update_rectangular_mask((10, 10, 60, 60), mask, z_index=3)

# Refine with an ellipse on the same slice
mask = update_elliptical_mask(mask, ellipsis_center=(35, 35), radius=(25, 25), z_index=3)

# Draw a polygon on slice 7
mask = update_polygon_mask(mask, [(20, 30), (90, 30), (90, 100), (20, 100)], z_index=7)

# Undo the polygon on slice 7
mask = restar_mask(mask, z_index=7)
All mask functions apply changes with np.minimum, which means the mask can only be narrowed — a voxel set to 0 on a previous call cannot be restored to 1 except by calling restar_mask on the entire slice.

Build docs developers (and LLMs) love

Get started for freeTalk to us