# Plant geometry format `plant-geometry/1`

A small JSON document describing a single-axis tracker plant. It is

* uploaded per plant in the portal (Plant settings → Geometry) – the portal takes latitude,
  longitude and time zone from it;
* the input of the box simulator (`services/boxsim/plants/*.json`);
* intended as an **export format of design tools** (a tracker design tool can write it directly,
  see ROADMAP.md) and as configuration input for controllers.

Schema: `protocol/schemas/plant_geometry.schema.json` (JSON Schema draft 2020-12).

## Fields

| Field | Type | Req. | Unit / range | Meaning |
|---|---|---|---|---|
| `format` | string | yes | `"plant-geometry/1"` | format identifier and version |
| `name` | string | no | ≤ 200 chars | display name |
| `lat` | number | yes | −90..90 ° | latitude (WGS84) |
| `lon` | number | yes | −180..180 ° | longitude (WGS84), east positive |
| `tz` | string | yes | IANA | time zone, e.g. `Europe/Berlin` |
| `elevation_m` | number | no | m | site elevation |
| `axis_azimuth_deg` | number | yes | 0..360 ° | compass direction the rotation axis points to; 180 = north–south axis (pvlib convention) |
| `axis_tilt_deg` | number | yes | 0..45 ° | axis inclination (0 = horizontal axis) |
| `pitch_m` | number | yes | > 0 m | row-to-row distance (axis to axis) |
| `table_width_m` | number | yes | > 0 m | collector width perpendicular to the axis; GCR = width / pitch |
| `max_angle_deg` | number | yes | 10..90 ° | mechanical rotation limit (symmetric ±) |
| `backtracking` | boolean | no | default `true` | controller uses backtracking |
| `n_trackers` | integer | yes | 1..999 | trackers controlled by one box |
| `drive_count` | integer | yes | 1..4 | drives / angle sensors per tracker (2 = two-drive tracker with `actual_deg_b`) |
| `stow_angle_deg` | number | no | −90..90 °, default 0 | stow and night position |
| `trackers` | array | no | | optional per-tracker overrides: `index` (required), `label`, `drive_count`, `x_m`, `y_m` (local coordinates, for future layout views) |

Angles follow the TTP v1 convention (docs/protocol/ttp-v1.md, 6.2): 0° horizontal, positive toward
west for a north–south axis.

## Example

```json
{
  "format": "plant-geometry/1",
  "name": "Agri-PV Beispielhof",
  "lat": 48.71,
  "lon": 9.12,
  "tz": "Europe/Berlin",
  "elevation_m": 420,
  "axis_azimuth_deg": 180,
  "axis_tilt_deg": 0,
  "pitch_m": 12.0,
  "table_width_m": 4.6,
  "max_angle_deg": 60,
  "backtracking": true,
  "n_trackers": 8,
  "drive_count": 2,
  "stow_angle_deg": 0
}
```

## Compatibility rules

* Additional properties are allowed and ignored; a breaking change uses `plant-geometry/2`.
* A plant with several boxes uses one file per box (same site data, `n_trackers` per box).