Migrations

Migrating model code to OpenCascade 8 (build123d 0.13+)

cadgen 0.8.1 moves from build123d 0.11 on OpenCascade 7.9 to build123d 0.13 on OpenCascade 8.0 (cadquery-ocp-novtk 8.0.x). Models using removed build123d methods need the edits listed below. A model that reaches into OCP directly — a bounding box without tessellation, a shape map, an explorer downcast, a B-spline built from arrays — may hit one of the renames below. Most name changes are one-line edits; the missing diagnostic and material fields need native operations instead.

How it shows up

ErrorCause
ImportError: cannot import name 'TopTools_IndexedMapOfShape' from 'OCP.TopTools' (or any TopTools_*, TDF_*, TColStd_*, TColgp_*, BOPAlgo_ListOf* collection)OCCT 8 replaced the collection typedefs with NCollection templates; OCP 8 binds each instantiation once, under OCP.collections, named by its template arguments.
AttributeError: type object 'TopoDS' has no attribute 'Edge_s' (or Face_s, Vertex_s, Wire_s, Shell_s, Solid_s)The static downcasts lost their _s suffix.
TypeError: Unregistered type : Bnd_Box::Limits from box.Get()Bnd_Box.Get() now returns a struct OCP 8 does not bind.
TypeError: Unregistered type : NCollection_Shared<NCollection_List<BRepCheck_Status>…> from BRepCheck_Result.Status()OCP 8 binds no list of BRepCheck_Status; read one status at a time from the per-type checkers.

The renames

OpenCascade 7.9OpenCascade 8
from OCP.TopTools import TopTools_IndexedMapOfShapefrom OCP.collections import IndexedMap_TopoDS_Shape_TopTools_ShapeMapHasher
from OCP.TopTools import TopTools_IndexedDataMapOfShapeListOfShapefrom OCP.collections import IndexedDataMap_TopoDS_Shape_List_TopoDS_Shape_TopTools_ShapeMapHasher
from OCP.TopTools import TopTools_ListOfShapefrom OCP.collections import List_TopoDS_Shape
from OCP.TDF import TDF_LabelSequencefrom OCP.collections import Sequence_TDF_Label
from OCP.TColStd import TColStd_Array1OfIntegerfrom OCP.collections import Array1_int
from OCP.TColStd import TColStd_Array1OfRealfrom OCP.collections import Array1_double
from OCP.TColStd import TColStd_Array2OfRealfrom OCP.collections import Array2_double
from OCP.TColStd import TColStd_HArray1OfRealfrom OCP.collections import HArray1_double
from OCP.TColgp import TColgp_Array1OfPnt / TColgp_Array1OfPnt2d / TColgp_Array2OfPntfrom OCP.collections import Array1_gp_Pnt / Array1_gp_Pnt2d / Array2_gp_Pnt
from OCP.TColgp import TColgp_HArray1OfPntfrom OCP.collections import HArray1_gp_Pnt
from OCP.BOPAlgo import BOPAlgo_ListOfCheckResultfrom OCP.collections import List_BOPAlgo_CheckResult
PCDM_ReaderFilter.AppendMode_OverwritePCDM_ReaderFilter.AppendMode_e.AppendMode_Overwrite
TopoDS.Edge_s(shape) (and Face_s, Vertex_s, Wire_s, Shell_s, Solid_s)TopoDS.Edge(shape) (and Face, Vertex, Wire, Shell, Solid)
xmin, ymin, zmin, xmax, ymax, zmax = box.Get()lo, hi = box.CornerMin(), box.CornerMax() then lo.X(), lo.Y(), lo.Z(), hi.X(), hi.Y(), hi.Z()
for status in result.Status() on a BRepCheck_ResultBRepCheck_Shell(shell).Closed(), .Orientation(); BRepCheck_Face(face).IntersectWires(), .ClassifyWires(), .OrientationOfWires(); BRepCheck_Wire(wire).Closed() — one BRepCheck_Status each

The constructors and methods of the renamed collections are unchanged (Array1_double(1, n), .SetValue(i, v), .Extent(), .FindKey(i), .FindFromIndex(i)); the import and each use take the new name.

Prefer the build123d API where it covers the job: shape.bounding_box() for extents when tessellation is acceptable, shape.faces()/edges() for enumeration, Face.make_surface_from_array_of_points for surfaces. A model that reaches into OCP for a reason (an exact bounding box without tessellation, an ordinal-stable shape map) keeps doing so with the spellings above.

build123d 0.11 → 0.13

Independent of the kernel, build123d 0.12 removed its deprecated API: Vector.to_tuple() → tuple(vector); Face.make_plane() → an unlimited face is Face(BRepBuilderAPI_MakeFace(plane.wrapped).Face()); Location.to_tuple() → (tuple(location.position), tuple(location.orientation)); Location.to_axis, Axis.to_plane, Edge.to_axis, Edge.to_wire, Wire.to_wire, Face.to_arcs and Shape.relocate are gone, and the centre arcs take arc_size in place of end_angle/angular_direction. Vertex.X/Y/Z read the native point live rather than the coordinates given at construction.

build123d 0.13 adds a native Shape.material property and shape provenance. Custom shape copying must retain topo_path and _history by reference, as build123d's own __deepcopy__ does; the history contains kernel handles that cannot be pickled.

Native materials

Use build123d's native bd_materials library. Its catalogue factories return FinishedMaterial objects, with physical properties in .material and native threejs_materials.PbrProperties in .pbr:

from bd_materials import metals
from cadgen import paint

aluminum = metals.aluminum(metals.Alu.G6061_T6)
aluminum.pbr = aluminum.pbr.override(
    roughness=0.35, metalness=0.9, clearcoat=0.2)
housing.material = aluminum
housing.color = "#606b78"
paint(housing, housing.faces().sort_by(bd.Axis.Z)[-1], metals.copper())

Prepare the look with PbrProperties.override, assigning its result back to .pbr. Set the material after geometry, then set any explicit colour: native material assignment also sets shape colour. For transmission, it infers a preview alpha (transmission=1 gives alpha 0.3), even when PBR opacity=1. To keep an opaque base colour with physical transmission, assign an opaque housing.color after its material, as above.

PBR controls include metalness, roughness, ior, clearcoat, clearcoat_roughness, anisotropy, anisotropy_rotation (radians), transmission, attenuation_color, attenuation_distance (metres), emissive, emissive_intensity, and opacity. Base-colour floats are sRGB ratios; emission and attenuation floats are linear RGB. Hex strings preserve the intended picked colour without that ambiguity.

Native family factories such as metals.custom_metal create custom physics. Density is a single value in kg/m³. Mechanical properties are ranges, with modulus in GPa and strengths in MPa; a custom factory also accepts a number as an exact range. Native shape.mass() and the physical material's mass(volume_mm3) return grams by default; cadgen inspect reports kilograms. For the full authoring example, see materials in the 0.7-to-0.8 guide.

XBF keeps native physics and the complete resolved PBR data. Reading it returns a native finished material with that look, rather than recreating its finish recipe. Scalar clearcoat, anisotropy, transmission, attenuation and emission survive viewer and GLB paths; OCCT snapshots retain their documented approximations. Native texture maps survive XBF, but the viewer, GLB export and snapshots explicitly refuse them until UV mapping is supported.

The XBF format is xbf/9; bd_materials and threejs_materials versions join the build key. The engine reads xbf/8 and xbf/9. Opening an xbf/8 file or cached snapshot converts its material metadata in memory, without source code or a rebuild. Original source and cache bytes, cache records and revisions, and the build closure and toolchain provenance stay unchanged; a separate migration record identifies the conversion.

An explicit cadgen export saved-v8.xbf upgraded-v9.xbf saves the complete upgraded XCAF document atomically to a different path. Export back over the source path is refused. Exporting a cached document by id to XBF also saves its upgraded form. The viewer's original-file download keeps the original XBF bytes, and ordinary current-format XBF-to-XBF translation remains refused. Unsupported formats or failed conversions preserve original bytes and cache records and give a clear error. Explicitly running model source still checks its build key and rebuilds normally when it differs. See the persisted-document policy.

OCP 8.0.1 also leaves XCAFDoc_VisMaterialPBR.EmissiveFactor unbound. To set it, put emission in XCAFDoc_VisMaterialCommon.EmissiveColor, call ConvertToPbrMaterial(), then set the other PBR fields. To read it, use ConvertToCommonMaterial().EmissiveColor. cadgen uses these native conversions for XBF and GLB materials. The scalar topology checkers name fewer faults than the unavailable status list; an invalid shape with no accessible diagnostic remains an error, never a valid result.

Export changes and known kernel issues

Regenerating a STEP file with OCP 8 can rewrite much of its text even when its geometry is unchanged. Compare dimensions, volume, solid count and rendered geometry; a textual STEP diff alone does not establish a geometry change. This was observed in the original migration review.

Two OCP 8.0.1 geometry regressions were independently reproduced on macOS arm64:

  • BRepBndLib.AddOptimal_s can underbound a B-spline shape. the native operation measures a 60 mm loft span as 59.912 mm. cadgen now measures free-form bounds using native distances to six exterior support planes, without tessellating or changing the geometry. The original loft regression passes unchanged, as do analytical bounds checks for translated and rotated ellipsoids through part inspection and face picking. Direct callers of OCP's AddOptimal_s still encounter the upstream defect.
  • A sweep with a binormal guide can distort the profile. A 6 × 6 rectangle swept 30 mm along a straight line, with a parallel guide, has volume 1,080 mm³ on the released 0.8.0 dependencies. On OCP 8.0.1 it has volume 1,072.310 mm³ and a 6.331 mm width, while still reporting valid. Shape validity alone does not establish dimensional correctness.

The guided-sweep defect remains an upstream limitation in the published OCP 8.0.1 wheels. The current model corpus uses no auxiliary-guide sweeps. An experimental kernel fix is not shipping in this release, which retains build123d 0.13/OCP 8. For a model that uses a guide, check dimensions and volume against the intended profile; shape validity alone does not establish correctness.

The separate F1 airbox loft Boolean instability also occurs on 7.9 and is not a newly introduced OCP 8 regression. The sample retains its existing guarded fuzzy union: check that the result contains at least approximately the larger input volume, then use the authored fallback when it does not. This is a sample-specific guard, not a general Boolean repair.