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 | MeasurementType | 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 | str | The name of the measurement object. |
Returns: MeasurementType — The type of the measurement object as api.MeasurementType. Raises an error if the measurement is not found.
set_annotation_measurement_text
Sets the annotation text of a measurement object.
Signature:
set_annotation_measurement_text(measurementName: str, text: str) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | str | The name of the measurement object. |
text | str | The annotation text to set for the measurement. If the text is empty, the image information at the anchor point will be displayed instead. |
get_annotation_measurement_text
Gets the current annotation text of a measurement object.
Signature:
get_annotation_measurement_text(measurementName: str) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | str | The name of the measurement object. |
Returns: str — The current annotation text of the measurement object.
set_measurement_properties
Applies user-configurable measurement appearance and type-specific editing properties. Fields that do not apply to the target measurement type are ignored. For example, annotationText and displayImageInfoAtAnchorPoint only apply to annotation measurements, while contour editing fields only apply to contour measurements.
Signature:
set_measurement_properties(measurementName: str, properties: MeasurementProperties) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | str | The name of the measurement object. |
properties | MeasurementProperties | The properties to apply. Create using api.MeasurementProperties(). |
get_measurement_properties
Gets the current user-configurable measurement appearance and type-specific editing properties. Only the fields that apply to the target measurement type are set; other type-specific fields remain at their default values.
Signature:
get_measurement_properties(measurementName: str) -> MeasurementProperties
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | str | The name of the measurement object. |
Returns: MeasurementProperties — The current measurement properties as api.MeasurementProperties.
get_measurement_data
Gets the measurement data of a measurement object.
Signature:
get_measurement_data(measurementName: str) -> MeasurementData
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | str | The name of the measurement object. |
Returns: MeasurementData — The measurement data structure as api.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 | str | 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 | str | The name of the point measurement object. |
Returns: PointMeasurement — The point measurement data as api.PointMeasurement.
get_distance_measurement
Gets distance measurement details.
Signature:
get_distance_measurement(measurementName: str) -> DistanceMeasurement
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | str | The name of the distance measurement object. |
Returns: DistanceMeasurement — The distance measurement data as api.DistanceMeasurement.
get_angle_measurement
Gets angle measurement details.
Signature:
get_angle_measurement(measurementName: str) -> AngleMeasurement
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | str | The name of the angle measurement object. |
Returns: AngleMeasurement — The angle measurement data as api.AngleMeasurement.
get_diameter_measurement
Gets diameter measurement details.
Signature:
get_diameter_measurement(measurementName: str) -> DiameterMeasurement
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | str | The name of the diameter measurement object. |
Returns: DiameterMeasurement — The diameter measurement data as api.DiameterMeasurement.
get_contour_measurement
Gets contour measurement details.
Signature:
get_contour_measurement(measurementName: str) -> ContourMeasurement
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | str | The name of the contour measurement object. |
Returns: ContourMeasurement — The contour measurement data as api.ContourMeasurement.
get_circle_measurement
Gets circle measurement details.
Signature:
get_circle_measurement(measurementName: str) -> CircleMeasurement
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | str | The name of the circle measurement object. |
Returns: CircleMeasurement — The circle measurement data as api.CircleMeasurement.
get_ellipse_measurement
Gets ellipse measurement details.
Signature:
get_ellipse_measurement(measurementName: str) -> EllipseMeasurement
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | str | The name of the ellipse measurement object. |
Returns: EllipseMeasurement — The ellipse measurement data as api.EllipseMeasurement.
get_rectangle_measurement
Gets rectangle measurement details.
Signature:
get_rectangle_measurement(measurementName: str) -> RectangleMeasurement
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | str | The name of the rectangle measurement object. |
Returns: RectangleMeasurement — The rectangle measurement data as api.RectangleMeasurement.
get_box_measurement
Gets box measurement details.
Signature:
get_box_measurement(measurementName: str) -> BoxMeasurement
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | str | The name of the box measurement object. |
Returns: BoxMeasurement — The box measurement data as api.BoxMeasurement.
get_annotation_measurement
Gets annotation measurement details.
Signature:
get_annotation_measurement(measurementName: str) -> AnnotationMeasurement
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementName | str | The name of the annotation measurement object. |
Returns: AnnotationMeasurement — The annotation measurement data as api.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 | list | The 3D position [x, y, z] of the point. |
name | str | 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 | list | The 3D position [x, y, z] of the first point. |
point2 | list | The 3D position [x, y, z] of the second point. |
name | str | 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 | list | The 3D position [x, y, z] of the first point. |
vertex | list | The 3D position [x, y, z] of the vertex point. |
point3 | list | The 3D position [x, y, z] of the third point. |
name | str | 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 = "", slicePlane: SlicePlane = api.SlicePlane.XY) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
points | list | List of 3D points [x, y, z] defining the contour. At least 3 points are required. |
closedLoop | bool | If true, creates a closed contour (default: true). |
name | str | Optional name for the measurement (auto-generated if empty). |
slicePlane | SlicePlane | Slice plane a closed contour measures the image density on. Use api.SlicePlane.XY (default), api.SlicePlane.XZ, or api.SlicePlane.YZ. |
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 | list | The 3D position [x, y, z] of the first point. |
point2 | list | The 3D position [x, y, z] of the second point. |
point3 | list | The 3D position [x, y, z] of the third point. |
name | str | 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 | list | The 3D center position [x, y, z] of the circle. |
pointOnCircumference | list | A 3D point [x, y, z] on the circumference to define the radius. |
name | str | 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 | list | The 3D center [x, y, z] of the ellipse. |
axisPoint1 | list | A point [x, y, z] defining the major axis direction and magnitude. |
axisPoint2 | list | A point [x, y, z] defining the minor axis direction and magnitude. |
name | str | 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 | list | The 3D center [x, y, z] of the rectangle. |
point2 | list | Second reference point [x, y, z] describing the rectangle orientation/extent. |
point3 | list | Third reference point [x, y, z] describing the rectangle orientation/extent. |
name | str | 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 | list | The 3D center position [x, y, z] of the box. |
name | str | 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 = "", slicePlane: SlicePlane = api.SlicePlane.XY) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
position | list | The 3D position [x, y, z] of the caption anchor point. |
text | str | The text content of the caption. If empty, the caption displays the image information at its anchor point. |
name | str | Optional name for the measurement (auto-generated if empty). |
slicePlane | SlicePlane | Slice plane whose position the image information names. Use api.SlicePlane.XY (default), api.SlicePlane.XZ, or api.SlicePlane.YZ. |
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 | str | The full path of the file to import. |
deleteExisting | bool | 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 | str | 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 | list | List of measurement object names to export. |
fileName | str | The full path of the file to export to. |
Returns: bool — True if the export was successful; false otherwise.
export_measurements_of_type_to_disk
Exports every measurement of one type to a file as a single table for that type. This writes the same file the measurement table writes when one measurement type is chosen in its export dialog: a legend and one column header for the type, followed by one row per measurement.
Signature:
export_measurements_of_type_to_disk(measurementType: MeasurementType, fileName: str) -> bool
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementType | MeasurementType | The type of the measurements to export. Use api.MeasurementType.Point, api.MeasurementType.Distance, api.MeasurementType.Angle, api.MeasurementType.Diameter, api.MeasurementType.Contour, api.MeasurementType.Circle, api.MeasurementType.Ellipse, api.MeasurementType.Rectangle, api.MeasurementType.Box, or api.MeasurementType.Annotation. |
fileName | str | The full path of the file to export to. |
Returns: bool — True if the export was successful; false otherwise, including when no measurement of that type exists.
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 | list | List of measurement object names. |
locked | bool | 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 | str | 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 | list | List of measurement object names. |
color | list | 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 | list | List of measurement object names. |
opacity | float | 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 | list | List of measurement object names. |
lineWidth | float | Line width value. Must be greater than 0. |
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 | list | List of measurement object names. |
color | list | 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 | list | List of measurement object names. |
sizeFactor | float | Size factor value. Must be greater than 0. |
set_annotation_visibility
Sets the annotation visibility of measurement objects.
Signature:
set_annotation_visibility(measurementNames: list, visible: bool) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementNames | list | List of measurement object names. |
visible | bool | 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 | list | List of measurement object names. |
type | MeasurementAnnotationType | The annotation display type. Use api.MeasurementAnnotationType.Name, api.MeasurementAnnotationType.Value, api.MeasurementAnnotationType.NameAndValue, 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 | list | List of measurement object names. |
color | list | 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 | list | List of measurement object names. |
opacity | float | 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 | list | List of measurement object names. |
visible | bool | 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 | list | List of measurement object names. |
visible | bool | 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 | list | List of measurement object names. |
visible | bool | 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 (Plane 1/YZ, Plane 2/XZ, Plane 3/XY).
Signature:
set_slice_views_visibility(measurementNames: list, visible: bool) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
measurementNames | list | List of measurement object names. |
visible | bool | 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 | str | The name of the measurement object. |
points | list | 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 | str | 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 | bool | 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 | bool | 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 | list | List of measurement object names. |
matrix | list | 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 | list | List of measurement object names. |
surfaceName | str | 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 | list | List of measurement object names. |
maskName | str | The name of the mask object to snap to. |