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.

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:

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:

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).

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):

Code
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.

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:

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

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

Exact value ranges and defaults are in the API Reference.