raytraverse helper functions written in c++

`raytraverse.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

`raytraverse.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

# cRtrace

class `raytraverse.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

  > - -lr 0 behaves differently from radiance, sets a true reflection limit of 0 rather than disabling limit, for behavior approaching radiance, set -lr -1000

  > - 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 0".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 cRcontrib instance is best managed from a seperate class that handles argument generation. See raytraverse.renderer.Rtrace

  `__call__`(self: raytraverse.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__`()

    Initialize self. See help(type(self)) for accurate signature.

  `__module__` = 'raytraverse.crenderer.rtrace_c'
  `__pybind11_module_local_v4_clang_libcpp_cxxabi1002__` = <capsule object NULL>
  `get_instance`() → raytraverse.crenderer.rtrace_c.cRtrace

    returns (instantiating if necessary) pointer to Renderer instance.

  `initialize`(self: raytraverse.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: raytraverse.crenderer.rtrace_c.cRtrace, octree: str) → None

    load scene file to renderer

    Parameters

      octee (str) – path to octree file.

  `load_source`(self: raytraverse.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: raytraverse.crenderer.rtrace_c.cRtrace) → None

    reset renderer state, must be called before loading an new scene or changing rendering parameters

  `update_ospec`(self: raytraverse.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

  `version` = 'RADIANCE 5.4a (https://github.com/LBNL-ETA/Radiance/tree/c59dce44) compiled 2021-09-02 for raytraverse'

# cRcontrib

class `raytraverse.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: raytraverse.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__`()

    Initialize self. See help(type(self)) for accurate signature.

  `__module__` = 'raytraverse.crenderer.rcontrib_c'
  `get_instance`() → raytraverse.crenderer.rcontrib_c.cRcontrib

    returns (instantiating if necessary) pointer to Renderer instance.

  `initialize`(self: raytraverse.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: raytraverse.crenderer.rcontrib_c.cRcontrib, octree: str) → 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`(*args) → None

    reset renderer state, must be called before loading an new scene or changing rendering parameters

  `version` = 'RADIANCE 5.4a (https://github.com/LBNL-ETA/Radiance/tree/c59dce44) compiled 2021-09-02 for raytraverse'