Primitive Operations
Primitive Operations Tutorial
This script demonstrates how to use the Primitive Operations API to create and manipulate 3D primitive shapes in Volvicon. Primitives are basic geometric shapes that can be used for visualization, CAD-like operations, measurement references, and 3D annotations.
Available primitive types:
- Point: A spherical point marker
- Line: A cylinder connecting two points
- Circle: A disk defined by center and radius
- Sphere: A spherical volume
- Ellipsoid: An ellipsoid with three radii
- Cylinder: A cylinder between two points
- Capsule: A cylinder with hemispherical caps
- Tube: A hollow cylinder (pipe)
- Cone: A cone with base and tip
- Arrow: An arrow with shaft and tip
- Spline: A curved tube through control points
- Plane: A flat rectangular surface
- Cube: A cubic volume
- Cuboid: A box-shaped volume
Prerequisites
- A project must be open
- For some operations, existing primitives are needed
Listing Primitives​
# Get all primitives in the project
all_primitives = app.get_all_primitive_names()
print(f"Total primitives in project: {len(all_primitives)}")
# for name in all_primitives:
# print(f" - {name}")
# Get primitives by type
# points = PrimitiveOperations.get_primitive_names_by_type(api.PrimitiveType.Point)
# lines = PrimitiveOperations.get_primitive_names_by_type(api.PrimitiveType.Line)
# spheres = PrimitiveOperations.get_primitive_names_by_type(api.PrimitiveType.Sphere)
# print(f"Points: {len(points)}, Lines: {len(lines)}, Spheres: {len(spheres)}")
# Get the type of a primitive
# if all_primitives:
# prim_type = PrimitiveOperations.get_primitive_type(all_primitives[0])
# print(f"Type of '{all_primitives[0]}': {prim_type}")
Importing and Exporting Primitives​
# Import primitives from file
# imported = PrimitiveOperations.import_primitives_settings_from_disk("C:\\Path\\To\\primitives.json")
# print(f"Imported {len(imported)} primitives")
# Export all primitives
# PrimitiveOperations.export_primitives_settings_to_disk("C:\\Path\\To\\all_primitives.json")
# Export specific primitives
# if all_primitives:
# PrimitiveOperations.export_primitives_settings_to_disk("C:\\Path\\To\\single_primitive.json")
Creating Primitives - Point and Sphere​
# Create a point (spherical marker)
# point1 = PrimitiveOperations.create_point([10.0, 20.0, 30.0], 2.0, "Point 001")
# point2 = PrimitiveOperations.create_point([50.0, 60.0, 70.0], 3.0, "Point 002")
# print(f"Created points: {point1}, {point2}")
# Create a sphere
# sphere1 = PrimitiveOperations.create_sphere([100.0, 100.0, 100.0], 15.0, "Sphere 001")
# sphere2 = PrimitiveOperations.create_sphere([200.0, 150.0, 100.0], 20.0, "Sphere 002")
# print(f"Created spheres: {sphere1}, {sphere2}")
Creating Primitives - Lines and Cylinders​
# Create a line (thin cylinder between two points)
# line1 = PrimitiveOperations.create_line([0.0, 0.0, 0.0], [100.0, 0.0, 0.0], 1.0, "Line X-Axis")
# line2 = PrimitiveOperations.create_line([0.0, 0.0, 0.0], [0.0, 100.0, 0.0], 1.0, "Line Y-Axis")
# line3 = PrimitiveOperations.create_line([0.0, 0.0, 0.0], [0.0, 0.0, 100.0], 1.0, "Line Z-Axis")
# print(f"Created coordinate axes: {line1}, {line2}, {line3}")
# Create a cylinder
# cylinder1 = PrimitiveOperations.create_cylinder([50.0, 50.0, 0.0], [50.0, 50.0, 100.0], 10.0, "Cylinder 001")
# print(f"Created cylinder: {cylinder1}")
Creating Primitives - Capsule and Tube​
# Create a capsule (cylinder with hemispherical caps)
# capsule1 = PrimitiveOperations.create_capsule([0.0, 0.0, 50.0], [100.0, 0.0, 50.0], 8.0, "Capsule 001")
# print(f"Created capsule: {capsule1}")
# Create a tube (hollow cylinder)
# tube1 = PrimitiveOperations.create_tube([0.0, 100.0, 0.0], [0.0, 100.0, 100.0], 15.0, 3.0, "Tube 001")
# print(f"Created tube (outer radius=15, thickness=3): {tube1}")
Creating Primitives - Cone and Arrow​
# Create a cone
# cone1 = PrimitiveOperations.create_cone([150.0, 0.0, 0.0], [150.0, 0.0, 80.0], 20.0, "Cone 001")
# print(f"Created cone: {cone1}")
# Create an arrow (useful for direction indicators)
# arrow1 = PrimitiveOperations.create_arrow([200.0, 200.0, 0.0], [200.0, 200.0, 100.0], 2.0, 8.0, 0.3, "Arrow 001")
# print(f"Created arrow (shaft=2, tip=8, tip_length=0.3): {arrow1}")
Creating Primitives - Circle and Ellipsoid​
# Create a circle (disk)
# circle1 = PrimitiveOperations.create_circle([50.0, 0.0, 100.0], 25.0, "Circle 001")
# print(f"Created circle: {circle1}")
# Create an ellipsoid with three radii
# ellipsoid1 = PrimitiveOperations.create_ellipsoid([150.0, 150.0, 50.0], 30.0, 20.0, 10.0, "Ellipsoid 001")
# print(f"Created ellipsoid (rx=30, ry=20, rz=10): {ellipsoid1}")
Creating Primitives - Spline​
# Create a spline (curved tube through control points)
# control_points = [
# [0.0, 0.0, 0.0],
# [50.0, 50.0, 20.0],
# [100.0, 30.0, 40.0],
# [150.0, 80.0, 30.0],
# [200.0, 100.0, 50.0]
# ]
# spline1 = PrimitiveOperations.create_spline(control_points, 5.0, False, "Spline 001")
# print(f"Created spline: {spline1}")
Creating Primitives - Plane, Cube, and Cuboid​
# Create a plane (flat rectangular surface)
# plane1 = PrimitiveOperations.create_plane([0.0, 0.0, 0.0], 100.0, 80.0, "Plane 001")
# print(f"Created plane (100x80): {plane1}")
# Create a cube
# cube1 = PrimitiveOperations.create_cube([250.0, 250.0, 50.0], 40.0, "Cube 001")
# print(f"Created cube (size=40): {cube1}")
# Create a cuboid (box with different dimensions)
# cuboid1 = PrimitiveOperations.create_cuboid([300.0, 300.0, 50.0], 50.0, 30.0, 20.0, "Cuboid 001")
# print(f"Created cuboid (50x30x20): {cuboid1}")
Querying Primitive Properties​
# if all_primitives:
# prim_name = all_primitives[0]
#
# # Get primitive data (name, visible, locked)
# prim_data = PrimitiveOperations.get_primitive_data(prim_name)
# print(f"Name: {prim_data.name}, Visible: {prim_data.visible}, Locked: {prim_data.locked}")
#
# # Get display properties (color, opacity, line width, etc.)
# display_props = PrimitiveOperations.get_display_properties(prim_name)
# print(f"Color: {display_props.color}, Opacity: {display_props.opacity}")
# print(f"Wireframe: {display_props.wireframe}")
# print(f"Resolution: {display_props.resolution}")
#
# # Get geometric properties
# center = PrimitiveOperations.get_center(prim_name)
# bounds = PrimitiveOperations.get_bounds(prim_name)
# print(f"Center: {center}")
# print(f"Bounds: xmin={bounds[0]}, xmax={bounds[1]}, ymin={bounds[2]}, ymax={bounds[3]}, zmin={bounds[4]}, zmax={bounds[5]}")
Modifying Primitive Appearance​
# if all_primitives:
# # Set color (RGB values 0.0-1.0)
# PrimitiveOperations.set_color([all_primitives[0]], [1.0, 0.0, 0.0]) # Red
#
# # Set opacity (0.0 = transparent, 1.0 = opaque)
# PrimitiveOperations.set_opacity([all_primitives[0]], 0.8)
#
# # Set line width for wireframe edges
# PrimitiveOperations.set_wireframe([all_primitives[0]], True)
#
# # Set end point (handle) color for control points
# PrimitiveOperations.set_end_point_color([all_primitives[0]], [0.0, 1.0, 0.0]) # Green
Setting Visibility Options​
# if all_primitives:
# # Set handle visibility (control points)
# PrimitiveOperations.set_handle_visibility([all_primitives[0]], True)
#
# # Set 2D cross visibility in slice views
# PrimitiveOperations.set_2d_cross_visibility([all_primitives[0]], True)
#
# # Set slice views visibility
# PrimitiveOperations.set_slice_views_visibility([all_primitives[0]], True)
Transforming Primitives​
# if all_primitives:
# # Translation matrix example (move by +10 in X, +20 in Y, +30 in Z)
# # Matrix format: 4x4 in column-major order
# # [m0, m1, m2, m3, m4, m5, m6, m7, m8, m9, m10, m11, m12, m13, m14, m15]
# translation_matrix = [
# 1, 0, 0, 0, # Column 0
# 0, 1, 0, 0, # Column 1
# 0, 0, 1, 0, # Column 2
# 10, 20, 30, 1 # Column 3 (translation in m12, m13, m14)
# ]
# PrimitiveOperations.transform([all_primitives[0]], translation_matrix)
#
# # Scale matrix example (scale by 2x in all dimensions)
# scale_matrix = [
# 2, 0, 0, 0,
# 0, 2, 0, 0,
# 0, 0, 2, 0,
# 0, 0, 0, 1
# ]
# # PrimitiveOperations.transform([all_primitives[0]], scale_matrix)
#
# # Rotation matrix example (90 degrees around Z-axis)
# import math
# angle = math.radians(90)
# cos_a = math.cos(angle)
# sin_a = math.sin(angle)
# rotation_matrix = [
# cos_a, sin_a, 0, 0,
# -sin_a, cos_a, 0, 0,
# 0, 0, 1, 0,
# 0, 0, 0, 1
# ]
# # PrimitiveOperations.transform([all_primitives[0]], rotation_matrix)
Managing Primitive Objects​
# if all_primitives:
# # Duplicate primitives
# duplicated = app.duplicate_primitives([all_primitives[0]])
# print(f"Duplicated: {duplicated}")
#
# # Rename a primitive
# app.rename_primitive(duplicated[0], "My Custom Primitive")
#
# # Set visibility
# app.set_primitives_visible([all_primitives[0]], False) # Hide
# app.set_primitives_visible([all_primitives[0]], True) # Show
#
# # Isolate specific primitives (hide all others)
# app.isolate_primitives([all_primitives[0], all_primitives[1]])
#
# # Show all primitives again
# app.isolate_primitives(all_primitives)
#
# # Lock primitives (prevents interactive editing)
# PrimitiveOperations.set_lock([all_primitives[0]], True)
#
# # Unlock
# PrimitiveOperations.set_lock([all_primitives[0]], False)
#
# # Delete primitives
# # app.delete_primitives([duplicated[0]])
Converting Primitives to Surfaces​
# if all_primitives:
# # Convert primitives to surface objects (for mesh operations)
# surfaces = PrimitiveOperations.convert_to_surfaces([all_primitives[0]])
# print(f"Created surface objects: {surfaces}")
#
# # The surface objects can now be used with SurfaceOperations API
# # app.get_all_surface_names() # Will include the new surfaces
Locating Primitives in Views​
# if all_primitives:
# # Focus 2D and 3D views on a specific primitive
# PrimitiveOperations.locate_primitive(all_primitives[0])
Always Show Mode​
# Enable "always show" mode (primitives visible even when primitive tool inactive)
# PrimitiveOperations.set_always_show(True)
# Check if always show is enabled
# is_always_show = PrimitiveOperations.is_always_show_enabled()
# print(f"Always show enabled: {is_always_show}")
# Disable always show mode
# PrimitiveOperations.set_always_show(False)
Practical Example: Creating a Coordinate System​
# # Create three arrows representing X, Y, Z axes
# origin = [0.0, 0.0, 0.0]
# axis_length = 100.0
#
# x_axis = PrimitiveOperations.create_arrow(origin, [axis_length, 0.0, 0.0], 2.0, 6.0, 0.2, "X-Axis")
# y_axis = PrimitiveOperations.create_arrow(origin, [0.0, axis_length, 0.0], 2.0, 6.0, 0.2, "Y-Axis")
# z_axis = PrimitiveOperations.create_arrow(origin, [0.0, 0.0, axis_length], 2.0, 6.0, 0.2, "Z-Axis")
#
# # Color them appropriately
# PrimitiveOperations.set_color([x_axis], [1.0, 0.0, 0.0]) # Red for X
# PrimitiveOperations.set_color([y_axis], [0.0, 1.0, 0.0]) # Green for Y
# PrimitiveOperations.set_color([z_axis], [0.0, 0.0, 1.0]) # Blue for Z
#
# print(f"Created coordinate system: {x_axis}, {y_axis}, {z_axis}")
Practical Example: Creating Measurement References​
# # Create spheres at key anatomical landmarks
# landmark1 = PrimitiveOperations.create_sphere([45.3, 67.8, 123.4], 3.0, "Landmark A")
# landmark2 = PrimitiveOperations.create_sphere([89.1, 102.5, 145.9], 3.0, "Landmark B")
#
# # Connect them with a line
# reference_line = PrimitiveOperations.create_line(
# PrimitiveOperations.get_center(landmark1),
# PrimitiveOperations.get_center(landmark2),
# 1.0,
# "A-B Distance Reference"
# )
#
# # Set color to highlight
# PrimitiveOperations.set_color([landmark1, landmark2], [1.0, 1.0, 0.0]) # Yellow
# PrimitiveOperations.set_color([reference_line], [1.0, 0.5, 0.0]) # Orange
#
# print(f"Created measurement reference: {landmark1}, {landmark2}, {reference_line}")
Practical Example: Creating a Cutting Plane​
# # Create a plane to visualize a cutting plane
# cut_plane = PrimitiveOperations.create_plane([128.0, 128.0, 64.0], 200.0, 200.0, "Cutting Plane")
#
# # Make it semi-transparent
# PrimitiveOperations.set_color([cut_plane], [0.5, 0.5, 1.0]) # Light blue
# PrimitiveOperations.set_opacity([cut_plane], 0.3)
#
# # Transform to orient it (rotate 45 degrees around Y)
# import math
# angle = math.radians(45)
# rotation_matrix = [
# math.cos(angle), 0, -math.sin(angle), 0,
# 0, 1, 0, 0,
# math.sin(angle), 0, math.cos(angle), 0,
# 128.0, 128.0, 64.0, 1
# ]
# PrimitiveOperations.transform([cut_plane], rotation_matrix)
#
# print(f"Created cutting plane: {cut_plane}")
print("Primitive operations tutorial completed successfully.")
Related Resources​
- API Reference - API documentation
- Quick Reference - Common methods at a glance