yapCAD 0.3.0__tar.gz → 0.5.0__tar.gz

{yapcad-0.3.0 → yapcad-0.5.0}/.readthedocs.yml

@@ -5,14 +5,23 @@
 # Required
 version: 2
 
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/conf.py
 
+python:
+  install:
+    - requirements: docs/requirements.txt
+
 # Optionally build your docs in additional formats such as PDF
 formats:
   - pdf
 
 submodules:
   include: all
-  recursive: true
+  recursive: true

{yapcad-0.3.0 → yapcad-0.5.0}/CHANGELOG.rst

@@ -2,19 +2,41 @@
 Changelog
 =========
 
-Version 0.3.0
-=============
+Version 0.5.0 (2024-09-30)
+==========================
 
 what's new:
 -----------
 
-- Require Python 3.10+ and align dependency metadata with current
-  interpreter and library versions.
-- Pin pyglet to 1.x rendering backend and add fallback
-  guards to every OpenGL-enabled example so they degrade gracefully on
-  systems without a working pyglet/Cocoa stack.
-- Sphinx documentation now builds even when optional themes are
-  missing, and `sphinx-apidoc` no longer depends on ``pkg_resources``.
+  - Adds shared geometry utilities and metadata helpers.
+  - Introduces STL export (`yapcad.io.stl`) plus tests.
+  - Provides `examples/rocket_demo.py` showing a full 3D workflow.
+  - Updates documentation with 3D-focused imagery and instructions.
+
+Known problems
+--------------
+
+- Incomplete documentation, though this is improving.
+
+Version 0.4.0 (Development)
+============================
+
+what's new:
+-----------
+
+- **Testing Infrastructure Overhaul**: Completely redesigned test execution system
+  to properly support both automated and interactive visual tests.
+
+  - Added comprehensive pytest markers: ``@pytest.mark.visual`` for interactive tests
+  - Created ``run_visual_tests.py`` and ``run_visual_tests_venv.sh`` for isolated
+    visual test execution using subprocess isolation
+  - Enhanced test discovery using AST parsing to automatically find decorated visual tests
+  - Fixed visual test termination issues that were causing pytest to exit prematurely
+  - Updated all test documentation with clear separation between non-visual and visual testing
+
+- **3D Geometry Enhancements**: Merged advanced 3D surface representation and
+  geometry system improvements from development branch, including enhanced
+  ``Geometry`` class architecture and improved computational geometry operations.
 
 Known problems
 --------------
@@ -23,31 +45,45 @@ Known problems
 - Occasional problems with complex boolean operations.
 - Incomplete functionality around 3D modeling.
 
-Version 0.1.5
+Version 0.3.1
 =============
 
 what's new:
 -----------
 
-- Pre-release, heading towards V0.2.x
+- Added Read the Docs configuration and ``docs/requirements.txt`` so hosted
+  builds use a consistent environment.
+- Updated README instructions for building documentation and running tests.
+- Follow-up to 0.3.0 (no functional code changes).
 
-- Restructuring for package release
+Known problems
+--------------
 
-- Lots more documentation (still incomplete)
+- Incomplete documentation, especially outside the ``yapcad.geom`` module.
+- Occasional problems with complex boolean operations.
+- Incomplete functionality around 3D modeling.
 
-- Fixes to package configuration
+Version 0.3.0
+=============
+
+what's new:
+-----------
+
+- Require Python 3.10+ and align dependency metadata with current
+  interpreter and library versions.
+- Pin pyglet to 1.x rendering backend and add fallback
+  guards to every OpenGL-enabled example so they degrade gracefully on
+  systems without a working pyglet/Cocoa stack.
+- Sphinx documentation now builds even when optional themes are
+  missing, and `sphinx-apidoc` no longer depends on ``pkg_resources``.
 
 Known problems
 --------------
 
 - Incomplete documentation, especially outside the ``yapcad.geom`` module.
+- Occasional problems with complex boolean operations.
+- Incomplete functionality around 3D modeling.
 
-- Occasional problems with complex boolean operations
-
-- Incomplete functionality around 3D modeling
-
-- Inconsistent inclusion of licensing boilerplate
-  
 Version 0.2.0
 =============
 
@@ -69,8 +105,8 @@ Known problems
   **yapCAD**'s documentation is in the form of docstrings in the
   source.  I'm working on getting this sorted out.  In the mean time,
   you may want to build a local copy of the documentation as described
-  in the main ``README`` file.   Or, checkout and read the source. 
-  
+  in the main ``README`` file.   Or, checkout and read the source.
+
 - Incomplete documentation, especially outside the ``yapcad.geom`` module.
 
 - Occasional problems with complex boolean operations.  A bug in the
@@ -81,4 +117,30 @@ Known problems
 - Inconsistent inclusion of licensing boilerplate, other minor
   formatting issues.
 
+Version 0.1.5
+=============
+
+what's new:
+-----------
+
+- Pre-release, heading towards V0.2.x
+
+- Restructuring for package release
+
+- Lots more documentation (still incomplete)
+
+- Fixes to package configuration
+
+Known problems
+--------------
+
+- Incomplete documentation, especially outside the ``yapcad.geom`` module.
+
+- Occasional problems with complex boolean operations
+
+- Incomplete functionality around 3D modeling
+
+- Inconsistent inclusion of licensing boilerplate
+  
+
 .. _yapCAD readthedocs: https://yapcad.readthedocs.io/en/latest/index.html

{yapcad-0.3.0 → yapcad-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: yapCAD
-Version: 0.3.0
+Version: 0.5.0
 Summary: yet another procedural CAD and computational geometry system
 Author-email: Richard DeVaul <richard.devaul@gmail.com>
 Project-URL: Homepage, https://github.com/rdevaul/yapCAD/
@@ -16,6 +16,8 @@ License-File: AUTHORS.rst
 Requires-Dist: ezdxf>=1.1
 Requires-Dist: pyglet<2,>=1.5
 Requires-Dist: mpmath>=1.2
+Requires-Dist: numpy>=1.22
+Requires-Dist: mapbox-earcut>=1.0.3
 Requires-Dist: pyobjc-core; platform_system == "Darwin"
 Requires-Dist: pyobjc-framework-Cocoa; platform_system == "Darwin"
 Requires-Dist: pyobjc-framework-Quartz; platform_system == "Darwin"
@@ -28,12 +30,12 @@ Dynamic: license-file
 ==========
 
 yet another procedural CAD and computational geometry system written in
-python 3
+python 3, now with a growing focus on 3D generative design and STL export
 
-.. figure:: images/yapCadSplash.png
-   :alt: **yapCAD** image
+.. figure:: images/RocketDemoScreenshot.png
+   :alt: **yapCAD** rocket example
 
-   **yapCAD** image
+   **yapCAD** rocket example
 
 what’s **yapCAD** for?
 ----------------------
@@ -42,8 +44,10 @@ First and foremost, **yapCAD** is a framework for creating
 `parametric <https://en.wikipedia.org/wiki/Parametric_design>`__,
 procedural, and
 `generative <https://en.wikipedia.org/wiki/Parametric_design>`__ design
-systems. You can also use **yapCAD** for other CAD, CAM, and
-computational geometry purposes.
+systems. Starting with the 0.5 release, the emphasis has shifted toward
+3D solid workflows, including STL export for downstream slicing and
+simulation, while retaining support for DXF generation and computational
+geometry experiments.
 
 software status
 ---------------
@@ -84,28 +88,23 @@ clone the github repository as shown above, and make sure that your
 PYTHONPATH includes the cloned top-level ``yapCAD`` directory. You will
 find the examples in the ``yapCAD/examples`` directory.
 
-For a fully worked parametric design system, see the ``boxcut`` example.
+For a fully worked 2D parametric design system, see the ``boxcut`` example.
+For a 3D generative example that builds a multi-stage rocket, visualises
+it, and exports STL, see ``examples/rocket_demo.py``.
 
 documentation
 ~~~~~~~~~~~~~
 
 Online **yapCAD** documentation can be found here:
-https://yapcad.readthedocs.io/en/latest/ — for some reason
-``readthedocs.io`` isn’t generating the full module documentation, so
-you might want to build a local copy, as described below.
+https://yapcad.readthedocs.io/en/latest/ — some module references lag
+behind the latest 3D-focused APIs, so you may want to build a local copy
+as described below to explore ``geometry_utils``, ``geometry_checks``,
+``metadata``, and ``io.stl``.
 
-To build the HTML **yapCAD** documentation locally, first make sure you
-have the sphinx package installed:
-
-::
-
-   pip install sphinx --user
-
-Then clone the github repository as shown above, ``cd`` to the
-``yapCAD`` directory, and type
-
-::
+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``
@@ -117,29 +116,77 @@ information.
 running tests
 ~~~~~~~~~~~~~
 
-The repository includes a small pytest suite that exercises the core
-geometry primitives. Install the testing dependencies and run pytest
-from the project root with the source tree on ``PYTHONPATH``::
+The repository includes a comprehensive pytest suite that exercises both core
+geometry primitives and visual rendering capabilities. First, set up the
+testing environment::
 
-   python3 -m pip install pytest pytest-cov
-   PYTHONPATH=./src python3 -m pytest
+   # Create and activate virtual environment
+   pyenv local 3.12  # or use python3.12 directly
+   python3 -m venv v_312
+   source v_312/bin/activate
 
-The default configuration enables coverage reporting via
-``pytest-cov``. If you prefer to skip coverage, you can override the
-options::
+   # Install dependencies
+   pip install -r requirements.txt
+   pip install pytest pytest-cov
 
-   PYTHONPATH=./src python3 -m pytest --override-ini addopts=
+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
-2D or 3D cad or drawing file format. At present, **yapCAD** supports the
-AutoCad DXF file format for creating two-dimensional drawings and OpenGL
-for creating interactive 2D and 3D renderings.
+**yapCAD** is designed to support multiple rendering back-ends, such that
+only a 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 <https://github.com/mozman/ezdxf>`__).
+* STL export for 3D solids (via the new ``yapcad.io.stl`` module).
+* 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.
 
 The foundations of **yapCAD** are grounded in decades of the author’s
 experience with graphics system programming, 3D CAD and simulation.
@@ -158,8 +205,8 @@ package, and interactive OpenGL visualization using the amazing
 
 (for a more complete list, see the `examples folder <./examples/>`__)
 
-It’s pretty easy to make a DXF drawing with **yapCAD**. Here is an
-example:
+It’s pretty easy to make a DXF drawing or a 3D model with **yapCAD**. Here
+is a DXF example:
 
 ::
 
@@ -194,6 +241,15 @@ example:
    # write out the geometry as example1-out.dxf
    dd.display()
 
+For a 3D example that generates a complete rocket assembly and exports
+STL::
+
+   from pathlib import Path
+   from examples.rocket_demo import build_rocket, export_stl
+
+   components, assembly = build_rocket()
+   export_stl(assembly, Path("rocket_demo.stl"))
+
 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:

{yapcad-0.3.0 → yapcad-0.5.0}/README.md

@@ -1,7 +1,7 @@
 # **yapCAD**
-yet another procedural CAD and computational geometry system written in python 3
+yet another procedural CAD and computational geometry system written in python 3, now with a growing focus on 3D generative design and STL export
 
-![**yapCAD** image](images/yapCadSplash.png)
+![**yapCAD** 3D rocket example](images/RocketDemoScreenshot.png)
 
 ## what's **yapCAD** for?
 
@@ -9,8 +9,12 @@ First and foremost, **yapCAD** is a framework for creating
 [parametric](https://en.wikipedia.org/wiki/Parametric_design),
 procedural, and
 [generative](https://en.wikipedia.org/wiki/Parametric_design) design
-systems.  You can also use **yapCAD** for other CAD, CAM, and
-computational geometry purposes.
+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
 
@@ -43,25 +47,26 @@ examples, clone the github repository as shown above, and make sure
 that your PYTHONPATH includes the cloned top-level `yapCAD` directory.
 You will find the examples in the `yapCAD/examples` directory.
 
-For a fully worked parametric design system, see the `boxcut` example.
+For a fully worked 2D parametric design system, see the `boxcut`
+example.  For a 3D generative example that builds a multi-stage rocket,
+visualises it, and exports STL, see `examples/rocket_demo.py`.
 
 ### documentation
 
 Online **yapCAD** documentation can be found here:
-https://yapcad.readthedocs.io/en/latest/ — for some reason
-`readthedocs.io` isn't generating the full module documentation, so
-you might want to build a local copy, as described below.
+https://yapcad.readthedocs.io/en/latest/ — some module references
+lag behind the current 3D-focused APIs, so you may want to build a
+local copy (see below) to explore the latest `geometry_utils`,
+`metadata`, `geometry_checks`, and `io.stl` modules.
 
-To build the HTML **yapCAD** documentation locally, first make sure
-you have the sphinx package installed:
+To build the HTML **yapCAD** documentation locally, install the
+documentation dependencies and run Sphinx from the project root:
 
-	pip install sphinx --user
-
-Then clone the github repository as shown above,
-`cd` to the `yapCAD` directory, and type
+```bash
+python3 -m pip install -r docs/requirements.txt
+make -C docs html
+```
 
-	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
@@ -70,33 +75,81 @@ information.
 
 ### running tests
 
-The repository includes a small pytest suite that exercises the core
-geometry primitives. Install the testing dependencies and run pytest
-from the project root with the source tree on `PYTHONPATH`:
+The repository includes a comprehensive pytest suite that exercises both core
+geometry primitives and visual rendering capabilities. First, set up the
+testing environment:
 
 ```bash
-python3 -m pip install pytest pytest-cov
-PYTHONPATH=./src python3 -m pytest
+# 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:
+
+```bash
+# 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=
 ```
 
-The default configuration enables coverage reporting via
-`pytest-cov`. If you prefer to skip coverage, you can override the
-options:
+#### 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:
 
 ```bash
-PYTHONPATH=./src python3 -m pytest --override-ini addopts=
+# 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 2D or 3D cad or drawing file format.  At present,
-**yapCAD** supports the AutoCad DXF file format for creating
-two-dimensional drawings and OpenGL for creating interactive 2D and 3D
-renderings.
+add support for a cad or drawing file format.  At present,
+**yapCAD** supports:
+
+- 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).
+- 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.
 
 The foundations of **yapCAD** are grounded in decades of the author's
 experience with graphics system programming, 3D CAD and
@@ -115,7 +168,8 @@ package, and interactive OpenGL visualization using the amazing
 
 (for a more complete list, see the [examples folder](./examples/))
 
-It's pretty easy to make a DXF drawing with **yapCAD**.  Here is an example:
+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 *
@@ -146,7 +200,17 @@ It's pretty easy to make a DXF drawing with **yapCAD**.  Here is an example:
     dd.draw(arc(point(0,3),3,45,135))
 
     # write out the geometry as example1-out.dxf
-	dd.display()
+    dd.display()
+
+For a 3D example that generates a complete rocket assembly and exports STL:
+
+```python
+from pathlib import Path
+from examples.rocket_demo import build_rocket, export_stl
+
+components, assembly = build_rocket()
+export_stl(assembly, Path("rocket_demo.stl"))
+```
 
 The **yapCAD** system isn't just about rendering, of course, it's
 about computational geometry.  For example, if you want to calculate