# Fretboard Calculator & CAD Generator (`fretboard_calc.py`)

## 📜 Overview

`fretboard_calc.py` is a **professional-grade, command-line fretboard calculation and CAD export tool** intended for **luthiers, guitar builders, CNC operators, and CAD/CAM users** who need **precise fret positions** for musical instruments — including both **traditional single-scale** and **modern multiscale (fanned fret)** designs.

Unlike many basic calculators, this script does **not** simply dump fret distances; it can:

- Compute **per-string 12-TET fret positions** accurately using the closed-form equation.  
- Support **multiscale interpolation** (linear or exponential).  
- Output **tabular and structured data** suitable for spreadsheets and downstream CAD workflows.  
- Generate **parametric SVG or DXF drawings** of the fretboard including frets, strings, nut, bridge, and board outline.  
- Apply a **datum angle rotation**, allowing the entire fretboard to be rotated around the neutral fret without changing the geometry.

The goal is to **bridge the gap between theoretical fret spacing math and practical CAD/CAM fabrication**.

---

## 🧮 Core Functionality

The script is built around **12-Tone Equal Temperament (12-TET)**:

\[
\text{pos}(n) = L - \frac{L}{2^{(n/12)}}
\]

- `L` = scale length for that string
- `n` = fret number
- `pos(n)` = distance from the nut to the `n`-th fret

This gives exact results without cumulative rounding errors.

For **multiscale instruments**, the script computes a different scale length for each string by interpolating between bass and treble scale lengths:

- **Linear mode**: even interpolation across strings.
- **Exponential mode**: interpolation weighted by a `gamma` factor, biasing toward bass or treble.

All geometry is constructed in a **neutral-fret coordinate system**, meaning the `x = 0` line runs through the chosen neutral fret. This simplifies later transformations, like rotating the entire board to a specific datum angle.

---

## 🧭 Coordinate System & Geometry

- **X-axis** = along-string direction (positive away from nut)  
- **Y-axis** = string spacing direction (bass string at `y = 0`)  
- All fret coordinates are stored **relative to the neutral fret** (the fret around which the board may be rotated).

### Key geometric features produced:
- Fret lines (full width across board)  
- Nut and bridge edges  
- Outline polygon (tapered quadrilateral)  
- Optional slot kerf offsets for toolpath generation  
- Optional string centerlines  

---

## 🪚 Datum Angle Rotation

After the entire fretboard is computed, you can optionally **rotate everything by a given angle** around the neutral fret.

This is useful for:
- Aligning the board to your machine’s datum
- Simulating fan alignment changes
- Adjusting zeroing strategies without recomputing the entire geometry

All segments and coordinates (frets, nut, bridge, outline, slots, strings) are rotated consistently.

---

## 🧾 Output Formats

The script can emit multiple outputs in a single run:

- 📝 **Markdown (stdout)** — Readable tables of fret positions and spacings. Great for inspection and version control.  
- 📊 **CSV** — Easy to load into spreadsheets or CAD/CAM tools.  
- 🧱 **JSON** — Fully structured geometric and parametric data. Ideal for downstream automation.  
- 🖼 **SVG** — Lightweight vector drawing with logical layers for frets, strings, outline, nut, bridge, and slot offsets.  
- 📐 **DXF (ASCII)** — Minimal DXF file containing only LINE entities on named layers, suitable for import into Inkscape, Fusion 360, LightBurn, FreeCAD, etc.

---

## 🧭 Units & Measurement

- Supported units: **inches** (`in`) and **millimeters** (`mm`).  
- You can specify units globally with `--unit in|mm`.  
- Most length arguments accept...