Mask3D¶

class Mask3D(data, sly_id=None, class_id=None, labeler_login=None, updated_at=None, created_at=None, volume_header=None, convert_to_ras=True)[source]¶

Bases: Geometry

3D volumetric mask (voxel data). Immutable.

Mask 3D geometry for a single Label. Mask3D object is immutable.

Parameters:

data : np.ndarray¶: Mask 3D mask data. Must be a numpy array with only 2 unique values: [0, 1] or [0, 255] or [False, True].
sly_id : int, optional¶: Mask 3D ID in Supervisely server.
class_id : int, optional¶: ID of ObjClass to which Mask 3D belongs.
labeler_login : str, optional¶: Login of the user who created Mask 3D.
updated_at : str, optional¶: Date and Time when Mask 3D was modified last. Date Format: Year:Month:Day:Hour:Minute:Seconds. Example: ‘2021-01-22T19:37:50.158Z’.
created_at : str, optional¶: Date and Time when Mask 3D was created. Date Format is the same as in “updated_at” parameter.
volume_header : dict, optional¶: NRRD header dictionary. Optional.
convert_to_ras : bool, optional¶: If True, converts the mask to RAS orientation. Default is True.

Raises:

ValueError – if data is not bool or no pixels set to True in data

Usage Example:

import supervisely as sly

# Create simple Mask 3D
mask3d = np.zeros((3, 3, 3), dtype=np.bool_)
mask3d[0:2, 0:2, 0:2] = True

shape = sly.Mask3D(mask3d)

print(shape.data)
# Output:
#    [[[ True  True False]
#      [ True  True False]
#      [False False False]]

#     [[ True  True False]
#      [ True  True False]
#      [False False False]]

#     [[False False False]
#      [False False False]
#      [False False False]]]

Methods

`add_mask_2d`	Draw a 2D mask on a 3D Mask.
`allowed_transforms`	Returns the allowed transforms for the Geometry.
`base64_2_data`	Convert base64 encoded string to numpy array.
`clone`	Clone from GEOMETRYYY
`config_from_json`	Convert geometry config from json format
`config_to_json`	Convert geometry config to json format
`convert`	Convert geometry to another geometry shape.
`create_from_file`	Creates Mask3D geometry from file.
`create_header`	Create header for encoding Mask3D to NRRD bytes
`crop`	Crop the geometry with given rectangle.
`data_2_base64`	Convert numpy array to base64 encoded string.
`draw`
`draw_contour`	Draws the figure contour on a given bitmap canvas :param bitmap: np.ndarray :param color: [R, G, B] :param thickness: (int) :param config: drawing config specific to a concrete subclass, e.g. per edge colors.
`fliplr`
`flipud`
`from_bytes`	Create a Mask3D geometry object from bytes.
`from_file`	Load figure geometry from file.
`from_json`	Convert a json dict to Mask 3D.
`geometry_name`	Return geometry name
`get_mask`	Returns 2D boolean mask of the geometry.
`name`	Get the name of the geometry.
`orient_ras`	Transforms the mask data and updates spatial metadata (origin, directions, spacing) to align with the RAS coordinate system using SimpleITK.
`relative_crop`	Crops object like "crop" method, but return results with coordinates relative to rect :param rect: Rectangle for crop.
`resize`
`rotate`	Rotates around image center -> New Geometry :param rotator: Class for image rotation.
`scale`	Scales around origin with a given factor.
`set_volume_space_meta`	Set space, space directions, and space origin attributes from a NRRD header dictionary.
`to_bbox`
`to_json`	Convert the Mask 3D to a json dict.
`translate`
`validate`	Validate geometry.

Attributes

`area`
`space`	Get the space of the Mask3D.
`space_directions`	Get the space directions of the Mask3D.
`space_origin`	Get the space origin of the Mask3D as a list of floats.

classmethod allowed_transforms()¶: Returns the allowed transforms for the Geometry.

classmethod create_from_file(file_path)[source]¶

Creates Mask3D geometry from file.

Parameters:

file_path : str¶: Path to nrrd file with data

classmethod from_bytes(geometry_bytes)[source]¶

Create a Mask3D geometry object from bytes.

Parameters:

geometry_bytes : bytes¶: NRRD file represented as bytes.

Returns:

A Mask3D geometry object.

Return type:

Mask3D

classmethod from_json(json_data)[source]¶

Convert a json dict to Mask 3D.

Parameters:

json_data : Dict¶: Mask in json format as a dict.

Returns:

Mask3D from json.

Return type:

Mask3D

Usage Example:

import supervisely as sly

figure_json = {
    "mask_3d": {
        "data": "eJzrDPBz5+WS4mJgYOD19HAJAtLMIMwIInOeqf8BUmwBPiGuQPr///9Lb86/C2QxlgT5BTM4PLuRBuTwebo4hlTMSa44sKHhISMDuxpTYrr03F6gDIOnq5/LOqeEJgDM5ht6",
    },
    "shape": "mask_3d",
    "geometryType": "mask_3d"
}
figure = sly.Mask3D.from_json(figure_json)

classmethod name()¶

Get the name of the geometry.

Same as geometry_name(), but shorter. In order to make the code more concise.

Returns:: string with name of geometry

static base64_2_data(encoded_string)[source]¶

Convert base64 encoded string to numpy array.

Parameters:

encoded_string : str¶: Input base64 encoded string.

Returns:

Bool numpy array

Return type:

np.ndarray

Usage Example:

import supervisely as sly

encoded_string = 'H4sIAGWoWmQC/zPWMdYxrmFkZAAiIIAz4AAAE56ciyEAAAA='
figure_data = sly.Mask3D.base64_2_data(encoded_string)
print(figure_data)
# [[[1 1 0]
#   [1 1 0]
#   [0 0 0]]
#  [[1 1 0]
#   [1 1 0]
#   [0 0 0]]
#  [[0 0 0]
#   [0 0 0]
#   [0 0 0]]]

static config_from_json(config)¶

Convert geometry config from json format

Parameters:

config : dict¶: dictionary(geometry config) in json format

Returns:

dictionary(geometry config) in json format

Return type:

dict

static config_to_json(config)¶

Convert geometry config to json format

Parameters:

config : dict¶: dictionary(geometry config)

Returns:

dictionary(geometry config) in json format

Return type:

dict

static data_2_base64(data)[source]¶

Convert numpy array to base64 encoded string.

Parameters:

data : np.ndarray¶: Bool numpy array.

Returns:

Base64 encoded string

Return type:

str

Usage Example:

import os
from dotenv import load_dotenv

import nrrd
import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

meta_json = api.project.get_meta(PROJECT_ID)
meta = sly.ProjectMeta.from_json(meta_json)

ann_json = api.volume.annotation.download_bulk(DATASET_ID, [VOLUME_ID])

figure_id = ann_json[0]["spatialFigures"][0]["id"]
path_for_mesh = f"meshes/{figure_id}.nrrd"
api.volume.figure.download_stl_meshes([figure_id], [path_for_mesh])

mask3d_data, _ = sly.volume.volume.read_nrrd_serie_volume_np(path_for_mesh)
encoded_string = sly.Mask3D.data_2_base64(mask3d_data)

print(encoded_string)
# 'H4sIAGWoWmQC/zPWMdYxrmFkZAAiIIAz4AAAE56ciyEAAAA='

static from_file(figure, file_path)[source]¶

Load figure geometry from file.

Parameters:

figure¶: Spatial figure
file_path : str¶: Path to nrrd file with data

static geometry_name()[source]¶: Return geometry name

add_mask_2d(mask_2d, plane_name, slice_index, origin=None)[source]¶

Draw a 2D mask on a 3D Mask.

Parameters:

mask_2d : np.ndarray¶: 2D array with a flat mask.
plane_name : str¶: Name of the plane: “axial”, “sagittal”, “coronal”.
slice_index : int¶: Slice index of the volume figure.
origin : Optional[List[int]], NoneType¶: (row, col) position. The top-left corner of the mask is located on the specified slice (optional).

clone()¶: Clone from GEOMETRYYY

convert(new_geometry, contour_radius=0, approx_epsilon=None)¶

Convert geometry to another geometry shape.

Parameters:

new_geometry¶: New geometry shape.
contour_radius : int¶: Radius of the contour.
approx_epsilon : float¶: Approximation epsilon.

Returns:

List of geometries.

Return type:

List[Geometry]

create_header()[source]¶

Create header for encoding Mask3D to NRRD bytes

Returns:: Header for NRRD file
Return type:: OrderedDict

crop(rect)¶

Crop the geometry with given rectangle.

Parameters:

rect¶: Rectangle for crop.

Returns:

List of Geometry after crop.

Return type:

List[Geometry]`

draw(bitmap, color, thickness=1, config=None)¶

Parameters:

bitmap¶: np.ndarray
color¶: Color [R, G, B]
thickness=1¶: used only in Polyline and Point
config : dict¶: Drawing config specific to a concrete subclass, e.g. per edge colors

Raises:

NotImplementedError – if method is not implemented in subclass

draw_contour(bitmap, color, thickness=1, config=None)¶: Draws the figure contour on a given bitmap canvas :param bitmap: np.ndarray :param color: [R, G, B] :param thickness: (int) :param config: drawing config specific to a concrete subclass, e.g. per edge colors

fliplr(img_size)¶

Parameters:

img_size : Tuple[int, int]¶: Image size (height, width) to which belongs Geometry.

Returns:

Geometry after flip in horizontal.

Return type:

Geometry

Raises:

NotImplementedError – if method is not implemented in subclass

flipud(img_size)¶

Parameters:

img_size : Tuple[int, int]¶: Image size (height, width) to which belongs Geometry.

Returns:

Geometry after flip in vertical.

Return type:

Geometry

Raises:

NotImplementedError – if method is not implemented in subclass

get_mask(img_size)¶

Returns 2D boolean mask of the geometry. With shape as img_size (height, width) and filled with True values inside the geometry and False values outside. dtype = np.bool shape = img_size

Parameters:

img_size : Tuple[int, int]¶: size of the image (height, width)

Returns:

2D boolean mask of the geometry

Return type:

np.ndarray

orient_ras()[source]¶

Transforms the mask data and updates spatial metadata (origin, directions, spacing) to align with the RAS coordinate system using SimpleITK.

Return type:: None

relative_crop(rect)¶: Crops object like “crop” method, but return results with coordinates relative to rect :param rect: Rectangle for crop. :type rect: Rectangle :returns: List of Geometry after relative crop. :rtype: List[Geometry]` :raises NotImplementedError: if method is not implemented in subclass

resize(in_size, out_size)¶

Parameters:

in_size : Tuple[int, int]¶: Input image size (height, width).
out_size : Tuple[int, int]¶: Desired output image size (height, width) of the Annotation to which Label belongs.

Returns:

Geometry after resize.

Return type:

Geometry

Raises:

NotImplementedError – if method is not implemented in subclass

rotate(rotator)¶: Rotates around image center -> New Geometry :param rotator: Class for image rotation. :type rotator: ImageRotator :returns: Geometry after rotation. :rtype: Geometry

scale(factor)¶: Scales around origin with a given factor. :param: factor: Scale factor. :type factor: float :returns: Geometry :rtype: Geometry :raises NotImplementedError: if method is not implemented in subclass

set_volume_space_meta(header)[source]¶

Set space, space directions, and space origin attributes from a NRRD header dictionary.

Parameters:

header : dict¶: NRRD header dictionary.

to_bbox()¶

Returns:: Rectangle from geometry.
Return type:: Rectangle
Raises:: NotImplementedError – if method is not implemented in subclass

to_json()[source]¶

Convert the Mask 3D to a json dict.

Returns:

Json format as a dict

Return type:

Dict

Usage Example:

import supervisely as sly

mask = np.array([[[1 1 0]
                [1 1 0]
                [0 0 0]]
                [[1 1 0]
                [1 1 0]
                [0 0 0]]
                [[0 0 0]
                [0 0 0]
                [0 0 0]]],
                dtype=np.bool_
)

figure = sly.Mask3D(mask)
figure_json = figure.to_json()
json.dumps(figure_json, indent=4)
# Output: {
#    "mask_3d": {
#        "data": "eJzrDPBz5+WS4mJgYOD19HAJAtLMIMwIInOeqf8BUmwBPiGuQPr///9Lb86/C2QxlgT5BTM4PLuRBuTwebo4hlTMSa44sKHhISMDuxpTYrr03F6gDIOnq5/LOqeEJgDM5ht6",
#    },
#    "shape": "mask_3d",
#    "geometryType": "mask_3d"
# }

translate(drow, dcol)¶

Parameters:

drow : int¶: Vertical shift.
dcol : int¶: Horizontal shift.

Returns:

Geometry after translate.

Return type:

Geometry

Raises:

NotImplementedError – if method is not implemented in subclass

validate(obj_class_shape, settings)¶

Validate geometry.

Parameters:

obj_class_shape : str¶: Object class shape.
settings : dict¶: Settings.

Raises:

ValueError – if geometry validation error

property area¶

Returns:: float

property space : str | None¶

Get the space of the Mask3D.

Returns:: Space of the Mask3D.
Return type:: str

property space_directions : list[list[float]] | None¶

Get the space directions of the Mask3D.

Returns:: Space directions of the Mask3D.
Return type:: List[List[float]]

property space_origin : list[float] | None¶

Get the space origin of the Mask3D as a list of floats.

Returns:: Space origin of the Mask3D.
Return type:: List[float] or None