build123d/docs/tutorial_stl_reconstruction.rst

.. _stl_reconstruction_tutorial:

#############################################
Tutorial: Reconstructing a Design from an STL
#############################################

This tutorial describes a practical workflow for using
:func:`~build123d.detect_primitives` to help reconstruct a parametric build123d
model from an STL mesh.

This is not a push-button STL-to-CAD converter. It is a mesh-guided redesign
process. The goal is to extract enough analytic structure from a triangulated
model to make manual reconstruction faster and more reliable.

.. warning::

    Rebuilding a design from STL is usually slow, approximate, and manual.
    STL files contain triangles, not modeling intent. Even when
    :func:`~build123d.detect_primitives` finds useful planes, cylinders, and
    spheres, the final build123d model still needs to be designed deliberately.

Before working through this tutorial, review Steps 1-3 of
:ref:`design_tutorial`. The same ideas apply here:

* identify planes of symmetry
* identify likely axes of rotation
* choose a convenient origin before doing any serious work

These preparation steps often reduce the amount of mesh that needs to be
reconstructed to one half, one quarter, or even less.

Overview
********

The workflow described here is:

1. Import the STL with :class:`~mesher.Mesher`.
2. Split the mesh by symmetry planes and isolate the region to redesign.
3. Save that reduced mesh section as a BREP file.
4. Reload the BREP section while iterating on reconstruction.
5. Run :func:`~build123d.detect_primitives`.
6. Inspect the returned primitives, leftovers, and generated code.
7. Rebuild the design intentionally from those clues.

The key output of ``detect_primitives`` is guidance:

* ``primitives`` shows what was recognized analytically
* ``leftovers`` shows what was not covered
* ``code_lines`` provides algebra-mode fragments that often reveal common
  planes and likely sketch structure

Why Cache a Working Section as BREP?
************************************

Importing STL with :class:`~mesher.Mesher` is convenient, but large meshes can be
slow to load and process. Once a useful section of the part has been isolated,
save it as a BREP file and use that for repeated experimentation.

BREP files reload much more efficiently in build123d and are better suited to
an iterative reconstruction script.

Preparing the Mesh
******************

Start with the STL import and isolate the smallest useful section of the part.

.. code-block:: build123d

    from build123d import *

    importer = Mesher()
    full_mesh = importer.read("target_part.stl")[0]

    # Example: reduce the work to one quarter of a symmetric model
    quarter_mesh = split(full_mesh, Plane.YZ)
    quarter_mesh = split(quarter_mesh, Plane.XZ)

    export_brep(quarter_mesh, "target_part_quarter.brep")

The exact planes depend on the part. The point is not to begin running
``detect_primitives`` on the full mesh if symmetry can remove most of the work.

Reconstruction Script
*********************

Once the mesh section has been cached as BREP, iterate on a separate script or
enable a reconstruction section of the same script with a Boolean switch.

.. code-block:: build123d

    from build123d import *

    working_mesh = import_brep("target_part_quarter.brep")

    primitives, leftovers, code_lines = detect_primitives(working_mesh)

    print(*code_lines, sep="\n")

This call returns three complementary outputs:

``primitives``
    A :class:`~topology.ShapeList` of analytic faces that were recognized from
    the mesh. These are typically planes, cylinders, and spheres. Planar
    primitives are returned as rectangles sized to the planar region's
    bounding box, not as the original tessellated mesh patch.

``leftovers``
    Mesh faces that were not matched by the primitive detectors. These indicate
    freeform regions, noisy regions, or places where manual work is still
    required.

``code_lines``
    Generated algebra-mode code corresponding to the recognized primitives.

Inspecting the Results
**********************

The inspection step is the heart of this workflow.

1. Examine the primitives visually
==================================

Look at the returned ``primitives`` and decide what the detector found well.

Useful questions include:

* Are the expected planar faces present?
* Do fillets appear as cylinders?
* Do rounded corners appear as spheres?
* Are repeated features recognized consistently?

In a simple mechanical part, good output often consists of a small number of
common planes, repeated cylinders with similar radii, and only a few leftovers.

2. Examine the leftovers
========================

``leftovers`` show what still needs manual interpretation.

Large leftover regions often indicate one of three things:

* the part contains geometry that is not well approximated by planes,
  cylinders, or spheres
* the mesh is noisy or irregular
* the working section is still too large to interpret comfortably

If too much of the mesh appears in ``leftovers``, it may be better to refine
the working section, identify more symmetry, or redesign that area manually
instead of trying to automate it further.

3. Examine the generated code
=============================

The generated ``code_lines`` are intentionally written in Algebra mode and use
``Plane * Pos`` structure to make repeated placement patterns easier to spot.

This often helps answer questions such as:

* which faces lie on the same construction plane?
* which circles belong to the same sketch?
* which cylindrical or spherical regions are repeated instances of one feature?

Treat this code as an annotated report, not necessarily as the final model.

For planar parts in particular, the generated lines are often naturally grouped
by plane. A sequence such as ``Plane.XY.offset(...)`` with a few repeated
offset values usually indicates related structure that may belong to one sketch
or one construction stage.

Worked Example: Filleted Box
****************************

As a controlled example, consider a filleted box:

.. code-block:: build123d

    fillet_box = fillet(Box(1, 1, 1).edges(), 0.1)

Running ``detect_primitives`` on this geometry produces output like:

.. code-block:: build123d

    r00 = Plane.XY.offset(-0.5) * Pos(-0.4, -0.4) * Rectangle(0.8, 0.8, align=Align.MIN)
    c01 = Plane.XY.offset(-0.4) * Pos(0.4, 0.4) * Face.extrude(Circle(0.0999996).edge(), (0, 0, 0.8))
    c02 = Plane.XY.offset(-0.4) * Pos(-0.4, 0.4) * Face.extrude(Circle(0.0999996).edge(), (0, 0, 0.8))
    c03 = Plane.XY.offset(-0.4) * Pos(-0.4, -0.4) * Face.extrude(Circle(0.0999996).edge(), (0, 0, 0.8))
    c04 = Plane.XY.offset(-0.4) * Pos(0.4, -0.4) * Face.extrude(Circle(0.0999996).edge(), (0, 0, 0.8))
    r05 = Plane.XY.offset(0.5) * Pos(-0.4, -0.4) * Rectangle(0.8, 0.8, align=Align.MIN)
    r06 = Plane.YZ.offset(-0.5) * Pos(-0.4, -0.4) * Rectangle(0.8, 0.8, align=Align.MIN)
    c07 = Plane.YZ.offset(-0.4) * Pos(-0.4, -0.4) * Face.extrude(Circle(0.0999996).edge(), (0, 0, 0.8))
    c08 = Plane.YZ.offset(-0.4) * Pos(-0.4, 0.4) * Face.extrude(Circle(0.0999996).edge(), (0, 0, 0.8))
    c09 = Plane.YZ.offset(-0.4) * Pos(0.4, -0.4) * Face.extrude(Circle(0.0999996).edge(), (0, 0, 0.8))
    c10 = Plane.YZ.offset(-0.4) * Pos(0.4, 0.4) * Face.extrude(Circle(0.0999996).edge(), (0, 0, 0.8))
    r11 = Plane.YZ.offset(0.5) * Pos(-0.4, -0.4) * Rectangle(0.8, 0.8, align=Align.MIN)
    r12 = Plane.ZX.offset(-0.5) * Pos(-0.4, -0.4) * Rectangle(0.8, 0.8, align=Align.MIN)
    c13 = Plane.ZX.offset(-0.4) * Pos(-0.4, 0.4) * Face.extrude(Circle(0.0999996).edge(), (0, 0, 0.8))
    c14 = Plane.ZX.offset(-0.4) * Pos(-0.4, -0.4) * Face.extrude(Circle(0.0999996).edge(), (0, 0, 0.8))
    c15 = Plane.ZX.offset(-0.4) * Pos(0.4, -0.4) * Face.extrude(Circle(0.0999996).edge(), (0, 0, 0.8))
    c16 = Plane.ZX.offset(-0.4) * Pos(0.4, 0.4) * Face.extrude(Circle(0.0999996).edge(), (0, 0, 0.8))
    r17 = Plane.ZX.offset(0.5) * Pos(-0.4, -0.4) * Rectangle(0.8, 0.8, align=Align.MIN)
    s18 = Pos((0.399999, -0.399999, 0.400026)) * Sphere(0.099983).faces().filter_by(GeomType.SPHERE)[0]
    s19 = Pos((-0.399999, 0.399999, -0.400026)) * Sphere(0.099983).faces().filter_by(GeomType.SPHERE)[0]
    s20 = Pos((-0.399999, -0.399999, -0.400026)) * Sphere(0.099983).faces().filter_by(GeomType.SPHERE)[0]
    s21 = Pos((0.399999, 0.399999, -0.400026)) * Sphere(0.099983).faces().filter_by(GeomType.SPHERE)[0]
    s22 = Pos((-0.399999, 0.400026, 0.399999)) * Sphere(0.099983).faces().filter_by(GeomType.SPHERE)[0]
    s23 = Pos((-0.399999, -0.399999, 0.400026)) * Sphere(0.099983).faces().filter_by(GeomType.SPHERE)[0]
    s24 = Pos((0.399999, 0.400026, 0.399999)) * Sphere(0.099983).faces().filter_by(GeomType.SPHERE)[0]
    s25 = Pos((0.399999, -0.399999, -0.400026)) * Sphere(0.099983).faces().filter_by(GeomType.SPHERE)[0]

This output is informative in several ways:

* the six box faces appear as rectangles on three principal planes
* the edge fillets appear as cylinders grouped around those same planes
* the corner blends appear as spheres near the eight cube corners

The generated code is also structured by plane:

* ``Plane.XY.offset(...)`` appears with three distinct offsets
* ``Plane.YZ.offset(...)`` appears with three distinct offsets
* ``Plane.ZX.offset(...)`` appears with three distinct offsets

That organization is often more useful than any one primitive by itself
because it suggests how the model could be regrouped into sketches and
construction steps.

Although this output is correct and useful, it still does not represent the
best final build123d model. The original design intent is much simpler:

.. code-block:: build123d

    fillet(Box(1, 1, 1).edges(), 0.1)

That is a good example of the main lesson of this tutorial: the generated code
helps reveal structure, but the final model should usually be rewritten in a
cleaner, higher-level form.

Turning Primitive Hints into Sketches
*************************************

Once repeated planes become obvious in ``code_lines``, start grouping related
features into sketches and features of your own.

For example:

* several rectangles on ``Plane.XY`` may indicate one base sketch and one or
  more extrusions
* repeated circles on one plane may indicate hole or boss locations
* a collection of cylinders with the same radius may indicate that a fillet or
  round was part of the original design intent

The generated code is often most useful when treated as:

* a list of candidate construction planes
* a list of likely sketch elements
* a list of repeated primitive sizes and placements

Signs of Good Output
********************

``detect_primitives`` is most helpful when:

* the mesh is reasonably clean
* the part is mostly mechanical
* many surfaces are planar, cylindrical, or spherical
* there are clear planes of symmetry or repeated features

In these cases, primitives and generated code often cluster into obvious
reconstruction steps.

Signs of Poor Output
********************

Expect more manual work when:

* the mesh contains freeform surfaces
* the STL is noisy or heavily tessellated
* the part has no obvious symmetry
* many important regions remain in ``leftovers``
* the generated code contains many tiny or redundant fragments

When this happens, it may be faster to use the mesh only as a visual reference
and rebuild the part manually from dimensions and intent.

Summary
*******

The STL reconstruction workflow in build123d is:

1. analyze the part as a designer, not as a mesh processor
2. isolate the smallest useful region with symmetry and splitting
3. cache that region as BREP
4. run :func:`~build123d.detect_primitives`
5. inspect primitives, leftovers, and code
6. rebuild the part intentionally in build123d

The most useful mindset is to treat ``detect_primitives`` as a design assistant.
It can show where the planes, cylinders, and spheres probably are, but the
final parametric model still comes from careful human interpretation.