# Shading & Horizon

pvnode combines several shading mechanisms. Some are applied automatically, others you
configure on the site or per string. This page explains where each one lives and how to set it.

:::tip
Shading is split between the **site** and its **strings**. Terrain horizon and sky obstructions
are site-wide (`config.shading`); row shading (`gcr`) and near-field shading
(`near_field_shading`) are set per [string](/en/v2/api/sites#pv-strings).
:::

## Terrain horizon (automatic)

Far shading from terrain — mountains, hills, ridgelines — is **active by default**. When a site
is created, pvnode derives a horizon profile from the coordinates using high-resolution terrain
data (25 m in Europe, 30 m globally) and applies it to every forecast and historical query.

You don't configure anything for this. If you ever need to disable it, set `use_terrain_horizon` to `false` in the site config:

```json title="Disable terrain horizon"
{
  "config": {
    "shading": {
      "use_terrain_horizon": false
    }
  }
}
```

## Sky obstructions (site-wide)

Use `sky_obstruction` to define nearby objects that block parts of the sky dome — buildings,
trees, walls. Each obstruction is three values separated by colons:

| Value         | Description                                                          |
|---------------|----------------------------------------------------------------------|
| Start azimuth | Angle in degrees from north where the obstruction begins (0–360).    |
| End azimuth   | Angle in degrees from north where the obstruction ends (0–360).      |
| Elevation     | Maximum angle above the horizon the obstruction covers (0–90).       |

Join multiple obstructions with underscores `_`. Up to **10** are allowed. They must be ordered
by **ascending azimuth** and **must not overlap** — each obstruction's start azimuth has to be
greater than or equal to the previous one's end azimuth (and within each triple, `az_start` must
be less than `az_end`).

```json title="Two obstructions: an NE segment and an SW segment"
{
  "config": {
    "shading": {
      "sky_obstruction": "0:90:20_180:270:30"
    }
  }
}
```

This describes a 20°-high obstruction across the north-east (azimuth 0°–90°) and a 30°-high
obstruction across the south-west (180°–270°).

## Row shading — Ground Coverage Ratio (per string)

For ground-mounted systems, rows of modules shade the rows behind them at low sun angles. This
is controlled per string with `gcr` (ground coverage ratio):

```
GCR = panel length / row distance
```

- `GCR = 0` (or unset) — no row shading.
- `GCR = 0.5` — modules cover half the ground area.
- Higher values = tighter row spacing = more inter-row shading.

```json title="A ground-mounted string with row shading"
{
  "strings": [
    { "slope": 25, "orientation": 180, "power_kw": 12, "gcr": 0.4 }
  ]
}
```

Because `gcr` lives on the string, each sub-array can have its own row geometry.

## Near-field shading (per string)

`near_field_shading` captures time-of-day and seasonal shading on a string — e.g. a chimney
that shades the array every winter morning. It's set per string so different sub-arrays can have
different shading patterns.

The format uses **three time blocks** joined with underscores, each holding **four
colon-separated values** (one per season). Each value is the shading percentage **× 10**.

**Time blocks:**

| Block | Time of day               |
|-------|---------------------------|
| 1st   | Morning (6 AM – 10 AM)    |
| 2nd   | Midday (11 AM – 2 PM)     |
| 3rd   | Afternoon (3 PM – 8 PM)   |

**Values per block:** Winter : Spring : Summer : Autumn.

```json title="Near-field shading on a string"
{
  "strings": [
    {
      "slope": 30,
      "orientation": 180,
      "power_kw": 8,
      "near_field_shading": "7:2:3:1_1:1:0:0_0:0:0:0"
    }
  ]
}
```

This means:

- **Morning:** 70 % shading in winter, 20 % spring, 30 % summer, 10 % autumn.
- **Midday:** 10 % in winter and spring, none in summer and autumn.
- **Afternoon:** no shading in any season.

## Summary

| Mechanism        | Where                       | Field                  | Default        |
|------------------|-----------------------------|------------------------|----------------|
| Terrain horizon  | Site (`config.shading`)     | `use_terrain_horizon`  | on             |
| Sky obstructions | Site (`config.shading`)     | `sky_obstruction`      | none           |
| Row shading      | String                      | `gcr`                  | none           |
| Near-field       | String                      | `near_field_shading`   | none           |

Exact value ranges and defaults are in the [API Reference](/api).