raytraverse (1.3.10)¶

raytraverse is a workflow for climate based daylight simulation for the evaluation of architectural spaces. Built around a wavelet guided adaptive sampling strategy, raytraverse can fully explore the daylight conditions throughout a space with efficient use of processing power and storage space.

Free software: Mozilla Public License 2.0 (MPL 2.0)
Documentation: https://raytraverse.readthedocs.io/en/latest/.

Installation¶

The easiest way to install raytraverse is with pip:

pip install --upgrade pip setuptools wheel
pip install raytraverse

or if you have cloned this repository:

cd path/to/this/file
pip install .

while raytraverse installs with the necessary essentials of radiance, it is recommended to also install radiance (see: https://github.com/LBNL-ETA/Radiance/releases and make sure you or the installer also sets the $RAYPATH variable) this is especially important if your material or light source definitions rely on .cal files distributed with radiance, such as perezlum.cal, window.cal, etc. Missing .cal files or other scene errors can cause raytraverse traverse to abort with cryptic eror messages (the number value is not meaningful and will be different every time):

python: : Unknown error -1624667552

If you encounter such an error, make sure your scene is valid in your current environment, using rvu, rpict, or rtrace.

Windows¶

Currently raytraverse is only compatible with macOS and linux operating systems. One way to use raytraverse on a Windows machine is with Docker. In adddition to the Docker installation, this process will require about 2.5 GB of disk space.

Install Docker from: https://www.docker.com/products/docker-desktop/ (click on “Windows”) and then follow the installation instructions.
Open the newly installed Docker Desktop application (you do not need to sign in or create an account)

In an empty directory make a file called Dockerfile_first with the following contents:

# syntax=docker/dockerfile:1
# docker build -f Dockerfile_first . --tag raytraverse:latest
FROM python:3.9

WORKDIR /build
RUN apt-get update
RUN apt-get -y install man

SHELL ["/bin/bash", "-c"]
RUN pip3 install raytraverse
RUN curl -s https://api.github.com/repos/LBNL-ETA/Radiance/releases\?per_page\=1 \
| grep "browser_download_url.*Linux.zip" | cut -d: -f2,3 | tr -d \" | wget -i -
RUN unzip Radiance_*_Linux.zip
RUN tar -xzf radiance-*-Linux.tar.gz
WORKDIR /radiance
RUN rm -rf bin lib man
RUN mv /build/radiance-*-Linux/usr/local/radiance/* ./
RUN rm -rf /build

ENV RAYPATH=.:/radiance/lib
ENV MANPATH=/radiance/man
ENV PATH=/radiance/bin:$PATH
RUN raytraverse --help
WORKDIR /working

in a command prompt navigate to this folder and run the following to create a docker image with raytraverse and radiance installed:
```
docker build - --tag raytraverse:latest < Dockerfile_first
```
To use raytraverse, navigate to a local folder that contains all necessary files (radiance scene files, sky data, etc.).
Now, in this folder (note that you may need to change the syntax of “$(pwd)” to be compatible with your shell, this works with the basic windows command prompt):
```
docker run -it --name rayt --mount type=bind,source="$(pwd)",target=/working raytraverse /bin/bash
```
You now have a linux/bash command prompt in an environment with raytraverse, radiance, and python 3.9 installed. The currrent directory will be named “working” within the linux environment and is a shared resource with the host (changes on the host side are immediately seen in the container and vice versa). When you are finished, exit the linux shell (“exit”), then in the (now) windows command prompt:
```
docker rm rayt
```
for ease of use, you can put these to lines in a .bat file somewhere in your execution PATH, just make sure that docker desktop is running before calling:
```
docker run -it --name rayt --mount type=bind,source="$(pwd)",target=/working raytraverse /bin/bash
docker rm rayt
```

to update raytraverse, the process is similar to step 4, but with a slightly different dockerfile:

# syntax=docker/dockerfile:1
# docker build -f Dockerfile_update . --tag raytraverse:latest
FROM raytraverse:latest

WORKDIR /build

SHELL ["/bin/bash", "-c"]
RUN pip3 install --upgrade --no-deps craytraverse
RUN pip3 install --upgrade --no-deps clasp
RUN pip3 install --upgrade --no-deps raytraverse
RUN curl -s https://api.github.com/repos/LBNL-ETA/Radiance/releases\?per_page\=1 \
| grep "browser_download_url.*Linux.zip" | cut -d: -f2,3 | tr -d \" | wget -i -
RUN unzip Radiance_*_Linux.zip
RUN tar -xzf radiance-*-Linux.tar.gz
WORKDIR /radiance
RUN rm -rf bin lib man
RUN mv /build/radiance-*-Linux/usr/local/radiance/* ./
RUN rm -rf /build

ENV RAYPATH=.:/radiance/lib
ENV MANPATH=/radiance/man
ENV PATH=/radiance/bin:$PATH
RUN raytraverse --help
WORKDIR /working

and this command:

docker build - --tag raytraverse:latest < Dockerfile_update

see the Docker settings for information about resource allocation to the docker container.

Usage¶

raytraverse includes a complete command line interface with all commands nested under the raytraverse parent command enter:

raytraverse --help

raytraverse also exposes an object oriented API written primarily in python. calls to Radiance are made through Renderer objects that wrap the radiance c source code in c++ classes, which are made available in python with pybind11. see craytraverse (https://pypi.org/project/craytraverse/).

For complete documentation of the API and the command line interface either use the Documentation link included above or:

pip install -r docs/requirements.txt
make docs

to generate local documentation.

Command Line Interface¶

The raytraverse command provides command line access to executing common tasks. The best way to manage all of the options is with a .cfg file. First, generate a template:

raytraverse --template > options.cfg

and then edit the options for each file. for example, here is a simplified configuration for a low accuracy sample simulation, assuming a model scaled in meters where plane.rad is betwee 4m and 10m on each side:

[shared]
weather_file = weather.epw

[raytraverse_scene]
out = outdir
scene = room.rad

[raytraverse_area]
ptres = 2.0
zone = plane.rad

[raytraverse_suns]
epwloc = True
loc = ${shared:weather_file}

[raytraverse_skydata]
wea = ${shared:weather_file}
skyres = 10

[raytraverse_skyengine]
accuracy = 2.0
skyres = 10

[raytraverse_sunengine]
accuracy = 2.0
rayargs = -ab 0
nlev = 5

[raytraverse_skyrun]
accuracy = 2.0
edgemode = reflect
nlev = 2

[raytraverse_sunrun]
accuracy = 3.0
edgemode = reflect
nlev = 2
srcaccuracy = 2.0
srcnlev = 2

[raytraverse_images]
basename = results
blursun = True
interpolate = highc
res = 800
resampleview = True
sdirs = None
sensors = None
skymask = 0:24

[raytraverse_evaluate]
basename = results
sdirs = None
sensors = None
skymask = None

[raytraverse_pull]
col = metric point
gridhdr = True
ofiles = results
skyfill = ${shared:weather_file}
viewfilter = 0

and then from the command line run:

raytraverse -c options.cfg skyrun directskyrun sunrun evaluate pull

Command Line Interface

raytraverse
- scene
- area
- suns
- skydata
- skyengine
- sunengine
- sourceengine
- skyrun
- directskyrun
- sunrun
- sourcerun
- images
- evaluate
- pull
raytu
- transform
- imgmetric
- project
- lp2img
- pull
- merge
- padsky

Tutorials¶

Toturials

Directional Sampling Overview

Citation¶

Either the latest or specific releases of this software are archived with a DOI at zenodo. See: https://doi.org/10.5281/zenodo.4091318

Please cite this journal article for a description and validation of the method:

Stephen Wasilewski, Lars O. Grobe, Jan Wienold, Marilyne Andersen, Efficient Simulation for Visual Comfort Evaluations, Energy and Buildings, Volume 267, 2022, 112141, ISSN 0378-7788, https://doi.org/10.1016/j.enbuild.2022.112141.

Additional peer-reviewed references related to this software:

Stephen Wasilewski, Lars O. Grobe, Roland Schregle, Jan Wienold, and Marilyne Andersen. 2021. Raytraverse: Navigating the Lightfield to Enhance Climate-Based Daylight Modeling. In 2021 Proceedings of the Symposium on Simulation in Architecture and Urban Design. https://infoscience.epfl.ch/record/290685?ln=en

Quek, G., Wasilewski, S., Wienold, J., Andersen, M., 2021a. Spatial evaluation of potential saturation and contrast effects of discomfort glare in an open-plan office, in: BS2021. Presented at the Building Simulation 2021 Conference, Bruges, Belgium. https://infoscience.epfl.ch/record/288945

Licence¶

Copyright (c) 2020 Stephen Wasilewski, HSLU and EPFL
This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/.

Acknowledgements¶

Thanks to additional project collaborators and advisors Marilyne Andersen, Lars Grobe, Roland Schregle, Jan Wienold, and Stephen Wittkopf

This software development was financially supported by the Swiss National Science Foundation as part of the ongoing research project “Light fields in climate-based daylight modeling for spatio-temporal glare assessment” (SNSF #179067).

Software Credits¶

Raytraverse uses Radiance

As well as all packages listed in the requirements.txt file, raytraverse relies heavily on the Python packages numpy, scipy, and for key parts of the implementation.

C++ bindings, including exposing core radiance functions as methods to the renderer classes are made with pybind11

Installation and building from source uses cmake and scikit-build

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.