raytraverse.craytraverse¶

Renderer¶

class craytraverse.renderer.Renderer(rayargs=None, scene=None, nproc=1)[source]¶

Bases: object

Virtual class for wrapping c++ Radiance renderer executable classes

Do not use directly, either subclass or use existing: Rtrace, Rcontrib

name = 'radiance_virtual'¶

instance = None¶

srcn = 1¶

features = 1¶

args = None¶

nproc = 1¶

run(*args, **kwargs)[source]¶: alias for call, for consistency with SamplerPt classes for nested dimensions of evaluation

classmethod reset()[source]¶: reset engine instance and unset associated attributees

classmethod set_args(args, nproc=1)[source]¶

prepare arguments to call engine instance initialization

Parameters

args (str) – rendering options
nproc (int, optional) – cpu limit

classmethod load_scene(scene)[source]¶

load octree file to engine instance

Parameters: scene (str) – path to octree file
Raises: ValueError: – can only be called after set_args, otherwise engine instance will abort.

Rtrace¶

class craytraverse.renderer.Rtrace(rayargs=None, scene=None, nproc=1)[source]¶

Bases: craytraverse.renderer.renderer.Renderer

singleton wrapper for c++ raytrraverse.crenderer.cRtrace class

this class sets default arguments, helps with initialization and setting cpu limits of the cRtrace instance. see raytraverse.crenderer.cRtrace for more details.

Parameters

rayargs (str, optional) – argument string (options and flags only) raises ValueError if arguments are not recognized by cRtrace.
scene (str, optional) – path to octree
nproc (int, optional) – if None, sets nproc to cpu count, or the RAYTRAVERSE_PROC_CAP environment variable

Examples

Basic Initialization and call:

r = renderer.Rtrace(args, scene)
ans = r(vecs)
# ans.shape -> (vecs.shape[0], 1)

If rayargs include cache files (ambient cache or photon map) be careful with updating sources. If you are going to swap sources, update the arguments as well with the new paths:

r = renderer.Rtrace(args, scene)
r.set_args(args.replace("temp.amb", "temp2.amb"))
r.load_source(srcdef)

Note that if you are using ambient caching, you must give an ambient file, because without a file ambient values are not shared across processes or successive calls to the instance.

name = 'rtrace'¶

instance = <craytraverse.crenderer.rtrace_c.cRtrace object>¶: craytraverse.crenderer.cRtrace

ospec = 'v'¶

classmethod set_args(args, nproc=1)[source]¶

prepare arguments to call engine instance initialization

Parameters

args (str) – rendering options
nproc (int, optional) – cpu limit

classmethod update_ospec(vs)[source]¶

set output of cRtrace instance

Parameters

vs (str) –

output specifiers for rtrace::: o origin (input) d direction (normalized) v value (radiance) V contribution (radiance) w weight W color coefficient l effective length of ray L first intersection distance c local (u,v) coordinates p point of intersection n normal at intersection (perturbed) N normal at intersection (unperturbed) r mirrored value contribution x unmirrored value contribution R mirrored ray length X unmirrored ray length

Returns

outcnt – the number of output columns to expect when calling rtrace instance

Return type

int

Raises

ValueError: – when an output specifier is not recognized

classmethod check_amb(args)[source]¶

classmethod load_source(srcfile, freesrc=- 1, ambfile=None)[source]¶

add a source description to the loaded scene

Parameters

srcfile (str) – path to radiance scene file containing sources, these should not change the bounding box of the octree and has only been tested with the “source” type.
freesrc (int, optional) – the number of objects to unload from the end of the rtrace object list, if -1 unloads all objects loaded by previous calls to load_source
ambfile (str, optional) – path to ambient file. if given, and arguments

Rcontrib¶

class craytraverse.renderer.Rcontrib(rayargs=None, scene=None, nproc=1, skyres=15, modname='skyglow', ground=True)[source]¶

Bases: craytraverse.renderer.renderer.Renderer

singleton wrapper for c++ raytrraverse.crenderer.cRcontrib class

this class sets default arguments, helps with initialization and setting cpu limits of the cRcontrib instance. see raytrraverse.crenderer.cRcontrib for more details.

Parameters

rayargs (str, optional) – argument string (options and flags only) raises ValueError if arguments are not recognized by cRtrace.
scene (str, optional) – path to octree
nproc (int, optional) –
skyres (int, optional) – resolution of sky patches (sqrt(patches / hemisphere)). So if skyres=18, each patch will be 100 sq. degrees (0.03046174197 steradians) and there will be 18 * 18 = 324 sky patches.
modname (str, optional) – passed the -m option of cRcontrib initialization
ground (bool, optional) – if True include a ground source (included as a final bin)

Examples

Basic Initialization and call:

r = renderer.Rcontrib(args, scene)
ans = r(vecs)
# ans.shape -> (vecs.shape[0], 325)

name = 'rcontrib'¶

instance = <craytraverse.crenderer.rcontrib_c.cRcontrib object>¶

ground = True¶

skyres = 15¶

srcn = 226¶

modname = 'skyglow'¶

classmethod setup(scene=None, ground=True, modname='skyglow', skyres=15)[source]¶

set class attributes for proper argument initialization

Parameters

scene (str, optional) – path to octree
ground (bool, optional) – if True include a ground source (included as a final bin)
modname (str, optional) – passed the -m option of cRcontrib initialization
skyres (float, optional) – resolution of sky patches (sqrt(patches / hemisphere)). So if skyres=10, each patch will be 100 sq. degrees (0.03046174197 steradians) and there will be 18 * 18 = 324 sky patches.

Returns

scene – path to scene with added sky definition

Return type

str

classmethod set_args(args, nproc=1)[source]¶

prepare arguments to call engine instance initialization

Parameters

args (str) – rendering options
nproc (int, optional) – cpu limit

cRtrace¶

class craytraverse.crenderer.cRtrace¶

Bases: pybind11_builtins.pybind11_object

singleton interface to the Radiance rtrace executable.

See the rtrace man page for a full description of the programs functionality. Instance is initialized with a list of arguments similar to the command line tool, but with several differences:

no -f format specifier, input and output is always a numpy array.

no -h option.

no -x/-y options, shape output data as necessary with np.reshape

no -P/-PP modes

an additional -c N option repeats each input N times and averages the result. Make sure that uncorrelated sampling is used (-U+, default)

the default output is -oz, z is an additional output specifier that yields a single photopic brightness per input ray.

no s/m/M/t/T/~ allowed as output specifiers

Examples

basic usage:

from raytraverse.crenderer import cRtrace
instance = cRtrace.get_instance()
instance.initialize(["rtrace", ...]) #Note: do not include octree at end!
instance.load_scene("scene.oct")
# ...
# define 'rays' as a numpy array of shape (N, 6)
# ...
lum = instance(rays)

cRtrace can also update the output specification and/or the settings without reloading the scene geometry:

instance.update_ospec("L") # to query ray distance
instance.initialize("rtrace -ab 0 -lr 1".split()) # note this begins with default arguments, it is not additive with previous settings!
raylength = instance(rays)

but if you are loading new geometry, the instance should be reset:

instance.reset()
instance.initialize(["rtrace", ...])
instance.load_scene("scene2.oct")

by loading a scene without light sources, sources can be dynamically loaded and unloaded without a reset:

instance.reset()
instance.initialize(["rtrace", ...])
instance.load_scene("scene_no_sources.oct")
instance.load_source("sky.rad")
skylum = instance(rays)
instance.load_source("sun.rad") # this unloads sky.rad and loads sun.rad
sunlum = instance(rays)
instance.load_source("sky.rad", 0) # using the optional freesrc, keep the sun loaded
totallum = instance(rays)
if np.allclose(skylum + sunlum, totallum, atol=.03): # depending on rendering settings / scene complexity
    print("light is additive!)

Notes

the cRtrace instance is best managed from a separate class that handles argument generation. See raytraverse.renderer.Rtrace

__call__(self: craytraverse.crenderer.rtrace_c.cRtrace, vecs: numpy.ndarray[numpy.float64]) → numpy.ndarray[numpy.float64]¶

run renderer for a set of rays

Parameters: vecs (np.array) – shape (N, 6) origin + direction vectors
Returns: values – shape (N, M) result array, M depends on output specification
Return type: np.array

__init__(*args, **kwargs)¶

get_instance() → craytraverse.crenderer.rtrace_c.cRtrace¶: returns (instantiating if necessary) pointer to Renderer instance.

get_sources(self: craytraverse.crenderer.rtrace_c.cRtrace) → tuple¶

return list of sources in model

Returns

sources (np.array) – shape: (N, 5) for each source x,y,z position (or direction), maximum radius, solid angle (or area)
distant (np.array) – shape: (N,) True if source is distant (so x,y,z should be interpreted as direction)

initialize(self: craytraverse.crenderer.rtrace_c.cRtrace, arglist: object) → int¶

arglist (a sequence of strings) must be a member of calling instance and persist for duration of program

Parameters: arglist (list) – a sequence of arguments to initialize renderer. must be a member of calling instance and persist for duration of program
Returns: nproc – number of processors renderer initialized with or -1 if initialization failed.
Return type: int

load_scene(self: craytraverse.crenderer.rtrace_c.cRtrace, octree: str) → None¶

load scene file to renderer

Parameters: octee (str) – path to octree file.

load_source(self: craytraverse.crenderer.rtrace_c.cRtrace, srcname: str, freesrc: int = - 1) → None¶

arglist (a sequence of strings) must be a member of calling instance and persist for duration of program

updates private srcobj parameter for default removing all sources

Parameters

srcname (str) – path to file with source definition.
freesrc (int, optional) – number of previous sources to unload (unloads from end of object list only safe if removing sources loaded by this function. If negative removes all sources loaded by this function.

reset(self: craytraverse.crenderer.rtrace_c.cRtrace) → None¶: reset renderer state, must be called before loading an new scene or changing rendering parameters

update_ospec(self: craytraverse.crenderer.rtrace_c.cRtrace, vs: str) → int¶

update output values request

Parameters: vs (str) – output specification string (see rtrace manpage option -o)
Returns: ncomp – number of components renderer will return, or -1 on failure.
Return type: int

cRcontrib¶

class craytraverse.crenderer.cRcontrib¶

Bases: pybind11_builtins.pybind11_object

singleton interface to the Radiance rcontrib executable.

See the rcontrib man page for a full description of the programs functionality. Instance is initialized with a list of arguments similar to the command line tool, but with several differences:

no -o option. All output is written to a memory buffer returned as a Numpy array

no -f format specifier, input and output is always a numpy array.

no -r option.

no -h option.

the -c option repeats and accumulates input rays rather than accumulating input.

an additional flag -Z outputs a single brightness value (photopic) rather than 3-color channels. this is True by default.

Examples

basic usage:

from raytraverse.crenderer import cRcontrib
instance = cRcontrib.get_instance()
instance.initialize(["rcontrib", "-n", "8", ..., "-m", "mod"])  #Note: do not include octree at end!
instance.load_scene("scene.oct")
# ...
# define 'rays' as a numpy array of shape (N, 6)
# ...
contributions = instance(rays)

Subsequent calls can be made to the instance, but if either the settings or scene are changed:

instance.reset()
instance.initialize(["rcontrib", "-n", "8", ..., "-m", "mod2"])
instance.load_scene("scene2.oct")

Notes

the cRcontrib instance is best managed from a seperate class that handles argument generation. See raytraverse.renderer.Rcontrib

__call__(self: craytraverse.crenderer.rcontrib_c.cRcontrib, vecs: numpy.ndarray[numpy.float64]) → numpy.ndarray[numpy.float64]¶

run renderer for a set of rays

Parameters: vecs (np.array) – shape (N, 6) origin + direction vectors
Returns: values – shape (N, M) result array, M depends on output specification
Return type: np.array

__init__(*args, **kwargs)¶

get_instance() → craytraverse.crenderer.rcontrib_c.cRcontrib¶: returns (instantiating if necessary) pointer to Renderer instance.

initialize(self: craytraverse.crenderer.rcontrib_c.cRcontrib, arglist: object) → int¶

arglist (a sequence of strings) must be a member of calling instance and persist for duration of program

Parameters: arglist (list) – a sequence of arguments to initialize renderer. must be a member of calling instance and persist for duration of program
Returns: nproc – number of processors renderer initialized with or -1 if initialization failed.
Return type: int

load_scene(self: craytraverse.crenderer.rcontrib_c.cRcontrib, octree: str) → None¶

load scene file to renderer

Parameters: octee (str) – path to octree file.

reset(self: craytraverse.crenderer.rcontrib_c.cRcontrib) → None¶: reset renderer state, must be called before loading an new scene or changing rendering parameters

raytraverse helper functions written in c++

craytraverse.craytraverse.from_pdf(pdf: numpy.ndarray[numpy.float64], threshold: float, lb: float = 0.5, ub: float = 4.0) → tuple¶

helper function for draw.from_pdf

Parameters

pdf (np.array) – array of doubles with weights to check against threshold
threshold (float) – value used to determine the number of indices to return
lb (float, optional) – values below threshold * lb will be excluded from candidates (lb must be in (0,1)
ub (float, optional) – values above threshold * ub will have indices written to bidx

Returns

candidates (np.array) – array of candidate indices
bidx (np.array) – array of definitely included indices
nsampc (int) – the number of draws that should be selected from the candidates

craytraverse.craytraverse.interpolate_kdquery(destvec: numpy.ndarray[numpy.float64], errs: numpy.ndarray[numpy.float64], idxs: numpy.ndarray[numpy.int32], srcvec: numpy.ndarray[numpy.float64], srclum: numpy.ndarray[numpy.float64], err: float = 0.00436) → numpy.ndarray[numpy.float64]¶

interpolate luminance values associated with query results from scipy.cKDTree.query. Finds closest point and then locates vertices of enclosing triangle from this point. returns 0 in cases where the query provides no results, so the distance_upper_bound must be set appropriately. :param dest_vec: destination vectors to interpolate to, shape (N, 3) :type dest_vec: np.array :param errs: distances between src and destination (row matches dest_vec, column is sorted ascending), shape (N, # of queries) :type errs: np.array :param idxs: query result, index row in src_vec close to dest_vec, shape (N, # of queries) :type idxs: np.array :param src_vec: vectors of src_kd, shape (N, 3) :type src_vec: np.array :param src_lum: luminance values for src_kd, shape (src_vec.shape[0], srcn) :type src_lum: np.array :param err: distance below which closest sample is used directly :type err: float, optional

Returns: arrout – destination luminances shape (N, srcn)
Return type: np.array