This tutorial will guide you through designing basic 3D objects using OpenVCAD. We will cover how to create objects with both single and multiple materials using Python and the pyvcad library. This guide assumes you are using VCAD Studio to compile these scripts for visualization and exporting.

Hello World

Let's examine this Python script that you can run in VCAD Studio. Going line by line: The import pyvcad as pv statement imports the pyvcad library and gives it the alias pv, which we'll use to prefix all our calls. Next, we create a MaterialDefs object that loads material configurations from a JSON file. This configuration maps material names and colors for visualization, allowing us to convert named materials like "red" or "blue" into integer IDs that OpenVCAD understands. We then use center_point = pv.Vec3(0, 0, 0) to define the center point of our rectangular prism, and dimensions = pv.Vec3(10,10,10) to set its size along the XYZ axes. Finally, root = pv.RectPrism(center_point, dimensions, materials.id("red")) creates our object using these variables. Since this is our only object, we assign the pv.RectPrism as the design's root. The materials object converts the color name "red" to its corresponding integer ID.

All pyvcad scripts in VCAD Studio must import pyvcad and define a root variable

import pyvcad as pv

# Load our material config. This provides a mapping between string names 
# and IDs VCAD can use
materials = pv.default_materials()

# Creates a 10mm cube centered at 0,0,0
center_point = pv.Vec3(0, 0, 0)
dimensions = pv.Vec3(10,10,10)

root = pv.RectPrism(center_point, dimensions, materials.id("red"))

Composition

OpenVCAD constructs objects using tree structures based on Constructive Solid Geometry (CSG). OpenVCAD classifies its nodes into categories according to how many children they can have: unary (one), binary (two), and n-ary (many). At the bottom of the tree, leaf nodes define the basic geometry. Intermediate nodes transform, combine, and modify different pieces of geometry. OpenVCAD also includes material nodes that can modify multi-material distribution (more details later). Below is a complete list of composition nodes:

Each node type has a specific method for adding children, which ensures the correct number of child nodes are attached. The following table shows the different methods used to add children for each node type.

Union

This example defines two spheres that overlap slightly. The union combines the objects into a single object.

import pyvcad as pv

materials = pv.default_materials()

# Create two overlapping spheres
radius = 5
left_sphere  = pv.Sphere(pv.Vec3(-radius/2, 0, 0), radius, materials.id("red"))
right_sphere = pv.Sphere(pv.Vec3(+radius/2, 0, 0), radius, materials.id("red"))

# Perform boolean operation
root = pv.Union()
root.add_child(left_sphere)
root.add_child(right_sphere)

Intersection

The same overlapping spheres are intersected.

Note: in this example we add the children at the same time we construct the Intersection node. We could have added them like the previous example with .add_child()

import pyvcad as pv

materials = pv.default_materials()

# Create two overlapping spheres
radius = 5
left_sphere  = pv.Sphere(pv.Vec3(-radius/2, 0, 0), radius, materials.id("red"))
right_sphere = pv.Sphere(pv.Vec3(+radius/2, 0, 0), radius, materials.id("red"))

# Perform boolean operation, in a single line, don't worry about the 'False' for now
root = pv.Intersection(False, [left_sphere, right_sphere])