# Shading & Horizon

pvnode supports multiple shading mechanisms that can be combined. All shading is applied automatically during the simulation — you just configure the parameters.

## Terrain-Based Horizon Shading

Set `terrain_based_horizon_coverage=true` to activate automatic far shading based on high-resolution terrain data (25m in Europe, 30m globally). This accounts for mountains, hills, and other terrain features that block direct sunlight at low sun angles.

No additional configuration needed — the horizon profile is derived from the site coordinates.

## Sky Obstruction Configuration

Use `sky_obstruction_config` to define nearby obstructions that block parts of the sky dome (buildings, trees, walls). Each obstruction is defined by three values separated by colons:

| Value | Description |
|---|---|
| Start azimuth | Angle in degrees from north where the obstruction begins |
| End azimuth | Angle in degrees from north where the obstruction ends |
| Elevation | Maximum angle above the horizon that the obstruction covers |

Multiple obstructions are joined with underscores `_`. You can define up to 10.

**Examples:**

```
# North-east obstruction, 0° to 90° azimuth, 20° high
sky_obstruction_config=0:90:20

# Two obstructions: NE segment + SW segment
sky_obstruction_config=0:90:20_180:270:30
```

## Row Shading (Ground Coverage Ratio)

The `ground_coverage_ratio` parameter controls inter-row shading for ground-mounted systems. It's defined as:

```
GCR = panel_length / row_distance
```

- `GCR = 0` means no row shading (default)
- `GCR = 0.5` means panels cover half the ground area
- Higher values = tighter spacing = more shading

The second array has its own parameter: `second_array_ground_coverage_ratio`.

## Seasonal Shading Configuration

Use `shading_config` to define time-of-day and seasonal shading patterns on the PV array. The format uses four integers per time block (one per season), separated by colons. Each integer represents shading as a percentage × 10.

**Three time blocks, joined with underscores:**

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

**Four values per block:** Winter, Spring, Summer, Autumn.

**Example:**

```
shading_config=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

The second array uses `second_array_shading_config`.

## String-Level Shading

For detailed string-level shading analysis, pvnode supports configuring shading per string within the PV array. See the [API Reference](https://pvnode.com/api-reference) for the full parameter specification.