From 0531920d3746cfd58f9e9001cdcd6fa187303720 Mon Sep 17 00:00:00 2001 From: unfunny Date: Sat, 14 Feb 2026 19:44:24 -0500 Subject: [PATCH] docs: add self-hosting guide and revise web app walkthrough for a better user experience. --- Home.md | 1 + Self-Hosting.md | 138 +++++++++++++++++++++++++++++++++++ Walkthrough-%28CLI%29.md | 2 + Walkthrough-%28Web-App%29.md | 84 ++++++++++----------- 4 files changed, 180 insertions(+), 45 deletions(-) create mode 100644 Self-Hosting.md diff --git a/Home.md b/Home.md index 3772772..7ad878f 100644 --- a/Home.md +++ b/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. diff --git a/Self-Hosting.md b/Self-Hosting.md new file mode 100644 index 0000000..4561dc6 --- /dev/null +++ b/Self-Hosting.md @@ -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. diff --git a/Walkthrough-%28CLI%29.md b/Walkthrough-%28CLI%29.md index 9d99fee..d2f4443 100644 --- a/Walkthrough-%28CLI%29.md +++ b/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 diff --git a/Walkthrough-%28Web-App%29.md b/Walkthrough-%28Web-App%29.md index 250d0b5..5d2cdca 100644 --- a/Walkthrough-%28Web-App%29.md +++ b/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.