# ray_shade

##### Rayshade

Calculates global shadow map for a elevation matrix by propogating rays from each matrix point to the light source(s), lowering the brightness at each point for each ray that intersects the surface.

##### Usage

```
ray_shade(heightmap, anglebreaks = seq(40, 50, 1), sunangle = 315,
maxsearch = 100, lambert = TRUE, zscale = 1, multicore = FALSE,
cache_mask = NULL, shadow_cache = NULL, progbar = TRUE, ...)
```

##### Arguments

- heightmap
A two-dimensional matrix, where each entry in the matrix is the elevation at that point. All points are assumed to be evenly spaced.

- anglebreaks
Default `seq(40,50,1)`. The azimuth angle(s), in degrees, as measured from the horizon from which the light originates.

- sunangle
Default `315` (NW). The angle, in degrees, around the matrix from which the light originates. Zero degrees is North, increasing clockwise.

- maxsearch
Default `100`. The maximum distance that the system should propogate rays to check. For longer

- lambert
Default `TRUE`. Changes the intensity of the light at each point based proportional to the dot product of the ray direction and the surface normal at that point. Zeros out all values directed away from the ray.

- zscale
Default `1`. The ratio between the x and y spacing (which are assumed to be equal) and the z axis. For example, if the elevation levels are in units of 1 meter and the grid values are separated by 10 meters, `zscale` would be 10.

- multicore
Default `FALSE`. If `TRUE`, multiple cores will be used to compute the shadow matrix. By default, this uses all cores available, unless the user has set `options("cores")` in which the multicore option will only use that many cores.

- cache_mask
Default `NULL`. A matrix of 1 and 0s, indicating which points on which the raytracer will operate.

- shadow_cache
Default `NULL`. The shadow matrix to be updated at the points defined by the argument `cache_mask`. If present, this will only compute the raytraced shadows for those points with value `1` in the mask.

- progbar
Default `TRUE`. If `FALSE`, turns off progress bar.

- ...
Additional arguments to pass to the `makeCluster` function when `multicore=TRUE`.

##### Value

Matrix of light intensities at each point.

##### Examples

```
# NOT RUN {
#Here we produce an shadow map of the `volcano` elevation map with the light from the NE.
#The default angle is from 40-50 degrees azimuth, from the north east.
volcanoshadow = ray_shade(volcano)
#Turn off Lambertian shading to get a shadow map solely based on the raytraced shadows.
volcanoshadow = ray_shade(heightmap = volcano,
anglebreaks = seq(30,40,10),
sunangle = 45,
maxsearch = 100,
lambert = FALSE)
plot_map(volcanoshadow)
# }
```

*Documentation reproduced from package rayshader, version 0.5.1, License: GPL-3*