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, then 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 evaluate
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
- sourceengine
initialize engine for sunrun
- skyrun
run scene under sky for a set of points…
- directskyrun
- sunrun
run scene for a set of suns (defined by…
- sourcerun
run scene for a single source (or multiple…
- images
render images
- evaluate
evaluate metrics
- pull
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:
- -jitterrate <FLOAT>¶
fraction of each axis to jitter over
- Default
0.5
- -name <TEXT>¶
name for zone/point group (impacts file naming)
- Default
plan
- -printlevel <INTEGER>¶
print a set of sun positions at sampling level (overrides printdata)
- -ptres <FLOAT>¶
initial sampling resolution for points (in model units
- 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
FLAGS (DEFAULT FALSE):
- --printdata, --no-printdata¶
if True, print areamapper positions (either boundary or static points)
- 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
suns¶
raytraverse suns [OPTIONS]
define solar sampling space
- Effects:
None
Options
VALUE OPTIONS:
- -jitterrate <FLOAT>¶
fraction of each axis to jitter over
- Default
0.5
- -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 source group (impacts file naming)
- Default
suns
- -printlevel <INTEGER>¶
print a set of sun positions at sampling level (overrides printdata)
- -skyro <FLOAT>¶
counterclockwise sky-rotation in degrees (equivalent to clockwise project north rotation)
- Default
0.0
- -sunres <INTEGER>¶
initial sampling resolution for suns (as sqrt of samples per hemisphere)
- Default
9
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
- --printdata, --no-printdata¶
if True, print skymapper sun positions (either boundary or candidates in xyz coordinates)
- 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.2
- -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
- -mindir <FLOAT>¶
minumum direct normal irradiance for daylight masking
- Default
0.0
- -name <TEXT>¶
output file name for skydata
- Default
skydata
- -skyres <INTEGER>¶
resolution of sky patches (sqrt(patches / hemisphere)).
- Default
15
- -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
FLAGS (DEFAULT FALSE):
- --printdata, --no-printdata¶
if True, print solar position and dirnorm/diff of loaded data
- Default
False
- --printfull, --no-printfull¶
with printdata, if True, print full unmasked skydata
- 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
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
- -adpatch <INTEGER>¶
prefered instead of -ad/-lw in rayargs to better coordinate settings of ad/lw and skypatch division, consider doubling this with each halving of accuracy and in cases with high proportion indirect contributions, such as deep spaces or complex fenestrations
- Default
50
- -dcompargs <TEXT>¶
additional arguments for running direct component. when using, set -ab in sunengine.rayargs to this ab minus one.
- Default
-ab 1
- -idres <INTEGER>¶
the initial directional sampling resolution (as sqrt of samples per hemisphere)
- Default
32
- -nlev <INTEGER>¶
number of directional sampling levels, yielding a finalresolution of idres^2 * 2^(nlev) samples per hemisphere
- Default
5
- -rayargs <TEXT>¶
additional arguments to pass to the rendering engine
- -skyres <INTEGER>¶
resolution of sky patches (sqrt(patches / hemisphere)).Must match argument givein to skydata
- Default
15
- -vlt <FLOAT>¶
primary transmitting vlt, used to scale the accuracy parameter to the expected scene variance. Optional, but helpful with, for example, electrochromic glazing or shades
- Default
0.64
FLAGS (DEFAULT TRUE):
- --default-args, --no-default-args¶
use raytraverse defaults before -rayargs, if False, uses radiance defaults. defaults are: -u+ -ab 16 -av 0 0 0 -aa 0 -as 0 -dc 1 -dt 0 -lr -14 -ad adpatch*(skyres^2+1) -lw 0.008/(skyres^2+1)/adpatch -st 0 -ss 16 -c 1. note that if this is false -ad and -lw will not be automatically set
- 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
- -idres <INTEGER>¶
the initial directional sampling resolution (as sqrt of samples per hemisphere)
- Default
32
- -nlev <INTEGER>¶
number of directional sampling levels, yielding a finalresolution of idres^2 * 2^(nlev) samples per hemisphere
- Default
6
- -rayargs <TEXT>¶
additional arguments to pass to the rendering engine, by default sets -ab 0, pass “” to clear
- Default
-ab 0
- -vlt <FLOAT>¶
primary transmitting vlt, used to scale the accuracy parameter to the expected scene variance. Optional, but helpful with, for example, electrochromic glazing or shades
- Default
0.64
FLAGS (DEFAULT TRUE):
- --default-args, --no-default-args¶
use raytraverse defaults before -rayargs, if False, uses radiance defaults. defaults are: -u+ -ab 16 -av 0 0 0 -aa 0 -as 0 -dc 1 -dt 0 -lr -14 -ad 1000 -lw 0.00004 -st 0 -ss 16 -w-
- 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
sourceengine¶
raytraverse sourceengine [OPTIONS]
initialize engine for sunrun
- Effects:
Invokes scene
Options
VALUE OPTIONS:
- -idres <INTEGER>¶
the initial directional sampling resolution (as sqrt of samples per hemisphere)
- Default
32
- -nlev <INTEGER>¶
number of directional sampling levels, yielding a finalresolution of idres^2 * 2^(nlev) samples per hemisphere
- Default
6
- -rayargs <TEXT>¶
additional arguments to pass to the rendering engine
- -source <TEXT>¶
name for this source
- Default
source
- -srcfile <FILE>¶
scene source description (required)
- -t0 <FLOAT>¶
initial sample threshold (in cd/m^2), use instead of accuracy when source luminance and meaningful differenceis known
- Default
20.0
- -t1 <FLOAT>¶
final sample threshold (in cd/m^2), use instead of accuracy when source luminance and meaningful differenceis known
- Default
400.0
- -vlt <FLOAT>¶
Leave at 1.0 for interior light sources. primary transmitting vlt, used to scale the accuracy parameter to the expected scene variance. Optional, but helpful with, for example, electrochromic glazing or shades
- Default
1.0
FLAGS (DEFAULT TRUE):
- --color, --no-color¶
- Default
True
- --default-args, --no-default-args¶
use raytraverse defaults before -rayargs, if False, uses radiance defaults. defaults are: -u+ -ab 16 -av 0 0 0 -aa 0 -as 0 -dc 1 -dt 0 -lr -14 -ad 1000 -lw 0.00004 -st 0 -ss 16 -w-
- 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
- -edgemode <CHOICE>¶
if ‘constant’ value is set to -self.t1, so edge is always seen as detail. Internal edges (resulting from PlanMapper borders) will behave like ‘nearest’ for all options except ‘constant’
- Default
reflect- Options
constant | reflect | nearest | mirror | wrap
- -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
- --plotp, --no-plotp¶
plot pdfs and sample vecs for each level
- 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
directskyrun¶
raytraverse directskyrun [OPTIONS]
Options
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)
- 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
- -edgemode <CHOICE>¶
if ‘constant’ value is set to -self.t1, so edge is always seen as detail. Internal edges (resulting from PlanMapper borders) will behave like ‘nearest’ for all options except ‘constant’
- Default
reflect- Options
constant | reflect | nearest | mirror | wrap
- -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):
- --jitter, --no-jitter¶
jitter samples on plane within adaptive sampling grid
- Default
True
- --recover, --no-recover¶
If True, recovers existing sampling
- 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):
- --overwrite, --no-overwrite¶
If True, reruns sampler when invoked, otherwise will first attempt to load results
- Default
False
- --plotp, --no-plotp¶
plot pdfs and sample vecs for each level
- 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
sourcerun¶
raytraverse sourcerun [OPTIONS]
run scene for a single source (or multiple defined in a single scene file)
Do not run as part of the same call as sunrun
make sure rayargs are properly set in sunengine (not -ab 0)
- Effects:
Invokes scene
Invokes area (no effects)
Invokes sunengine (no effects)
- creates outdir/area.name/SOURCE_points.tsv
contents: 5cols x N rows: [sample_level idx x y z]
- creates outdir/area.name/sky/SOURCE/######.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
- -distance <FLOAT>¶
when using scene detail, the difference in ray length equivalent to final sampling luminance threshold
- Default
0.5
- -edgemode <CHOICE>¶
if ‘constant’ value is set to -self.t1, so edge is always seen as detail. Internal edges (resulting from PlanMapper borders) will behave like ‘nearest’ for all options except ‘constant’
- Default
reflect- Options
constant | reflect | nearest | mirror | wrap
- -nlev <INTEGER>¶
number of levels to sample (final resolution will be ptres/2^(nlev-1))
- Default
3
- -normal <FLOAT>¶
when using scene detail, the difference in surface normal (degrees) equivalent to final sampling luminance threshold
- Default
5.0
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
- --plotp, --no-plotp¶
plot pdfs and sample vecs for each level
- Default
False
- --scenedetail, --no-scenedetail¶
If True, includes scene details (distance, surface normal,and modifier as features). Increases sampling rate to improve image reconstruction
- 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
images¶
raytraverse images [OPTIONS]
render images
Prerequisites:
skyrun and sunrun must be manually invoked prior to this
Effects:
Invokes scene
Invokes skydata
invokes area (no effects)
invokes suns (no effects)
writes: output images according to –namebyindex
Options
VALUE OPTIONS:
- -bandwidth <INTEGER>¶
used by interpolation.
- Default
20
- -basename <TEXT>¶
prefix of namebyindex.
- Default
results
- -interpolate <CHOICE>¶
- Options
linear | fast | high | fastc | highc | | None | False
- -res <INTEGER>¶
image resolution
- Default
800
- -resamprad <FLOAT>¶
radius for resampling sun vecs
- Default
0.0
- -resuntol <FLOAT>¶
tolerance for resampling sun views
- Default
1.0
- -sdirs <TEXT>¶
sensor directions, 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. vectors should all be 3 componnent (dx,dy,dz). used with3-component -sensors argument, all points are run for allviews, creating len(sensors)*len(sdirs) results. thisis the preferred option for multiple view directions, asthe calculations are grouped more efficiently
- -sensors <TEXT>¶
sensor points, 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). If 3 component, -sdirs is required, if 6-component, -sdirs is ignored. leave as None for zonal evaluation (sdirs required)
- -simtype <TEXT>¶
simulation process/integration type:
1comp: standard DC method, sky patch only, full contribution depending on skyengine settings
2comp: sky patch for sky contribution, sun run for sun contribution, depth of contributions depends on skyengine and sunengine settings, no approximation for sun from sky patch
3comp: 2-phase DDS, sky handles sky+indirect sun, sun handles direct sun requires directskyrun -ab 1 and sunrun -ab 0
1compdv: standad DC method, but with direct view replacement of sun and specular reflections
directview: only evaluate srcviewpts (direct views to sun and specular reflections
directpatch: only evaluate results from dskyrun
sunonly: only evaluate results from sunrun
sunpatch: use skyrun results to evaluate sun contribution
skyonly: use skyrun to evaluate sky contribution only
or source name (overrides –resampleview, –directview, etc.
- Default
3comp
- -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>¶
- Default
180.0
FLAGS (DEFAULT TRUE):
- --maskfull, --maskday¶
if false, skymask assumes daystep indices
- Default
True
FLAGS (DEFAULT FALSE):
- --blursun, --no-blursun¶
for simulating point spread function for direct sun view
- Default
False
- --directview, --no-directview¶
if True, ignore sky data and use daylight factors directly
- Default
False
- --namebyindex, --no-namebyindex¶
if False (default), names images by: <prefix>_sky-<row>_pt-<x>_<y>_<z>_vd-<dx>_<dy>_<dz>.hdr if True, names images by: <prefix>_sky-<row>_pt-<pidx>_vd-<vidx>.hdr, where pidx, vidx refer to the order of points, and vm.
- Default
False
- --resampleview, --no-resampleview¶
resample direct sun view directions
- 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
Prequisites
skyrun and sunrun must be manually invoked prior to this
Effects:
Invokes scene
Invokes skydata
invokes area (no effects)
invokes suns (no effects)
writes: <basename>.npz light result file (use “raytraverse pull” to extract data views)
Options
VALUE OPTIONS:
- -basename <TEXT>¶
LightResult object is written to basename.npz.
- 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
- -resamprad <FLOAT>¶
radius for resampling sun vecs
- Default
0.0
- -resuntol <FLOAT>¶
tolerance for resampling sun views
- Default
1.0
- -sdirs <TEXT>¶
sensor directions, 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. vectors should all be 3 componnent (dx,dy,dz). used with3-component -sensors argument, all points are run for allviews, creating len(sensors)*len(sdirs) results. thisis the preferred option for multiple view directions, asthe calculations are grouped more efficiently
- -sensors <TEXT>¶
sensor points, 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). If 3 component, -sdirs is required, if 6-component, -sdirs is ignored. leave as None for zonal evaluation (sdirs required)
- -simtype <TEXT>¶
simulation process/integration type:
1comp: standard DC method, sky patch only, full contribution depending on skyengine settings
2comp: sky patch for sky contribution, sun run for sun contribution, depth of contributions depends on skyengine and sunengine settings, no approximation for sun from sky patch
3comp: 2-phase DDS, sky handles sky+indirect sun, sun handles direct sun requires directskyrun -ab 1 and sunrun -ab 0
1compdv: standad DC method, but with direct view replacement of sun and specular reflections
directview: only evaluate srcviewpts (direct views to sun and specular reflections
directpatch: only evaluate results from dskyrun
sunonly: only evaluate results from sunrun
sunpatch: use skyrun results to evaluate sun contribution
skyonly: use skyrun to evaluate sky contribution only
or source name (overrides –resampleview, –directview, etc.
- Default
3comp
- -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)
- -threshold <FLOAT>¶
same as the evalglare -b option. if factor is larger than 100, it is used as constant threshold in cd/m2, else this factor is multiplied by the average task luminance. task position is center of image with a 30 degree field of view
- Default
2000.0
- -viewangle <FLOAT>¶
- Default
180.0
FLAGS (DEFAULT TRUE):
- --maskfull, --maskday¶
if false, skymask assumes daystep indices
- Default
True
- --npz, --no-npz¶
write LightResult object to .npz, use ‘raytraverse pull’or LightResult(‘basename.npz’) to access results
- Default
True
FLAGS (DEFAULT FALSE):
- --blursun, --no-blursun¶
for simulating point spread function for direct sun view
- Default
False
- --coercesumsafe, --no-coercesumsafe¶
to speed up evaluation, treat sources seperately,only compatible with illum, avglum, ugp (but note this is often WRONG!!!), dgp
- Default
False
- --lowlight, --no-lowlight¶
use lowlight correction for dgp
- Default
False
- --resampleview, --no-resampleview¶
resample direct sun view directions
- Default
False
- --serr, --no-serr¶
include columns of sampling info/errors columns are: sun_pt_err, sun_pt_bin, sky_pt_err, sky_pt_bin, sun_err, sun_bin. ‘err’ is distance from queried vector to actual. ‘bin’ is the unraveled idx of source vector at a 500^2 resolution of the mapper.
- 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
pull¶
raytraverse pull [OPTIONS]
Options
VALUE OPTIONS:
- -col <TEXTS>¶
axis to preserve and order for flattening, if not all axes are specified default order is (sky, point, view, metric) the first value is the column preserved, the second (with -ofiles) is the file to write, and the rest determine the order for ravelling into rows.
- Default
metric
- -imgfilter <INTS>¶
image indices to return (ignored for lightfield result)
- -imgzone <TEXT>¶
for making images from ZonalLightResult, path to areato sample over.
- -lr <FILE>¶
.npz LightResult, overrides lightresult from chained commands (evaluate/imgmetric). required if not chained with evaluate or imgmetric.
- -metricfilter <TEXTS>¶
metrics to return (non-existant are ignored)
- -ofiles <TEXT>¶
if given output serialized files along first axis (given by order) with naming [ofiles]_XXXX.txt
- -ptfilter <INTS>¶
point indices to return (ignored for imgmetric result)
- -res <INTEGER>¶
image resolution for plan based image pulls.
- Default
480
- -skyfill <FILE>¶
path to skydata file. assumes rows are timesteps. skyfilter should be None and other beside col should reduce to 1 or ofiles is given and sky is not first in order and all but first reduces to 1. LightResult should be a full evaluation (not masked)
- -skyfilter <INTS>¶
sky indices to return (ignored for imgmetric result)
- -spd <INTEGER>¶
steps per day. for use with –gridhdr col != sky matches data underlying -skyfill
- Default
24
- -viewfilter <INTS>¶
view direction indices to return (ignored for imgmetric result)
FLAGS (DEFAULT TRUE):
- --header, --no-header¶
print col labels
- Default
True
- --rowlabel, --no-rowlabel¶
label row
- Default
True
FLAGS (DEFAULT FALSE):
- --gridhdr, --no-gridhdr¶
use with ‘ofiles’, order ‘X point/sky Y’ and make sure Y only has one value (with appropriate filter)
- Default
False
- --info, --no-info¶
skip execution and return shape and axis info about LightResult
- 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
raytu¶
raytu [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...
the raytu executable is a command line interface to utility commands as part of the raytraverse python package.
the easiest way to manage options is to use a configuration file, to make a template:
raytu --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, for example:
raytraverse -c run.cfg imgmetric pull
will calculate metrics on a set of images and then print to the stdout.
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)
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
- transform
coordinate transformations
- imgmetric
calculate metrics for hdr images, similar…
- project
project images between angular and…
- lp2img
make hdr directview of lightpoint
- pull
- merge
- padsky
pad filtered result data according to sky…
transform¶
raytu transform [OPTIONS]
coordinate transformations
Options
VALUE OPTIONS:
- -cols <INTS>¶
coordinate columns (if none uses first N as required)
- -d <TEXT>¶
a .npy file, a whitespace seperated text file (can be - for stdin) or entered as a string with commas between components of a point and spaces between rows.
- -op <CHOICE>¶
transformation: ‘xyz2xy’: cartesian direction vector to equiangular. ‘xyz2aa’: cartesian direction vector to alt/azimuth. ‘xyz2tp’: cartesian to spherical (normalized). ‘xyz2uv’: cartesian to shirley-chiu square. ‘uv2xyz’: shirley-chiu square to certesian.
- Default
xyz2xy- Options
xyz2xy | xyz2aa | xyz2tp | xyz2uv | uv2xyz
- -outf <TEXT>¶
if none, return to stdout, else save as text file
- -reshape <INTS>¶
reshape before transform (before flip)
FLAGS (DEFAULT FALSE):
- --flip, --no-flip¶
transpose matrix before transform (after reshape)
- 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
imgmetric¶
raytu imgmetric [OPTIONS]
calculate metrics for hdr images, similar to evalglare but without glare source grouping, equivalent to -r 0 in evalglare. This ensures that all glare source positions are weighted by the metrics to which they are applied. Additional peak normalization reduces the deviation between images processed in different ways, for example pfilt with -r, rpict drawsource(), or an undersampled vwrays | rtrace run where the pixels give a coarse estimate of the actual sun area.
Options
VALUE OPTIONS:
- -basename <TEXT>¶
LightResult object is written to basename.npz.
- Default
img_metrics
- -imgs <FILES>¶
hdr image files, must be angular fisheye projection,if no view in header, assumes 180 degree
- -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”, “gss”]
- Default
illum dgp ugp
- -peaka <FLOAT>¶
expected peak area over which peak energy is distributed
- Default
6.7967e-05
- -peakr <FLOAT>¶
for peaks that do not meet expected area (such as partial suns, to determines the ratio of what counts as part of the source (max/peakr)
- Default
4.0
- -peakt <FLOAT>¶
include down to this threshold in possible peak, note thatonce expected peak energy is satisfied remaining pixels aremaintained, so it is safe-ish to keep this value low
- Default
100000.0
- -scale <FLOAT>¶
scale factor applied to pixel values to convert to cd/m^2
- Default
179.0
- -threshold <FLOAT>¶
same as the evalglare -b option. if factor is larger than 100, it is used as constant threshold in cd/m2, else this factor is multiplied by the average task luminance. task position is center of image with a 30 degree field of view
- Default
2000.0
FLAGS (DEFAULT TRUE):
- --npz, --no-npz¶
write LightResult object to .npz, use ‘raytraverse pull’or LightResult(‘basename.npz’) to access results
- Default
True
- --parallel, --no-parallel¶
use available cores
- Default
True
- --peakn, --no-peakn¶
corrrect aliasing and/or filtering artifacts for direct sun by assigning up to expected energy to peakarea
- Default
True
FLAGS (DEFAULT FALSE):
- --blursun, --no-blursun¶
applies human PSF to peak glare source (only if peekn=True
- Default
False
- --lowlight, --no-lowlight¶
use lowlight correction for dgp
- 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
project¶
raytu project [OPTIONS]
project images between angular and shirley-chiu square coordinates
Options
VALUE OPTIONS:
- -img <FILES>¶
hdr image files, uv anr angular
FLAGS (DEFAULT TRUE):
- --useview, --no-useview¶
use view direction for transform ang2uv to match standardprojection
- Default
True
FLAGS (DEFAULT FALSE):
- --uv2ang, --ang2uv¶
direction of transform
- 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
lp2img¶
raytu lp2img [OPTIONS]
make hdr directview of lightpoint
Options
REQUIRED:
- -lp <FILES>¶
Required path to lightpoint(s)
VALUE OPTIONS:
- -interp <CHOICE>¶
- Options
fast | high | | None | False
- -res <INTEGER>¶
- Default
800
- -scalefactor <FLOAT>¶
- Default
1.0
- -srcidx <INTEGER>¶
FLAGS (DEFAULT TRUE):
- --fisheye, --no-fisheye¶
- Default
True
- --showweight, --no-showweight¶
- Default
True
FLAGS (DEFAULT FALSE):
- --omega, --no-omega¶
- Default
False
- --order, --no-order¶
- Default
False
- --rnd, --no-rnd¶
- Default
False
- --showsample, --no-showsample¶
- 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
pull¶
raytu pull [OPTIONS]
Options
VALUE OPTIONS:
- -col <TEXTS>¶
axis to preserve and order for flattening, if not all axes are specified default order is (sky, point, view, metric) the first value is the column preserved, the second (with -ofiles) is the file to write, and the rest determine the order for ravelling into rows.
- Default
metric
- -imgfilter <INTS>¶
image indices to return (ignored for lightfield result)
- -imgzone <TEXT>¶
for making images from ZonalLightResult, path to areato sample over.
- -lr <FILE>¶
.npz LightResult, overrides lightresult from chained commands (evaluate/imgmetric). required if not chained with evaluate or imgmetric.
- -metricfilter <TEXTS>¶
metrics to return (non-existant are ignored)
- -ofiles <TEXT>¶
if given output serialized files along first axis (given by order) with naming [ofiles]_XXXX.txt
- -ptfilter <INTS>¶
point indices to return (ignored for imgmetric result)
- -res <INTEGER>¶
image resolution for plan based image pulls.
- Default
480
- -skyfill <FILE>¶
path to skydata file. assumes rows are timesteps. skyfilter should be None and other beside col should reduce to 1 or ofiles is given and sky is not first in order and all but first reduces to 1. LightResult should be a full evaluation (not masked)
- -skyfilter <INTS>¶
sky indices to return (ignored for imgmetric result)
- -spd <INTEGER>¶
steps per day. for use with –gridhdr col != sky matches data underlying -skyfill
- Default
24
- -viewfilter <INTS>¶
view direction indices to return (ignored for imgmetric result)
FLAGS (DEFAULT TRUE):
- --header, --no-header¶
print col labels
- Default
True
- --rowlabel, --no-rowlabel¶
label row
- Default
True
FLAGS (DEFAULT FALSE):
- --gridhdr, --no-gridhdr¶
use with ‘ofiles’, order ‘X point/sky Y’ and make sure Y only has one value (with appropriate filter)
- Default
False
- --info, --no-info¶
skip execution and return shape and axis info about LightResult
- 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
merge¶
raytu merge [OPTIONS]
Options
REQUIRED:
- -lr <FILES>¶
Required lightresults to merge, must match along all axes except ‘axis
VALUE OPTIONS:
- -axis <TEXT>¶
axis along which to merge. in case of duplicate values, output uses first occurence from order of -lr, otherwise axes order is not changed
- Default
sky
- -out <TEXT>¶
output file to write, will change/append .npz extension
- Default
merged
HELP:
- -opts, --opts¶
check parsed options
- Default
False
- --debug¶
show traceback on exceptions
- Default
False
- --version¶
Show the version and exit.
- Default
False
padsky¶
raytu padsky [OPTIONS]
pad filtered result data according to sky filtering
Options
VALUE OPTIONS:
- -cols <INTS>¶
cols of data to return (default all)
- -data <TEXT>¶
data to pad
- -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
- -mindir <FLOAT>¶
minumum direct normal irradiance for daylight masking
- 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).
HELP:
- -opts, --opts¶
check parsed options
- Default
False
- --debug¶
show traceback on exceptions
- Default
False
- --version¶
Show the version and exit.
- Default
False