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

docs: add self-hosting guide and revise web app walkthrough for a better user experience.

unfunny
2026-02-14 19:44:24 -05:00
parent f1cf4a4f46
commit 0531920d37
4 changed files with 180 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
Home.md

@@ -6,6 +6,7 @@ Welcome to the **svg2nametag-Ren** wiki! This project provides tools to convert
- [[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.
- [[Self-Hosting]]: Guide on deploying the web app to your own server.
## Features
- **Automatic Multi-Material Separation**: Detects colors based on SVG classes (`st1`, `st2`) and creates separate STL files.

138
Self-Hosting.md Normal file

@@ -0,0 +1,138 @@
# Self-Hosting Guide
The **svg2nametag-Ren** web app is a static site that can be hosted on any modern web server (Nginx, Apache, Caddy) or static hosting service (GitHub Pages, Netlify, Vercel).
## Prerequisites
- **Node.js**: Version 18 or higher.
- **npm** or **yarn**.
---
## 1. Build the Application
Before deploying, you must generate the optimized production build:
```bash
cd webapp
npm install
npm run build
```
This will create a `dist` folder containing the compiled HTML, JavaScript, CSS, and the required WebAssembly (WASM) files.
## 2. Server Configuration
The app uses **WebAssembly (WASM)** for geometry processing. Your web server **must** serve `.wasm` files with the correct MIME type: `application/wasm`.
### Nginx Example
Add this to your `server` block:
```nginx
server {
listen 80;
server_name your-domain.com;
root /path/to/svg2nametagRen/webapp/dist;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
# Ensure WASM files are served correctly
location ~* \.wasm$ {
default_type application/wasm;
add_header Cache-Control "public, max-age=31536000";
}
}
```
### Static Hosting (GitHub Pages / Netlify)
Most modern static hosts (Netlify, Vercel, GitHub Pages) automatically handle `.wasm` MIME types correctly. Simply point the "Publish Directory" to `webapp/dist`.
---
## 3. Local Hosting (Preview)
If you want to host the production build locally to test it:
```bash
npm run preview
```
## 4. Troubleshooting
### WASM Initialization Errors
If the app loads but fails to process SVGs with a "WASM loading" error:
1. Check the browser console.
2. Ensure `manifold.wasm` is present in the root of your deployment folder.
3. Verify that your server isn't blocking `.wasm` files or serving them as `text/plain`.
### Path Issues
If you are hosting the app in a subfolder (e.g., `https://example.com/nametag/`), you must update the `base` configuration in `webapp/vite.config.js`:
```javascript
export default defineConfig({
base: '/nametag/', // Add this line
plugins: [react()],
})
```
---
## 5. Containerization (OCI / Docker)
A `Dockerfile` is provided in the `webapp` directory for easy deployment using Docker or Podman.
### Build and Run
```bash
cd webapp
docker build -t nametag-web .
docker run -d -p 8080:80 nametag-web
```
The app will be available at `http://localhost:8080`.
### Docker Compose
Create a `docker-compose.yml` in the root directory:
```yaml
services:
nametag-web:
build: ./webapp
ports:
- "8080:80"
restart: unless-stopped
```
### CLI via Docker
If you prefer not to install Python locally, you can use the CLI via its own Dockerfile:
```bash
# Build the CLI image
docker build -t nametag-cli -f Dockerfile.cli .
# Run the conversion (mounts local directories into the container)
docker run --rm \
-v /path/to/your/svgs:/input \
-v /path/to/output:/output \
nametag-cli /input --output-dir /output
```
---
---
## 6. LXC (Linux Containers)
LXC is ideal for hosting on Proxmox or standard Linux servers where you want a lightweight system container.
### Manual Setup (Debian/Ubuntu LXC)
1. **Create the container** (e.g., using `pct` on Proxmox or `lxc-create`).
2. **Install Nginx and Node.js**:
```bash
apt update && apt install -y nginx nodejs npm
```
3. **Deploy the code**:
Clone the repo inside the LXC or copy the `dist` folder to `/var/www/html`.
4. **Configure Nginx**:
Use the Nginx configuration provided in [Section 2](#nginx-example).
5. **Permissions**:
Ensure `www-data` has access to the files:
```bash
chown -R www-data:www-data /var/www/html
```
### Proxmox Helper Script (Optional)
If you use Proxmox, you can use a generic Nginx LXC and simply rsync the `webapp/dist` folder into it.

2
Walkthrough-%28CLI%29.md

@@ -1,5 +1,7 @@
# 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

84
Walkthrough-%28Web-App%29.md

@@ -1,53 +1,47 @@
# Walkthrough (Web App)
The Web App provides a modern, interactive way to convert SVGs to nametags directly in your browser without installing Python.
The **svg2nametag-Ren** project includes a modern, client-side Web App powered by WebAssembly (WASM). This allows you to convert SVG files directly in your browser without needing to install Python or any dependencies on your machine.
## Usage Guide
## Features
- **Zero Install**: Runs entirely in the browser.
- **Offline Support (PWA)**: Once loaded, it works without an internet connection. Install it to your desktop or mobile device!
- **Batch Processing**: Drag & drop multiple files or select an entire folder.
- **Instant Preview**: Fast geometry processing using Manifold 3D.
- **Secure**: Files processed locally; nothing is uploaded to a server.
### 1. Launching the App
The app is built with Vite and React. To run it locally:
## Getting Started
```bash
cd webapp
npm install
npm run dev
```
### Running Locally (Development)
If you have the source code and want to run it yourself:
1. Navigate to the `webapp` directory:
```bash
cd webapp
```
2. Install dependencies:
```bash
npm install
```
3. Start the development server:
```bash
npm run dev
```
4. Open `http://localhost:5173` in your browser.
### 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.
### Using the App
1. **Open the App**: Launch the web app in your browser.
2. **Add Files**:
* **Drag & Drop**: Drag one or more `.svg` files into the dashed upload area.
* **Select Folder**: Click the folder icon in the top-right corner to select a directory containing SVGs.
3. **Wait for Engine**: Ensure the status indicator says **"Engine Ready"** in green.
4. **Convert**: Click the **"Convert & Download ZIP"** button.
5. **Download**: The app will process all files and automatically download a `Nametags_Converted.zip` file containing organized STL models for each nametag.
---
## Progressive Web App (PWA)
This app is a PWA, meaning you can install it as a standalone application.
1. Open the web app in a supported browser (Chrome, Edge, Safari).
2. Click the **"Install"** icon in the address bar (desktop) or "Add to Home Screen" (mobile).
3. Launch the app from your desktop/home screen. It will work **offline**!
## 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.
## Troubleshooting
- **"Engine Loading..." forever**: Ensure `manifold.wasm` is correctly served. Check the browser console (F12) for errors.
- **Blank Screen Offline**: Ensure you have launched the app at least once while online to cache resources.