Architecture: Behind the Scenes

This page explains the core principles and shared logic between the CLI and the Web App.

Technical Goals

The primary goal is to convert 2D Vector paths (infinite precision curves) into 3D Manifold meshes (polygonal surfaces) while preserving:

Multi-color separation (based on CSS classes).
Structural integrity (handling holes and overlapping shapes).
Dimensional accuracy (standardizing output size).

1. The Discretization Problem

SVG paths are defined by cubic and quadratic Bézier curves. 3D printers require triangulated meshes (STL). The first step is always Discretization:

CLI (Python): Uses svg.path to sample points. It employs adaptive sampling for smoother curves.
Web App (JS): Uses the browser's getPointAtLength() API. This is highly efficient as it leverages the browser's native C++ implementation of SVG math.

2. Even-Odd Fill Rule

Handling "holes" is the most complex part of vector-to-geometry conversion. Both tools use the Even-Odd rule:

A point is considered "inside" if a ray starting from that point crosses an odd number of path segments.
CLI: Implements this using Shapely's symmetric_difference (XOR) on nested polygons.
Web App: Implements this using Manifold's CrossSection with the EvenOdd fill rule.

3. The Geometry Engine

Once we have 2D polygons:

Python: Uses trimesh, which is a robust surface-mesh library. It handles extrusion by creating a top and bottom cap and sewing them together with a side-wall.
WebAssembly: Uses Manifold-3d, which uses signed distance functions (SDF) logic under the hood to ensure the output is always "Water-tight" (manifold). This is critical for 3D printing to avoid slicing errors.

4. Multi-Material Workflow

The system splits the STL into three parts:

Base: The silhouette of the nametag.
Primary: The main text (White).
Accent: logos or sub-text (Cyan).

By placing them at different Z-heights or as separate parts in a single object, slicers (like Bambu Studio or PrusaSlicer) can easily assign different colors to different parts of the print.

Data Flow Diagram

graph TD
    A[SVG File] --> B{Classifier}
    B -->|class='st1'| C[Cyan Layer]
    B -->|class='st2'| D[White Layer]
    B -->|default| E[Background Layer]
    
    C --> F[Discretize to Points]
    D --> F
    E --> F
    
    F --> G[Boolean Operations / Holes]
    G --> H[Extrude to 3D]
    H --> I[Scale to 87.80mm]
    I --> J[Export STL]