MaskOperations
Provides tools for creating, editing, and analyzing 3D mask objects. Supports import/export, segmentation, region operations, and conversion between mask, volume, and surface data.
Import
import ScriptingApi as api
# Access via Application
app = api.Application()
ops = app.get_mask_operations()
Methods
Properties
get_render_properties_operations
Returns an api.MaskRenderPropertiesOperations object.
Signature:
get_render_properties_operations() -> MaskRenderPropertiesOperations
Returns: MaskRenderPropertiesOperations — The api.MaskRenderPropertiesOperations object.
get_mask_uint8
Retrieves the mask data as an 8-bit unsigned integer structure.
Signature:
get_mask_uint8(maskName: str) -> MaskUint8
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskName | str | The name of the mask to retrieve. |
Returns: MaskUint8 — The api.MaskUint8 mask data as an 8-bit unsigned integer structure.
get_mask_uint_16
Retrieves the mask data as a 16-bit unsigned integer structure.
Signature:
get_mask_uint_16(maskName: str) -> MaskUint16
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskName | str | The name of the mask to retrieve. |
Returns: MaskUint16 — The api.MaskUint16 mask data as a 16-bit unsigned integer structure.
set_mask_uint8
Sets the mask data as an 8-bit unsigned integer structure. This method checks for dimension, spacing, and origin compatibility before setting the data. If the new data matches the existing data exactly, the update is skipped.
Signature:
set_mask_uint8(maskName: str, maskData: MaskUint8) -> bool
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskName | str | The name of the mask to set. |
maskData | MaskUint8 | The mask data to set. Create using api.MaskUint8(). |
Returns: bool — True if the mask data was set successfully; False otherwise.
set_mask_uint_16
Sets the mask data as a 16-bit unsigned integer structure. This method checks for dimension, spacing, and origin compatibility before setting the data. If the new data matches the existing data exactly, the update is skipped.
Signature:
set_mask_uint_16(maskName: str, maskData: MaskUint16) -> bool
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskName | str | The name of the mask to set. |
maskData | MaskUint16 | The mask data to set. Create using api.MaskUint16(). |
Returns: bool — True if the mask data was set successfully; False otherwise.
is_multilabel_mask
Checks if a mask is a multi-label mask.
Signature:
is_multilabel_mask(maskName: str) -> bool
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskName | str | The name of the mask to check. |
Returns: bool — True if the mask is a multi-label mask; False otherwise.
get_mask_labels
Retrieves information about the labels in a multi-label mask.
Signature:
get_mask_labels(maskName: str) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskName | str | The name of the mask to retrieve label information from. |
Returns: list — A list of api.MaskLabelInfo containing information about each label, or an empty list if the mask is not multi-label. Usage example: mask_operations = app.get_mask_operations() mask_label_info_list = mask_operations.get_mask_labels('multilabel_mask') for info in mask_label_info_list: mask_label_info : api.MaskLabelInfo = info print(mask_label_info.value)
get_mask_label_values
Retrieves the label values present in a multi-label mask.
Signature:
get_mask_label_values(maskName: str) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskName | str | The name of the mask to retrieve label values from. |
Returns: list — A list of integers representing the label values, or an empty list if the mask is not multi-label.
get_basic_surface_mesh_info
Retrieves basic 3D preview mesh information for a specified mask.
Signature:
get_basic_surface_mesh_info(maskName: str) -> BasicSurfaceMeshInfo
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskName | str | The name of the mask to retrieve information for. |
Returns: BasicSurfaceMeshInfo — A api.BasicSurfaceMeshInfo object containing the 3D preview mesh information.
File System
import_3d_mask_images_from_disk
Imports mask image files from disk.
Signature:
import_3d_mask_images_from_disk(fileNames: list) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
fileNames | list | A list containing the full paths of the mask image files to import. Supported file extensions are: mha, mhd, nii, nii.gz, vti. |
Returns: list — A list of names of the imported masks on successful import; otherwise, returns an empty list.
import_3d_mask_image_from_disk
Imports a mask image file from disk.
Signature:
import_3d_mask_image_from_disk(fileName: str) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
fileName | str | The full path of the mask image file to import. Supported file extensions are: mha, mhd, nii, nii.gz, vti. |
Returns: str — Returns the name of the imported mask if successful; otherwise, returns an empty string.
export_mask_images_to_disk
Exports masks specified by their names to disk files in a given directory with a specified file extension.
Signature:
export_mask_images_to_disk(maskNames: list, directoryPath: str, fileExtension: str = "mha") -> bool
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskNames | list | A list containing the names of the masks to export. |
directoryPath | str | The path to the directory where the mask image files will be saved. |
fileExtension | str | The file extension to use for the exported mask image files. Supported file extensions are: mha, mhd, nii, nii.gz, vti. |
Returns: bool — Returns True if all masks were successfully exported; otherwise, returns False.
export_mask_image_to_disk
Exports a mask image to a file on disk.
Signature:
export_mask_image_to_disk(maskName: str, fileName: str) -> bool
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskName | str | The name of the mask image to export. |
fileName | str | The path and name of the file to write the mask image data to. Supported file extensions are: mha, mhd, nii, nii.gz, vti. File name should include the file extension, e.g., 'C:/temp/mask.mha'. |
Returns: bool — True if the export was successful; false otherwise.
Creation
create_mask
Creates a new blank mask.
Signature:
create_mask(name: str, autoColor: bool = True, rgb: list = [1.0, 0.0, 0.0]) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
name | str | The name of the mask to create. |
autoColor | bool | Whether to automatically assign a color to the mask. |
rgb | list | The RGB color [R, G, B] values to assign to the mask (ignored if autoColor is true). |
Returns: str — The name of the created mask.
create_new_mask_from_labels
Creates a new mask from specified labels of an existing mask.
Signature:
create_new_mask_from_labels(volumeName: str, maskName: str, labels: list) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
volumeName | str | Name of the volume object (can be empty if not needed). |
maskName | str | Name of the source mask. |
labels | list | List of label values to include in the new mask. |
Returns: str — Name of the created mask containing only the specified labels on success; otherwise, returns an empty string.
General
threshold
Segments a volume using range-based thresholding. Creates a new mask or updates an existing mask with voxels within the specified grayvalue range.
Signature:
threshold(volumeName: str, params: ThresholdParams) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
volumeName | str | Name of the volume to segment. |
params | ThresholdParams | Threshold parameters. Create using api.ThresholdParams(). |
Returns: str — Name of the created mask if new mask is requested; otherwise, name of the updated mask. Empty string on failure.
surface_determination
Determines the material surface of a volume and stores it in a mask with sub-voxel partial gray values. Manual, ISO50 and histogram methods classify the volume against one gray value. The advanced method refines that surface locally along the surface normal. The mask surface lies at 127.5, where every mask consumer (3D preview, convert to surface, deviation, wall thickness) extracts it.
Signature:
surface_determination(volumeName: str, params: SurfaceDeterminationParams) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
volumeName | str | Name of the volume. |
params | SurfaceDeterminationParams | Surface determination parameters. Create using api.SurfaceDeterminationParams(). |
Returns: str — Name of the created mask, or of the replaced mask when params.target_mask_name names one. Empty when no surface crosses the volume or the run was cancelled. Invalid settings and resource limits raise an error.
estimate_surface_determination
Resolves the surface determination settings for a volume without creating a mask. Returns the estimated background and material gray values, the resulting isovalue and, for the advanced method with automatic search distance, the proposed search distance.
Signature:
estimate_surface_determination(volumeName: str, params: SurfaceDeterminationParams) -> SurfaceDeterminationEstimate
Parameters:
| Parameter | Type | Description |
|---|---|---|
volumeName | str | Name of the volume. |
params | SurfaceDeterminationParams | Surface determination parameters. Create using api.SurfaceDeterminationParams(). |
Returns: SurfaceDeterminationEstimate — The estimate. Its valid flag is false and its message explains why when the settings cannot be resolved.
region_grow
Performs region growing segmentation from an existing mask. Grows regions from seed points within the source mask.
Signature:
region_grow(volumeName: str, params: RegionGrowSegmentationParams) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
volumeName | str | Name of the volume to segment. |
params | RegionGrowSegmentationParams | Region grow parameters. Create using api.RegionGrowSegmentationParams(). |
Returns: str — Name of the created mask if new mask is requested; otherwise, name of the updated mask. Empty string on failure.
dynamic_region_grow_connectivity
Performs dynamic region growing using connectivity-based method. Grows regions based on statistical properties of the local neighborhood. Identifies a connected set of pixels with pixel intensities matching the statistical properties of a seed point.
Signature:
dynamic_region_grow_connectivity(volumeName: str, params: DynamicRegionGrowConnectivitySegmentationParams) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
volumeName | str | Name of the volume to segment. |
params | DynamicRegionGrowConnectivitySegmentationParams | Connectivity-based region grow parameters. Create using api.DynamicRegionGrowConnectivitySegmentationParams(). |
Returns: str — Name of the created mask if new mask is requested; otherwise, name of the updated mask. Empty string on failure.
dynamic_region_grow_threshold
Performs dynamic region growing using threshold-based method. Grows regions based on grayvalue thresholds. Identifies pixels connected to a seed point with grayscale values within a specified range.
Signature:
dynamic_region_grow_threshold(volumeName: str, params: DynamicRegionGrowThresholdSegmentationParams) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
volumeName | str | Name of the volume to segment. |
params | DynamicRegionGrowThresholdSegmentationParams | Threshold-based region grow parameters. Create using api.DynamicRegionGrowThresholdSegmentationParams(). |
Returns: str — Name of the created mask if new mask is requested; otherwise, name of the updated mask. Empty string on failure.
otsu_thresholding_segmentation
Performs Otsu multi-level thresholding segmentation. Automatically determines optimal thresholds and creates multiple masks. Otsu thresholding is a global thresholding technique that selects the optimal thresholds by maximizing the between-class variance of the resulting segmented regions.
Signature:
otsu_thresholding_segmentation(volumeNames: list, numberOfDesiredMasks: int = 2) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
volumeNames | list | Names of the volumes to segment. |
numberOfDesiredMasks | int | The number of desired masks. |
Returns: list — A list of names of the created masks on successful segmentation, otherwise returns an empty list.
kmeans_thresholding_segmentation
Performs K-means clustering thresholding segmentation. Uses K-means algorithm to cluster grayvalues and create masks. K-means thresholding is a clustering-based approach to image segmentation. It partitions the image pixels into K clusters based on their intensity values, and the cluster centroids are then used as the thresholds for segmentation.
Signature:
kmeans_thresholding_segmentation(volumeNames: list, numberOfDesiredMasks: int = 2) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
volumeNames | list | Names of the volumes to segment. |
numberOfDesiredMasks | int | The number of desired masks. |
Returns: list — A list of names of the created masks on successful segmentation, otherwise returns an empty list.
watershed_segmentation
Performs watershed segmentation on masks for object separation. Separates touching objects using morphological watershed algorithm.
Signature:
watershed_segmentation(maskNames: list, level: float = 1, minimumObjectSize: int = 8, removeObjectsTouchingBorder: bool = False, createMultilabelMask: bool = True, connectivity: VoxelConnectivity = api.VoxelConnectivity.Connectivity6) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskNames | list | List of mask names to process. |
level | float | Segmentation depth control (higher values = more separation). |
minimumObjectSize | int | Minimum object size to retain (in voxels). |
removeObjectsTouchingBorder | bool | If True, remove objects that touch boundaries. If False, keep all objects regardless of their position. |
createMultilabelMask | bool | If True, creates multi-label mask; if False, creates separate masks. |
connectivity | VoxelConnectivity | Connectivity criterion for labeling. Use api.VoxelConnectivity.Connectivity6 or api.VoxelConnectivity.Connectivity26. 6-connectivity: A voxel is considered connected only to its directly adjacent neighbors that share a face, excluding connections along edges or corners, resulting in up to 6 possible connections in a 3D grid. 26-connectivity: A voxel is considered connected to all of its surrounding neighbors, including those along edges and corners(diagonal connections), resulting in a total of 26 possible connections in a 3D grid. |
Returns: list — A list of names of the created masks on successful segmentation, otherwise returns an empty list.
voids_and_inclusion_segmentation
Performs porosity/inclusion segmentation and analysis. Detects and segments voids or inclusions within volume objects.
Signature:
voids_and_inclusion_segmentation(volumeNames: list, params: VoidInclusionSegmentationParams) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
volumeNames | list | Names of the volumes to analyze. |
params | VoidInclusionSegmentationParams | Porosity/inclusion analysis parameters. Create using api.VoidInclusionSegmentationParams(). |
Returns: list — A list of names of the created masks on successful segmentation; otherwise, returns an empty list.
crop_mask
Crops a mask using the specified bounding box. Everything outside the bounding box will be removed.
Signature:
crop_mask(maskName: str, bounds: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskName | str | Name of the mask to crop. |
bounds | list | Bounding box as [xMin, xMax, yMin, yMax, zMin, zMax]. |
clear_masks
Clears the content of masks, setting all voxels to zero.
Signature:
clear_masks(maskNames: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskNames | list | List of mask names to clear. |
morphological_operation
Perform a morphological operation on specified masks.
Signature:
morphological_operation(maskNames: list, operation: MorphologicalOperationType, ballRadius: list = [1, 1, 1]) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskNames | list | List of mask names to process. |
operation | MorphologicalOperationType | The morphological operation to execute. Use api.MorphologicalOperationType.Erode, api.MorphologicalOperationType.Dilate, etc. |
ballRadius | list | Kernel (structuring element) radius in pixels per axis, as [radiusX, radiusY, radiusZ]. |
boolean
Performs boolean operations between masks. Combines masks using logical operations (union, intersection, difference). The result is stored in the target mask or a new mask if createNewMask is True.
Signature:
boolean(input1Name: str, input2Names: list, targetName: str, operation: BooleanOperation, createNewMask: bool = True) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
input1Name | str | Name of the first input mask. |
input2Names | list | Names of additional masks to combine with the first mask. |
targetName | str | Name of the target mask (where result will be stored). Only used if createNewMask=False. |
operation | BooleanOperation | Type of boolean operation (Union, Intersection, Difference). Use api.BooleanOperation.Union, api.BooleanOperation.Intersection, or api.BooleanOperation.Difference. |
createNewMask | bool | If True, creates a new mask; if False, updates target mask. |
Returns: str — Name of the resulting mask containing the result of the boolean operation.
split_multi_label_mask
Separates labels from a multi-label mask into individual masks.
Signature:
split_multi_label_mask(volumeName: str, maskName: str, separateOnlyLargestLabels: bool = False, numLargestLabels: int = 0, removeActiveMask: bool = False) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
volumeName | str | Name of the volume object (can be empty if not needed). |
maskName | str | Name of the multi-label mask to split. |
separateOnlyLargestLabels | bool | If True, only separate the largest labels. |
numLargestLabels | int | Number of largest labels to separate (used when separateOnlyLargestLabels=True). |
removeActiveMask | bool | If True, removes the original mask after splitting. |
Returns: list — A list of names of the created masks for each separated label on success; otherwise, returns an empty list.
merge_into_multi_label_mask
Merges multiple masks into a single multi-label mask.
Signature:
merge_into_multi_label_mask(maskNames: list, targetName: str, createNewMask: bool = True, removeInputMasks: bool = False) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskNames | list | Names of the masks to merge. |
targetName | str | Name of the target mask (only used when createNewMask=False). |
createNewMask | bool | If True, creates a new mask; if False, updates target mask. |
removeInputMasks | bool | If True, removes input masks after successful merge. |
Returns: str — Name of the resulting multi-label mask on success; otherwise, returns an empty string.
combine_labels_in_multi_label_mask
Combines specified labels within a multi-label mask into a single label.
Signature:
combine_labels_in_multi_label_mask(maskName: str, labels: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskName | str | Name of the multi-label mask. |
labels | list | List of label values to combine. |
convert_multi_label_mask_to_normal_mask
Converts a multi-label mask to a normal binary mask.
Signature:
convert_multi_label_mask_to_normal_mask(maskNames: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskNames | list | Names of the multi-label masks to convert. |
remove_labels_from_mask
Removes specified labels from a mask.
Signature:
remove_labels_from_mask(maskName: str, labels: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskName | str | Name of the mask to modify. |
labels | list | List of label values to remove. |
split_mask
Separates disconnected regions into individual masks. Creates new masks for each disconnected region, either as separate masks or as a single multi-label mask.
Signature:
split_mask(maskName: str, numLargestRegions: int = 0, createMultilabelMask: bool = False, removeActiveMask: bool = False, connectivity: VoxelConnectivity = api.VoxelConnectivity.Connectivity6) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskName | str | Name of the mask to split. |
numLargestRegions | int | Number of largest regions to extract (0 for all). |
createMultilabelMask | bool | If True, creates single multi-label mask; if False, creates separate masks. |
removeActiveMask | bool | If True, removes the original mask after splitting. |
connectivity | VoxelConnectivity | Connectivity criterion for region definition. Use api.VoxelConnectivity.Connectivity6 or api.VoxelConnectivity.Connectivity26. 6-connectivity: A voxel is considered connected only to its directly adjacent neighbors that share a face, excluding connections along edges or corners, resulting in up to 6 possible connections in a 3D grid. 26-connectivity: A voxel is considered connected to all of its surrounding neighbors, including those along edges and corners(diagonal connections), resulting in a total of 26 possible connections in a 3D grid. |
Returns: list — A list of names of the created masks for each separated region on success; otherwise, returns an empty list.
filter_regions
Filters regions in masks based on size criteria. Either keeps the N largest regions or removes regions smaller than specified size.
Signature:
filter_regions(maskNames: list, keepLargestRegions: bool = True, numberOfLargestRegions: int = 1, minimumRegionSizeInVoxels: int = 512, connectivity: VoxelConnectivity = api.VoxelConnectivity.Connectivity6) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskNames | list | List of mask names to process. |
keepLargestRegions | bool | If True, keeps N largest regions; if False, filters by minimum size. |
numberOfLargestRegions | int | The number of largest regions to keep based on their volume. Only used when keepLargestRegions=True. |
minimumRegionSizeInVoxels | int | Minimum size in voxels for a region. Any region smaller than this size will be removed from the resulting mask. Only used when keepLargestRegions=False. |
connectivity | VoxelConnectivity | Connectivity criterion for region definition. Use api.VoxelConnectivity.Connectivity6 or api.VoxelConnectivity.Connectivity26. 6-connectivity: A voxel is considered connected only to its directly adjacent neighbors that share a face, excluding connections along edges or corners, resulting in up to 6 possible connections in a 3D grid. 26-connectivity: A voxel is considered connected to all of its surrounding neighbors, including those along edges and corners(diagonal connections), resulting in a total of 26 possible connections in a 3D grid. |
keep_largest_regions
Keeps only the largest N regions in masks. Removes all regions except the specified number of largest ones based on voxel count.
Signature:
keep_largest_regions(maskNames: list, numberOfLargestRegions: int = 1, connectivity: VoxelConnectivity = api.VoxelConnectivity.Connectivity6) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskNames | list | List of mask names to process. |
numberOfLargestRegions | int | The number of largest regions to keep based on their volume. |
connectivity | VoxelConnectivity | Connectivity criterion for region definition. Use api.VoxelConnectivity.Connectivity6 or api.VoxelConnectivity.Connectivity26. 6-connectivity: A voxel is considered connected only to its directly adjacent neighbors that share a face, excluding connections along edges or corners, resulting in up to 6 possible connections in a 3D grid. 26-connectivity: A voxel is considered connected to all of its surrounding neighbors, including those along edges and corners(diagonal connections), resulting in a total of 26 possible connections in a 3D grid. |
count_regions_in_mask
Counts the number of disconnected regions (or islands) in a mask.
Signature:
count_regions_in_mask(maskName: str, connectivity: VoxelConnectivity = api.VoxelConnectivity.Connectivity6) -> int
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskName | str | Name of the mask to analyze. |
connectivity | VoxelConnectivity | Connectivity criterion for region definition. Use api.VoxelConnectivity.Connectivity6 or api.VoxelConnectivity.Connectivity26. 6-connectivity: A voxel is considered connected only to its directly adjacent neighbors that share a face, excluding connections along edges or corners, resulting in up to 6 possible connections in a 3D grid. 26-connectivity: A voxel is considered connected to all of its surrounding neighbors, including those along edges and corners(diagonal connections), resulting in a total of 26 possible connections in a 3D grid. |
Returns: int — Number of disconnected regions found in the mask.
refine_mask
Refines mask by removing small regions and filling small cavities. Combined operation that filters out small regions and fills small holes.
Signature:
refine_mask(maskName: str, minRegionSizeInVoxels: float = 10, maxCavitySizeInVoxels: float = 10, connectivity: VoxelConnectivity = api.VoxelConnectivity.Connectivity6) -> tuple
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskName | str | Name of the mask to refine. |
minRegionSizeInVoxels | float | The minimum size (in voxels) for a connected region to be retained in the mask Smaller regions (particles) will be removed from the mask. Set to 0 to disable region removal. |
maxCavitySizeInVoxels | float | The maximum size (in voxels) of an internal cavity (enclosed hole) that should be filled. Larger cavities will remain unfilled. Set to 0 to disable cavity filling. |
connectivity | VoxelConnectivity | Connectivity criterion for region definition. Use api.VoxelConnectivity.Connectivity6 or api.VoxelConnectivity.Connectivity26. 6-connectivity: A voxel is considered connected only to its directly adjacent neighbors that share a face, excluding connections along edges or corners, resulting in up to 6 possible connections in a 3D grid. 26-connectivity: A voxel is considered connected to all of its surrounding neighbors, including those along edges and corners(diagonal connections), resulting in a total of 26 possible connections in a 3D grid. |
Returns: tuple — Pair of counts: (removed regions count, filled cavities count). Empty if operation failed.
cavity_fill
Removes holes that are not connected to the mask boundary.
Signature:
cavity_fill(maskNames: list, connectivity: VoxelConnectivity = api.VoxelConnectivity.Connectivity6) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskNames | list | List of mask names to process. |
connectivity | VoxelConnectivity | Connectivity criterion for cavities. Use api.VoxelConnectivity.Connectivity6 or api.VoxelConnectivity.Connectivity26. 6-connectivity: A voxel is considered connected only to its directly adjacent neighbors that share a face, excluding connections along edges or corners, resulting in up to 6 possible connections in a 3D grid. 26-connectivity: A voxel is considered connected to all of its surrounding neighbors, including those along edges and corners(diagonal connections), resulting in a total of 26 possible connections in a 3D grid. |
grow_masks
Expand the size of the mask, increasing the area it covers. Expands mask boundaries outward by the specified margin.
Signature:
grow_masks(maskNames: list, marginSizeMM: float = 2.0) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskNames | list | List of mask names to process. |
marginSizeMM | float | Margin size to grow in millimeters. |
shrink_masks
Decrease the size of the mask, reducing the area it covers. Contracts mask boundaries inward by the specified margin.
Signature:
shrink_masks(maskNames: list, marginSizeMM: float = 2.0) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskNames | list | List of mask names to process. |
marginSizeMM | float | Margin size to shrink in millimeters. |
interpolate_3d
Interpolates masks in empty slices along specified axis. Fills empty slices between mask regions using interpolation.
Signature:
interpolate_3d(maskNames: list, axis: InterpolationAxis = api.InterpolationAxis.All) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskNames | list | List of mask names to interpolate. |
axis | InterpolationAxis | Interpolation axis. Use api.InterpolationAxis.All, api.InterpolationAxis.X, api.InterpolationAxis.Y, or api.InterpolationAxis.Z. |
binarize
Binarizes masks, effectively removing any partially masked voxel values.
Signature:
binarize(maskNames: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskNames | list | List of mask names to binarize. |
partial_volume_calculation
Recalculates partial volume fractions at mask boundaries. Minimizes the influence of mixed background voxels by recalculating partial volumes. If a valid volume name is provided, volume grayvalues are used; otherwise artificial grayvalues are generated.
Signature:
partial_volume_calculation(volumeName: str, maskNames: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
volumeName | str | Name of the volume object to use for grayvalues (empty string to generate artificial values). |
maskNames | list | Names of the mask objects to process. |
invert_masks
Inverts masks, effectively flipping masked and unmasked regions.
Signature:
invert_masks(maskNames: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskNames | list | List of mask names to invert. |
fill_holes
Fills holes and cavities by iteratively applying a voting operation. This operation only supports binary masks (not multi-label masks).
Signature:
fill_holes(maskNames: list, numberOfIterations: int = 2, neighborhoodRadius: int = 1, majorityThreshold: int = 1) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskNames | list | Names of the mask objects to process. |
numberOfIterations | int | Maximum number of iterations to perform. |
neighborhoodRadius | int | Radius of the neighborhood (in pixels) used to compute the median. |
majorityThreshold | int | Number of pixels over 50% that decides whether an OFF pixel becomes ON. |
flip
Flips masks along the selected axes. Flips the specified masks along every selected axis at once. Can flip about the object's origin or center. Raises an error when no axis is selected.
Signature:
flip(maskNames: list, flipX: bool, flipY: bool, flipZ: bool, aboutOrigin: bool = False) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskNames | list | Names of the masks to flip. |
flipX | bool | If True, mirror along the X axis. |
flipY | bool | If True, mirror along the Y axis. |
flipZ | bool | If True, mirror along the Z axis. |
aboutOrigin | bool | If True, flip about origin; otherwise flip about center. |
mirror_to_plane
Mirrors (reflects) masks across a specified plane. Uses a Householder reflection matrix with nearest-neighbor interpolation to preserve label values. Each mask voxel at position P is reflected as P' = P - 2 * dot(P - O, N) * N, where O is the plane origin and N is the unit normal vector.
Signature:
mirror_to_plane(maskNames: list, planeOrigin: list, planeNormal: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskNames | list | Names of the masks to mirror. |
planeOrigin | list | Plane origin point [x, y, z]. |
planeNormal | list | Plane normal vector [x, y, z]. |
convert_to_volume_objects
Converts masks to volume objects.
Signature:
convert_to_volume_objects(maskNames: list) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskNames | list | Names of the masks to convert. |
Returns: list — A list of names for the created volume objects on success; otherwise, returns an empty list.
convert_3d_preview_to_surface_objects
Converts the 3D preview of visible masks to surface objects.
Signature:
convert_3d_preview_to_surface_objects() -> list
Returns: list — A list of names for the created surface objects on success; otherwise, returns an empty list.
convert_to_surface_objects
Converts masks to surface objects using explicit mask preview parameters. This method first generates mask preview using the provided parameters and then converts the preview to surfaces.
Signature:
convert_to_surface_objects(maskNames: list, params: MaskToSurfaceParams = MaskToSurfaceParams()) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskNames | list | Names of the masks to convert. |
params | MaskToSurfaceParams | Parameters used for generating mask preview and conversion. Create using api.MaskToSurfaceParams(). |
Returns: list — A list of names for the created surface objects on success; otherwise, returns an empty list.
convert_to_volume_mesh_objects
Converts masks to volume mesh objects using the Grid3D meshing method.
Signature:
convert_to_volume_mesh_objects(maskNames: list, samplingRate: float = 1.0, featureScaling: float = 1.0, rateOfChangeOfElementSize: float = 0.2, sigma: float = 0, outputMeshElementTypeToQuadratic10Node: bool = False) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskNames | list | Names of the masks to convert. |
samplingRate | float | Smaller sampling creates coarser meshes and runs faster. |
featureScaling | float | Scales features of the mesh affecting element size. Higher values create coarser meshes. |
rateOfChangeOfElementSize | float | Maximum rate of change of element size throughout the mesh. |
sigma | float | Gaussian smoothing sigma. |
outputMeshElementTypeToQuadratic10Node | bool | If True, create quadratic 10-node elements; if False, tetra 4-node. |
Returns: list — A list of names for the created volume mesh objects on success; otherwise, returns an empty list.
Modification
grow_cut_segmentation
Performs GrowCut segmentation using seed masks. Segments regions based on competition between seed mask labels.
Signature:
grow_cut_segmentation(volumeName: str, params: GrowCutSegmentationParams) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
volumeName | str | Name of the volume to segment. |
params | GrowCutSegmentationParams | GrowCut parameters. Create using api.GrowCutSegmentationParams(). |
Returns: str — Name of the created or updated mask.
smooth_discrete_gaussian_filter
Applies discrete Gaussian smoothing to masks.
Signature:
smooth_discrete_gaussian_filter(maskNames: list, sigmaX: float = 1.0, sigmaY: float = 1.0, sigmaZ: float = 1.0) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskNames | list | List of mask names to smooth. |
sigmaX | float | The standard deviation of the Gaussian in the X direction in pixels. |
sigmaY | float | The standard deviation of the Gaussian in the Y direction in pixels. |
sigmaZ | float | The standard deviation of the Gaussian in the Z direction in pixels. |
smooth_recursive_gaussian_filter
Applies recursive Gaussian smoothing to masks.
Signature:
smooth_recursive_gaussian_filter(maskNames: list, sigmaX: float = 1.0, sigmaY: float = 1.0, sigmaZ: float = 1.0) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskNames | list | List of mask names to smooth. |
sigmaX | float | The standard deviation of the Gaussian in the X direction in pixels. |
sigmaY | float | The standard deviation of the Gaussian in the Y direction in pixels. |
sigmaZ | float | The standard deviation of the Gaussian in the Z direction in pixels. |
smooth_mean_filter
Applies mean smoothing to masks.
Signature:
smooth_mean_filter(maskNames: list, radiusX: int = 1, radiusY: int = 1, radiusZ: int = 1) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskNames | list | List of mask names to smooth. |
radiusX | int | Radius of neighborhood in X direction in pixels. |
radiusY | int | Radius of neighborhood in Y direction in pixels. |
radiusZ | int | Radius of neighborhood in Z direction in pixels. |
smooth_median_filter
Applies median smoothing to masks.
Signature:
smooth_median_filter(maskNames: list, radiusX: int = 1, radiusY: int = 1, radiusZ: int = 1) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskNames | list | List of mask names to smooth. |
radiusX | int | Radius of neighborhood in X direction in pixels. |
radiusY | int | Radius of neighborhood in Y direction in pixels. |
radiusZ | int | Radius of neighborhood in Z direction in pixels. |
hollow_masks
Create a hollow effect by replacing the mask with a shell of uniform thickness at the mask boundary. Replaces masks with uniformly thick shells at boundaries.
Signature:
hollow_masks(maskNames: list, shellMode: HollowShellMode = api.HollowShellMode.InsideSurface, shellThicknessMM: float = 2.0) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
maskNames | list | List of mask names to process. |
shellMode | HollowShellMode | Mode defining shell position. Use api.HollowShellMode.InsideSurface, api.HollowShellMode.MedialSurface, or api.HollowShellMode.OutsideSurface. |
shellThicknessMM | float | Thickness of the hollow shell in millimeters. |