yapCAD

yet another procedural CAD and computational geometry system written in python 3, now with a growing focus on 3D generative design and STL export

what's yapCAD for?

First and foremost, yapCAD is a framework for creating parametric, procedural, and generative design systems. With the 0.5.0 release the emphasis has shifted toward 3D geometry workflows, including solids that can be exported directly to STL for downstream slicing and simulation. You can still use yapCAD for DXF generation, CAM, and computational geometry experiments, but the core is increasingly optimised for 3D generative design.

software status (October 2025)

yapCAD is in active development and already powers production design pipelines. Highlights from the 0.5.x cycle include:

• .ycpkg project packaging with manifest, geometry JSON, exports, and metadata.
• CLI helpers (tools/ycpkg_validate.py, tools/ycpkg_export.py) for validation and DXF/STEP/STL export.
• Robust 3D boolean operations with validated tessellation and mesh diagnostics.
• Native OCC/BREP workflow: import STEP, run --engine occ booleans on analytic solids, and round-trip BREP data inside .ycpkg geometry JSON.
• Native sketch primitives (lines, arcs, splines) preserved through package round-trips and exported to DXF as analytic entities.
• Regression-tested spline extrusion flow (tests/test_splines.py) covering STEP/STL/DXF export.

Upcoming work (tracked in docs/yapCADone.rst and docs/yapBREP.rst) focuses on the parametric DSL/compiler, validation execution layer, provenance signatures, STEP/STL import, and analytic BREP/STEP export.

If you are using yapCAD in interesting ways, feel free to let us know in the yapCAD discussions forum

yapCAD installation, documentation, and examples

installation

yapCAD is a pure python library, so no special steps are required for installation. You can install it a variety of ways, but the recommended method is to use pip to install it into your local site-packages directory, as follows:

pip install yapCAD --user

You can also clone the github repository and install from source:

git clone https://github.com/rdevaul/yapCAD.git
cd yapCAD
python setup.py install --user

examples

Clone the repository (or install the package) and ensure PYTHONPATH contains the top-level src directory. Example entry points:

• examples/boxcut – fully parametric 2D joinery workflow (DXF output).
• examples/rocket_demo.py – generative multi-stage rocket with viewer + STL export.
• examples/rocket_cutaway_internal.py – layout/cutaway helper demo exporting STEP (screenshot below).
• examples/involute_gear_package/ – canonical gear library packaged as .ycpkg and reused by assemblies.
• examples/bulkhead_sweep.py – sweeps bulkhead thickness from 5–12 mm, runs CalculiX through the new analysis framework, and reports max deflection per case.
• examples/thread_profiles.py – previews/exporst thread surfaces using the thread sampler + theta-based revolve.
• examples/threaded_fastener_package.py – generates .ycpkg packages for screws, nuts, or washers (metric/unified catalog defaults or custom parameters), and can emit paired screw+nut assemblies with threads aligned mid-shank. Fastener helpers expose metric_hex_cap_catalog() / unified_hex_cap_catalog() as well as metric_hex_nut_catalog() / unified_hex_nut_catalog() for dimensional lookups.

The fastener helpers live in yapcad.fasteners and cover metric and unified hex-cap screws, nuts, and small hardware such as bearing washers. They share the same thread sampler (internal/external, multi-start, handedness-aware) so threaded assemblies can be generated programmatically or packaged for downstream workflows.

Several demos were authored with LLM assistance to illustrate automation-friendly workflows.

documentation

Online yapCAD documentation can be found here: https://yapcad.readthedocs.io/en/latest/ — key documents include:

• docs/ycpkg_spec.rst – .ycpkg manifest schema, packaging workflow, CLI usage.
• docs/metadata_namespace.rst – standard metadata blocks for materials, manufacturing, and analysis annotations.
• docs/yapBREP.rst – analytic STEP/BREP upgrade roadmap.
• docs/dsl_spec.rst – parametric DSL and validation plans.
• Example analysis plans live under examples/ (see examples/bulkhead_calculix.yaml) and can be staged with python tools/ycpkg_analyze.py <package> --plan validation/plans/.... The bundled CalculiX adapter approximates the bulkhead as an axisymmetric plate and will attempt to run ccx if available (otherwise the plan is marked skipped).
• Module references for yapcad.io, yapcad.geom3d_util, yapcad.geometry_utils, and yapcad.metadata.
• Mesh validation workflow (docs/mesh_validation.md, tools/validate_mesh.py).

To build the HTML yapCAD documentation locally, install the documentation dependencies and run Sphinx from the project root:

python3 -m pip install -r docs/requirements.txt
make -C docs html

This will build the HTML documents in the build/sphinx/html directory. You can also build documentation in the other formats supported by Sphinx. See the Sphinx documentation for more information.

project packages & CLI

The preferred interchange format is the .ycpkg project package:

my_design.ycpkg/
├── manifest.yaml
├── geometry/primary.json
├── exports/
├── validation/
└── ...

Helper commands:

# Validate package structure / hashes
python tools/ycpkg_validate.py path/to/design.ycpkg

# Export STEP/STL/DXF from a package
python tools/ycpkg_export.py path/to/design.ycpkg --format step --format stl --output exports/

See docs/ycpkg_spec.rst for the manifest schema and workflow details.

Import STEP geometry (experimental)

BREP-backed STEP import relies on pythonocc-core, so activate the conda environment described in docs/BREP_integration_strategy.md before running the importer:

conda activate yapcad-brep
# Inspect bounding boxes via the importer API
PYTHONPATH=src python - <<'PY'
from yapcad.io.step_importer import import_step
parts = import_step("examples/rocket_grid_demo.step")
for geom in parts:
    print(geom.bbox)
PY

# Launch the interactive scaling/boolean demo
PYTHONPATH=src python examples/step_import_demo.py examples/rocket_grid_demo.step

The importer currently extracts solids and wraps them as Geometry(BrepSolid) instances, preserving the OCC BREP data inside .ycpkg serialization so future loads can run exact booleans via --engine occ. When both operands carry BREP metadata, the demo selects the OCC engine; otherwise it falls back to the first trimesh backend available (install the manifold3d pip package inside the conda env to enable trimesh:manifold) or to the native kernel.

running tests

The repository includes a comprehensive pytest suite that exercises both core geometry primitives and visual rendering capabilities. First, set up the testing environment:

# Create and activate virtual environment
pyenv local 3.12  # or use python3.12 directly
python3 -m venv v_312
source v_312/bin/activate

# Install dependencies
pip install -r requirements.txt
pip install pytest pytest-cov

Non-Visual Tests (Automated/CI-friendly)

Run the core computational geometry tests (including triangle, metadata, validation, and STL exporter checks) without interactive displays:

# Run all non-visual tests
PYTHONPATH=./src pytest tests/ -m "not visual"

# With coverage reporting (default)
PYTHONPATH=./src pytest tests/ -m "not visual" --cov=src

# Skip coverage for faster execution
PYTHONPATH=./src pytest tests/ -m "not visual" --override-ini addopts=

Visual Tests (Interactive)

yapCAD includes visual tests that create interactive 3D renderings to verify geometry generation and display functionality (for example, tests/test_mesh_view.py::test_mesh_view_visual_normals). These require a display and user interaction:

# Run all visual tests (opens interactive windows)
./run_visual_tests_venv.sh

# Run specific visual tests by pattern
./run_visual_tests_venv.sh test_geom      # Only test_geom* visual tests
./run_visual_tests_venv.sh surface        # Tests matching "surface"
./run_visual_tests_venv.sh Face           # Face-related tests

# Alternative: Manual pytest execution
VISUALTEST=true PYTHONPATH=./src pytest tests/ -m visual

# Or run individual visual tests
VISUALTEST=true PYTHONPATH=./src pytest tests/test_geom3d.py::TestSurface::test_surface -s

Note: Visual tests require closing each interactive window to proceed to the next test. Use the dedicated run_visual_tests_venv.sh script for the best experience, as it runs each test in an isolated subprocess to prevent early termination.

yapCAD goals

The purpose of yapCAD is to support 2D and 3D computational geometry and parametric, procedural, and generative design projects in python3. yapCAD is designed to support multiple rendering back-ends, such that a relatively small amount of code is necessary to add support for a cad or drawing file format. At present, yapCAD supports:

• AutoCAD DXF output for two-dimensional drawings (via ezdxf).
• STL and STEP export for 3D solids (via yapcad.io.stl and yapcad.io.step modules).
• OpenGL visualisation for 2D/3D geometries using pyglet.
• Modular 3D boolean operations supporting both native and external engines (trimesh with Manifold/Blender backends).

The 0.5.x series delivers robust 3D boolean operations, validated primitive generation (sphere, cylinder, cone, tube, etc.), comprehensive mesh validation tools, and production-ready export capabilities. These foundations pave the way toward enhanced STEP support and a packaged, provenance-aware project model targeted for the forthcoming 1.0 release.

The foundations of yapCAD are grounded in decades of the author's experience with graphics system programming, 3D CAD and simulation. yapCAD has an underlying framework and architecture designed to support sophisticated computational geometry and procedural CAD applications. At the same time, the design of yapCAD should make easy stuff relatively easy, and the more advanced stuff possible.

The initial implementation of yapCAD provides DXF file creation support through the awesome ezdxf package, and interactive OpenGL visualization using the amazing pyglet package.

yapCAD examples

(for a more complete list, see the examples folder)

It's pretty easy to make a DXF drawing or a 3D model with yapCAD. Here is a DXF example:

from yapcad.ezdxf_drawable import *
from yapcad.geom import *

#set up DXF rendering
dd=ezdxfDraw()
dd.filename = "example1-out"

## make dxf-renderable geometry

# make a point located at 10,10 in the x-y plane, rendered as a small
# red cross and circle
dd.pointstyle = 'xo' # also valid are 'x' or 'o'
dd.linecolor = 1 # set color to red (DXF index color 1)
dd.draw(point(10,10))

# make a line segment between the points -5,10 and 10,-5 in the x-y plane
# and draw it in white

dd.linecolor='white' # set color by name
dd.draw(line(point(-5,10),
	         point(10,-5)))

# make an arc with a center at 0,3 with a radius of 3, from 45 degrees
# to 135 degrees, and draw it in aqua

dd.linecolor=[0,255,255] # RGB tripple, corresponds to 'aqua'
dd.draw(arc(point(0,3),3,45,135))

# write out the geometry as example1-out.dxf
dd.display()

For a 3D example that generates a complete rocket assembly and exports STL and STEP:

from pathlib import Path
from examples.rocket_demo import build_rocket, export_stl
from yapcad.io.step import write_step

components, assembly = build_rocket()
export_stl(assembly, Path("rocket_demo.stl"))
write_step(assembly, Path("rocket_demo.step"))

There is also an advanced rocket_grid_demo.py example featuring grid fins, a linear exploded view, and simultaneous STL/STEP export.

The yapCAD system isn't just about rendering, of course, it's about computational geometry. For example, if you want to calculate the intersection of lines and arcs in a plane, we have you covered:

from yapcad.geom import *

# define some points
a = point(5,0)
b = point(0,5)
c = point(-3,0)
d = point(10,10)

# make a couple of lines
l1 = line(a,b)
l2 = line(c,d)

# define a semicircular arc centered at 2.5, 2,5 with a radius of 2.5
# extending from 90 degrees to 135 degrees

arc1=arc(point(2.5,2.5),2.5,90.0,270.0)

# calculate the intersection of lines l1 and l2
int0 = intersectXY(l1,l2)

# calculate the intersection of the line l1 and the arc arc1
int1 = intersectXY(l1,arc1)

print("intersection of l1 and l2:",vstr(int0))
print("intersection of l1 and arc1:",vstr(int1))

And of course yapCAD supports calculating intersections between any simple and compound, or compound and compound geometry object.

There are lots more examples available to demonstrate the various computational geometry and rendering capabilities of yapCAD, including 3D geometry and OpenGL rendering.

yapCAD geometry

yapCAD distinguishes between "pure" geometric elements, such as lines, arcs, etc., and drawn representations of those things, which might have attributes like line color, line weight, drawing layer, etc. This distinction is important, because the pure geometry exists independent of these attributes, which are themselves rendering-system dependent.

More importantly, for every geometric element you decide to draw, there will typically be many more — perhaps dozens — that should not be in the final rendering. By separating these two elements — computation and rendering — yapCAD makes them both more intentional and reduces the likelihood of certain type of drawing-quality issues, such as redundant or spurious drawing elements, that can cause confusion problems for computer-aided manufacturing (CAM).

For example, you might construct a finished drawing that includes a drill pattern that consists of circles (drill holes with centers) that follow a complex, geometrically constrained pattern. This pattern is itself the result of numerous computational geometry operations, perhaps driven by parameters relating to the size and shape of other parts.

In a program like Autodesk's Fusion360, you would typically use construction lines and constraints to create the underlying geometric pattern. These additional construction elements would have to be removed in order to make a clean DXF export of your drawing. On more than one occasion yapCAD's author has created headaches by failing to remove some of these elements, confusing CAM technicians, causing delays, and sometimes resulting in expensive part fabrication errors.

Thus, yapCAD allows you to work freely with computational geometry without cluttering up your drawing page, since you specifically decide what to draw. It also means you can do computational geometry in yapCAD without ever invoking a rendering system, which can be useful when incorporating these geometry operations as part of a larger computational system, such as a tool-path generator.

As a rule, in yapCAD pure geometry representations capture only the minimum necessary to perform computational geometry, and the rest gets dealt with by the rendering system, which are subclasses of Drawable that actually make images, CAD drawings, etc.

vector representation in yapCAD

For the sake of uniformity, all yapCAD vectors are stored as projective geometry 4-vectors. (see discussion in architecture, below) However, most of the time you will work with them as though they are 3-vectors or 2-vectors.

It would be annoying to have to specify the redundant coordinates you aren't using every time you specify a vector, so yapCAD provides you with the vect function. It fills in defaults for the z and w parameters you may not want to specify. e.g.

>>> from yapcad.geom import *
>>> vect(10,4)
[10, 4, 0, 1]
>>> add(vect(10,4),vect(10,9))  ## add operates in 3-space
[20, 13, 0, 1.0]

Of course, you can specify all three (or even four) coordinates using vect.

Since it gets ugly to look at a bunch of [x, y, z, w] lists that all end in 0, 1] when you are doing 2D stuff, yapCAD provides a convenience function vstr that intelligently converts yapCAD vectors (and lists that contain vectors, such as lines, triangles, and polygons) to strings, assuming that as long as z = 0 and w = 1, you don't need to see those coordinates.

>>> from yapcad.geom import *
>>> a = sub(vect(10,4),vect(10,9)) ## subtract a couple of vectors 
>>> a
[0, -5, 0, 1.0]
>>> print(vstr(a)) ## pretty printing, elide the z and w coordinates
>>> [0, -5]

pure geometry

Pure geometric elements in yapCAD form the basis for computational geometry operations, including intersection and inside-outside testing. Pure geometry can also be drawn, of course — see drawable geometry below.

In general, yapCAD pure geometry supports the operations of parametric sampling, intersection calculation, inside-outside testing (for closed figures), "unsampling" (going from a point on the figure to the sampling parameter that would produce it), and bounding box calculation. yapCAD geometry is based on projective or homogeneous coordinates, thus supporting generalized affine transformations; See the discussion in architecture, below.

simple (non-compound) pure geometric elements

Simple, which is to say non-compound, geometry includes vectors, points, and lines. A vector is a list of exactly four numbers, each of which is a float or integer. A point is a vector that lies in a w > 0 hyperplane; Points are used to represent transformable coordinates in yapCAD geometry. A line is a list of two points.

Simple geometry also includes arcs. An arc is a list of a point and a vector, followed optionally by another point. The first list element is the center of the arc, the second is a vector in the w=-1 hyperplane (for right-handed arcs) whose first three elements are the scalar parameters [r, s, e]: the radius, the start angle in degrees, and the end angle in degrees. The third element (if it exists) is the normal for the plane of the arc, which is assumed to be [0, 0, 1] (the x-y plane) if it is not specified. Arcs are by default right-handed, but left-handed arcs are also supported, with parameter vectors lying in the w=-2 hyperplane.

compound figures

A list of more than two points represents a multi-vertex polylines. If there are at least four points in the list and the last point is the same as the first, the polyline figure is closed. (We sometimes refer to these point-list polygons or polylines as poly() entities.) Closed coplanar polylines are drawn as polygons and may be subject to inside-outside testing. Like other elements of pure geometry, polylines are subject to sampling, unsampling, intersection calculation, etc.

If instead of sharp corners you want closed or open figures with rounded corners, you should use Polyline or Polygon instances. Instances of these classes are used for representing compound geometric elements in an XY plane with C0 continuity. They differ from the point-list-based poly() representation in that the elements of a Polyline or Polygon can include lines and arcs as well as points. These elements need not be contiguous, as successive elements will be automatically joined by straight lines. Polygons are special in that they are always closed, and that any full circle elements are interpreted as "rounded corners," with the actual span of the arc calculated after tangent lines are drawn.

The Polygon class supports boolean operations, as described below, and also supports the grow() operation that makes generating a derived figure that is bigger by a fixed amount easy. This grow feature is very useful for many engineering operations, such as creating an offset path for drill holes, CAM paths, etc.

boolean operations on Polygon instances

yapCAD supports boolean set operations on Polygon instances, allowing you to construct more complex two-dimensional figures from union, intersection, and difference operations. Note that the difference operation can result in the creation of disjoint geometry in the form of two or more closed figures with positive area (see below), or closed figures with holes.

See Example 11 for a relatively simple example of boolean operations, and Example 12 for a more complex example.

yapCAD employs the convention that closed figures with right-handed geometry (increasing the sampling parameter corresponds to points that trace a counter-clockwise path) represent "positive" area, and that closed figures with left-handed geometry represent holes. This distinction is currently not operational, but will be important for future development such as turning polygons into rendered surfaces and extruding these surfaces into 3D.

disjoint compound geometry

Boolean difference operations can result in disjoint figures. It is also possible to combine yapCAD geometric elements in geometry lists, which is to say a list of zero or more elements of yapCAD pure geometry, which enforce no continuity constraints. Geometry lists provide the basis for yapCAD rendering.

drawable geometry

The idea is that you will do your computational geometry with "pure" geometry, and then generate rendered previews or output with one or more Drawable instances.

In yapCAD, geometry is rendered with instances of subclasses of Drawable, which at present include ezdxfDrawable, a class for producing DXF renderings using the awesome ezdxf package, and pygletDrawable, a class for interactive 2D and 3D OpenGL rendering.

To setup a drawing environment, you create an instance of the Drawable base class corresponding to the rendering system you want to use.

To draw, create the pure geometry and then pass that to the drawbles's draw() method. To display or write out the results you will invoke the display method of the drawable instance.

supported rendering systems

DXF rendering using ezdxf and interactive OpenGL rendering using pyglet are currently supported, and the design of yapCAD makes it easy to support other rendering backends.

yapCAD architecture

Under the hood, yapCAD is using projective coordinates, sometimes called homogeneous coordinates, to represent points as 3D coordinates in the w=1 hyperplane. If that sounds complicated, its because it is. :P But it does allow for a wide range of geometry operations, specifically affine transforms to be represented as composable transformation matrices. The benefits of this conceptual complexity is an architectural elegance and generality.

Support for affine transforms is at present rudimentary, but once a proper matrix transform stack is implemented it will allow for the seamless implementation and relatively easy use of a wide range of transformation and projection operations.

What does that buy you? It means that under the hood, yapCAD uses the same type of geometry engine that advanced CAD and GPU-based rendering systems use, and should allow for a wide range of computational geometry systems, possibly hardware-accelerated, to be built on top of it.

The good news is that you don't need to know about homogeneous coordinates, affine transforms, etc., to use yapCAD. And most of the time you can pretend that your vectors are just two-dimensional if everything you are doing happens to lie in the x-y plane.

So, if you want to do simple 2D drawings, we have you covered. If you want to build a GPU-accelerated constructive solid geometry system, you can do that, too.

Third-party credits

The involute gear helper is derived from the MIT-licensed figgear project. The vendored implementation lives in yapcad.contrib.figgear, and the original license text is preserved in third_party/figgear_LICENSE.

Note

This project has been set up using PyScaffold 3.2.3. For details and usage information on PyScaffold see https://pyscaffold.org/.