> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plantpredict.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 3D Shading - Site Level (Version 12+)

export const ShadingFactor = () => <Tooltip tip="Fraction of irradiance reaching modules after accounting for shadows (0–1); higher values mean less shading.">
    shading factor
  </Tooltip>;

export const PolygonClipping = () => <Tooltip tip="Computing the intersection area of overlapping 2D shapes; used in shading calculations.">
    polygon clipping
  </Tooltip>;

export const Bay = () => <Tooltip tip="Section of a tracker where modules share the same tilt and rotation angle, receiving uniform irradiance.">
    bay
  </Tooltip>;

## Summary

The Site-Level 3D Shading engine, introduced in Version 12, uses a <PolygonClipping /> approach to calculate beam shading at the individual <Bay /> level across the entire site. The algorithm transforms the scene to view it from the sun's perspective, identifies which bays and objects could cast shade onto each target bay, then computes exact shade polygon intersections. It supports complex terrain, non-uniform row spacing, arbitrary array geometries, and external obstructions with significantly improved computational performance compared to the legacy DC field-level approach. This is a continuous-space approach with no dependence on rendering resolution.

## Inputs

| Name                         | Symbol     | Units   | Description                                                          |
| ---------------------------- | ---------- | ------- | -------------------------------------------------------------------- |
| **Bay Vertices**             | —          | m       | 3D coordinates of each bay's 4 corners (parallelograms)              |
| **External Object Vertices** | —          | m       | 3D vertices of obstruction polygons (triangles or parallelograms)    |
| **Solar Zenith Angle**       | $\theta_z$ | degrees | Angle between sun and vertical                                       |
| **Solar Azimuth Angle**      | $\gamma_s$ | degrees | Sun azimuth, measured clockwise from North                           |
| **Tracker Rotation Angle**   | $\alpha_i$ | degrees | Rotation angle about tracker axis for bay $i$ (tracker systems only) |

***

## Outputs

| Name                    | Symbol      | Units | Description                                                  |
| ----------------------- | ----------- | ----- | ------------------------------------------------------------ |
| **Beam Shading Factor** | $U_{shd,B}$ | —     | Site-average fraction of beam irradiance reaching bays (0-1) |

***

## Detailed Description

The algorithm operates in four main steps:

1. **Scene Preparation** — Rotate bays to tracker angles, then transform scene to sun-aligned coordinates
2. **Broad-Phase Collision** — Identify which bays and objects can cast shade onto each target bay
3. **Narrow-Phase Collision** — Compute exact shade polygon intersections for each candidate pair
4. **Shading Factor Calculation** — Calculate per-bay shaded fractions and aggregate to site average

### Step 1: Scene Preparation

The algorithm transforms the 3D scene into a coordinate system aligned with the sun's view:

1. **Bay rotation:** For tracker systems, rotate each bay around its tracker axis by angle $\alpha_i$
2. **Scene rotation:** Rotate the entire scene (bays and external objects) so that sun rays become parallel to the Z-axis, effectively viewing the scene from the sun's perspective

After transformation, shade can be computed by projecting polygons onto the X-Y plane—polygons with higher Z values (closer to the sun) cast shade on polygons with lower Z values.

### Step 2: Broad-Phase Collision

For each target bay, the algorithm identifies candidate occluders—other bays and external objects that could potentially cast shade onto it. A candidate must:

1. **Overlap in X-Y:** It overlaps the target bay when viewed from the sun
2. **Be in front:** It is closer to the sun than the target bay

This filtering eliminates most bay pairs from consideration, significantly reducing computational cost for large sites.

### Step 3: Narrow-Phase Collision

For each target bay with one or more candidates, the algorithm computes the exact shade geometry using polygon clipping:

1. **Merge candidate polygons:** Combine all candidate occluder polygons into a single shade polygon
2. **Intersect with target:** Compute the intersection of the merged shade polygon with the target bay polygon
3. **Calculate shaded area:** Measure the area of the intersection polygon

### Step 4: Shading Factor Calculation

The shaded fraction for each bay is:

$$
f_{shaded,i} = \frac{A_{shade,i}}{A_{bay,i}}
$$

If the sun is behind a bay, the bay receives no direct beam irradiance and $f_{shaded,i} = 1$.

The beam <ShadingFactor /> for each bay is:

$$
U_{shd,B,i} = 1 - f_{shaded,i}
$$

The site-average shading factor is computed as an area-weighted average across all bays:

$$
\bar{U}_{shd,B} = \frac{\sum_i A_{bay,i} \cdot U_{shd,B,i}}{\sum_i A_{bay,i}}
$$