README.md

FlatlandRT

Description

FlatlandRT is a 2D ray tracer visualization tool. The following pictures were created using FlatlandRT:

From left to right: Refraction, ambient occlusion and reflection:

Quadtree intersection of 2D triangle meshes:

More examples scenes can be found here. See the user manual if you want to find out how to use it.

Quick start

This project uses Bazel as a build system. The current used version is defined in .bazelversion.

Prerequisites:

The following tools should be installed:

• Git
• Bazel
• A C++ compiler (GCC, Visual Studio, Clang, etc.)

Checkout, build, and run:

You can use Flatland by invoking the following commands:

All platforms:

git clone https://github.com/Vertexwahn/FlatlandRT # clone the repository
cd FlatlandRT # change directory to cloned repository
cd devertexwahn # switch to the location where the WORKSPACE.bazel file is located

Render a scene with Windows 10/11 x64 with Visual Studio 2019:

bazel --output_base=C:/bazel_output_base  run --config=vs2019 //flatland/cli:flatland.cli --scene_filename=C:\scenes\bunny.flatland.xml

Render a scene with Windows 10/11 x64 with Visual Studio 2022:

bazel --output_base=C:/bazel_output_base  run --config=vs2022 //flatland/cli:flatland.cli --scene_filename=C:\scenes\bunny.flatland.xml

For more hints on how to use Bazel on Windows have a look at the Bazel on Windows document.

Render a scene with Ubuntu 20.04:

bazel run --config=gcc9 //flatland/cli:flatland.cli -- --scene_filename=$(pwd)/flatland/scenes/bunny/bunny.flatland.xml

Render a scene with Ubuntu 22.04:

bazel run --config=gcc11 //flatland/cli:flatland.cli -- --scene_filename=$(pwd)/flatland/scenes/bunny/bunny.flatland.xml

Render a scene with macOS 11/12/13:

bazel run --config=macos //flatland/cli:flatland.cli -- --scene_filename=$(pwd)/flatland/scenes/bunny/bunny.flatland.xml

Building & Testing

Building and testing with Linux

Command line (bash/zsh)

# Run all tests using GCC 9.3
bazel test --config=gcc9 //...
# Build all targets uing GCC 9.3
bazel build --config=gcc9 //... 
# Run all tests using GCC 11
bazel test --config=gcc11 //...
# Build all targets uing GCC 11
bazel build --config=gcc11 //...
# Run all tests using Clang 14
bazel test --config=clang14 //...
# Build all targets uing Clang 14
bazel build --config=clang14 //...

CLion

There is a Bazel plug-in for CLion. It can be downloaded from here.

You can use the following .bazelproject file:

directories:
  .

test_sources:
  flatland/tests

derive_targets_from_directories: true

additional_languages:
  python

build_flags:
  --config=gcc11

Code coverage

Make sure that lcov is installed.

sudo apt install lcov

Go to the directory that contains the WORKSPACE.bazel file and execute:

./coverage.sh buchgr_remote_cache
xdg-open coverage_report/index.html

Address Sanitizer

There is a build config called asan that can be used for detecting memory errors.

bazel run --config=asan --compilation_mode=opt //flatland/cli:flatland.cli --  $(pwd)/flatland/scenes/sphere.flatland.xml

Clang Tidy

bazel build --config=clang-tidy //flatland/core/...

Building with Windows

Command line (Powershell)

# Build with Visual Studio C++ Compiler
bazel build --config=vs2022 //...

Using Visual Studio

Use Lavender to generate a solution and project files for Visual Studio.

python3 G:\dev\lavender\generate.py --config=vs2022  //...

Lavender is far from being perfect. It might be necessary to do some modifications to the generated solution and project files.

Development process

I made a short video where I describe how I use test driven development to implement this project:

Ray tracing 101

I have written some blog post about ray tracing that can be found here: Ray Tracing 101

License

The source code of FlatlandRT itself is under the Apache License 2.0 (see LICENSE). The license of its third-party dependencies or some third-party code fragments can and is under different license terms. See copyright notes in the next section.

Copyright notes

FlatlandRT makes use of several software libraries. Some tools and libraries were copied to this repository (see third_party folder). The corresponding licenses can be found in the third_party folder of this repository. Besides this, some source code was directly copied from other open-source software libraries or programs. This is always clearly stated as a comment in the source code of FlatlandRT. If you find any copyright or license violations or issues please let me know.

Copied source code/ideas

• Mitsuba Renderer 2 (https://github.com/mitsuba-renderer/mitsuba2) (scene file format) (License)
• pbrt, Version 3 (https://github.com/mmp/pbrt-v3) (Refract, face_forward functions) (License)
• pbrt, Version 4 (https://github.com/mmp/pbrt-v4) (concentric sampling of unit disk) (License)
• bazel_clang_tidy (https://github.com/erenon/bazel_clang_tidy) (almost everything) (License)

Build related

• LLVM toolchain for Bazel (https://github.com/grailbio/bazel-toolchain) (building Flatland with LLVM) (License)

Third party dependencies

• {fmt} (https://github.com/fmtlib/fmt) (see third_party folder)
• abseil (https://abseil.io/) (see third_party folder)
• Boost (https://www.boost.org/) (third party dependency) (License)
• Catch2 (https://github.com/catchorg/Catch2) (see third_party folder)
• Eigen (see third_party folder)
• gflags (https://github.com/gflags/gflags/) (see third_party folder)
• glog (https://github.com/google/glog) (see third_party folder)
• Google Test (https://github.com/google/googletest) (see third_party folder)
• hypothesis (https://github.com/wjakob/hypothesis) (see third_party folder)
• Imath (see third_party folder)
• libpng (http://www.libpng.org/pub/png/libpng.html) (License)
• LLVM toolchain for Bazel (see third_party folder)
• OpenEXR (https://github.com/AcademySoftwareFoundation/openexr) (License)
• pcg-cpp (https://github.com/imneme/pcg-cpp/)
• pugixml (https://pugixml.org/, https://github.com/zeux/pugixml)
• rules_boost (https://github.com/nelhage/rules_boost) (License)
• rules_pkg-0.9.1
• yaml-cpp (https://github.com/jbeder/yaml-cpp) (third party dependency) (License)
• zlib (https://zlib.net/) (License)

Artwork

The Stanford Bunny was derived from the Stanford Bunny provided from the Stanford 3D Scanning Repository (see here).

The data for the Donut, Armadillo and Stanford Bunny for the 2D triangle data was derived from https://github.com/mmacklin/sandbox.

Credits

A big thank goes to all the providers, developers, and maintainers of the aforementioned open source projects and artifacts.