# pvl_detect_shadows

Identify shading on a GHI instrument from nearby structures such as wires and poles.

## Contents

- Syntax
- Description
- Inputs
- Output
- Notes
- References
- Load example data

## Syntax

`out = pvl_detect_shadows(Time, GHI, dbg)`

## Description

`pvl_detect_shadows` uses morphological image processing methods to identify shadows from fixed local objects in GHI data. GHI data are are assumed to be reasonably complete with relatively few missing values and at a fixed time interval nominally of 1 minute over the course of several months. Shadows are assumed to be relatively short duration. The algorithm forms a 2D image of the GHI data by arranging time of day along the x-axis and day of year along the y-axis. Rapid change in GHI in the x-direction is used to identify edges of shadows; continuity in the y-direction is used to separate local object shading from cloud shadows.

## Inputs

- `Time` - a K x 1 vector of datetimes in UTC corresponding to the measured GHI
- `GHI` - a K x 1 vector of measured GHI (W/m2)
- `interval` - an integer number of minutes between data points
- `site_info` - a structure with the following fields:
- `site_info.lat` - site latitude
- `site_info.long` - site longitude, positive is east of prime meridian
- `site_info.alt` - site altitude in meters
- `UTCoffset` - in hours, positive for east of prime meridian
- `dbg` - a boolean; additional plots are created if set to True

## Output

- `out` - a structure with the following fields:
- *|out.localtime - a K x 1 vector of datetime in adjusted by UTCoffset
- `out.GHI` - copy of input GHI in M x N = (samples per day) x (days) format
- `out.boosted` - M x N array of GHI after adjustment for dynamic range
- `out.alpha` - scalar used to adjust dynamic range
- `out.gradient` - M x N array of morphological gradient of boosted
- `out.clouds` - M x N array of boolean with True indicating non-clearsky conditions
- `out.night` - M x N array of boolean with True indicating clearsky GHI<100 W/m2
- `thresholded` - M x N array of boolean with True indicating a large morphological gradient
- `wires` - M x N array of boolean with True indicating a shadow

## Notes

Morphological image functions are defined as methods in class GHIImage. Method names are common in literature, and the Matlab Image Processing toolbox uses the common naming convention. To avoid namespace conflict with the Matlab toolbox, the PVLib implementation uses a class definition.

## References

[1] Martin, C. E., Hansen, C. W., An Image Processing Algorithm to Identify Near-Field Shading in Irradiance Measurements, preprint 2016.

[2] Reno, M.J. and C.W. Hansen, "Identification of periods of clear sky irradiance in time series of GHI measurements" Renewable Energy, v90, p. 520-531, 2016.

## Load example data

    fprintf('Loading data...');
    load('SMUD22_GHI_data.mat');
    data_interval = 1; % minutes, time between GHI samples
    x = pvl_detect_shadows(data.Time, data.GHI, data_interval, data.info, false);
    tmp=x.GHI+1;  % add 1 to avoid zeros, which can be a problem for the image
    tmp(x.night)=NaN;
    make_shadow_figure(tmp, x.localtime,-1);
    c=colorbar;
    c.Label.String = 'Scaled GHI (W/m^2)';
    title('GHI data')

    %  figure showing only wires
    tmp=100*x.wires;
    tmp(x.night)=18;
    make_shadow_figure(tmp,x.localtime,1);
    title('Detected shadows');

    Loading data...
    Computing clear sky estimate...
    Removing clouds...