raytraverse¶
raytraverse [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...
the raytraverse executable is a command line interface to the raytraverse python package for running and evaluating climate based daylight models. sub commands of raytraverse can be chained but should be invoked in the order given.
the easiest way to manage options is to use a configuration file, to make a template:
raytraverse --template > run.cfg
after adjusting the settings, than each command can be invoked in turn and any dependencies will be loaded with the correct options, a complete run and evaluation can then be called by:
raytraverse -c run.cfg skyrun sunrun
as all required precursor commands will be invoked automatically as needed.
Options
VALUE OPTIONS:
-
-config
,
-c
<PATH>
¶ path of config file to load
-
-n
<INTEGER>
¶ sets the environment variable RAYTRAVERSE_PROC_CAP set to 0 to clear (parallel processes will use cpu_limit)
-
-out
<DIRECTORY>
¶
FLAGS (DEFAULT FALSE):
-
--template
,
--no-template
¶
write default options to std out as config
- Default
False
HELP:
-
-opts
,
--opts
¶
check parsed options
- Default
False
-
--debug
¶
show traceback on exceptions
- Default
False
-
--version
¶
Show the version and exit.
- Default
False
Commands
-
scene
define scene files for renderer and output…
-
area
define sampling area
-
suns
define solar sampling space
-
skydata
define sky conditions for evaluation
-
skyengine
initialize engine for skyrun
-
sunengine
initialize engine for sunrun
-
skyrun
run scene under sky for a set of points…
-
sunrun
run scene for a set of suns (defined by…
-
evaluate
evaluate metrics and/or make hdr for a…
-
examplescript
print an example workflow for script…
scene¶
raytraverse scene [OPTIONS]
define scene files for renderer and output directory
Effects¶
creates outdir and outdir/scene.oct
Options
VALUE OPTIONS:
-
-out
<DIRECTORY>
¶
-
-scene
<TEXT>
¶ space separated list of radiance scene files (no sky) or precompiled octree
FLAGS (DEFAULT TRUE):
-
--log
,
--no-log
¶
log progress to stderr
- Default
True
-
--reload
,
--no-reload
¶
if a scene already exists at OUT reload it, note that if this is False and overwrite is False, the program will abort
- Default
True
FLAGS (DEFAULT FALSE):
-
--overwrite
,
--no-overwrite
¶
Warning! if set to True all files inOUT will be deleted
- Default
False
HELP:
-
-opts
,
--opts
¶
check parsed options
- Default
False
-
--debug
¶
show traceback on exceptions
- Default
False
-
--version
¶
Show the version and exit.
- Default
False
area¶
raytraverse area [OPTIONS]
define sampling area
Effects¶
None
Options
VALUE OPTIONS:
-
-name
<TEXT>
¶ name for zone/point group (impacts file naming)
- Default
plan
-
-ptres
<FLOAT>
¶ initial sampling resolution for points
- Default
1.0
-
-rotation
<FLOAT>
¶ positive Z rotation for point grid alignment
- Default
0.0
-
-static_points
<TEXT>
¶ points to simulate, this can be a .npy file, a whitespace seperated text file or entered as a string with commas between components of a point and spaces between points. points should either all be 3 componnent (x,y,z) or 6 component (x,y,z,dx,dy,dz) but the dx,dy,dz is ignored
-
-zheight
<FLOAT>
¶ replaces z in points or zone
-
-zone
<TEXT>
¶ zone boundary to dynamically sample. can either be a radiance scene file defining a plane to sample or an array of points (same input options as -static_points). Pointsare used to define a convex hull with an offset of 1/2*ptres in which to sample. Note that if static_pointsand zone are both give, static_points is silently ignored
HELP:
-
-opts
,
--opts
¶
check parsed options
- Default
False
-
--debug
¶
show traceback on exceptions
- Default
False
-
--version
¶
Show the version and exit.
- Default
False
suns¶
raytraverse suns [OPTIONS]
define solar sampling space
Effects¶
None
Options
VALUE OPTIONS:
-
-loc
<TEXT>
¶ can be a number of formats:
a string of 3 space seperated values (lat lon mer) where lat is +west and mer is tz*15 (matching gendaylit).
a string of comma seperated sun positions with multiple items seperated by spaces: “0,-.7,.7 .7,0,.7” following the shape requirements of 3.
a file loadable with np.loadtxt) of shape (N, 2), (N,3), (N,4), or (N,5):
2 elements: alt, azm (angles in degrees)
3 elements: dx,dy,dz of sun positions
4 elements: alt, azm, dirnorm, diffhoriz (angles in degrees)
5 elements: dx, dy, dz, dirnorm, diffhoriz.
path to an epw or wea formatted file: solar positions are generated and used as candidates unless –epwloc is True.
None (default) all possible sun positions are considered
in the case of a location, sun positions are considered valid when in the solar transit for that location. for candidate options (2., 3., 4.), sun positions are drawn from this set (with one randomly chosen from all candidates within adaptive grid.
-
-name
<TEXT>
¶ name for solar sourcee group (impacts file naming)
- Default
suns
-
-skyro
<FLOAT>
¶ counterclockwise sky-rotation in degrees (equivalent to clockwise project north rotation)
- Default
0.0
-
-sunres
<FLOAT>
¶ initial sampling resolution for suns
- Default
30.0
FLAGS (DEFAULT FALSE):
-
--epwloc
,
--no-epwloc
¶
if True, use location from epw/wea argument to -loc as a transit mask (like -loc option 1.) instead of as a list of candidate sun positions.
- Default
False
HELP:
-
-opts
,
--opts
¶
check parsed options
- Default
False
-
--debug
¶
show traceback on exceptions
- Default
False
-
--version
¶
Show the version and exit.
- Default
False
skydata¶
raytraverse skydata [OPTIONS]
define sky conditions for evaluation
Effects¶
Invokes scene
write outdir/name.npz (SkyData initialization object)
Options
VALUE OPTIONS:
-
-ground_fac
<FLOAT>
¶ ground reflectance
- Default
0.15
-
-loc
<FLOATS>
¶ location data given as ‘lat lon mer’ with + west of prime meridian overrides location data in wea
-
-minalt
<FLOAT>
¶ minimum solar altitude for daylight masking
- Default
2.0
-
-mindiff
<FLOAT>
¶ minumum diffuse horizontal irradiance for daylight masking
- Default
5.0
-
-name
<TEXT>
¶ output file name for skydata
- Default
skydata
-
-skyres
<FLOAT>
¶ approximate square patch size in degrees (must match argument given to skyengine)
- Default
10.0
-
-skyro
<FLOAT>
¶ angle in degrees counter-clockwise to rotate sky (to correct model north, equivalent to clockwise rotation of scene)
- Default
0.0
-
-wea
<TEXT>
¶ path to epw, wea, .npy file or np.array, or .npz file,if loc not set attempts to extract location data (if needed).
FLAGS (DEFAULT TRUE):
-
--reload
,
--no-reload
¶
reload saved skydata if it exists in scene directory
- Default
True
HELP:
-
-opts
,
--opts
¶
check parsed options
- Default
False
-
--debug
¶
show traceback on exceptions
- Default
False
-
--version
¶
Show the version and exit.
- Default
False
skyengine¶
raytraverse skyengine [OPTIONS]
initialize engine for skyrun
Effects¶
Invokes scene
creates outdir/scene_sky.oct
Options
VALUE OPTIONS:
-
-accuracy
<FLOAT>
¶ a generic accuracy parameter that sets the threshold variance to sample. A value of 1 will have a sample count at the final sampling level equal to the number of directions with a contribution variance greater than .25
- Default
1.0
-
-fdres
<INTEGER>
¶ the final directional sampling resolution, yielding a grid of potential samples at 2^fdres x 2^fdres per hemisphere
- Default
9
-
-idres
<INTEGER>
¶ the initial directional sampling resolution. each side of the sampling square (representing a hemisphere) will be subdivided 2^idres, yielding 2^(2*idres) samples and a resolution of 2^(2*idres)/(2pi) samples/steradian. this value should be smaller than 1/2 the size of the smallest view to an aperture that should be captured with 100% certainty
- Default
5
-
-rayargs
<TEXT>
¶ additional arguments to pass to the rendering engine
-
-skyres
<FLOAT>
¶ approximate resolution for skypatch subdivision (in degrees). Patches will have (rounded) size skyres x skyres. So if skyres=10, each patch will be 100 sq. degrees (0.03046174197 steradians) and there will be 18 * 18 = 324 sky patches. Must match argument givein to skydata
- Default
10.0
FLAGS (DEFAULT TRUE):
-
--default-args
,
--no-default-args
¶
use raytraverse defaults before -rayargs, if False, uses radiance defaults
- Default
True
HELP:
-
-opts
,
--opts
¶
check parsed options
- Default
False
-
--debug
¶
show traceback on exceptions
- Default
False
-
--version
¶
Show the version and exit.
- Default
False
sunengine¶
raytraverse sunengine [OPTIONS]
initialize engine for sunrun
Effects¶
Invokes scene
Options
VALUE OPTIONS:
-
-accuracy
<FLOAT>
¶ a generic accuracy parameter that sets the threshold variance to sample. A value of 1 will have a sample count at the final sampling level equal to the number of directions with a contribution variance greater than .25
- Default
1.0
-
-fdres
<INTEGER>
¶ the final directional sampling resolution, yielding a grid of potential samples at 2^fdres x 2^fdres per hemisphere
- Default
10
-
-idres
<INTEGER>
¶ the initial directional sampling resolution. each side of the sampling square (representing a hemisphere) will be subdivided 2^idres, yielding 2^(2*idres) samples and a resolution of 2^(2*idres)/(2pi) samples/steradian. this value should be smaller than 1/2 the size of the smallest view to an aperture that should be captured with 100% certainty
- Default
5
-
-maxspec
<FLOAT>
¶ the maximum value in the specular guide considered as a specular reflection source. Above this value it is assumed that these are direct view rays to the source so are not sampled. in the case of low vlt glazing, this value should be reduced. In mixed (high-low) vlt scenes the specular guide will either over sample (including direct views) or under sample (miss specular reflections) depending on this setting.
- Default
0.2
-
-rayargs
<TEXT>
¶ additional arguments to pass to the rendering engine
-
-slimit
<FLOAT>
¶ the minimum value in the specular guide considered as a potential specular reflection source, in the case of low vlt glazing, this value should be reduced.
- Default
0.01
-
-speclevel
<INTEGER>
¶ at this sampling level, pdf is made from brightness of sky sampling rather than progressive variance to look for fine scale specular highlights, this should be atleast 1 level from the end and the resolution of this level should be smaller than the size of the source
- Default
9
FLAGS (DEFAULT TRUE):
-
--default-args
,
--no-default-args
¶
use raytraverse defaults before -rayargs, if False, uses radiance defaults
- Default
True
HELP:
-
-opts
,
--opts
¶
check parsed options
- Default
False
-
--debug
¶
show traceback on exceptions
- Default
False
-
--version
¶
Show the version and exit.
- Default
False
skyrun¶
raytraverse skyrun [OPTIONS]
run scene under sky for a set of points (defined by area)
Effects¶
Invokes scene
Invokes area (no effects)
Invokes skyengine
- creates outdir/area.name/sky_points.tsv
contents: 5cols x N rows: [sample_level idx x y z]
- creates outdir/area.name/sky/######.rytpt
each file is a LightPointKD initialization object
Options
VALUE OPTIONS:
-
-accuracy
<FLOAT>
¶ parameter to set threshold at sampling level relative to final level threshold (smaller number will increase sampling)
- Default
1.0
-
-nlev
<INTEGER>
¶ number of levels to sample (final resolution will be ptres/2^(nlev-1))
- Default
3
FLAGS (DEFAULT TRUE):
-
--jitter
,
--no-jitter
¶
jitter samples on plane within adaptive sampling grid
- Default
True
FLAGS (DEFAULT FALSE):
-
--overwrite
,
--no-overwrite
¶
If True, reruns sampler when invoked, otherwise will first attempt to load results
- Default
False
HELP:
-
-opts
,
--opts
¶
check parsed options
- Default
False
-
--debug
¶
show traceback on exceptions
- Default
False
-
--version
¶
Show the version and exit.
- Default
False
sunrun¶
raytraverse sunrun [OPTIONS]
run scene for a set of suns (defined by suns) for a set of points (defined by area)
Effects¶
Invokes scene
Invokes area (no effects)
Invokes sunengine (no effects)
invokes skyrun (if guided=True)
- creates outdir/area.name/sun_####_points.tsv
contents: 5cols x N rows: [sample_level idx x y z]
- creates outdir/area.name/sky/sun_####/######.rytpt
each file is a LightPointKD initialization object
Options
VALUE OPTIONS:
-
-accuracy
<FLOAT>
¶ parameter to set threshold at sampling level relative to final level threshold (smaller number will increase sampling)
- Default
1.0
-
-nlev
<INTEGER>
¶ number of levels to sample (final resolution will be ptres/2^(nlev-1))
- Default
3
-
-srcaccuracy
<FLOAT>
¶ parameter to set threshold at sampling level relative to final level threshold (smaller number will increase sampling)
- Default
1.0
-
-srcnlev
<INTEGER>
¶ number of levels to sample (final resolution will be sunres/2^(nlev-1))
- Default
3
FLAGS (DEFAULT TRUE):
-
--guided
,
--no-guided
¶
If True, uses skysampling results to guide sun sampling this is necessary if the model has any specular reflections, will raise an error if skyrun has not been called yet.
- Default
True
-
--jitter
,
--no-jitter
¶
jitter samples on plane within adaptive sampling grid
- Default
True
-
--srcjitter
,
--no-srcjitter
¶
jitter solar source within adaptive sampling grid for candidate SkyMappers, only affects weighting of selecting candidates in the same grid true positions are still used
- Default
True
FLAGS (DEFAULT FALSE):
-
--recover
,
--no-recover
¶
If True, recovers existing sampling
- Default
False
HELP:
-
-opts
,
--opts
¶
check parsed options
- Default
False
-
--debug
¶
show traceback on exceptions
- Default
False
-
--version
¶
Show the version and exit.
- Default
False
evaluate¶
raytraverse evaluate [OPTIONS]
evaluate metrics and/or make hdr for a single sensor location
Prequisites¶
skyrun and sunrun must be manually invoked prior to this
Effects¶
Invokes scene
Invokes skydata
invokes area (no effects)
invokes suns (no effects)
if hdr=True, writes: <basename>_#####.hdr
if metric=True, writes: <basename>.tsv
Options
VALUE OPTIONS:
-
-basename
<TEXT>
¶ basename for hdr outputs will write: <basename>_#####.hdr for each value in skymask (or range(len(skydata)) if skymask is None).
- Default
results
-
-metrics
<TEXTS>
¶ metrics to compute, choices: [“illum”, “avglum”, “gcr”, “ugp”, “dgp”, “tasklum”, “backlum”, “dgp_t1”, “log_gc”, “dgp_t2”, “ugr”, “threshold”, “pwsl2”, “view_area”, “backlum_true”, “srcillum”, “srcarea”, “maxlum”]
- Default
illum dgp ugp
-
-res
<INTEGER>
¶ image resolution
- Default
800
-
-sensor
<FLOATS>
¶ the sensor location (6 component vector ‘x y z dx dy dz’)
-
-skymask
<INTS>
¶ mask to reduce output from full SkyData, enter as index rows in wea/epw file using space seperated list or python range notation:
370 371 372 (10AM-12PM on jan. 16th)
12:8760:24 (everyday at Noon)
-
-viewangle
<FLOAT>
¶ applies to both image and metrics, should be <= 180 or 360
- Default
180.0
FLAGS (DEFAULT TRUE):
-
--metric
,
--no-metric
¶
calculate metrics
- Default
True
FLAGS (DEFAULT FALSE):
-
--hdr
,
--no-hdr
¶
make an image for every unmasked item in skydata
- Default
False
-
--interpolate
,
--no-interpolate
¶
use linear iinterpolation in image output
- Default
False
HELP:
-
-opts
,
--opts
¶
check parsed options
- Default
False
-
--debug
¶
show traceback on exceptions
- Default
False
-
--version
¶
Show the version and exit.
- Default
False
examplescript¶
raytraverse examplescript [OPTIONS]
print an example workflow for script based/api level access to raytraverse
Options
HELP:
-
-opts
,
--opts
¶
check parsed options
- Default
False
-
--debug
¶
show traceback on exceptions
- Default
False
-
--version
¶
Show the version and exit.
- Default
False