Package 'rasterShade'

Title: Wrapper around rayshader package
Description: The package rasterShade is just a wrapper around function in rayshader package. The rasterShade package allows using rayshader algorithm directly on spatial data in form of Raster. The package tries to set "reasonable" default values for parameters in rayshadering algorithm. These default values are based on real world shadows that can be seen in nature.
Authors: Jan Caha [aut, cre]
Maintainer: Jan Caha <[email protected]>
License: GPL (>= 3)
Version: 0.6.0
Built: 2024-11-01 11:16:48 UTC
Source: https://github.com/JanCaha/rasterShade

Help Index

Extract sun position at given location in specific date and time

Description

The function is a wrapper around getSunlightPosition function. It performs several validy checks on inputs to ensure that they are logically valid. It also allows specification of time as and as an solar event.

Usage

get_sun_position(
  date = lubridate::ymd(Sys.Date()),
  time = "noon",
  tzone = "UTC",
  lat,
  lon
)

Arguments

date

Date specified as character in form YYYY-MM-DD. Default value is Sys.Date.
time

Either character representation of time (in format HH:MM:SS), or hms class, or one of text values: "noon", "sunrise", "sunset", "goldenHour", "goldenHourEnd". The textual representation is used to determine sun elevation using function getSunlightPosition. Value "sunrise" represents end of sunrise, while "sunset" represents start of sunset. Default value is "noon".
tzone

a character string that specifies which time zone to parse the date with. The string must be a time zone that is recognized by the user's OS. If no time zone is given the default value "UTC" is used. Default value "UTC".
lat

latitude of the location. Numeric from range -90,90. Positive values are north of the Equator.
lon

longtitude of the location. Numeric from range -180,180. Positive values are east of the central meridian.

Value

data.frame with one row and two columns sun_azimuth and sun_elevation indicating sun position on the sky. Both values are in degrees. Sun azimuth value 0 is pointing towards North and in rises clockwise direction. Sun elevation 0 means that sun is exactly on the horizon, value 90 means that sun is exactly az zenith.

Function for calculation of ambient shading on raster data

Description

This function is just a wrapper around ambient_shade that supports directly using Raster in the function. The function also tries to set "reasonable" default values for parameters.

Usage

shade_ambient_date_time(
  surface_raster,
  date = as.character(Sys.Date()),
  time = "noon",
  tzone = "UTC",
  rays_number = 36,
  search_distance = 200,
  z_value = 1,
  verbose = FALSE
)

shade_ambient_sun_position(
  surface_raster,
  sun_elevation = 45,
  rays_number = 36,
  search_distance = 200,
  z_value = 1,
  verbose = FALSE
)

Arguments

surface_raster

Object of class Raster.
date

Date specified as character in form YYYY-MM-DD. Default value is Sys.Date.
time

Either character representation of time (in format HH:MM:SS), or hms class, or one of text values: "noon", "sunrise", "sunset", "goldenHour", "goldenHourEnd". The textual representation is used to determine sun elevation using function getSunlightPosition. Value "sunrise" represents end of sunrise, while "sunset" represents start of sunset. Default value is "noon".
tzone

a character string that specifies which time zone to parse the date with. The string must be a time zone that is recognized by the user's OS. If no time zone is given the default value "UTC" is used. Default value "UTC".
rays_number

Number of rays that are calculated around each pixel. Default value is 36, which means that one ray per 10 degrees of orientation.
search_distance

Distance in which sun blocking objects are searched for, specified in map units. Default value is 200 map units.
z_value

numeric value indicating the scale between xy and z. Typical use is if the distance is measured in meters and elevation in foots, in such case the z value needs to be recalculated to meters. Default value is 1, which means that both measures use the same units.
verbose

Should informative message be printed? Default FALSE.
sun_elevation

Numeric value, from range 0 - 90, with 0 being sun elevation directly on horizon while 90 means that sun is directly above the surface.

Value

Object of class Raster.

Function for calculation of global shading on raster data

Description

This function is just a wrapper around ray_shade that supports directly using Raster in the function. The function also tries to set "reasonable" default values for parameters.

Usage

shade_global_date_time(
  surface_raster,
  date = as.character(Sys.Date()),
  time = "noon",
  tzone = "UTC",
  search_distance = 200,
  z_value = 1,
  verbose = FALSE
)

shade_global_sun_position(
  surface_raster,
  sun_elevation = 45,
  sun_azimuth = 180,
  search_distance = 200,
  z_value = 1,
  verbose = FALSE
)

Arguments

surface_raster

Object of class RasterLayer.
date

Date specified as character in form YYYY-MM-DD. Default value is Sys.Date.
time

Either character representation of time (in format HH:MM:SS), or hms class, or one of text values: "noon", "sunrise", "sunset", "goldenHour", "goldenHourEnd". The textual representation is used to determine sun elevation using function getSunlightPosition. Value "sunrise" represents end of sunrise, while "sunset" represents start of sunset. Default value is "noon".
tzone

a character string that specifies which time zone to parse the date with. The string must be a time zone that is recognized by the user's OS. If no time zone is given the default value "UTC" is used. Default value "UTC".
search_distance

Distance in which sun blocking objects are searched for, specified in map units. Default value is 200 map units.
z_value

numeric value indicating the scale between xy and z. Typical use is if the distance is measured in meters and elevation in foots, in such case the z value needs to be recalculated to meters. Default value is 1, which means that both measures use the same units.
verbose

Should informative message be printed? Default FALSE.
sun_elevation

Numeric value, from range 0 - 90, with 0 being sun elevation directly on horizon while 90 means that sun is directly above the surface. Default value is 45.
sun_azimuth

Numeric value that specifies azimuth from which the sun is shining on the surface. Value has to be from the range 0 - 360. Default value is 180.

Value

Object of class Raster.

Function for calculation of lambert shading (also known as hillshade in GIS) on raster data

Description

This function is just a wrapper around lamb_shade that supports directly using Raster in the function. The function also tries to set "reasonable" default values for parameters.

Usage

shade_lambert_date_time(
  surface_raster,
  date = as.character(Sys.Date()),
  time = "noon",
  tzone = "UTC",
  only_facing_sun = FALSE,
  z_value = 1,
  verbose = FALSE
)

shade_lambert_sun_position(
  surface_raster,
  sun_elevation = 45,
  sun_azimuth = 180,
  only_facing_sun = FALSE,
  z_value = 1,
  verbose = FALSE
)

Arguments

surface_raster

Object of class Raster.
date

Date specified as character in form YYYY-MM-DD. Default value is Sys.Date.
time

Either character representation of time (in format HH:MM:SS), or hms class, or one of text values: "noon", "sunrise", "sunset", "goldenHour", "goldenHourEnd". The textual representation is used to determine sun elevation using function getSunlightPosition. Value "sunrise" represents end of sunrise, while "sunset" represents start of sunset. Default value is "noon".
tzone

a character string that specifies which time zone to parse the date with. The string must be a time zone that is recognized by the user's OS. If no time zone is given the default value "UTC" is used. Default value "UTC".
only_facing_sun

Boolean value specifing if the value should be determined for all parts of the surface or only for parts oriented towards sun. Default value is FALSE, which means that it is calculated for all parts of the surface.
z_value

numeric value indicating the scale between xy and z. Typical use is if the distance is measured in meters and elevation in foots, in such case the z value needs to be recalculated to meters. Default value is 1, which means that both measures use the same units.
verbose

Should informative message be printed? Default FALSE.
sun_elevation

Numeric value, from range 0 - 90, with 0 being sun elevation directly on horizon while 90 means that sun is directly above the surface. Default value is 45.
sun_azimuth

Numeric value that specifies azimuth from which the sun is shining on the surface. Value has to be from the range 0 - 360. Default value is 180.

Value

Object of class Raster.