Retro/svg2NameTag-Ren
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Add architecture and web app walkthrough, and enhance CLI and home page documentation.

unfunny
2026-02-14 17:43:36 -05:00
parent 6e240c5e4c
commit f1cf4a4f46
4 changed files with 188 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
Architecture.md Normal file

@@ -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]
```

16
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.

111
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!
### 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 `<path>` 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!

53
Walkthrough-%28Web-App%29.md Normal file

@@ -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.