MeasurementOperations
Provides tools for creating, editing, and analyzing 3D measurement objects. Supports point, distance, angle, diameter, contour, circle, ellipse, rectangle, box, and caption measurements. Enables import/export, geometric transformation, and measurement retrieval.
Import
import ScriptingApi as api
# Access via Application
app = api.Application()
ops = app.get_measurement_operations()
Methods
Analysis
get_measurement_names_by_type
Gets the names of measurement objects of a specific type.
Signature:
get_measurement_names_by_type(type: MeasurementType) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
type | any | The type of measurement objects to retrieve. Use api.MeasurementType.Point, api.MeasurementType.Distance, api.MeasurementType.Angle, etc. |
Returns: list — A list of measurement object names matching the specified type.
get_measurement_type
Gets the type of a measurement object.
Signature:
get_measurement_type(measurementName: str) -> MeasurementType
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | any | The name of the measurement object. |
Returns: MeasurementType — The type of the measurement object as api.MeasurementType
get_measurement_data
Gets the measurement data of a measurement object.
Signature:
get_measurement_data(measurementName: str) -> MeasurementData
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | any | The name of the measurement object. |
Returns: MeasurementData — The measurement data structure as MeasurementData.
get_measurement_value_string
Gets the computed measurement value as a formatted string.
Signature:
get_measurement_value_string(measurementName: str) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | any | The name of the measurement object. |
Returns: str — The formatted measurement string (e.g., "12.5 mm" for distance).
get_point_measurement
Gets point measurement details.
Signature:
get_point_measurement(measurementName: str) -> PointMeasurement
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | any | The name of the point measurement object. |
Returns: PointMeasurement — The point measurement data as PointMeasurement.
get_distance_measurement
Gets distance measurement details.
Signature:
get_distance_measurement(measurementName: str) -> DistanceMeasurement
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | any | The name of the distance measurement object. |
Returns: DistanceMeasurement — The distance measurement data as DistanceMeasurement.
get_angle_measurement
Gets angle measurement details.
Signature:
get_angle_measurement(measurementName: str) -> AngleMeasurement
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | any | The name of the angle measurement object. |
Returns: AngleMeasurement — The angle measurement data as AngleMeasurement.
get_diameter_measurement
Gets diameter measurement details.
Signature:
get_diameter_measurement(measurementName: str) -> DiameterMeasurement
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | any | The name of the diameter measurement object. |
Returns: DiameterMeasurement — The diameter measurement data as DiameterMeasurement.
get_contour_measurement
Gets contour measurement details.
Signature:
get_contour_measurement(measurementName: str) -> ContourMeasurement
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | any | The name of the contour measurement object. |
Returns: ContourMeasurement — The contour measurement data as ContourMeasurement.
get_circle_measurement
Gets circle measurement details.
Signature:
get_circle_measurement(measurementName: str) -> CircleMeasurement
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | any | The name of the circle measurement object. |
Returns: CircleMeasurement — The circle measurement data as CircleMeasurement.
get_ellipse_measurement
Gets ellipse measurement details.
Signature:
get_ellipse_measurement(measurementName: str) -> EllipseMeasurement
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | any | The name of the ellipse measurement object. |
Returns: EllipseMeasurement — The ellipse measurement data as EllipseMeasurement.
get_rectangle_measurement
Gets rectangle measurement details.
Signature:
get_rectangle_measurement(measurementName: str) -> RectangleMeasurement
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | any | The name of the rectangle measurement object. |
Returns: RectangleMeasurement — The rectangle measurement data as RectangleMeasurement.
get_box_measurement
Gets box measurement details.
Signature:
get_box_measurement(measurementName: str) -> BoxMeasurement
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | any | The name of the box measurement object. |
Returns: BoxMeasurement — The box measurement data as BoxMeasurement.
get_annotation_measurement
Gets annotation measurement details.
Signature:
get_annotation_measurement(measurementName: str) -> AnnotationMeasurement
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | any | The name of the annotation measurement object. |
Returns: AnnotationMeasurement — The annotation measurement data as AnnotationMeasurement.
Creation
create_point
Creates a point measurement at the specified position.
Signature:
create_point(position: list, name: str = "") -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
position | any | The 3D position [x, y, z] of the point. |
name | any | Optional name for the measurement (auto-generated if empty). |
Returns: str — The name of the created measurement object.
create_distance
Creates a distance measurement between two points.
Signature:
create_distance(point1: list, point2: list, name: str = "") -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
point1 | any | The 3D position [x, y, z] of the first point. |
point2 | any | The 3D position [x, y, z] of the second point. |
name | any | Optional name for the measurement (auto-generated if empty). |
Returns: str — The name of the created measurement object.
create_angle
Creates an angle measurement defined by three points.
Signature:
create_angle(point1: list, vertex: list, point3: list, name: str = "") -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
point1 | any | The 3D position [x, y, z] of the first point. |
vertex | any | The 3D position [x, y, z] of the vertex point. |
point3 | any | The 3D position [x, y, z] of the third point. |
name | any | Optional name for the measurement (auto-generated if empty). |
Returns: str — The name of the created measurement object.
create_contour
Creates a contour measurement from a list of points.
Signature:
create_contour(points: list, closedLoop: bool = True, name: str = "") -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
points | any | List of 3D points [x, y, z] defining the contour. |
closedLoop | any | If true, creates a closed contour (default: true). |
name | any | Optional name for the measurement (auto-generated if empty). |
Returns: str — The name of the created measurement object.
create_diameter
Creates a diameter measurement defined by three points.
Signature:
create_diameter(point1: list, point2: list, point3: list, name: str = "") -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
point1 | any | The 3D position [x, y, z] of the first point. |
point2 | any | The 3D position [x, y, z] of the second point. |
point3 | any | The 3D position [x, y, z] of the third point. |
name | any | Optional name for the measurement (auto-generated if empty). |
Returns: str — The name of the created measurement object.
create_circle
Creates a circle measurement given the center and a boundary point.
Signature:
create_circle(center: list, pointOnCircumference: list, name: str = "") -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
center | any | The 3D center position [x, y, z] of the circle. |
pointOnCircumference | any | A 3D point [x, y, z] on the circumference to define the radius. |
name | any | Optional name for the measurement (auto-generated if empty). |
Returns: str — The name of the created measurement object.
create_ellipse
Creates an ellipse measurement given center and two axis-defining points.
Signature:
create_ellipse(center: list, axisPoint1: list, axisPoint2: list, name: str = "") -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
center | any | The 3D center [x, y, z] of the ellipse. |
axisPoint1 | any | A point [x, y, z] defining the major axis direction and magnitude. |
axisPoint2 | any | A point [x, y, z] defining the minor axis direction and magnitude. |
name | any | Optional name for the measurement (auto-generated if empty). |
Returns: str — The name of the created measurement object.
create_rectangle
Creates a rectangle measurement defined by its center and two points that help define the rectangle extents.
Signature:
create_rectangle(center: list, point2: list, point3: list, name: str = "") -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
center | any | The 3D center [x, y, z] of the rectangle. |
point2 | any | Second reference point [x, y, z] describing the rectangle orientation/extent. |
point3 | any | Third reference point [x, y, z] describing the rectangle orientation/extent. |
name | any | Optional name for the measurement (auto-generated if empty). |
Returns: str — The name of the created measurement object.
create_box
Creates a 3D box measurement defined by its center position.
Signature:
create_box(center: list, name: str = "") -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
center | any | The 3D center position [x, y, z] of the box. |
name | any | Optional name for the measurement (auto-generated if empty). |
Returns: str — The name of the created measurement object.
create_annotation
Creates a caption (text annotation) at the specified position.
Signature:
create_annotation(position: list, text: str, name: str = "") -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
position | any | The 3D position [x, y, z] of the caption anchor point. |
text | any | The text content of the caption. |
name | any | Optional name for the measurement (auto-generated if empty). |
Returns: str — The name of the created measurement object.
File System
import_measurements_settings_from_disk
Imports measurements from a file.
Signature:
import_measurements_settings_from_disk(fileName: str, deleteExisting: bool = True) -> bool
Parameters:
| Parameter | Type | Description |
|---|---|---|
fileName | any | The full path of the file to import. |
deleteExisting | any | If true, deletes existing measurements before importing (default: True). |
Returns: bool — True if the import was successful; false otherwise.
export_measurements_settings_to_disk
Exports all measurements settings to a file.
Signature:
export_measurements_settings_to_disk(fileName: str) -> bool
Parameters:
| Parameter | Type | Description |
|---|---|---|
fileName | any | The full path of the file to export to. |
Returns: bool — True if the export was successful; false otherwise.
export_measurements_to_disk
Exports specific measurements to a file.
Signature:
export_measurements_to_disk(measurementNames: list, fileName: str) -> bool
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementNames | any | List of measurement object names to export. |
fileName | any | The full path of the file to export to. |
Returns: bool — True if the export was successful; false otherwise.
Properties
set_lock
Sets the lock status of measurement objects. Locked measurements cannot be moved interactively.
Signature:
set_lock(measurementNames: list, locked: bool) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementNames | any | List of measurement object names. |
locked | any | True to lock, false to unlock. |
set_active
Activates a measurement object for editing.
Signature:
set_active(measurementName: str) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | any | The name of the measurement object to activate. |
set_color
Sets the color of measurement objects.
Signature:
set_color(measurementNames: list, color: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementNames | any | List of measurement object names. |
color | any | RGB color values [r, g, b], each in range [0.0, 1.0]. |
set_opacity
Sets the opacity of measurement objects.
Signature:
set_opacity(measurementNames: list, opacity: float) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementNames | any | List of measurement object names. |
opacity | any | Opacity value in range [0.0, 1.0]. |
set_line_width
Sets the line width of measurement objects.
Signature:
set_line_width(measurementNames: list, lineWidth: float) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementNames | any | List of measurement object names. |
lineWidth | any | Line width value. |
set_end_point_color
Sets the end point (handle) color of measurement objects.
Signature:
set_end_point_color(measurementNames: list, color: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementNames | any | List of measurement object names. |
color | any | RGB color values [r, g, b], each in range [0.0, 1.0]. |
set_end_point_size_factor
Sets the end point (handle) size factor of measurement objects.
Signature:
set_end_point_size_factor(measurementNames: list, sizeFactor: float) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementNames | any | List of measurement object names. |
sizeFactor | any | Size factor value. |
set_annotation_visibility
Sets the annotation visibility of measurement objects.
Signature:
set_annotation_visibility(measurementNames: list, visible: bool) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementNames | any | List of measurement object names. |
visible | any | True to show annotations, false to hide. |
set_annotation_type
Sets the annotation type of measurement objects.
Signature:
set_annotation_type(measurementNames: list, type: MeasurementAnnotationType) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementNames | any | List of measurement object names. |
type | any | The annotation display type. Use api.MeasurementAnnotationType.Text, etc. |
set_annotation_background_color
Sets the annotation background frame color.
Signature:
set_annotation_background_color(measurementNames: list, color: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementNames | any | List of measurement object names. |
color | any | RGB color values [r, g, b], each in range [0.0, 1.0]. |
set_annotation_background_opacity
Sets the annotation background frame opacity.
Signature:
set_annotation_background_opacity(measurementNames: list, opacity: float) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementNames | any | List of measurement object names. |
opacity | any | Opacity value in range [0.0, 1.0]. |
set_annotation_visibility_on_active_only
Sets annotation visibility on the active measurement only. All other measurements will have their annotations hidden.
Signature:
set_annotation_visibility_on_active_only() -> None
set_3d_axes_visibility
Sets the 3D axes visibility of measurement objects.
Signature:
set_3d_axes_visibility(measurementNames: list, visible: bool) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementNames | any | List of measurement object names. |
visible | any | True to show 3D axes, false to hide. |
set_3d_axes_visibility_on_active_only
Sets 3D axes visibility on the active measurement only. All other measurements will have their 3D axes hidden.
Signature:
set_3d_axes_visibility_on_active_only() -> None
set_2d_cross_visibility
Sets the 2D cross visibility of measurement objects in slice views.
Signature:
set_2d_cross_visibility(measurementNames: list, visible: bool) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementNames | any | List of measurement object names. |
visible | any | True to show 2D cross, false to hide. |
set_handle_visibility
Sets the point handle visibility of measurement objects.
Signature:
set_handle_visibility(measurementNames: list, visible: bool) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementNames | any | List of measurement object names. |
visible | any | True to show handles, false to hide. |
set_slice_views_visibility
Sets the slice views annotation visibility of measurement objects. Controls visibility of measurement annotations in 2D slice views (axial, coronal, sagittal).
Signature:
set_slice_views_visibility(measurementNames: list, visible: bool) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementNames | any | List of measurement object names. |
visible | any | True to show in slice views, false to hide. |
set_points
Sets the point coordinates of a measurement object.
Signature:
set_points(measurementName: str, points: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | any | The name of the measurement object. |
points | any | List of 3D points [x, y, z]. |
get_points
Gets the point coordinates of a measurement object.
Signature:
get_points(measurementName: str) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | any | The name of the measurement object. |
Returns: list — List of 3D points [x, y, z].
UI
set_always_show
Enables or disables the "always show" mode for measurements. When enabled, measurements remain visible even when the markup tool is not active.
Signature:
set_always_show(enable: bool) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
enable | any | True to enable always show mode, false to disable. |
is_always_show_enabled
Gets the current state of the "always show" mode.
Signature:
is_always_show_enabled() -> bool
Returns: bool — True if always show mode is enabled; false otherwise.
hide_based_on_always_show_flag
Hides or shows visible measurements based on the always show flag. If always show is enabled, this function does nothing. Otherwise, it hides measurements when hide=true without changing their visibility flags, or restores visibility when hide=false.
Signature:
hide_based_on_always_show_flag(hide: bool) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
hide | any | True to hide measurements, false to restore visibility. |
Modification
transform
Applies a transformation matrix to measurement objects.
Signature:
transform(measurementNames: list, matrix: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementNames | any | List of measurement object names. |
matrix | any | 4x4 transformation matrix (16 elements in row-major order). |
General
snap_to_surface
Snaps measurement points to the nearest surface.
Signature:
snap_to_surface(measurementNames: list, surfaceName: str) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementNames | any | List of measurement object names. |
surfaceName | any | The name of the surface object to snap to. |
snap_to_mask
Snaps measurement points to the nearest mask surface.
Signature:
snap_to_mask(measurementNames: list, maskName: str) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementNames | any | List of measurement object names. |
maskName | any | The name of the mask object to snap to. |