# Vehicle Templates — Multi-Mic Spatial Averaging

Built-in position layouts the tech picks from in the **Array Builder** (or the **Session Setup popup** on Auto-Tune). Each template is a pre-defined set of mic positions for a specific vehicle type — picking one creates the matching number of USB slots, ready for mics to be assigned from the Mic Catalog.

**Source of truth:** `portal/js/multi-mic-processor.js` — `window.VEHICLE_TEMPLATES`. Edits to position counts, labels, or zones happen there and propagate to every consumer.

---

## How templates feed into the tuning pipeline

```
Vehicle Template  →  Array Builder slots  →  Mic Catalog assignments  →  Saved Shop Array
                                                                              ↓
                                                              Picked on Auto-Tune (popup or toolbar)
                                                                              ↓
                                                                  Multi-mic spatial averaging
                                                                  with per-position labels live
```

The template provides the **position layout** (how many mics, what each one is for, zone groupings). The Array Builder turns it into a **saved hardware rig** (which physical mic sits on each USB channel). The Placement editor adds **per-vehicle measurements** (inch distances from a reference point, per contestant).

---

## Template catalog

### Open-air, light vehicles

#### Motorcycle — 4 mics
- **Positions:** Helmet L, Helmet R, Fairing L, Fairing R
- **Zones:** `helmet` (positions 0-1), `fairing` (2-3)
- **Use:** Baggers, touring bikes, anything with a fairing-mounted speaker pair + rider-position evaluation. The helmet mics catch what the rider hears at speed; the fairing mics catch the on-axis response close to the drivers.

#### Golf Cart — 4 mics
- **Positions:** Driver L, Driver R, Pass L, Pass R
- **Zones:** `driver` (0-1), `passenger` (2-3)
- **Use:** Two-row golf carts and LSVs. Simplest open-air template — head-position mics for both occupants.

#### Slingshot / 3-Wheeler — 6 mics
- **Positions:** Driver L, Driver R, Pod L, Pod R, Center, Rear
- **Zones:** `driver` (0-1), `pods` (2-3), `center` (4), `rear` (5)
- **Use:** Polaris Slingshot and similar 3-wheel autocycles. Side pods catch the door-pod speakers; center + rear catch dash + cargo subwoofer placement.

#### UTV / SxS — 6 mics
- **Positions:** Driver L, Driver R, Pass L, Pass R, Cage L, Cage R
- **Zones:** `driver` (0-1), `passenger` (2-3), `cage` (4-5)
- **Use:** Side-by-sides (RZR, Maverick, X3, etc.) with roll-cage-mounted soundbars or pod speakers. Cage mics evaluate the overhead/rear-coverage path.

#### Jeep / Open-Top — 6 mics
- **Positions:** Driver L, Driver R, Pass L, Pass R, Soundbar L, Soundbar R
- **Zones:** `driver` (0-1), `passenger` (2-3), `soundbar` (4-5)
- **Use:** Wranglers, Broncos, anything with top off / doors off. The soundbar pair evaluates overhead-mounted speakers separate from the front-seat head positions.

---

### Enclosed cabins

#### Show Vehicle / Car — 6 mics
- **Positions:** Driver L, Driver R, Pass L, Pass R, Center Dash, Rear Deck
- **Zones:** `driver` (0-1), `passenger` (2-3), `center` (4), `rear` (5)
- **Use:** Daily-driver and show-car installs. The two-row + center-dash + rear-deck pattern catches the front stage, the center-fill (if any), and the rear-deck or rear-cabin sub placement.

---

### Marine / large open platforms

#### Boat — 8 mics
- **Positions:** Helm L, Helm R, Bow L, Bow R, Tower L, Tower R, Transom L, Transom R
- **Zones:** `helm` (0-1), `bow` (2-3), `tower` (4-5), `transom` (6-7)
- **Use:** Wakeboard towers, bow/transom speaker pairs, helm-mounted pairs. Each zone scores independently — useful when the bow and transom have very different sources (deck speakers vs tower wakeboard horns).

#### Parade Float / Large Platform — 8 mics
- **Positions:** Front L, Front R, Mid L, Mid R, Rear L, Rear R, Center Front, Center Rear
- **Zones:** `front` (0-1), `mid` (2-3), `rear` (4-5), `center` (6-7)
- **Use:** Bagger-Nationals-style float rigs, demo trailers, any large flat platform with speakers spread over a long axis. Center-front / center-rear mics catch the listening-aisle response.

---

### Competition templates (high mic count)

> All competition templates fall back to the plain VEHICLE_SVGS overlay in `multi-mic-ui.js` because the animated MicPlacementDiagrams helper caps at 8 mics. Level meters, variance heatmap, and assign tables all work normally above 8.

#### Competition 3×3 Grid — 9 mics
- **Positions:** Driver L, Center Front, Pass R, Driver Center, Cabin Center, Pass Center, Driver Rear, Center Rear, Pass Rear
- **Zones:** `front` (0-2), `middle` (3-5), `rear` (6-8)
- **Use:** ISO-style grid coverage of the entire cabin floor area. Evaluates spatial uniformity across the seating envelope without locking to seat positions.

#### Competition 4-Seat × 3-Position — 12 mics
- **Positions:** Driver Head L/R/Chest, Pass Head L/R/Chest, Rear-Driver L/R/Chest, Rear-Pass L/R/Chest
- **Zones:** `driver` (0-2), `passenger` (3-5), `rear_driver` (6-8), `rear_passenger` (9-11)
- **Use:** SQ competition rigs (MECA, IASCA Expert, EMMA) evaluating both ears + chest position for every occupant. Chest mic catches midbass coupling that the ear mics miss.

#### Competition 4-Seat × 4-Position — 16 mics
- **Positions:** Driver L Ear / R Ear / Head Top / Chest — repeated for Pass, Rear-Driver, Rear-Pass
- **Zones:** `driver` (0-3), `passenger` (4-7), `rear_driver` (8-11), `rear_passenger` (12-15)
- **Use:** Maximum-density SQ measurement for installs being scored at the championship level. Head Top mic catches dome/A-pillar reflections; chest mic catches midbass/sub coupling.

#### Large Venue / Boat 16-Position Spatial — 16 mics
- **Positions:** Helm L/R/Center, Mid L/R/Center, Bow L/R/Center, Tower L/R/Center, Transom L/R/Center, Cabin Center
- **Zones:** `helm` (0-2), `mid` (3-5), `bow` (6-8), `tower` (9-11), `transom` (12-14), `cabin` (15)
- **Use:** Tower-boats and large-platform rigs at competition. Centers in each zone catch the on-axis response of pair speakers from the listening aisle.

---

### Custom

#### Custom Layout
- **Positions:** *(empty — user adds via `addCustomPosition`)*
- **Zones:** *(none)*
- **Use:** Anything that doesn't fit the built-ins. Loaded automatically when applying a saved shop array whose layout doesn't match any built-in template.

---

## Adding a new template

Edit `portal/js/multi-mic-processor.js`. Add a new key to `VEHICLE_TEMPLATES`:

```javascript
'my_new_template': {
  label: 'Display Name',
  positions: ['Pos A', 'Pos B', ...],   // human-readable labels, in slot order
  count: N,                              // must match positions.length
  zones: { zoneName: [0, 1], ... },      // optional grouping for averaging
  micXY: [[x%, y%], ...]                 // optional — SVG overlay coords (vehicle diagram)
}
```

Then update **this doc** with the same content. Templates appear automatically in:

- **Array Builder** → "Vehicle Templates" card (in `portal/index.html`, populated from `window.VEHICLE_TEMPLATES`)
- **Auto-Tune Session Setup popup** → Microphone dropdown, `── Vehicle Templates ──` optgroup
- **Auto-Tune toolbar** → same dropdown, same group

No further wiring needed — both consumers read `window.VEHICLE_TEMPLATES` at runtime.

---

## Zones

`zones` is a `{name: [slotIndex, ...]}` map. Zones drive **per-zone spatial averaging** in `MultiMicProcessor.getSpatialAverage(zoneName)` — used by SEM electronic judging to score the driver position separately from the rear-cabin position, or the bow separately from the transom on a boat.

A position can appear in only one zone. The zone names are conventional (no system meaning) but should stay consistent across templates so judging rules can reference them generically (e.g. `driver` always means the driver-seat zone).