From 281ace6d3977dedd12bad6c20f443588e9acfb21 Mon Sep 17 00:00:00 2001 From: Richard DeVaul Date: Tue, 14 Oct 2025 12:43:41 -0700 Subject: [PATCH] Prepare v0.5.1 release - Update documentation for 3D boolean improvements - Add comprehensive release notes - Update roadmap with completed work --- .gitignore | 4 ++ CHANGELOG.rst | 45 +++++++++++++++++++ README.md | 30 ++++++++----- README.rst | 33 +++++++++----- docs/index.rst | 25 ++++++----- docs/solid_boolean_roadmap.md | 83 ++++++++++++++++++++++++++++------- 6 files changed, 168 insertions(+), 52 deletions(-) diff --git a/.gitignore b/.gitignore index 7819436..659c807 100644 --- a/.gitignore +++ b/.gitignore @@ -70,3 +70,7 @@ v_*/ *.step # but include documentation step files !docs/*.step + +# ignore test python scripts in root +/*.py + diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 5e4ee55..d6c0dfe 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -2,6 +2,51 @@ Changelog ========= +Version 0.5.1 (2025-10-14) +========================== + +what's new: +----------- + + - **3D Boolean Operations Fixes**: Complete overhaul of solid boolean operations + with robust normal orientation and interior triangle filtering. + + - Fixed sphere union normal orientation issues by filtering interior overlap triangles + - Added quality-based filtering for degenerate sliver triangles (aspect ratio checks) + - Implemented containment-based filtering to remove artifacts in overlap regions + - All primitive tests now pass with correct watertight geometry + + - **2D Boolean Operations Fixes**: Resolved crash when performing boolean operations + on ``Circle`` and other single-geometry primitives. + + - Fixed geometry wrapping in ``Boolean._prepare_geom()`` to handle unwrapped arc format + - Added comprehensive regression tests for 2D boolean operations + + - **Primitive Improvements**: Enhanced reliability of 3D geometric primitives. + + - Fixed ``conic()`` primitive to generate proper watertight solids + - Fixed ``tube()`` primitive normal orientation and end cap connectivity + - All 9 core primitives (box, sphere, cylinder, cone, tube, etc.) validated as watertight + + - **Modular Boolean Engine Architecture**: Separated boolean operations into + ``yapcad.boolean.native`` module for better maintainability. + + - Support for multiple boolean engine backends (native, trimesh:manifold, trimesh:blender) + - Engine selection via ``solid_boolean(..., engine='native')`` parameter + - Environment variable support (``YAPCAD_BOOLEAN_ENGINE``, ``YAPCAD_TRIMESH_BACKEND``) + + - **Test Suite Improvements**: Enhanced test coverage and reliability. + + - 106 tests passing (up from 99 in v0.5.0) + - Added boolean regression test suite + - Improved solid topology tests with better error reporting + +Known problems +-------------- + +- Incomplete documentation for some advanced 3D features. +- STEP export currently supports tessellated geometry; analytical BREP support planned for 1.0. + Version 0.5.0 (2024-09-30) ========================== diff --git a/README.md b/README.md index 3ae448b..0efbab1 100644 --- a/README.md +++ b/README.md @@ -18,9 +18,13 @@ design. ## software status -**yapCAD** is still very much in **beta**, although it is already being -used by for professional engineering purposes. If you are using -**yapCAD** in interesting ways, feel free to let us know in the +**yapCAD** is in **active development** and is already being used for +professional engineering purposes. Recent improvements include robust 3D +boolean operations (union, intersection, difference) with proper normal +orientation and degenerate triangle filtering. The 0.5.x series focuses on +production-ready 3D workflows with validated STL and STEP export. + +If you are using **yapCAD** in interesting ways, feel free to let us know in the [**yapCAD** discussions](https://github.com/rdevaul/yapCAD/discussions) forum @@ -77,8 +81,9 @@ calling out include: directives (used by the rocket cutaway demo). - `yapcad.geom3d_util.cutaway_solid_x` – simple clipping helper for creating sectional views of assemblies. -- `yapcad.io.step`/`yapcad.io.stl` – faceted exporters suitable for - interchange with FreeCAD, slicers, and other simulation tools. +- `yapcad.io.step`/`yapcad.io.stl` – production-ready faceted exporters suitable for + interchange with FreeCAD, slicers, and other simulation tools. STEP export supports + multi-component assemblies with proper face orientation. - `tools/validate_mesh.py` – CLI helper that runs `admesh`, `meshfix`, and an optional slicer to gauge whether STL output is robust enough for CAM; see `docs/mesh_validation.md` for usage. @@ -166,14 +171,17 @@ add support for a cad or drawing file format. At present, - AutoCAD DXF output for two-dimensional drawings (via [ezdxf](https://github.com/mozman/ezdxf)). -- STL export for 3D solids (via the new `yapcad.io.stl` module). +- STL and STEP export for 3D solids (via `yapcad.io.stl` and `yapcad.io.step` modules). - OpenGL visualisation for 2D/3D geometries using [pyglet](https://github.com/pyglet/pyglet). - -The 0.5.0 release lays the shared foundations (triangle utilities, -metadata, validation checks, and STL export) that pave the way toward -STEP support and a packaged, provenance-aware project model targeted for -the forthcoming 1.0 release. +- 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 diff --git a/README.rst b/README.rst index a5140a4..43dd246 100644 --- a/README.rst +++ b/README.rst @@ -42,10 +42,14 @@ geometry experiments. software status --------------- -**yapCAD** is still very much in **beta**, although it is already being -used by for professional engineering purposes. If you are using -**yapCAD** in interesting ways, feel free to let us know in the `yapCAD -discussions `__ forum +**yapCAD** is in **active development** and is already being used for +professional engineering purposes. Recent improvements include robust 3D +boolean operations (union, intersection, difference) with proper normal +orientation and degenerate triangle filtering. The 0.5.x series focuses on +production-ready 3D workflows with validated STL and 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 ---------------------------------------------------- @@ -100,8 +104,9 @@ recent updates include: using bounding boxes and optional ``space:`` directives. * ``yapcad.geom3d_util.cutaway_solid_x`` – trim solids against a plane to create sectional visualisations. -* ``yapcad.io.step``/``yapcad.io.stl`` – streamlined mesh exporters for - interchange with FreeCAD, slicers, and analysis tools. +* ``yapcad.io.step``/``yapcad.io.stl`` – production-ready faceted exporters + suitable for interchange with FreeCAD, slicers, and other simulation tools. + STEP export supports multi-component assemblies with proper face orientation. To build the HTML **yapCAD** documentation locally, install the documentation dependencies and run Sphinx from the project root:: @@ -181,14 +186,18 @@ drawing file format. At present, **yapCAD** supports: * AutoCAD DXF output for two-dimensional drawings (via `ezdxf `__). -* STL export for 3D solids (via the new ``yapcad.io.stl`` module). +* STL and STEP export for 3D solids (via ``yapcad.io.stl`` and + ``yapcad.io.step`` modules). * OpenGL visualisation for 2D/3D geometries using `pyglet `__. - -The 0.5.0 release lays the shared foundations (triangle utilities, -metadata, validation checks, and STL export) that pave the way toward STEP -support and a packaged, provenance-aware project model targeted for the -forthcoming 1.0 release. +* 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. diff --git a/docs/index.rst b/docs/index.rst index f2f3cda..b54eea8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,19 +16,19 @@ yapCAD the exported STEP file in FreeCAD. Welcome to **yapCAD**, yet another procedural CAD and computational -geometry system, written in Python_. The project is still evolving, -but recent releases focus on making 3D generative workflows (solid -modeling, STL export, interactive rendering) as straightforward as the -original 2D/DXF tooling. +geometry system, written in Python_. The project is in active development, +with recent releases focusing on production-ready 3D generative workflows +(solid modeling, robust boolean operations, STL/STEP export, interactive +rendering) alongside the original 2D/DXF tooling. .. note:: - + **yapCAD** was created to solve some fairly specific problems in procedural CAD and `parametric design`_. Earlier releases were primarily geared toward generating 2D drawings in the `AutoCad - DXF`_ format; the current 0.5 series lays the groundwork for 3D - workflows, including STL export, metadata tracking, and geometry - validation utilities. + DXF`_ format; the current 0.5.x series delivers robust 3D boolean + operations, validated primitive generation, comprehensive mesh + validation tools, and production-ready STL/STEP export. Why use yapCAD? yapCAD allows you to transform the 2D and 3D mechanical design process from the manual creation of drawings, parts, and assemblies @@ -38,7 +38,7 @@ original 2D/DXF tooling. Because yapCAD's foundations are in software, you can use powerful agentic or "vibe coding" tools to translate your design intent into functional and parameterized design, without ever writing a line of code yourself. For - example, the rocket example rendred above was generated in one-shot by + example, the rocket example rendered above was generated in one-shot by `gpt-5-codex` from the prompt: "Using what you know about yapCAD, I'd like you to create a demo that builds a simple 3D model of a rocket, visualizes it using pyglet, and then writes out the STL file. I'd like the rocket to @@ -56,12 +56,13 @@ original 2D/DXF tooling. Much of the documentation for **yapCAD** can be found in the **README** files, as well as in the ``yapcad.geom`` module - documentation linked below. New helper modules worth exploring - include ``yapcad.geometry_utils``/``yapcad.triangulator`` (triangle + documentation linked below. Key helper modules include + ``yapcad.geometry_utils``/``yapcad.triangulator`` (triangle helpers and ear-cut tessellation), ``yapcad.geometry_checks`` (mesh validation), ``yapcad.metadata`` (surface/solid provenance), ``yapcad.geom3d_util.stack_solids`` and ``cutaway_solid_x`` (layout and - section tools), and ``yapcad.io`` for STL/STEP export. + section tools), ``yapcad.boolean.native`` (production-ready boolean + engine), and ``yapcad.io`` for validated STL/STEP export. Contents ======== diff --git a/docs/solid_boolean_roadmap.md b/docs/solid_boolean_roadmap.md index b32258b..ee4d28d 100644 --- a/docs/solid_boolean_roadmap.md +++ b/docs/solid_boolean_roadmap.md @@ -1,24 +1,73 @@ # Boolean Engine Roadmap -Status snapshot as of this session: +## Status as of v0.5.1 (January 2025) -- Native mesh boolean workflow now lives in `yapcad/boolean/native.py`, with `geom3d` re-exporting it for backward compatibility. -- Diagnostics still rely on `tools/validate_mesh.py`; no engine-specific metrics yet. -- External engine integration is underway; a `trimesh` backend is plumbed (requires an installed boolean operator such as Blender/OpenSCAD/Cork). +### Completed Work -Near-term tasks: +- ✅ **Native Boolean Engine**: Production-ready implementation in `yapcad/boolean/native.py` + - Robust normal orientation for all operations (union, intersection, difference) + - Quality-based filtering for degenerate triangles (aspect ratio checks) + - Containment-based filtering to eliminate interior overlap artifacts + - All primitive boolean operations validated with correct watertight geometry -- [x] **Code extraction** – current boolean implementation now resides in `yapcad/boolean/native.py`, referenced by `geom3d` wrappers. -- [x] **Engine selector UX** – `solid_boolean(..., engine=...)` now routes through the native engine by default, accepts `trimesh` (and optional `trimesh:backend`), and the demo exposes `--engine`; document env flags (`YAPCAD_BOOLEAN_ENGINE`, `YAPCAD_TRIMESH_BACKEND`) for benchmarking. -- [ ] **External prototype** – wrap at least one library boolean (e.g., `trimesh` or PyMeshFix) for STL solids, including geometry conversion helpers. -- [ ] **Benchmark harness** – update the demo CLI and validation scripts to iterate across registered engines, saving STL/lint outputs for comparison. +- ✅ **Code Organization**: Clean separation of boolean operations + - Native engine in `yapcad/boolean/native.py` + - Backward-compatible re-exports from `geom3d` + - Modular architecture supports multiple backends -Open questions: -- Which external kernel offers the best balance of licensing, install footprint, and mesh quality? -- Do we keep the native engine on equal footing (for offline/embedded use), or treat it as a fallback once a third-party backend is available? -- What minimal metrics should every engine report (shell count, single-facet edges, `validate_mesh` scores, render snapshots)? +- ✅ **Engine Selector UX**: Flexible backend selection + - `solid_boolean(..., engine='native')` API + - Support for `trimesh:manifold` and `trimesh:blender` backends + - Environment variables: `YAPCAD_BOOLEAN_ENGINE`, `YAPCAD_TRIMESH_BACKEND` + - Command-line demo with `--engine` flag -Once the refactor lands, future work will include: -- Automatic tolerance scaling per engine. -- Capturing validation output in machine-readable form (JSON) to feed regression dashboards. -- Evaluating hybrid workflows (native preprocessing, external boolean, native stitches/cleanup). +- ✅ **Validation Infrastructure**: Comprehensive mesh quality checks + - `tools/validate_mesh.py` CLI tool + - Integration with `admesh`, `meshfix`, and slicers + - 106 tests passing including boolean regression suite + +### In Progress + +- [ ] **Benchmark Harness**: Systematic comparison across engines + - Need automated iteration across all registered engines + - STL output comparison and quality metrics + - Performance profiling for complex operations + +- [ ] **External Engine Refinement**: Production deployment guidance + - Document installation requirements for each backend + - Best practices for engine selection + - Tolerance mapping for different engines + +### Near-Term Goals + +- [ ] **Documentation Expansion**: Complete API reference + - Engine selection guide with decision matrix + - Performance characteristics and trade-offs + - Migration guide from 0.5.0 to 0.5.1 + +- [ ] **Metrics Collection**: Engine-specific reporting + - Shell count, boundary edge detection + - Validation scores in machine-readable format (JSON) + - Automated regression dashboards + +### Open Questions + +- **Engine Strategy**: Keep native engine as equal option vs fallback? + - **Current stance**: Native engine is production-ready for most use cases + - External engines provide alternatives for specific requirements (licensing, performance) + - Recommend native for offline/embedded use, external for high-complexity operations + +- **Quality Metrics**: What should every engine report? + - Proposed minimum: triangle count, boundary edge count, watertightness status + - Optional: volume calculation, self-intersection checks, performance timing + +- **Hybrid Workflows**: When to combine engines? + - Native preprocessing + external boolean + native cleanup? + - Needs experimentation with real-world complex geometries + +### Future Work (v0.6.0 and beyond) + +- Automatic tolerance scaling per engine +- JSON-formatted validation output for CI/CD integration +- Performance optimization for large assemblies +- Enhanced STEP export with analytical surfaces (not just tessellated)