Moving from Version 2 to 3#

Compatibility with Older OpenVCAD Versions#

OpenVCAD 3.X.X is not directly backwards compatible with the older OpenVCAD API. Existing scripts may need to be updated before they run on the new version.

The important point is that the old capabilities have not gone away. Everything you could do in the old version can be done in OpenVCAD 3.0, but some designs need to be expressed using the new attribute-modeling workflow.

What to Read First#

Start by reading and following along with the guides. Even if you have used OpenVCAD before, OpenVCAD 3.X.X changes the modeling workflow enough that the guide sequence matters.

Read these first:

It is especially important to read Theory and Motivation first, then follow along with the Getting Started with OpenVCAD guide. Together, those guides introduce the new attribute-modeling workflow, how attributes attach to geometry, how composition affects attributes, and how coordinate spaces work.

You should also scan the Compilers overview so you understand which guide matches your output workflow. You do not need to read every compiler guide before starting. Read the guide for the printing or export system you plan to use. For most users, that will likely be one of the inkjet guides:

Transitioning from OpenVCAD 2.x#

If you used the OpenVCAD 2.x main branch, the biggest change is the role of volume fractions.

In the older workflow, material behavior was commonly modeled directly as volume fractions on an object. Functional grading tools existed to help define those material mixtures across space. That made sense for early multi-material workflows, but it also made volume fractions feel like the central material abstraction.

In OpenVCAD 3.x attribute modeling, volume fractions are just one attribute type. You can still create VOLUME_FRACTIONS fields, and downstream inkjet or simulation workflows can still consume them, but they no longer need to be the first thing you model. You can attach attributes anywhere in the design tree: leaf nodes, composed objects, transformed branches, or parent wrappers.

The practical shift is:

old pattern: define material volume fractions directly, often through functional grading nodes
new pattern: attach the attribute that expresses your intent, then derive or compile the attributes needed by the target workflow

This is why the older functional grading node is obsolete in the attribute-modeling branch. Functional grading is now a general capability of every expression-based attribute. A MODULUS gradient, COLOR_RGBA gradient, TEMPERATURE field, and VOLUME_FRACTIONS blend all use the same modeling pattern: attach a field to the node where that field should live.

Migrating lattice and TPMS scripts within version 3#

The attribute-modeling line also replaces the experimental conformal-mapping prototypes and the earlier Cartesian metamaterials builders. Spatial layout now belongs to an explicit CellMap; the TPMS or graph-cell builder receives that map as its first argument.

# Earlier builder style
root = mm.gyroid(cell=10.0, thickness=1.2, size=30.0)

# Version 3 map-first style
cell_map = mm.rectangular_cell_map(
    (pv.Vec3(-15.0, -15.0, -15.0), pv.Vec3(15.0, 15.0, 15.0)),
    cells=(3, 3, 3),
)
root = mm.gyroid(cell_map, wall_thickness=1.2)

The equivalent graph-lattice rename is radius to beam_radius. Builder arguments named cell, size, bounds, and center have been removed. For CAD-conformal geometry, construct the map with cell_map_from_cad_face or cell_map_between_cad_faces; the old Map, ConformalMap, and SurfaceParamerterizer prototypes no longer exist.

Lattice geometry controls are ordinary typed attributes. Cartesian attributes are evaluated in the consuming node’s coordinates; use cell_map.logical_position, cell_map.unit_cell_phase, or cell_map.cell_index for explicit lattice coordinates. All returned lattice objects remain ordinary pv.Node instances and continue through the normal attribute and compiler pipelines.