# Hornfolding (Alpha)

**Hornfolding** is a command-line tool for loudspeaker builders that folds a linearly expanding horn or tapped-horn (THAM-style) channel into a rectangular enclosure of given outer dimensions.

It calculates the exact board geometry using the **Advanced Centerline Method (ACM)**, generates an SVG cross-section drawing with an unfolded area profile, outputs a workshop-ready cut list (console + CSV), and imports/exports simulation parameters for **Hornresp**.

> **Status: Alpha Release**  
This software is in active development. Calculations have not yet been systematically validated against acoustic measurements of built prototypes. Always verify the generated geometry and cut list before cutting wood.


## Requirements

- **Python 3.8+** (standard library only — no external packages required)


## Quick Start

### Interactive mode

Run the script without arguments:

```
python Hornfolding\_v0.69.py
```

The script prompts for enclosure dimensions, wood thickness, driver parameters, and horn data. All inputs are automatically saved to `Hornfolding\_Input.txt` next to the script and offered as defaults on the next run.

### Using an input file or Hornresp file directly

```
\# Run with a custom input file (no prompting)  
python Hornfolding\_v0.69.py my\_enclosure.txt  
  
\# Import an exported Hornresp single-simulation text file  
python Hornfolding\_v0.69.py my\_hornresp\_export.txt  
  
\# Additional CLI options  
python Hornfolding\_v0.69.py --batch --output-dir ./build --no-save-input
```


## Hornresp Workflow (`Par` vs. `Con`)

1. **Always use `Par` segments in Hornresp:**  
Because the enclosure has constant internal width (`Width - BraceWidth - 2 \* WoodThickness`) and linearly sloping boards, the cross-sectional area grows **linearly** with path length. In Hornresp, this corresponds to flare type **`Par`** (parallel side walls). Do **not** use `Con` (conical), as `Con` assumes two-dimensional expansion (`sqrt(area)` linear).

2. **Importing from Hornresp:**  
When you pass a Hornresp exported text file, the script reads `S1`–`S5` and `L23` (Mode 1), calculates the folded enclosure, and writes a new file `\<name\>\_Hornfolding.txt` with updated areas and lengths while preserving all driver and chamber settings.

3. **Note on `S4` and `S5`:**  
In a fixed outer box, `S2`, `S3`, and `L23` are matched directly, whereas `S4`, `S5`, and `L12`/`L34`/`L45` result from the enclosure geometry and are shown for comparison and re-simulation in Hornresp.

4. **Hornresp `S1` and `S5` (model since 0.69):**  
The straight Hornresp segments should contain the same air volume as the built segments.

   - `S1` follows from the volume of segment `S1`–`S2` (`S1 = 2·V12/L12 − S2`). With `S1 = auto` there is no kink. A manually specified `S1` is the Hornresp value: it requires `Kink = y`, board `a` is then split into `a1`/`a2` and the real `S1` is solved so that the volume matches. Without a kink a specified `S1` has no effect (a console note says so).

   - `S5` is the mean of the volume-equal `S5` (`2·V45/L45 − S4`) and the inertance-equal `S5` (same ∫ds/A as the built chamber) of the chamber `S4`–`S5`. A straight segment of the given length cannot match both; the console shows both values and a note appears if they differ by more than 2 %. This mean is a heuristic and has not been validated against measurements.


## Key Parameters & S3 Positions

- **Units:** The script is unit-free as long as all inputs match (`UNIT = "cm"` by default, or change to `"mm"` at the top of the script).

- **Input order:** The horn values are asked for in the order of Hornresp: `S1`, `S2`, `S3` (or the slope), `L23`, `S4`, `S5` (`S4`/`S5` are optional comparison targets), then `DriverOffset` (distance of `S2` + `S4`, i.e. the driver centre, from the left outer edge).

- **`DriverDiameter`, `MagnetDiameter`, `DriverDepth` (optional):** `DriverDepth` is checked against the free depth from the driver centre, measured along the normal of board `a` to the opposite wall (underside of board `d`; behind the end of `d` its end face or the ceiling). `MagnetDiameter` (default `auto` = 0.5 x `DriverDiameter`) adds a check of the free depth at the magnet edges along board `a` and warns if an edge leaves the channel under `d`. The check is a console diagnosis only.

- **Mouth boards `D1`/`D2` (since 0.67):** `D1` and `D2` continue the slopes of board `a` (`a1` with a kink) and of board `d` up to the outer edge `x = 0`; `S5` is the clear opening at `x = 0`.

- **`S3Position` (`1`–`7` or `auto`):**  
Slope changes from `b` (S2–S3) to `b'` (S3–S4) are only placed at bend entries or exits where a board ends:

  - `1` / `2`: Entry / exit of bend 3 (top left, before/at the vertical shaft)

  - `3` / `4`: Entry / exit of bend 4 (bottom/top of the vertical shaft, into the middle channel)

  - `5` / `6`: Entry / exit of bend 5 (right turn into the short descent)

  - `7`: Entry of bend 6 (into the rear chamber)

  - `auto`: Among the positions whose length `L23` deviates by at most 10 % from the desired `L23`, the one with the smallest cross-sectional undershoot (shortfall) below the idealised linear horn is chosen; shortfalls within 0.5 percentage points count as equal and the smaller `L23` deviation decides. If no position is within 10 %, the closest calculable position is used. The table "S3 positions compared" shows the deviation `dL23 %` for every position.

- **"S3 position N cannot be calculated":**  
This message means that for the chosen position and box dimensions, no slope `b'` exists that closes all bends inside the enclosure without boards colliding, leaving the box walls, or producing negative channel widths. Try a different `S3Position`, adjust `DriverOffset`, or increase the enclosure depth/height.


## Output Files

- **`horn\_folding.svg`:** Side-view section of the enclosure showing all boards (`A`–`D2`, `a`–`d`), the ACM bend constructions (`C`, `O1`/`O2`, `A`/`B`), the red centreline path, cross-sections `S1`–`S5`, the cut list, and the unfolded area profile (`Reference` vs. `Linear-area model` vs. `Actual` with fan profile).

- **`horn\_cutlist.csv`:** Workshop cut list with gross length of the longest face and interior end angles (`90.0` = square cut).

- **`Hornfolding\_Input.txt`:** Automatically saved parameters of the last run.


## Known Limitations & Model Assumptions

- **Bend approximation (`ACM`):** Valid well below the first cross-mode frequency ($\\lambda/4$ of the largest bend width). If the exit/entry width ratio of a bend exceeds `1.33`, a warning is displayed because the path length approximation becomes less reliable.

- **`S4` inside bend 6:** If `DriverOffset` places the driver centre inside bend 6, `S4` is calculated as a theoretical equivalent area so that the straight line from `S4` to the built mouth area `S5` passes through the built exit area of bend 6.

- **Driver & brace displacement:** `BraceWidth` is subtracted uniformly from the internal width across the entire horn. The physical volume of the driver magnet/basket (which reduces the rear chamber `S4`–`S5`) is not deducted automatically.

- **Board `a` with kink:** When `S1` deviates from the continuous slope and `Kink = y`, board `a` is split into `a1`/`a2`; the real `S1` is matched to the specified Hornresp `S1` by segment volume equality. The centreline of the chamber `S4`–`S5` is then a polyline (kink at the cross-section through the kink point).


## Development & Acknowledgements

- **Author & Domain Logic:** Acoustic concepts, geometric specifications, architecture decisions, and validation test cases were authored by Tobias McFadden.

- **AI-Assisted Implementation (Vibe-Coding):** The Python source code was implemented and iteratively refined with the assistance of AI coding assistants (LLMs). All generated code was reviewed and verified against the project's regression and fuzz test suite.

- **Theoretical Foundation:** Based on the Advanced Centerline Method documented by the DIY loudspeaker community (special thanks to soho54, Xoc1, Brian Steele, just-a-guy).


## License

Copyright (C) 2026 Tobias McFadden

This program is free software: you can redistribute it and/or modify it under the terms of the **GNU Affero General Public License v3.0 (AGPL-3.0)** — see the [License.md](file:///O:/Python/THAM/Release/License.md) file for details.  
*(If you are interested in integrating this code or its algorithms into proprietary/closed-source software or commercial web services under alternative licensing terms, please contact the author: [Tobias@McFadden.de](mailto:Tobias@McFadden.de).)*

