3

Walkthrough (CLI)

unfunny edited this page 2026-02-14 19:44:24 -05:00

Table of Contents

• Walkthrough (CLI)
• Usage Guide
• 1. Environment Setup
• 2. Running the Conversion
• 3. Output Structure
• How it Works (Under the Hood)
• 1. SVG Parsing & Classification
• 2. Geometry Discretization
• 3. 2D Boolean Logic (Hole Handling)
• 4. 3D Extrusion
• 5. Automatic Scaling
• Printing Instructions (Bambu Studio)

Walkthrough (CLI)

Note

: For a simpler, visual experience without command-line usage, try the Walkthrough-(Web-App).

The Python CLI tool convert_nametags.py is designed for bulk processing of SVG files into 3D printable STL models.

Usage Guide

1. Environment Setup

Ensure you have Python 3 installed. It is recommended to use a virtual environment:

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2. Running the Conversion

The script takes an input directory containing SVG files and produces an output directory with STLs.

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!