bosl2 — a pure-Python PythonSCAD port of BOSL2
==============================================

``bosl2`` is a pure-Python / numpy port of the pieces of `BOSL2 <https://github.com/BelfrySCAD/BOSL2>`_
that this toolkit uses, with **no** ``osuse()``/BOSL2 runtime dependency. Every operation hangs off
an object — :class:`~bosl2.paths.Path` for 2-D outlines, :class:`~bosl2.regions.Region` for
outlines-with-holes, :class:`~bosl2.beziers.Bezier` / :class:`~bosl2.beziers.BezierPatch` for bezier
curves and surfaces, :class:`~bosl2.vnf.VNF` for vertex-face meshes, and the
:class:`~bosl2.shapes3d.Bosl2Solid` primitives — so new code reads as fluent chains::

    Path([[0, 0], [80, 0], [80, 60], [0, 60]]).offset(r=-2).round_corners(radius=1).polygon()

.. raw:: html

   <p style="margin:1.4em 0;padding:14px 18px;border:1px solid #38bdf0;border-radius:10px;
      background:rgba(56,189,240,0.07);font-size:1.05em;">
     &#9881;&#65039; <b><a href="specs/index.html">Visual parts catalog &amp; spec sheets &rarr;</a></b>
     &nbsp;&mdash;&nbsp; the gears, hinges, joiners, cube-truss and ball-bearing modules with
     technical schematics and metrics measured from real rendered STL.
   </p>

Rendered examples
-----------------

Every documented function with a rendered example shows both the exact PythonSCAD code and what the
real PythonSCAD binary builds for it, via the ``pythonscad-example`` directive (in
``docs/_ext/bosl2_example.py``): an **interactive 3-D viewer** for the exported STL mesh (rotate,
pan and zoom — served by the ``stl_viewer`` extension's three.js viewer, a working drop-in for the
``sphinxstl`` ``.. stl::`` directive), plus a **download link** to the mesh. Two-dimensional or
open-surface examples that have no solid mesh fall back to a static preview image.

.. note::

   The interactive viewers fetch each ``.stl`` over HTTP, so view the built docs through a web
   server (for example ``python3 -m http.server`` from ``bosl2/wiki``) rather than opening the
   HTML files directly with a ``file://`` URL, where browsers block the local mesh fetch. You can
   also embed a viewer for any STL yourself with ``.. stl:: path/to/mesh.stl``.

A cuboid primitive:

.. pythonscad-example::

   s3.cuboid([40, 30, 20], rounding=4).show()

A bezier surface patch, meshed to a VNF and rendered as a polyhedron:

.. pythonscad-example::

   patch = [
       [[-50, -50, 0], [-16, -50, 20], [16, -50, -20], [50, -50, 0]],
       [[-50, -16, 20], [-16, -16, 20], [16, -16, -20], [50, -16, 20]],
       [[-50, 16, 20], [-16, 16, -20], [16, 16, 20], [50, 16, 20]],
       [[-50, 50, 0], [-16, 50, -20], [16, 50, 20], [50, 50, 0]],
   ]
   BezierPatch(patch).sheet([0, -6], splinesteps=16).polyhedron().show()

Sweeping a profile along a bezier curve:

.. pythonscad-example::

   circle = [[2 * math.cos(t), 2 * math.sin(t)] for t in np.linspace(0, 2 * math.pi, 24, endpoint=False)]
   Bezier([[0, 0, 5], [0, 0, 20], [25, 12, 15], [30, 4, 6]]).sweep(circle, splinesteps=24).polyhedron().show()

API reference
-------------

The modules are grouped by role, mirroring BOSL2's own organisation. **Foundational** holds the
primitives and transforms most models start from; **Paths, regions & surfaces** the advanced
2-D/3-D modelling toolkit; **Math & geometry** the numeric helpers; and **Parts library** the
ready-made mechanical parts — each with a visual spec sheet in the catalog linked above.

.. toctree::
   :maxdepth: 1
   :caption: Solid backends

   CSG & SDF backends <backends>

.. toctree::
   :maxdepth: 1
   :caption: Foundational

   3-D shapes <shapes3d>
   2-D shapes <shapes2d>
   Transforms <transforms>
   Distributors <distributors>
   Drawing <drawing>
   Colour <color>
   Masking <masking>
   Partitions <partitions>
   Native ops <native_ops>
   Textures <texture>
   Constants <constants>

.. toctree::
   :maxdepth: 1
   :caption: Paths, regions & surfaces

   Paths <paths>
   Regions <regions>
   Rounding <rounding>
   Turtle (3-D) <turtle3d>
   Beziers <beziers>
   NURBS <nurbs>
   Skin & sweeps <skin>
   VNF meshes <vnf>
   Isosurface <isosurface>

.. toctree::
   :maxdepth: 1
   :caption: Math & geometry

   Geometry <geometry>
   Math <math>
   Vectors <vectors>
   Comparisons <comparisons>

.. toctree::
   :maxdepth: 1
   :caption: Parts library

   Gears <gears>
   Threading <threading>
   Screws <screws>
   Screw drives <screw_drive>
   Bottle caps <bottlecaps>
   NEMA steppers <nema_steppers>
   Cube trusses <cubetruss>
   Hinges <hinges>
   Joiners <joiners>
   Hooks <hooks>
   Walls <walls>
   Wiring <wiring>
   Sliders <sliders>
   Polyhedra <polyhedra>
   Ball bearings <ball_bearings>
   Linear bearings <linear_bearings>
   Modular hose <modular_hose>

.. toctree::
   :maxdepth: 1
   :caption: Extras

   Miscellaneous <miscellaneous>