yapCAD BREP Implementation
==========================


This document describes yapCAD's BREP (Boundary Representation) implementation,
which provides native solid modeling through integration with OpenCascade (OCC).

Overview
--------

yapCAD supports two modes of solid geometry:

1. **Tessellated Mode** (default, no dependencies) - Solids are represented as
   triangle meshes. Suitable for visualization and STL export.

2. **BREP Mode** (requires pythonocc-core) - Solids carry native OCC BREP data
   with exact geometric definitions. Required for STEP import/export and
   high-fidelity boolean operations.

Implementation Status
---------------------

**Complete:**

* Full OCC BREP wrapper classes (``BrepSolid``, ``BrepFace``, ``BrepEdge``, ``BrepVertex``)
* BREP-aware primitives: ``box()``, ``sphere()``, ``cylinder()``, ``cone()``, ``prism()``
* Solid operations: ``extrude()``, ``tube()``, ``makeRevolutionSolid()``, ``makeLoftSolid()``
* Adaptive sweep: ``sweep_adaptive()``, ``sweep_adaptive_hollow()``
* Boolean operations via OCC when BREP data present
* STEP import with topology preservation
* STEP export (tessellated and analytic modes)
* STL import/export
* Transform propagation to BREP data

**Curves (2D/3D):**

* Line, arc, circle, ellipse (full and partial arcs)
* Catmull-Rom splines (open and closed)
* NURBS curves
* Parabola, hyperbola primitives

**Surfaces:**

* Planar, cylindrical, conical, spherical surfaces via OCC
* Tessellation on demand with quality controls
* Surface evaluation and normal computation

Installation
------------

BREP functionality requires pythonocc-core, installed via conda::

    conda env create -f environment.yml
    conda activate yapcad-brep

Without OCC, yapCAD operates in tessellation-only mode with reduced functionality:

* No STEP import/export
* Boolean operations use mesh-based algorithms (lower fidelity)
* Sweep operations produce tessellated results only

Architecture
------------

BREP Wrapper Classes
~~~~~~~~~~~~~~~~~~~~

Located in ``yapcad/brep.py``:

* ``BrepSolid`` - Wraps OCC TopoDS_Solid with lazy tessellation
* ``BrepFace`` - Surface face with trim curves
* ``BrepEdge`` - Edge with curve geometry
* ``BrepVertex`` - Vertex with tolerance

These classes provide bidirectional conversion::

    # yapCAD solid -> OCC shape
    from yapcad.brep import brep_from_solid
    occ_shape = brep_from_solid(solid).shape

    # OCC shape -> yapCAD solid
    from yapcad.brep import solid_from_brep
    solid = solid_from_brep(occ_shape)

BREP Attachment
~~~~~~~~~~~~~~~

Solids store BREP data in metadata under ``'brep'`` key::

    solid = box(10, 20, 30)
    brep = solid[5].get('brep')  # BrepSolid instance if OCC available

Boolean Operations
~~~~~~~~~~~~~~~~~~

Environment variables control engine selection:

* ``YAPCAD_BOOLEAN_ENGINE`` - Force engine: ``native``, ``trimesh``, ``occ``
* ``YAPCAD_MESH_BOOLEAN_ENGINE`` - Mesh fallback when OCC unavailable

Auto-selection logic:

1. If both operands have BREP data → use OCC
2. Otherwise → use mesh-based engine

STEP Import/Export
------------------

Import
~~~~~~

::

    from yapcad.brep import import_step

    # Returns yapCAD Geometry with attached BREP
    geometry = import_step("model.step")

    # Access the underlying solid
    solid = geometry.geom

Export
~~~~~~

Two modes available:

**Tessellated (default)**::

    from yapcad.geom3d import write_solid_step
    write_solid_step(solid, "output.step")

**Analytic** (preserves exact geometry)::

    # Via environment variable
    import os
    os.environ['YAPCAD_STEP_FORMAT'] = 'analytic'
    write_solid_step(solid, "output.step")

    # Or via write_step_analytic directly
    from yapcad.brep import write_step_analytic
    write_step_analytic(solid, "output.step")

Adaptive Sweep Operations
-------------------------

The ``sweep_adaptive()`` function creates solids by sweeping a profile along
a path with tangent-tracking orientation::

    from yapcad.geom3d_util import sweep_adaptive

    solid = sweep_adaptive(
        profile,           # region2d for cross-section
        spine,             # path3d with line/arc segments
        angle_threshold_deg=5.0,  # threshold for new section
        frame_mode='minimal_twist'  # or 'frenet', 'custom'
    )

For hollow profiles (pipes)::

    solid = sweep_adaptive(
        outer_profile,
        spine,
        inner_profiles=[inner_profile],  # one or more voids
        angle_threshold_deg=5.0
    )

API Reference
-------------

Key Functions
~~~~~~~~~~~~~

``yapcad.brep``:

* ``import_step(path)`` - Import STEP file
* ``write_step_analytic(solid, path)`` - Export analytic STEP
* ``brep_from_solid(solid)`` - Extract BREP wrapper
* ``solid_from_brep(shape)`` - Create solid from OCC shape

``yapcad.geom3d``:

* ``box(l, w, h)`` - Rectangular prism with BREP
* ``sphere(center, radius)`` - Sphere with BREP
* ``cylinder(center, axis, radius, height)`` - Cylinder with BREP
* ``cone(center, axis, radius1, radius2, height)`` - Cone/frustum with BREP

``yapcad.geom3d_util``:

* ``extrude(profile, direction, height)`` - Linear extrusion
* ``makeRevolutionSolid(profile, axis, angle)`` - Revolution
* ``makeLoftSolid(profiles)`` - Loft through profiles
* ``sweep_adaptive(profile, spine, ...)`` - Adaptive sweep

Testing
-------

BREP tests are in ``tests/test_brep.py`` and ``tests/test_step_import.py``.
Run with::

    PYTHONPATH=./src pytest tests/test_brep.py -v

Limitations
-----------

* Complex surfaces (NURBS, offset) may tessellate during operations
* Boolean operations on complex geometry may fail; check results
* Performance depends on OCC installation quality

Future Work
-----------

* Improved NURBS surface support
* Direct BREP editing operations
* Better error reporting for failed operations
* Integration with DSL for BREP-specific operations