# Surface Generator � Full Technical & Architectural Specification for LLMs

## Overview
- **Application Name**: Surface Generator (Surface-Gen)
- **Primary Domain**: https://surface-gen.va-tool.de/
- **Target Audience**: Pro audio systems engineers, front-of-house (FOH) engineers, sound designers, acoustic consultants, event production planners.
- **License / Access**: Free-to-use web application with client-side processing, optional project cloud sync, and donation support.

---

## 1. Core Operating Modes

### 1.1 Map Mode (Outdoor / Festival Planning)
- Uses Leaflet with Google Maps Satellite / Hybrid basemaps (Leaflet.GoogleMutant) and OpenStreetMap fallbacks.
- Includes location search via Google Places / Nominatim geocoding.
- Users place an **Origin Reference Point (Stage Center / FOH / Speaker Rig)** with customizable stage rotation angle (0� to 360�).
- Converts GPS coordinates (WGS84 Latitude / Longitude) into metric cartesian coordinates (X = Lateral offset, Y = Distance/Depth along stage axis, Z = Elevation).
- Integrates Google Maps Elevation API to automatically sample real-world terrain heights at polygon vertices and compute ground slope.

### 1.2 Floor Plan Mode (Indoor Venues & Arenas)
- Supports drag-and-drop or file upload of PDF drawings (multi-page PDF navigation via PDF.js), high-res PNG, or JPG images.
- Two-point scale calibration: The user draws a reference line between two known architectural points and enters the real-world distance (meters or feet) to scale the canvas accurately.
- Includes canvas rotation, stage alignment, and opacity overlay controls.

---

## 2. Geometry & Surface Tools

- **Polygon Drawing**: Arbitrary n-gon audience areas and stage planes.
- **Rectangle & Circle Tools**: Quick creation of standard stage or venue layouts.
- **Parametric Grandstand / Riser Generator**:
  - Automatically calculates tiered seating steps based on tier depth (tread), riser height, count of tiers, and start elevation.
- **Parametric Amphitheater / Curved Tier Generator**:
  - Creates segmented concentric curved listener zones with arc angle, inner/outer radius, and step heights.
- **Listener Ear Height Calculation**:
  - Seated audience: +1.20 m (+3.94 ft) above floor level.
  - Standing audience: +1.65 m (+5.41 ft) above floor level.
  - Custom height offset for bar areas, balconies, or VIP risers.
- **3D Realtime WebGL Viewport**:
  - Built with Three.js.
  - Orbit controls, wireframe/solid toggle, coordinate axis indicators, and human listener scale models (1.75m avatars).

---

## 3. Supported Export Formats & Syntax

1. **L-Acoustics Soundvision (.txt)**
   - Text format with standard header, reference point coordinates, and polygon vertex lists in Soundvision XYZ format.
2. **d&b audiotechnik ArrayCalc (.dbac / .dbacv)**
   - XML-structured project archive with audience plane entities, listener height properties, coordinate transforms, and site layouts.
3. **AFMG EASE 5 & EASE Focus 3 (.dxf / PDF report)**
   - 3D Face entities on dedicated AUDIENCE / STAGE layers with metric units.
4. **CODA Audio System Optimiser (.cvlf)**
   - JSON-based venue file format describing 3D surface geometry, coordinate vertices, and ear heights.
5. **JBL Venue Synthesis (.gcf)**
   - Boundary and audience surface specification for Harman/JBL line array prediction.
6. **Meyer Sound MAPP 3D (.dxf)**
   - 3DFACE layer geometry formatted specifically for MAPP 3D import.
7. **NEXO NS-1 & Yamaha AFC Image (.dxf)**
   - Compatible 3D polygon mesh format.
8. **Bose Professional Modeler (.dxf)**
   - 3D Room model with listener areas (seated/standing) and surface material layer mapping.
9. **RCF RDShape (.xrds)**
   - XML-based surface format for RCF line array prediction.
10. **Martin Audio DISPLAY 3 (.skp)**
   - Native binary SketchUp 3D venue model generated in-browser with dedicated AUDIENCE, STAGE, BALCONY, and HARD_AVOID layers (for Hard Avoid® FIR beamsteering optimization).
11. **Electro-Voice PREVIEW (.dae)**
   - Native 3D COLLADA venue model with colored materials and extrusion walls.
12. **Universal Formats**:
   - AutoCAD 3D DXF (.dxf) with 3DFACE entities.
   - CSV / Excel coordinate tables (Vertex index, X, Y, Z, Area, Slope).
   - Project JSON (.json) for saving and reloading complete sessions.
   - PDF Measurement & Rigging Reports.
13. **L-Acoustics Soundvision Rigging Guide (Array-View)**:
   - Interactive 2D CAD elevation blueprint with real-world dimensions.
   - Live trim height calculations (Unterkante/Top/Bottom), motorized hoist pick points, splay angles, site tilt, Panflex directivity, and bumper accessories.
   - Print-ready blueprint mode and mobile crew sharing.

---

## 4. Built-In Acoustic Analyzers

- **Soundvision Analyzer**: Parses existing Soundvision TXT or PDF reports to extract speaker arrays, listener planes, and rigging data.
- **ArrayCalc Analyzer**: Inspects d&b .dbac/.dbacv files to analyze room surfaces, loudspeaker positions, delay settings, and rigging angles.

---

## 5. Frequently Asked Questions (FAQ)

### How do I import a festival venue into Soundvision?
1. Open https://surface-gen.va-tool.de/ in Map Mode.
2. Search the venue address in the search box.
3. Set the Stage Center as Reference Point and rotate the axis toward the main audience area.
4. Draw polygons for FOH, Main Audience, and VIP areas.
5. Click **Elevations** to query Google Elevation API for terrain heights.
6. Click **File > Export** and select **L-Acoustics Soundvision (.txt)**.
7. In Soundvision, choose *File > Import > Room Geometry*.

### How do I calibrate a PDF floor plan in Surface Generator?
1. Switch to **Floor Plan Mode** and upload your PDF.
2. Click **Calibrate Scale**, click two points of a known distance (e.g., stage width = 12 m), and enter the dimension.
3. Align the stage reference point and draw the audience planes.
4. Export directly to ArrayCalc, Soundvision, or EASE Focus DXF.