raytraverse.sky

skycalc

functions for loading sky data and computing sun position

raytraverse.sky.skycalc.read_epw(epw)[source]

read daylight sky data from epw or wea file

Returns

out – (month, day, hour, dirnorn, difhoriz)

Return type

np.array

raytraverse.sky.skycalc.read_epw_full(epw, columns=None)[source]
Parameters

  • epw –

  • columns (list, optional) – integer indices or keys of columns to return

Returns

Return type

requested columns from epw as np.array shape (8760, N)

raytraverse.sky.skycalc.get_loc_epw(epw, name=False)[source]

get location from epw or wea header

raytraverse.sky.skycalc.sunpos_utc(timesteps, lat, lon, builtin=True)[source]

Calculate sun position with local time

Calculate sun position (altitude, azimuth) for a particular location (longitude, latitude) for a specific date and time (time is in UTC)

Parameters

  • timesteps (np.array(datetime.datetime)) –

  • lon (float) – longitude in decimals. West is +ve

  • lat (float) – latitude in decimals. North is +ve

  • builtin (bool) – use skyfield builtin timescale

Returns

  • (skyfield.units.Angle, skyfield.units.Angle)

  • altitude and azimuth in degrees

raytraverse.sky.skycalc.row_2_datetime64(ts, year=2020)[source]
raytraverse.sky.skycalc.datetime64_2_datetime(timesteps, mer=0.0)[source]

convert datetime representation and offset for timezone

Parameters

  • timesteps (np.array(np.datetime64)) –

  • mer (float) – Meridian of the time zone. West is +ve

Returns

Return type

np.array(datetime.datetime)

raytraverse.sky.skycalc.sunpos_degrees(timesteps, lat, lon, mer, builtin=True, ro=0.0)[source]

Calculate sun position with local time

Calculate sun position (altitude, azimuth) for a particular location (longitude, latitude) for a specific date and time (time is in local time)

Parameters

  • timesteps (np.array(np.datetime64)) –

  • lon (float) – longitude in decimals. West is +ve

  • lat (float) – latitude in decimals. North is +ve

  • mer (float) – Meridian of the time zone. West is +ve

  • builtin (bool, optional) – use skyfield builtin timescale

  • ro (float, optional) – ccw rotation (project to true north) in degrees

Returns

Sun position as (altitude, azimuth) in degrees

Return type

np.array([float, float])

raytraverse.sky.skycalc.sunpos_radians(timesteps, lat, lon, mer, builtin=True, ro=0.0)[source]

Calculate sun position with local time

Calculate sun position (altitude, azimuth) for a particular location (longitude, latitude) for a specific date and time (time is in local time)

Parameters

  • timesteps (np.array(np.datetime64)) –

  • lon (float) – longitude in decimals. West is +ve

  • lat (float) – latitude in decimals. North is +ve

  • mer (float) – Meridian of the time zone. West is +ve

  • builtin (bool) – use skyfield builtin timescale

  • ro (float, optional) – ccw rotation (project to true north) in radians

Returns

Sun position as (altitude, azimuth) in radians

Return type

np.array([float, float])

raytraverse.sky.skycalc.sunpos_xyz(timesteps, lat, lon, mer, builtin=True, ro=0.0)[source]

Calculate sun position with local time

Calculate sun position (altitude, azimuth) for a particular location (longitude, latitude) for a specific date and time (time is in local time)

Parameters

  • timesteps (np.array(np.datetime64)) –

  • lon (float) – longitude in decimals. West is +ve

  • lat (float) – latitude in decimals. North is +ve

  • mer (float) – Meridian of the time zone. West is +ve

  • builtin (bool) – use skyfield builtin timescale

  • ro (float, optional) – ccw rotation (project to true north) in degrees

Returns

Sun position as (x, y, z)

Return type

np.array

raytraverse.sky.skycalc.generate_wea(ts, wea, interp='linear')[source]
raytraverse.sky.skycalc.coeff_lum_perez(sunz, epsilon, delta, catn)[source]

matches coeff_lum_perez in gendaylit.c

raytraverse.sky.skycalc.perez_apply_coef(coefs, cgamma, dz)[source]
raytraverse.sky.skycalc.perez_lum_raw(tp, dz, sunz, coefs)[source]

matches calc_rel_lum_perez in gendaylit.c

raytraverse.sky.skycalc.perez_lum(xyz, coefs)[source]

matches perezlum.cal

raytraverse.sky.skycalc.scale_efficacy(dirdif, sunz, csunz, skybright, catn, td=10.9735311509)[source]
raytraverse.sky.skycalc.perez(sxyz, dirdif, md=None, ground_fac=0.2, td=10.9735311509)[source]

compute perez coefficients

Notes

to match the results of gendaylit, for a given sun angle without associated date, the assumed eccentricity is 1.035020

Parameters

  • sxyz (np.array) – (N, 3) dx, dy, dz sun position

  • dirdif (np.array) – (N, 2) direct normal, diffuse horizontal W/m^2

  • md (np.array, optional) – (N, 2) month day of sky calcs (for more precise eccentricity calc)

  • ground_fac (float) – scaling factor (reflectance) for ground brightness

  • td (np.array, float) – (N,) dew point temperature in C

Returns

perez – (N, 10) diffuse normalization, ground brightness, perez coefs, x, y, z

Return type

np.array

raytraverse.sky.skycalc.sky_mtx(sxyz, dirdif, side, jn=4, ground_fac=0.2)[source]

generate sky, ground and sun values from sun position and sky values

Parameters

  • sxyz (np.array) – sun directions (N, 3)

  • dirdif (np.array) – direct normal and diffuse horizontal radiation (W/m^2) (N, 2)

  • side (int) – sky subdivision

  • jn (int) – sky patch subdivision n = jn^2

  • ground_fac (float) – scaling factor (reflecctance) for ground brightness

Returns

  • skymtx (np.array) – (N, side*side)

  • grndval (np.array) – (N,)

  • sunval (np.array) – (N, 4) - sun direction and radiance

SkyData

class raytraverse.sky.SkyData(wea, suns=None, loc=None, skyro=0.0, ground_fac=0.15, skyres=10.0)[source]

Bases: object

class to generate sky conditions

This class provides an interface to generate sky data using the perez sky model

Parameters

  • wea (str np.array) – path to epw, wea, or .npy file or np.array, if loc not set attempts to extract location data (if needed). The Integrator does not need to be initialized with weather data but for convinience can be. However, self.skydata must be initialized (directly or through self.sky) before calling integrate.

  • suns (raytraverse.sky.Suns, optional) –

  • loc ((float, float, int), optional) – location data given as lat, lon, mer with + west of prime meridian overrides location data in wea (but not in sunfield)

  • skyro (float, optional) – angle in degrees counter-clockwise to rotate sky (to correct model north, equivalent to clockwise rotation of scene) does not override rotation in SunField)

  • ground_fac (float, optional) – ground reflectance

  • skyres (float, optional) – approximate square patch size in degrees

_loc = None

location and sky rotation information

property skyres
property skyro

sky rotation (in degrees, ccw)

property loc

lot, lon, mer (in degrees, west is positive)

property smtx

shape (np.sum(daysteps), skyres**2 + 1) coefficients for each sky patch each row is a timestep, coefficients exclude sun

property sun

shape (np.sum(daysteps), 5) sun position (index 0,1,2) and coefficients for sun at each timestep assuming the true solid angle of the sun (index 3) and the weighted value for the sky patch (index 4).

property daysteps

shape (len(skydata),) boolean array masking timesteps when sun is below horizon

property proxysort

sorting indices to arange daystep axis by solar proxy this is useful when combining sky/sun kdtrees without writing to disk to only do the interpolation once for a set of sky conditions.

property invsort

reverse sorting indices to restore input daystep order

property serr

the error (in degrees) between the actual sun position and the applied sunproxy

property skydata

sun position and dirnorm diffhoriz

property sunproxy

array of sun proxy data shape (len(daysteps), 2). column 0 is the corresponding sky bin (column of smtx), column 1 is the row of self.suns

smtx_patch_sun()[source]

generate smtx with solar energy applied to proxy patch for directly applying to skysampler data (without direct sun components can also be used in a partial mode (with sun view / without sun reflection.

header()[source]

generate image header string

_format_skydata(dat)[source]

process dat argument as skydata

see sky.setter for details on argument

Returns

dx, dy, dz, dir, diff

Return type

np.array

SolarBoundary

class raytraverse.sky.SolarBoundary(loc, skyro=0.0)[source]

Bases: object

sky location data object

Parameters

  • loc (tuple) – lat, lon, tz (in degrees, west is positive

  • skyro (float) – sky rotation (in degrees, ccw)

skyro = None

ccw rotation (in degrees) for sky

Type

float

property solarbounds

read only extent of solar bounds for given location set via loc

Getter

Returns solar bounds

Type

(np.array, np.array)

property loc

scene location

Getter

Returns location

Setter

Sets location and self.solarbounds

Type

(float, float, int)

in_solarbounds(uv, size=0.0)[source]

for checking if src direction is in solar transit

Parameters

  • uv (np.array) – source directions

  • size (float) – offset around UV to test

Returns

result – Truth of ray.src within solar transit

Return type

np.array

Suns

class raytraverse.sky.Suns(scene, skyro=0.0, reload=True, sunres=10.0, prefix='suns', suns=None, **kwargs)[source]

Bases: object

select suns to sample based on sky pdf and scene.

Parameters

  • scene (str,) – path of scene

  • skyro (float, optional) – sky rotation (in degrees, ccw)

  • reload (bool) – if True reloads existing sun positions, else always generates new

  • sunres (float) –

  • prefix (str) –

  • suns (np.array) – shape (N, 3) to directly set suns.

skyro = None

ccw rotation (in degrees) for sky

Type

float

property sunres
property sun_kd

sun kdtree for directional queries

property suns

holds sun positions

Getter

Returns the sun source array

Setter

Set the sun source array and write to files

Type

np.array

property sbins

holds sun bin numbers

_jitter_suns(si)[source]
choose_suns()[source]
direct_view()[source]
proxy_src(tsuns, tol=10.0)[source]

check if sun directions have matching source in SunSetter

Parameters

  • tsuns (np.array) – (N, 3) array containing sun source vectors to check

  • tol (float) – tolerance (in degrees)

Returns

  • np.array – (N,) index to proxy src

  • list – (N,) error in degrees to proxy sun

SunsLoc

class raytraverse.sky.SunsLoc(scene, loc, skyro=0.0, **kwargs)[source]

Bases: raytraverse.sky.suns.Suns

select suns to sample based on sky pdf, scene, and location.

Parameters

  • scene (str,) – path of scene

  • loc (tuple) – lat, lon, tz (in degrees, west is positive)

  • srct (float, optional) – threshold of sky contribution for determining appropriate srcn

  • skyro (float, optional) – sky rotation (in degrees, ccw)

  • reload (bool) – if True reloads existing sun positions, else always generates new

sky = None

raytraverse.sky.SolarBoundary

choose_suns()[source]

SunsPos

class raytraverse.sky.SunsPos(scene, wea, skyro=0.0, **kwargs)[source]

Bases: raytraverse.sky.suns.Suns

select suns to sample based on sun positions. the wea argument provides a list of sun positions to draw from rather than randomly generating the sun position like Suns and SunsLoc.

Parameters

  • sscene (str,) – path of scene

  • wea (str, np.array, optional) – path to sun position file or wea file, or array of sun positions

  • srct (float, optional) – threshold of sky contribution for determining appropriate srcn

  • skyro (float, optional) – sky rotation (in degrees, ccw)

  • reload (bool) – if True reloads existing sun positions, else always generates new

skyro = None

ccw rotation (in degrees) for sky

Type

float

property candidates

candidate sun positions

Getter

Returns the sun source array

Setter

Set the sun source array and write to files

Type

np.array

choose_suns()[source]