Skip to main content

Primitives

The Primitives tool allows you to create, edit, and manage geometric primitive objects in your project. Primitives are idealized geometric shapes used for reference measurements, region-of-interest (ROI) definition, and geometric analysis.

Accessing the Tool​

  1. Navigate to the Measure tab in the ribbon
  2. Click the Primitives button in the Primitive tools section

Primitive Types​

Select a primitive type from the dropdown menu before placing:

Point​

Create a single reference point.

  • Placement: Click once to place the point
  • Use case: Mark reference positions, create point sets for fitting

Line​

Create a line segment between two points.

  • Placement: Click to place the first point, then click for the second point
  • Use case: Define axes, directions, or reference lines

Circle​

Create a planar circle.

  • Placement: Click to set the center, then drag to define the radius
  • Use case: Circular ROI, cross-section analysis

Sphere​

Create a 3D sphere.

  • Placement: Click to set the center, then drag to define the radius
  • Use case: Spherical ROI, tumor delineation, anatomical landmarks

Ellipsoid​

Create a 3D ellipsoid with three independent axes.

  • Placement: Click to set the center, then drag to define the initial size
  • Use case: Non-spherical anatomical structures, elongated ROIs

Cylinder​

Create a cylinder along a specified axis.

  • Placement: Click to place two points defining the axis and height
  • Use case: Tubular structures, vessel analysis

Capsule​

Create a capsule (cylinder with hemispherical caps).

  • Placement: Click to place two points defining the axis
  • Use case: Pill-shaped ROIs, rounded tubular structures

Tube​

Create a hollow tube.

  • Placement: Click to place two points defining the axis
  • Use case: Hollow tubular structures, vessel walls

Cone​

Create a cone with a specified apex and base.

  • Placement: Click to place two points defining apex and base
  • Use case: Conical structures, directional indicators

Arrow​

Create an arrow indicator.

  • Placement: Click to place two points defining direction
  • Use case: Directional markers, flow indicators

Spline​

Create a smooth curve through multiple points.

  • Placement: Left-click to add control points, right-click to finalize
  • Use case: Complex curved paths, anatomical tracing
Spline Interaction

Left-click to add control points, right-click to finalize the spline. The curve automatically smooths between control points using interpolation.

Plane​

Create an infinite reference plane.

  • Placement: Click to set the origin, then drag to orient
  • Use case: Cutting planes, reference surfaces, alignment

Cube​

Create a cube with equal dimensions.

  • Placement: Click to set the center, then drag to define size
  • Use case: Cubic ROI, regular sampling volumes

Cuboid​

Create a box with independent dimensions on each axis.

  • Placement: Click to set the center, then drag to define size
  • Use case: Rectangular ROI, bounding regions

User Interface​

Description Group​

Displays instructions for the currently selected primitive type.

Primitive Dropdown​

Select the primitive type to create from the dropdown menu.

Primitives Table​

Lists all primitives in the project.

ColumnDescription
#Primitive index
NameEditable primitive name

Toolbar Buttons​

ButtonDescription
Add (+)Enter placement mode to add a new primitive
Remove (-)Delete selected primitives
ClearDelete all primitives
Move UpMove selected primitive up in the list
Move DownMove selected primitive down in the list
SaveExport primitives to file
LoadImport primitives from file
MoreAdditional options menu

Workflow​

Creating a Primitive​

  1. Select the desired primitive type from the dropdown
  2. Click the Add (+) button to enter placement mode
  3. Click in a 2D or 3D view to place the primitive
  4. For drag-based primitives, hold and drag to define the size
  5. For multi-point primitives, click additional points as needed

Editing Primitives​

After creation, primitives can be manipulated using the 3D gizmo:

  • Move: Drag the gizmo center to translate
  • Rotate: Drag rotation handles to orient
  • Scale: Drag scale handles to resize

Locating Primitives​

Select a primitive in the table, right-click, and choose Locate to center all views on that primitive.

Properties and Appearance​

Visual Properties​

Primitives have the following default appearance:

  • Color: Cyan (0, 1, 0.9)
  • Opacity: 100%
  • Wireframe: Solid (not wireframe)

Follow Object Profile​

When enabled, primitive visibility updates based on the current slice plane positions, showing only the portion of the primitive that intersects the visible slice.

Import and Export​

Supported Formats​

Primitives can be saved and loaded using the INI settings format (.ini), preserving:

  • Primitive type and name
  • Position and orientation
  • Dimensions and parameters
  • Visual properties
Human-Readable Format

Primitive export files use a human-readable INI format to support transparency, interoperability, and reproducibility. This allows external tools and scripts to process ROI data when needed.

Exporting Primitives​

  1. Click the Save button in the toolbar
  2. Choose a location and filename
  3. Select "Settings (*.ini)" as the file type
  4. Primitives are saved with an integrity checksum

Importing Primitives​

  1. Click the Load button in the toolbar
  2. Select a previously saved primitives file
  3. Primitives are added to the current project
  4. Volvicon automatically verifies file integrity on import

Data Integrity Verification​

Volvicon includes data integrity verification for primitive/ROI export files to ensure data traceability and detect external modifications.

How It Works​

When you export primitives:

  • Volvicon computes a SHA-256 cryptographic hash of all primitive data
  • The hash is stored in a dedicated [Integrity] section of the exported file
  • This process is automatic and transparent to the user

When you import primitives:

  • Volvicon recomputes the hash from the file content
  • The computed hash is compared with the stored hash
  • Any mismatch indicates the file was modified externally

Integrity Status​

StatusDescription
VerifiedFile integrity confirmed—data has not been modified since export
ModifiedHash mismatch detected—file was altered outside Volvicon
No HashIntegrity section missing or removed—integrity cannot be verified
Modified Files

If a file is detected as modified, Volvicon displays a warning:

"This measurements file was modified outside Volvicon. Measurement accuracy and validity cannot be guaranteed."

The import proceeds, but you should verify the ROI definitions before relying on them for analysis.

File Structure​

Exported primitive files include:

[Document]
ApplicationName=Volvicon
ApplicationVersion=x.x.x
DateTime=2026-01-30 12:00:00

[PrimitiveObjects]
; ... primitive data ...

[Integrity]
FormatVersion=1.0
IntegrityHash=SHA256:9f3a8c...e21

Regulatory Considerations​

The integrity verification system supports regulatory requirements for data traceability:

  • Tamper Detection: Any modification to ROI data is detected on import
  • Audit Trail: Integrity status is logged for debugging and audit purposes
  • User Notification: Clear warnings ensure users are informed of data modifications
  • No Data Blocking: Modified files can still be imported—users retain full control
Best Practice

For regulatory submissions (FDA, CE), maintain the original exported files without modification. If adjustments are needed, re-export from Volvicon to generate a new verified file.

Scripting​

Primitives can be created and manipulated programmatically:

import ScriptingApi as api

app = api.Application()
primitive_operations = app.get_primitive_operations()

# Create a sphere
primitive_operations.create_sphere([0, 0, 0], 10, "Sphere_1")

# Create a cylinder
primitive_operations.create_cylinder([0, 0, 0], [0, 0, 50], 5, "Cylinder_1")

# Get all sphere primitives
spheres = primitive_operations.get_primitive_names_by_type(api.PrimitiveType.Sphere)

See the Primitive Operations API for the complete function reference.