PrimitiveOperations
Provides tools for creating, editing, and managing 3D primitive objects (ROIs). Supports point, line, circle, sphere, ellipsoid, cylinder, capsule, tube, cone, arrow, spline, plane, cube, and cuboid primitives. Enables import/export, geometric transformation, appearance control, and conversion to surface objects. All positions, radii, and dimensions are expressed in millimeters (mm); all rotation angles are expressed in degrees.
Import
import ScriptingApi as api
# Access via Application
app = api.Application()
ops = app.get_primitive_operations()
Methods
Properties
get_primitive_names_by_type
Gets the names of primitive objects of a specific type.
Signature:
get_primitive_names_by_type(type: PrimitiveType) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
type | PrimitiveType | The type of primitive objects to retrieve. Use api.PrimitiveType.Point, api.PrimitiveType.Sphere, etc. |
Returns: list — A list of primitive object names matching the specified type.
get_primitive_type
Gets the type of a primitive object.
Signature:
get_primitive_type(primitiveName: str) -> PrimitiveType
Parameters:
| Parameter | Type | Description |
|---|---|---|
primitiveName | str | The name of the primitive object. |
Returns: PrimitiveType — The type of the primitive object as api.PrimitiveType.
set_lock
Sets the lock status of primitive objects. Locked primitives cannot be moved interactively.
Signature:
set_lock(primitiveNames: list, locked: bool) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
primitiveNames | list | List of primitive object names. |
locked | bool | True to lock, false to unlock. |
set_active
Activates a primitive object for editing.
Signature:
set_active(primitiveName: str) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
primitiveName | str | The name of the primitive object to activate. |
set_color
Sets the color of primitive objects.
Signature:
set_color(primitiveNames: list, color: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
primitiveNames | list | List of primitive object names. |
color | list | RGB color values [r, g, b], each in range [0.0, 1.0]. |
set_opacity
Sets the opacity of primitive objects.
Signature:
set_opacity(primitiveNames: list, opacity: float) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
primitiveNames | list | List of primitive object names. |
opacity | float | Opacity value in range [0.0, 1.0]. |
set_wireframe
Sets the wireframe display mode of primitive objects.
Signature:
set_wireframe(primitiveNames: list, wireframe: bool) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
primitiveNames | list | List of primitive object names. |
wireframe | bool | True to display as wireframe, false for solid surface. |
set_resolution
Sets the resolution of primitive objects (affects curved surfaces).
Signature:
set_resolution(primitiveNames: list, resolution: int) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
primitiveNames | list | List of primitive object names. |
resolution | int | Number of subdivisions for curved surfaces. Must be at least 3. |
set_end_point_color
Sets the end point (handle) color of primitive objects.
Signature:
set_end_point_color(primitiveNames: list, color: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
primitiveNames | list | List of primitive object names. |
color | list | RGB color values [r, g, b], each in range [0.0, 1.0]. |
set_handle_visibility
Sets the point handle visibility of primitive objects.
Signature:
set_handle_visibility(primitiveNames: list, visible: bool) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
primitiveNames | list | List of primitive object names. |
visible | bool | True to show handles, false to hide. |
set_2d_cross_visibility
Sets the 2D cross visibility of primitive objects in slice views.
Signature:
set_2d_cross_visibility(primitiveNames: list, visible: bool) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
primitiveNames | list | List of primitive object names. |
visible | bool | True to show 2D cross, false to hide. |
set_slice_views_visibility
Sets the slice views visibility of primitive objects.
Signature:
set_slice_views_visibility(primitiveNames: list, visible: bool) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
primitiveNames | list | List of primitive object names. |
visible | bool | True to show in slice views, false to hide. |
get_primitive_data
Gets the primitive data of a primitive object.
Signature:
get_primitive_data(primitiveName: str) -> PrimitiveData
Parameters:
| Parameter | Type | Description |
|---|---|---|
primitiveName | str | The name of the primitive object. |
Returns: PrimitiveData — The primitive data structure as api.PrimitiveData.
set_primitive_properties
Applies user-configurable primitive appearance and type-specific geometry properties. Fields that do not apply to the target primitive type are ignored. For example, spline-specific fields only affect spline primitives, while line endpoint fields only affect line, cylinder, capsule, tube, cone, and arrow primitives.
Signature:
set_primitive_properties(primitiveName: str, properties: PrimitiveProperties) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
primitiveName | str | The name of the primitive object. |
properties | PrimitiveProperties | The properties to apply. Create using api.PrimitiveProperties(). |
get_primitive_properties
Gets the current user-configurable primitive appearance and type-specific geometry properties. Only the fields that apply to the target primitive type are set; other type-specific fields remain at their default values.
Signature:
get_primitive_properties(primitiveName: str) -> PrimitiveProperties
Parameters:
| Parameter | Type | Description |
|---|---|---|
primitiveName | str | The name of the primitive object. |
Returns: PrimitiveProperties — The current primitive properties as api.PrimitiveProperties.
get_center
Gets the center position of a primitive object.
Signature:
get_center(primitiveName: str) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
primitiveName | str | The name of the primitive object. |
Returns: list — The center position [x, y, z].
get_bounds
Gets the bounding box of a primitive object.
Signature:
get_bounds(primitiveName: str) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
primitiveName | str | The name of the primitive object. |
Returns: list — The bounds [xmin, xmax, ymin, ymax, zmin, zmax].
Creation
create_point
Creates a point primitive (spherical marker) at the specified position.
Signature:
create_point(center: list, radius: float = 1.0, name: str = "") -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
center | list | The 3D center position [x, y, z] of the point. |
radius | float | The radius of the spherical marker. |
name | str | Optional name for the primitive (auto-generated if empty). |
Returns: str — The name of the created primitive object, or an empty string if creation failed.
create_circle
Creates a circle primitive (disk) at the specified position.
Signature:
create_circle(center: list, radius: float = 1.0, name: str = "", angle: float = 0.0, axis: list = [0.0, 0.0, 1.0]) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
center | list | The 3D center position [x, y, z] of the circle. |
radius | float | The radius of the circle. |
name | str | Optional name for the primitive (auto-generated if empty). |
angle | float | Rotation angle in degrees about axis. The default 0 keeps the disk in the XY plane. |
axis | list | Rotation axis [x, y, z]. It must not be a zero vector. |
Returns: str — The name of the created primitive object, or an empty string if creation failed.
create_sphere
Creates a sphere primitive at the specified position.
Signature:
create_sphere(center: list, radius: float = 1.0, name: str = "") -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
center | list | The 3D center position [x, y, z] of the sphere. |
radius | float | The radius of the sphere. |
name | str | Optional name for the primitive (auto-generated if empty). |
Returns: str — The name of the created primitive object, or an empty string if creation failed.
create_ellipsoid
Creates an ellipsoid primitive at the specified position.
Signature:
create_ellipsoid(center: list, radiusX: float = 1.0, radiusY: float = 1.0, radiusZ: float = 1.0, name: str = "", angle: float = 0.0, axis: list = [0.0, 0.0, 1.0]) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
center | list | The 3D center position [x, y, z] of the ellipsoid. |
radiusX | float | The radius along X-axis. |
radiusY | float | The radius along Y-axis. |
radiusZ | float | The radius along Z-axis. |
name | str | Optional name for the primitive (auto-generated if empty). |
angle | float | Rotation angle in degrees about axis. The default 0 keeps the radii along the X, Y and Z axes. |
axis | list | Rotation axis [x, y, z]. It must not be a zero vector. |
Returns: str — The name of the created primitive object, or an empty string if creation failed.
create_line
Creates a line primitive (solid cylinder) between two points.
Signature:
create_line(point1: list, point2: list, radius: float = 1.0, name: str = "") -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
point1 | list | The 3D position [x, y, z] of the start point. |
point2 | list | The 3D position [x, y, z] of the end point. |
radius | float | The radius of the line cylinder. |
name | str | Optional name for the primitive (auto-generated if empty). |
Returns: str — The name of the created primitive object, or an empty string if creation failed.
create_cylinder
Creates a cylinder primitive between two points.
Signature:
create_cylinder(point1: list, point2: list, radius: float = 1.0, name: str = "") -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
point1 | list | The 3D position [x, y, z] of the start point. |
point2 | list | The 3D position [x, y, z] of the end point. |
radius | float | The radius of the cylinder. |
name | str | Optional name for the primitive (auto-generated if empty). |
Returns: str — The name of the created primitive object, or an empty string if creation failed.
create_capsule
Creates a capsule primitive (cylinder with hemispherical caps) between two points.
Signature:
create_capsule(point1: list, point2: list, radius: float = 1.0, name: str = "") -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
point1 | list | The 3D position [x, y, z] of the start point. |
point2 | list | The 3D position [x, y, z] of the end point. |
radius | float | The radius of the capsule. |
name | str | Optional name for the primitive (auto-generated if empty). |
Returns: str — The name of the created primitive object, or an empty string if creation failed.
create_tube
Creates a tube primitive (hollow cylinder) between two points.
Signature:
create_tube(point1: list, point2: list, radius: float = 1.0, thickness: float = 0.25, name: str = "") -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
point1 | list | The 3D position [x, y, z] of the start point. |
point2 | list | The 3D position [x, y, z] of the end point. |
radius | float | The outer radius of the tube. |
thickness | float | The wall thickness of the tube. |
name | str | Optional name for the primitive (auto-generated if empty). |
Returns: str — The name of the created primitive object, or an empty string if creation failed.
create_cone
Creates a cone primitive between two points.
Signature:
create_cone(point1: list, point2: list, radius: float = 1.0, name: str = "") -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
point1 | list | The 3D position [x, y, z] of the base center. |
point2 | list | The 3D position [x, y, z] of the tip. |
radius | float | The base radius of the cone. |
name | str | Optional name for the primitive (auto-generated if empty). |
Returns: str — The name of the created primitive object, or an empty string if creation failed.
create_arrow
Creates an arrow primitive between two points.
Signature:
create_arrow(point1: list, point2: list, shaftRadius: float = 1.0, tipRadius: float = 2.0, tipLengthFactor: float = 1.0, name: str = "") -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
point1 | list | The 3D position [x, y, z] of the shaft start. |
point2 | list | The 3D position [x, y, z] of the arrow tip. |
shaftRadius | float | The radius of the arrow shaft. |
tipRadius | float | The radius of the arrow tip (arrowhead). |
tipLengthFactor | float | The length factor of the tip relative to arrow length. |
name | str | Optional name for the primitive (auto-generated if empty). |
Returns: str — The name of the created primitive object, or an empty string if creation failed.
create_plane
Creates a plane primitive at the specified position.
Signature:
create_plane(center: list, width: float = 1.0, height: float = 1.0, name: str = "", angle: float = 0.0, axis: list = [0.0, 0.0, 1.0]) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
center | list | The 3D center position [x, y, z] of the plane. |
width | float | The width of the plane. |
height | float | The height of the plane. |
name | str | Optional name for the primitive (auto-generated if empty). |
angle | float | Rotation angle in degrees about axis. The default 0 keeps the plane parallel to the XY plane. |
axis | list | Rotation axis [x, y, z]. It must not be a zero vector. |
Returns: str — The name of the created primitive object, or an empty string if creation failed.
create_cube
Creates a cube primitive at the specified position.
Signature:
create_cube(center: list, size: float = 1.0, name: str = "", angle: float = 0.0, axis: list = [0.0, 0.0, 1.0]) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
center | list | The 3D center position [x, y, z] of the cube. |
size | float | The edge length of the cube. |
name | str | Optional name for the primitive (auto-generated if empty). |
angle | float | Rotation angle in degrees about axis. The default 0 keeps the edges along the X, Y and Z axes. |
axis | list | Rotation axis [x, y, z]. It must not be a zero vector. |
Returns: str — The name of the created primitive object, or an empty string if creation failed.
create_cuboid
Creates a cuboid primitive at the specified position.
Signature:
create_cuboid(center: list, width: float = 1.0, height: float = 1.0, depth: float = 1.0, name: str = "", angle: float = 0.0, axis: list = [0.0, 0.0, 1.0]) -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
center | list | The 3D center position [x, y, z] of the cuboid. |
width | float | The width (X dimension) of the cuboid. |
height | float | The height (Y dimension) of the cuboid. |
depth | float | The depth (Z dimension) of the cuboid. |
name | str | Optional name for the primitive (auto-generated if empty). |
angle | float | Rotation angle in degrees about axis. The default 0 keeps width, height and depth along the X, Y and Z axes. |
axis | list | Rotation axis [x, y, z]. It must not be a zero vector. |
Returns: str — The name of the created primitive object, or an empty string if creation failed.
create_spline
Creates a spline primitive from a list of control points.
Signature:
create_spline(points: list, radius: float = 1.0, closedLoop: bool = False, name: str = "") -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
points | list | List of 3D control points [x, y, z] defining the spline path. At least 2 points are required. |
radius | float | The radius of the spline tube. Must be greater than 0. |
closedLoop | bool | If true, creates a closed loop spline (default: false). |
name | str | Optional name for the primitive (auto-generated if empty). |
Returns: str — The name of the created primitive object, or an empty string if creation failed.
File System
import_primitives_settings_from_disk
Imports primitives from a file.
Signature:
import_primitives_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 primitives before importing (default: True). |
Returns: bool — True if the import was successful; false otherwise.
export_primitives_settings_to_disk
Exports all primitives settings to a file.
Signature:
export_primitives_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.
UI
set_always_show
Enables or disables the "always show" mode for primitives. When enabled, primitives remain visible even when the primitive 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.
get_display_properties
Gets the display properties of a primitive object.
Signature:
get_display_properties(primitiveName: str) -> PrimitiveDisplayProperties
Parameters:
| Parameter | Type | Description |
|---|---|---|
primitiveName | str | The name of the primitive object. |
Returns: PrimitiveDisplayProperties — The display properties as api.PrimitiveDisplayProperties.
Modification
transform
Applies a transformation matrix to primitive objects.
Signature:
transform(primitiveNames: list, matrix: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
primitiveNames | list | List of primitive object names. |
matrix | list | 4x4 transformation matrix (16 elements in row-major order). |
General
snap_to_surface
Snaps the points of primitives to the nearest points of a surface.
Signature:
snap_to_surface(primitiveNames: list, surfaceName: str) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
primitiveNames | list | List of primitive object names. |
surfaceName | str | The name of the surface object to snap to. |
snap_to_mask
Snaps the points of primitives to the nearest points of a mask surface. The mask must have a generated 3D preview.
Signature:
snap_to_mask(primitiveNames: list, maskName: str) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
primitiveNames | list | List of primitive object names. |
maskName | str | The name of the mask object to snap to. |
convert_to_surfaces
Converts primitives to surface objects. Creates a new surface object from each primitive's mesh geometry.
Signature:
convert_to_surfaces(primitiveNames: list) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
primitiveNames | list | List of primitive object names to convert. |
Returns: list — List of created surface object names. Empty if the input list is empty or no primitives could be converted.
locate_primitive
Locates a primitive in the 2D and 3D views. Centers the views on the primitive and adjusts the camera to focus on it.
Signature:
locate_primitive(primitiveName: str) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
primitiveName | str | The name of the primitive object to locate. |