Skip to content

README.md

Latest commit

 

History

History
135 lines (91 loc) · 4.46 KB

README.md

File metadata and controls

135 lines (91 loc) · 4.46 KB

CardBoxGen — Laser-cut Card Tray / Dispenser SVG Generator

Parametric SVG generator for 3mm laser-cut board card trays / dispensers / boxes.

This project focuses on:

  • Correct cavity sizing (inner dimensions are the source of truth)
  • Reliable finger joints that always mate (deterministic edge pairing)
  • Practical kerf + fit handling for press-fit / friction-fit
  • Browser-first workflow via a static Pyodide web app (GitHub Pages)

Current version: v0.6

Live web app:

Key Names (presets + parts)

Presets (--preset)

  • tray_open_front: open top, lowered/open front, optional scoop
  • dispenser_slot_front: front present with dispense slot
  • window_front: front with large window cutout + thumb notch
  • box_with_lid: box + slip lid

Panel names (SVG group IDs)

  • Base: BOTTOM, BACK, LEFT, RIGHT, optional FRONT
  • Lid (preset box_with_lid): LID_TOP, LID_BACK, LID_FRONT, LID_LEFT, LID_RIGHT

SVG layer/group conventions

  • CUT (red stroke, 0.2)
  • ENGRAVE (text/labels, black)

How Finger Joints Are Made (no “phase guessing”)

Instead of choosing a “phase” per panel edge, the generator defines mating edge pairs. Each pair shares one computed FingerPlan (finger count + segment widths). One side uses the plan, the other side uses the complement (tabs vs slots), so the two edges always match.

Finger count is stable:

$$n = \max(\text{min_fingers}, \lfloor L / w_{target} \rfloor)$$

Then n is forced odd.

Optional: force fixed counts per joint family:

  • --finger-count-outer
  • --finger-count-vertical

Kerf + Clearance Model

Parameters:

  • --kerf-mm: laser kerf (typical ~0.15–0.25mm)
  • --clearance-mm: desired slot–tab clearance (0.00 tight → 0.25 looser)

We model in-plane finger width compensation (so tabs/slots fit after cutting):

  • Tabs (external features) shrink after cutting by ~kerf.
  • Slots (internal openings) grow after cutting by ~kerf.

Symmetric drawn-width rule used in the generator:

$$w_{tab,drawn} = w_{nominal} + (kerf - clearance/2)$$ $$w_{slot,drawn} = w_{nominal} + (clearance/2 - kerf)$$

Widths are normalized per edge so the total length stays exactly $L$.

Local CLI

Acceptance example:

  • python3 cardboxgen_v0_1.py --preset tray_open_front --inner-width 135 --inner-depth 90 --inner-height 225 --thickness 3 --kerf 0.2 --clearance 0.15 --out out.svg

Optional holding tabs (bridges so parts don’t drop out while cutting):

  • python3 cardboxgen_v0_1.py --preset tray_open_front --inner-width 135 --inner-depth 90 --inner-height 225 --thickness 3 --kerf 0.2 --clearance 0.15 --holding-tabs --tab-width 2 --out out.svg

Calibration SVG (mating strips across clearances):

  • python3 cardboxgen_v0_1.py --calibration --kerf 0.2 --thickness 3 --out calibration.svg

Local Web App (recommended)

The web app runs fully in your browser via Pyodide.

  1. Sync generator into the web folder:
  • python3 tools/sync_docs.py
  1. Start a local static server:
  • python3 -m http.server 8000
  1. Open:
  • http://localhost:8000/docs/

Examples

  • python3 examples/generate_examples.py

Outputs in examples/:

  • tray_open_front.svg
  • dispenser_slot_front.svg
  • box_with_lid.svg
  • calibration_mating_strips.svg

Tests

Dev deps:

  • pip install -r requirements-dev.txt

Run:

  • pytest -q

GitHub Pages

This repo includes an Actions workflow to deploy docs/ to GitHub Pages.

Steps:

  1. Push to main or master
  2. GitHub repo → Settings → Pages → Source: GitHub Actions
  3. Wait for the “Deploy GitHub Pages” workflow to finish

Your site URL will be:

  • https://<user>.github.io/<repo>/

Versioning + Releases

Release checklist (for a new version):

  • Bump __version__ in both generator copies (or bump root + run python3 tools/sync_docs.py).
  • Update APP_VERSION and app.version strings.
  • Run tests: pytest -q
  • Commit, then tag and publish:
    • git tag -a vX.Y -m "CardBoxGen vX.Y"
    • git push origin vX.Y
    • (optional) gh release create vX.Y --title "vX.Y" --notes-file CHANGELOG.md

See CHANGELOG.md for published versions.