raytraverse

raytraverse [OPTIONS] OUT 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 and sure that Scene and SunSetter classes are properly reloaded 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 OUT sky sunrun integrate

as both scene and sun will be invoked automatically as needed.

Arguments:

• ctx: click.Context

• out: path to new or existing directory for raytraverse run

• config: path to config file

• n: max number of processes to spawn

Arguments

OUT

Required argument

Options

VALUE OPTIONS:

-c, --config <PATH>

path of config file to load

-n <INTEGER>

sets the environment variable RAYTRAVERSE_PROC_CAP set to0 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

scene

The scene commands creates a Scene object…

sky

the sky command intitializes and runs a sky…

suns

the suns command provides a number of options…

sunrun

the sunrun command intitializes and runs a…

integrate

the integrate command combines sky and sun…

scene

raytraverse scene [OPTIONS]

The scene commands creates a Scene object which holds geometric information about the model including object geometry (and defined materials), the analysis plane and the desired resolutions for sky and analysis plane subdivision

Options

VALUE OPTIONS:

-area <TEXT>

radiance scene file containing planar geometry of analysis area

-maxspec <FLOAT>

an important parameter for guiding reflected sun rays. contribution values above this threshold are assumed to be direct view rays. If possible, (1) this value should be less than the tvis of the darkest glass in the scene, and (2) greater than the highest expected contribution from a specular reflection or scattering interaction. If it is not possible to meet both conditions, then ensure that condition (2) is met and consider using a substantially higher skyres to avoid massive over sampling of direct view rays

Default

0.3

-ptres <FLOAT>

resolution of point subdivision on analysis plane. units match radiance scene file

Default

2.0

-scene <TEXT>

space separated list of radiance scene files (no sky) or precompiled octree

-skyres <FLOAT>

sky is subdivided accoring to a shirley-chiu disk to square mapping, total number of sky bins will equal skyres^2. solid angle of each patch will be 2*pi/(skyres^2)

Default

10.0

FLAGS (DEFAULT TRUE):

--reload, --no-reload

if a scene already exists at OUT reload it, note that ifthis is False and overwrite is False, the program willabort

Default

True

FLAGS (DEFAULT FALSE):

--info, --no-info

print info on scene to stderr

Default

False

--overwrite, --no-overwrite

Warning! if set to True and reload is False all files inOUT will be deleted

Default

False

--points, --no-points

print point locations to stdout

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

sky

raytraverse sky [OPTIONS]

the sky command intitializes and runs a sky sampler and then readies the results for integration by building a SCBinField. sky should be invoked before calling suns, as the sky contributions are used to select the necessary sun positions to run

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

4

-rcopts <TEXT>

rtrace options to pass to the rcontrib call see the man pages for rtrace, rcontrib, and rcontrib -defaults for more information

Default

-ab 7 -ad 60000 -as 30000 -lw 1e-7 -st 0 -ss 16

FLAGS (DEFAULT TRUE):

--rmraw, --no-rmraw

if True removes output of sampler.run(), after SCBinField is constructed. Note that SCBinField cannot be rebuilt once raw files are removed

Default

True

--run, --no-run

if True calls sampler.run()

Default

True

FLAGS (DEFAULT FALSE):

--plotdview, --no-plotdview

plot a direct view of the sky field (as a .hdr file), this is equivalent to integrating with a value of 1 for all sky patches with no interpolation, plots pixels of actualsample vectors in red

Default

False

--plotp, --no-plotp

for diagnostics only, plots the pdf at each level for point[0,0] in an interactive display (note that program will hang until the user closes the plot window at 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

suns

raytraverse suns [OPTIONS]

the suns command provides a number of options for creating sun positions used by sunrun see wea and usepositions options for details

Note:

the wea and skyro parameters are used to reduce the number of suns in cases where a specific site is known. Only suns within the solar transit (or positions if usepositions is True will be selected. It is important to note that when integrating, if a sun position outside this range is queried than results will not include the more detailed simulations involved in sunrun and will instead place the suns energy within the nearest sky patch. if skyres is small and or the patch is directly visible this will introduce significant bias in most metrics.

Options

VALUE OPTIONS:

-loc <FLOATS>

specify the scene location (if not specified in -wea or to override. give as “lat lon mer” where lat is + North, lon is + West and mer is the timezone meridian (full hours are 15 degree increments)

-skyro <FLOAT>

counter clockwise rotation (in degrees) of the sky to rotate true North to project North, so if project North is 10 degrees East of North, skyro=10

Default

0.0

-srct <FLOAT>

if the contribution of a sky patch (for any view ray) is above this threshold, a sun will be created in this patch

Default

0.01

-sunres <FLOAT>

resolution in degrees of the sky patch grid in which to stratify sun samples. Suns are randomly located within the grid, so this corresponds to the average distance between sources. The average error to a randomly selected sun position will be on average ~0.4 times this value

Default

10.0

-wea <TEXT>

path to weather/sun position file. possible formats are:

1. .wea file

2. .wea file without header (require -loc and –no-usepositions)

3. .epw file

4. .epw file without header (require -loc and –no-usepositions)

5. 3 column tsv file, each row is dx, dy, dz of candidate sun position (requires –usepositions)

6. 4 column tsv file, each row is altitude, azimuth, direct normal, diff. horizontal of canditate suns (requires –usepositions)

7. 5 column tsv file, each row is dx, dy, dz, direct normal, diff. horizontal of canditate suns (requires –usepositions)

tsv files are loaded with loadtxt

FLAGS (DEFAULT TRUE):

--reload, --no-reload

if False, regenerates sun positions, because positions may be randomly selected this will make any sunrun results obsolete

Default

True

FLAGS (DEFAULT FALSE):

--plotdview, --no-plotdview

creates a png showing sun positions on an angular fisheye projection of the sky. sky patches are colored by the maximum contributing ray to the scene

Default

False

--usepositions, --no-usepositions

if True, sun positions will be chosen from the positions listed in wea. if more than one position is a candidate for that particular sky patch (as determined by sunres) than a random choice will be made. by using one of the tsv format options for wea, and preselecting sun positions such that there is 1 per patch a deterministic result canbe achieved.

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]

the sunrun command intitializes and runs a sun sampler and then readies the results for integration by building a SunField.

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

4

-rcopts <TEXT>

rtrace options for sun reflection runs see the man pages for rtrace, and rtrace -defaults for more information

Default

-ab 6 -ad 3000 -as 1500 -st 0 -ss 16 -aa .1

-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):

--ambcache, --no-ambcache

whether the rcopts indicate that the calculation will use ambient caching (and thus should write an -af file argument to the engine)

Default

True

--reflection, --no-reflection

run/build/plot reflected sun components

Default

True

--rmraw, --no-rmraw

if True removes output of sampler.run(), after SCBinField is constructed. Note that SCBinField cannot be rebuilt once raw files are removed

Default

True

--run, --no-run

if True calls sampler.run()

Default

True

--view, --no-view

run/build/plot direct sun views

Default

True

FLAGS (DEFAULT FALSE):

--keepamb, --no-keepamb

whether to keep ambient files after run, if kept, a successive call will load these ambient files, so care must be taken to not change any parameters

Default

False

--plotdview, --no-plotdview

plot a direct view of the sky field (as a .hdr file), this is equivalent to integrating with a value of 1 for all sky patches with no interpolation, plots pixels of actualsample vectors in red

Default

False

--plotp, --no-plotp

for diagnostics only, plots the pdf at each level for point[0,0] in an interactive display (note that program will hang until the user closes the plot window at 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

integrate

raytraverse integrate [OPTIONS]

the integrate command combines sky and sun results and evaluates the given set of positions and sky conditions

Options

VALUE OPTIONS:

-interp <INTEGER>

number of nearby rays to use for interpolation of hdroutput (weighted by a gaussian filter). this doesnot apply to metric calculations

Default

12

-loc <FLOATS>

specify the scene location (if not specified in -wea or to override. give as “lat lon mer” where lat is + North, lon is + West and mer is the timezone meridian (full hours are 15 degree increments)

-pts <TEXT>

points to evaluate, 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. in all cases each point requires 6 numbers x,y,z,dx,dy,dz so the shape of the array will be (N, 6)

Default

0,0,0,0,-1,0

-res <INTEGER>

the resolution of hdr output in pixels

Default

800

-skyro <FLOAT>

counter clockwise rotation (in degrees) of the sky to rotate true North to project North, so if project North is 10 degrees East of North, skyro=10

Default

0.0

-vname <TEXT>

name to include with hdr outputs

Default

view

-wea <TEXT>

path to weather/sun position file. possible formats are:

1. .wea file

2. .wea file without header (requires -loc)

3. .epw file

4. .epw file without header (requires -loc)

5. 4 column tsv file, each row is altitude, azimuth, direct normal, diff. horizontal of canditate suns (requires –usepositions)

6. 5 column tsv file, each row is dx, dy, dz, direct normal, diff. horizontal of canditate suns (requires –usepositions)

tsv files are loaded with loadtxt

FLAGS (DEFAULT TRUE):

--hdr, --no-hdr

produce an hdr output for each point and line in wea

Default

True

--metric, --no-metric

calculate metrics for each point and wea file output is ordered by point than sky

Default

True

FLAGS (DEFAULT FALSE):

--header, --no-header

print column headings on metric output

Default

False

--skyonly, --no-skyonly

if True, only integrate on Sky Field, useful for diagnostics

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