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.
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 | any | 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 | any | 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 | any | List of primitive object names. |
locked | any | 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 | any | 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 | any | List of primitive object names. |
color | any | 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 | any | List of primitive object names. |
opacity | any | 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 | any | List of primitive object names. |
wireframe | any | 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 | any | List of primitive object names. |
resolution | any | Number of subdivisions for curved surfaces. |
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 | any | List of primitive object names. |
color | any | 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 | any | List of primitive object names. |
visible | any | 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 | any | List of primitive object names. |
visible | any | 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 | any | List of primitive object names. |
visible | any | 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 | any | The name of the primitive object. |
Returns: PrimitiveData — The primitive data structure as PrimitiveData.
get_center
Gets the center position of a primitive object.
Signature:
get_center(primitiveName: str) -> list
Parameters:
| Parameter | Type | Description |
|---|---|---|
primitiveName | any | 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 | any | 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 | any | The 3D center position [x, y, z] of the point. |
radius | any | The radius of the spherical marker. |
name | any | Optional name for the primitive (auto-generated if empty). |
Returns: str — The name of the created primitive object.
create_circle
Creates a circle primitive (disk) at the specified position.
Signature:
create_circle(center: list, radius: float = 1.0, name: str = "") -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
center | any | The 3D center position [x, y, z] of the circle. |
radius | any | The radius of the circle. |
name | any | Optional name for the primitive (auto-generated if empty). |
Returns: str — The name of the created primitive object.
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 | any | The 3D center position [x, y, z] of the sphere. |
radius | any | The radius of the sphere. |
name | any | Optional name for the primitive (auto-generated if empty). |
Returns: str — The name of the created primitive object.
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 = "") -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
center | any | The 3D center position [x, y, z] of the ellipsoid. |
radiusX | any | The radius along X-axis. |
radiusY | any | The radius along Y-axis. |
radiusZ | any | The radius along Z-axis. |
name | any | Optional name for the primitive (auto-generated if empty). |
Returns: str — The name of the created primitive object.
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 | any | The 3D position [x, y, z] of the start point. |
point2 | any | The 3D position [x, y, z] of the end point. |
radius | any | The radius of the line cylinder. |
name | any | Optional name for the primitive (auto-generated if empty). |
Returns: str — The name of the created primitive object.
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 | any | The 3D position [x, y, z] of the start point. |
point2 | any | The 3D position [x, y, z] of the end point. |
radius | any | The radius of the cylinder. |
name | any | Optional name for the primitive (auto-generated if empty). |
Returns: str — The name of the created primitive object.
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 | any | The 3D position [x, y, z] of the start point. |
point2 | any | The 3D position [x, y, z] of the end point. |
radius | any | The radius of the capsule. |
name | any | Optional name for the primitive (auto-generated if empty). |
Returns: str — The name of the created primitive object.
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 | any | The 3D position [x, y, z] of the start point. |
point2 | any | The 3D position [x, y, z] of the end point. |
radius | any | The outer radius of the tube. |
thickness | any | The wall thickness of the tube. |
name | any | Optional name for the primitive (auto-generated if empty). |
Returns: str — The name of the created primitive object.
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 | any | The 3D position [x, y, z] of the base center. |
point2 | any | The 3D position [x, y, z] of the tip. |
radius | any | The base radius of the cone. |
name | any | Optional name for the primitive (auto-generated if empty). |
Returns: str — The name of the created primitive object.
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 | any | The 3D position [x, y, z] of the shaft start. |
point2 | any | The 3D position [x, y, z] of the arrow tip. |
shaftRadius | any | The radius of the arrow shaft. |
tipRadius | any | The radius of the arrow tip (arrowhead). |
tipLengthFactor | any | The length factor of the tip relative to arrow length. |
name | any | Optional name for the primitive (auto-generated if empty). |
Returns: str — The name of the created primitive object.
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 = "") -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
center | any | The 3D center position [x, y, z] of the plane. |
width | any | The width of the plane. |
height | any | The height of the plane. |
name | any | Optional name for the primitive (auto-generated if empty). |
Returns: str — The name of the created primitive object.
create_cube
Creates a cube primitive at the specified position.
Signature:
create_cube(center: list, size: float = 1.0, name: str = "") -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
center | any | The 3D center position [x, y, z] of the cube. |
size | any | The edge length of the cube. |
name | any | Optional name for the primitive (auto-generated if empty). |
Returns: str — The name of the created primitive object.
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 = "") -> str
Parameters:
| Parameter | Type | Description |
|---|---|---|
center | any | The 3D center position [x, y, z] of the cuboid. |
width | any | The width (X dimension) of the cuboid. |
height | any | The height (Y dimension) of the cuboid. |
depth | any | The depth (Z dimension) of the cuboid. |
name | any | Optional name for the primitive (auto-generated if empty). |
Returns: str — The name of the created primitive object.
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 | any | List of 3D control points [x, y, z] defining the spline path. |
radius | any | The radius of the spline tube. |
closedLoop | any | If true, creates a closed loop spline (default: false). |
name | any | Optional name for the primitive (auto-generated if empty). |
Returns: str — The name of the created primitive object.
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 | any | The full path of the file to import. |
deleteExisting | any | 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 | any | 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 | 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.
get_display_properties
Gets the display properties of a primitive object.
Signature:
get_display_properties(primitiveName: str) -> PrimitiveDisplayProperties
Parameters:
| Parameter | Type | Description |
|---|---|---|
primitiveName | any | The name of the primitive object. |
Returns: PrimitiveDisplayProperties — The display properties as PrimitiveDisplayProperties.
Modification
transform
Applies a transformation matrix to primitive objects.
Signature:
transform(primitiveNames: list, matrix: list) -> None
Parameters:
| Parameter | Type | Description |
|---|---|---|
primitiveNames | any | List of primitive object names. |
matrix | any | 4x4 transformation matrix (16 elements in row-major order). |
General
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 | any | List of primitive object names to convert. |
Returns: list — List of created surface object names.
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 | any | The name of the primitive object to locate. |