# Renderer

class craytraverse.renderer.Renderer(rayargs=None, scene=None, nproc=1)

  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)

    alias for call, for consistency with SamplerPt classes for nested dimensions of evaluation

  classmethod reset()

    reset engine instance and unset associated attributees

  classmethod set_args(args, nproc=1)

    prepare arguments to call engine instance initialization

    Parameters

      - args (str) – rendering options

      - nproc (int, optional) – cpu limit

  classmethod load_scene(scene)

    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)

  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)

    prepare arguments to call engine instance initialization

    Parameters

      - args (str) – rendering options

      - nproc (int, optional) – cpu limit

  classmethod update_ospec(vs)

    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)
  classmethod load_source(srcfile, freesrc=- 1, ambfile=None)

    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)

  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)

    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)

    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