diff --git a/Architecture.md b/Architecture.md new file mode 100644 index 0000000..9904758 --- /dev/null +++ b/Architecture.md @@ -0,0 +1,55 @@ +# 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: +1. **Multi-color separation** (based on CSS classes). +2. **Structural integrity** (handling holes and overlapping shapes). +3. **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 +```mermaid +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] +``` diff --git a/Home.md b/Home.md index eb87070..3772772 100644 --- a/Home.md +++ b/Home.md @@ -1 +1,15 @@ -Welcome to the Wiki. +# svg2nametag-Ren + +Welcome to the **svg2nametag-Ren** wiki! This project provides tools to convert 2D SVG designs into 3D printable nametag models (STL). It specifically targets multi-material or multi-color 3D prints by generating separate STL files for different layers/colors based on SVG class mappings. + +## Quick Links +- [[Walkthrough-(CLI)]]: Learn how to use the Python command-line tool for bulk conversions. +- [[Walkthrough-(Web-App)]]: Learn how to use the client-side Web application for a visual experience. +- [[Architecture]]: Deep dive into the geometry logic and "behind the scenes" math. + +## Features +- **Automatic Multi-Material Separation**: Detects colors based on SVG classes (`st1`, `st2`) and creates separate STL files. +- **Precision Scaling**: Automatically scales designs to a standard nametag width (87.80mm). +- **Hole Handling**: Correctly processes "Even-Odd" fill rules found in complex SVG paths (like letters with holes). +- **Two Modalities**: Bulk processing via Python CLI or interactive processing via Web App. +- **Behind the Scenes**: Uses high-performance libraries like `Shapely` and `Manifold (WASM)` for geometry processing. diff --git a/Walkthrough-%28CLI%29.md b/Walkthrough-%28CLI%29.md index 6f3ef34..9d99fee 100644 --- a/Walkthrough-%28CLI%29.md +++ b/Walkthrough-%28CLI%29.md @@ -1,52 +1,71 @@ -# SVG to Nametag Converter Walkthrough -This guide explains how to use the convert_nametags.py script to generate 3D printable STL files from SVGs. +# Walkthrough (CLI) -## Overview -The script processes -.svg - files and generates three separate STL files for each nametag. This allows you to assign different filaments to each part in Bambu Studio: +The Python CLI tool `convert_nametags.py` is designed for bulk processing of SVG files into 3D printable STL models. -Black: The base/background (3mm thick). -White: The Name text (2mm thick). -Cyan: The Title/Logo (2mm thick). -The script also automatically scales every nametag to a width of 87.80mm. +## Usage Guide -### Usage -1. Setup Environment -Ensure you are in the project directory. -`cd /your/path/here/svg2nametagRen` -Create a virtual environment (or venv) and switch to it -`python -m venv` -`source .venv/bin/activate` -Install depedencies -`pip install -r requirements.txt` +### 1. Environment Setup +Ensure you have Python 3 installed. It is recommended to use a virtual environment: +```bash +# Create and activate virtual environment +python -m venv .venv +source .venv/bin/activate -2. Run the Script -You can run the script on a single file or a whole directory. - -Process the entire drive: - - -`python3 convert_nametags.py "/media/unfunny/FREEDOM" --output-dir "/home/unfunny/Desktop/Nametags_STL" ` - -Output Structure -The script creates a folder for each nametag containing its three STL files: +# Install dependencies +pip install -r requirements.txt ``` -Output_Directory/ -├── Jordan/ -│ ├── Jordan_Black.stl -│ ├── Jordan_White.stl -│ └── Jordan_Cyan.stl -└── Staff Nametags_Data Set 30-01/ - ├── Staff Nametags_Data Set 30-01_Black.stl - ├── Staff Nametags_Data Set 30-01_White.stl - └── Staff Nametags_Data Set 30-01_Cyan.stl - ``` -Printing Instructions (Bambu Studio) -Open Bambu Studio. -Drag all three .stl files for a single nametag into the plate at the same time. -Bambu Studio will ask: "Load these files as a single object with multiple parts?" -> Select Yes. -Go to the Objects view (left panel). -Select each part and assign the correct filament color. -Slice and print! \ No newline at end of file + +### 2. Running the Conversion +The script takes an input directory containing SVG files and produces an output directory with STLs. + +```bash +python3 convert_nametags.py /path/to/svgs --output-dir /path/to/output +``` + +If `--output-dir` is omitted, it defaults to a folder named `stl_output` inside the input directory. + +### 3. Output Structure +For every SVG file (e.g., `Name.svg`), the script creates a folder named `Name` containing: +- `Name_Black.stl`: The base/background. +- `Name_White.stl`: Elements with class `st2` (primary text). +- `Name_Cyan.stl`: Elements with class `st1` (accent text/logo). + +--- + +## How it Works (Under the Hood) + +### 1. SVG Parsing & Classification +The script uses `xml.dom.minidom` to parse the SVG structure. It extracts `` elements and classifies them into three logical "layers": +- **White**: Paths with `class="st2"`. +- **Cyan**: Paths with `class="st1"`. +- **Black (Background)**: Paths with any other class (or no class). + +### 2. Geometry Discretization +SVG paths are mathematical curves (Beziers, Arcs). To convert them to 3D, we first turn them into 2D polygons using the `svg.path` library. +- It samples the curves at a specific resolution (`CURVE_RESOLUTION = 64`). +- It uses **adaptive sampling** for Beziers, increasing points based on the curve length to ensure smoothness. + +### 3. 2D Boolean Logic (Hole Handling) +One of the trickiest parts of SVG-to-3D is handling holes (e.g., the center of an 'O'). +- The script uses `Shapely` to perform **Symmetric Difference** (XOR) operations on nested loops. This correctly implements the **Even-Odd** fill rule common in vector graphics. +- Multiple paths of the same color are merged using `unary_union` to create a single manifold shape. + +### 4. 3D Extrusion +Once we have a clean 2D polygon with holes: +- It uses `trimesh.creation.extrude_polygon` to turn the 2D shape into a 3D volume. +- **Background** is extruded to **3.0mm**. +- **Text/Logo** is extruded to **2.0mm** and offset by **3.0mm** along the Z-axis, placing it perfectly on top of the background. + +### 5. Automatic Scaling +To ensure consistency across different SVG sources: +- The script measures the bounding box of the background path. +- It calculates a scale factor to bring the total width to exactly **87.80mm**. +- This scale factor is then applied consistently to all color layers. + +## Printing Instructions (Bambu Studio) +1. Open Bambu Studio. +2. Drag all three STL files for one nametag into the plate simultaneously. +3. When prompted, select **"Load these files as a single object with multiple parts?"**. +4. In the **Objects** tab, assign the respective filaments to each part. +5. Slice and print! \ No newline at end of file diff --git a/Walkthrough-%28Web-App%29.md b/Walkthrough-%28Web-App%29.md new file mode 100644 index 0000000..250d0b5 --- /dev/null +++ b/Walkthrough-%28Web-App%29.md @@ -0,0 +1,53 @@ +# Walkthrough (Web App) + +The Web App provides a modern, interactive way to convert SVGs to nametags directly in your browser without installing Python. + +## Usage Guide + +### 1. Launching the App +The app is built with Vite and React. To run it locally: + +```bash +cd webapp +npm install +npm run dev +``` + +### 2. Processing Files +- **Upload**: Drag and drop SVG files or select a folder. +- **Preview**: The app displays the processing status for each file. +- **Download**: Once processed, click the buttons to download the generated STL files. + +--- + +## How it Works (Under the Hood) + +The Web App mirrors the logic of the Python script but is optimized for client-side performance using WebAssembly. + +### 1. High-Performance Boolean Engine (Manifold WASM) +Unlike the CLI which uses `trimesh` and `shapely`, the Web App uses **[Manifold](https://github.com/elalish/manifold)**. +- Manifold is a state-of-the-art geometry library compiled to **WebAssembly (WASM)**. +- It provides nearly instantaneous 3D boolean operations (merging paths, subtracting holes) directly in the browser. + +### 2. Browser-Native SVG Parsing +Instead of a separate library, the app utilizes the browser's own rendering engine: +- It creates off-screen `SVGPathElement` nodes. +- It uses `pathEl.getTotalLength()` and `pathEl.getPointAtLength()` to sample the curve into a series of points (discretization). +- This ensures that the conversion exactly matches what you see in the browser. + +### 3. Geometry Pipeline +1. **Classification**: Paths are sorted into Black, White (class `st2`), and Cyan (class `st1`). +2. **Path to CrossSection**: Points are fed into Manifold's `CrossSection` object using the `EvenOdd` fill rule to handle nested holes. +3. **WASM Multi-threading**: The heavy geometry computation happens in the WASM module, keeping the UI responsive. +4. **Three.js STL Export**: The resulting Manifold mesh is converted to a `Three.js` BufferGeometry and exported as a binary STL blob for download. + +### 4. Technical Specs +- **Background Thickness**: 3.0mm +- **Text Thickness**: 2.0mm +- **Z-Offset**: 4.0mm (Raised slightly above the base for clear visual separation). +- **Target Width**: 87.80mm (Automatically scaled). + +## Advantages of the Web App +- **No Dependencies**: No need to install Python or libraries like `trimesh` (which can be difficult to install on some OSs). +- **Instant Preview**: Feedback on whether an SVG is being parsed correctly. +- **Cross-Platform**: Works on any modern browser.