# Verschattung & Horizont

pvnode kombiniert mehrere Verschattungsmechanismen. Einige werden automatisch angewendet,
andere konfigurieren Sie auf dem Standort oder je String. Diese Seite erklärt, wo welcher
Mechanismus liegt und wie Sie ihn setzen.

:::tip
Die Verschattung verteilt sich auf den **Standort** und seine **Strings**. Geländehorizont und
Himmelshindernisse sind anlagenweit (`config.shading`); Reihenverschattung (`gcr`) und
Nahfeld-Verschattung (`near_field_shading`) werden je [String](/de/v2/api/sites#pv-strings) gesetzt.
:::

## Geländehorizont (automatisch)

Fernverschattung durch Gelände — Berge, Hügel, Bergkämme — ist **standardmäßig aktiv**. Beim
Anlegen eines Standorts leitet pvnode aus den Koordinaten ein Horizontprofil ab (hochaufgelöste
Geländedaten, 25 m in Europa, 30 m weltweit) und wendet es auf jede Prognose- und Verlaufsabfrage an.

Dafür müssen Sie nichts konfigurieren. Falls Sie es deaktivieren möchten, setzen Sie `use_terrain_horizon` in der
Standort-Config auf `false`:

```json title="Geländehorizont deaktivieren"
{
  "config": {
    "shading": {
      "use_terrain_horizon": false
    }
  }
}
```

## Himmelshindernisse (anlagenweit)

Mit `sky_obstruction` definieren Sie nahe Objekte, die Teile des Himmelsgewölbes verdecken —
Gebäude, Bäume, Mauern. Jedes Hindernis besteht aus drei durch Doppelpunkt getrennten Werten:

| Wert            | Beschreibung                                                            |
|-----------------|-------------------------------------------------------------------------|
| Start-Azimut    | Winkel in Grad von Nord, wo das Hindernis beginnt (0–360).              |
| End-Azimut      | Winkel in Grad von Nord, wo das Hindernis endet (0–360).               |
| Elevation       | Maximaler Winkel über dem Horizont, den das Hindernis abdeckt (0–90).   |

Mehrere Hindernisse werden mit Unterstrichen `_` verbunden. Maximal **10** sind erlaubt. Sie
müssen nach **aufsteigendem Azimut** geordnet sein und dürfen sich **nicht überlappen** — der
Start-Azimut jedes Hindernisses muss größer oder gleich dem End-Azimut des vorherigen sein
(und innerhalb eines Tripels muss `az_start` kleiner als `az_end` sein).

```json title="Zwei Hindernisse: ein NO- und ein SW-Segment"
{
  "config": {
    "shading": {
      "sky_obstruction": "0:90:20_180:270:30"
    }
  }
}
```

Das beschreibt ein 20° hohes Hindernis im Nordosten (Azimut 0°–90°) und ein 30° hohes Hindernis
im Südwesten (180°–270°).

## Reihenverschattung — Ground Coverage Ratio (je String)

Bei aufgeständerten Freiflächenanlagen verschatten Modulreihen die dahinterliegenden Reihen bei
niedrigem Sonnenstand. Das steuern Sie je String über `gcr` (Ground Coverage Ratio):

```
GCR = Modullänge / Reihenabstand
```

- `GCR = 0` (oder nicht gesetzt) — keine Reihenverschattung.
- `GCR = 0.5` — Module bedecken die Hälfte der Grundfläche.
- Höhere Werte = engerer Reihenabstand = mehr Reihenverschattung.

```json title="Ein aufgeständerter String mit Reihenverschattung"
{
  "strings": [
    { "slope": 25, "orientation": 180, "power_kw": 12, "gcr": 0.4 }
  ]
}
```

Da `gcr` am String hängt, kann jede Teilanlage ihre eigene Reihengeometrie haben.

## Nahfeld-Verschattung (je String)

`near_field_shading` erfasst tages- und jahreszeitliche Verschattung eines Strings — z. B. ein
Schornstein, der die Anlage an jedem Wintermorgen verschattet. Sie wird je String gesetzt, sodass
verschiedene Teilanlagen unterschiedliche Verschattungsmuster haben können.

Das Format nutzt **drei Tagesblöcke**, mit Unterstrichen verbunden, mit je **vier durch
Doppelpunkt getrennten Werten** (einer pro Jahreszeit). Jeder Wert ist der Verschattungsprozentsatz
**× 10**.

**Tagesblöcke:**

| Block | Tageszeit                  |
|-------|----------------------------|
| 1.    | Morgen (6 – 10 Uhr)        |
| 2.    | Mittag (11 – 14 Uhr)       |
| 3.    | Nachmittag (15 – 20 Uhr)   |

**Werte je Block:** Winter : Frühling : Sommer : Herbst.

```json title="Nahfeld-Verschattung an einem String"
{
  "strings": [
    {
      "slope": 30,
      "orientation": 180,
      "power_kw": 8,
      "near_field_shading": "7:2:3:1_1:1:0:0_0:0:0:0"
    }
  ]
}
```

Das bedeutet:

- **Morgen:** 70 % Verschattung im Winter, 20 % Frühling, 30 % Sommer, 10 % Herbst.
- **Mittag:** 10 % in Winter und Frühling, keine in Sommer und Herbst.
- **Nachmittag:** keine Verschattung in keiner Jahreszeit.

## Überblick

| Mechanismus      | Wo                          | Feld                   | Standard       |
|------------------|-----------------------------|------------------------|----------------|
| Geländehorizont  | Standort (`config.shading`) | `use_terrain_horizon`  | an             |
| Himmelshindernisse | Standort (`config.shading`) | `sky_obstruction`    | keine          |
| Reihenverschattung | String                    | `gcr`                  | keine          |
| Nahfeld          | String                      | `near_field_shading`   | keine          |

Genaue Wertebereiche und Standards finden Sie in der [API-Referenz](/api).