Editing Appleseed

= Appleseed Integration Project =
This is an effort to bring physically-based rendering (PBR) to solid geometry CAD modeling in BRL-CAD.  The goal of the project is to be able to support as many 'rt' features as possible so that 'art' is a drop-in replacement.  Collaboration with [https://appleseedhq.net appleseed] began in 2014 after talks at the 10th-year GSoC summit.  Appleseed devs created [https://github.com/appleseedhq/appleseed/blob/master/src/appleseed/renderer/modeling/object/proceduralobject.h a procedural geometry interface] that enabled PBR on BRL-CAD geometry using our ray tracing engine (LIBRT).  

This project has been realized through the development efforts of GCI students, GSoC students, and capstone students at Texas A&M University, enabled by development support and mentoring by BRL-CAD and Appleseed development teams.


== Progress ==
The appleseed integration project takes advantage of appleseed's support for procedural objects, which allows for the creation of a custom plugin to execute custom ray-intersect logic. By linking with librt, the plugin is thus able to render BRL-CAD geometry. Aside from simply being able to render the geometry, art.exe currently supports a few select rt features. At the moment, art.exe is capable of:
* selecting the geometry model and the regions to render
* defining the render image pixel dimensions
* setting the azimuth/elevation and perspective angle
* selecting the number of cores to use for multithreaded rendering

As mentioned, the goal of the project is for art.exe to implement the same features as rt.exe, so that, in a sense, they can be used interchangeably. Therefore, if possible, it would be preferred if art could reuse the same helper functions and variables used by rt. For example, much of the command-line option parsing performed by art directly comes from opt.c/usage.cpp, which was originally used by rt. This makes the code much cleaner and easier to maintain.

== To-Do ==
=== Separating Regions ===
* The custom BRL-CAD plugin currently tracks all BRL-CAD regions and their mappings to Appleseed instances via a single "ray trace instance pointer" (rtip).  It uses a string comparison to determine if a hit is on a corresponding appleseed instance.  While this works, it's incredibly inefficient.  It either needs a separate rtip per object (ideal) or it needs to use pointers/integers to determine if we hit the Appleseed instance.

=== Colors/Materials ===
* BRL-CAD objects are rendered by appleseed individually and can have different colors and/or materials assigned to each instance.  However, there is no automatic mapping from BRL-CAD shader settings to Appleseed settings.  PBR shaders are supported via BRL-CAD 'material' objects (see 'material' command and gltf import). Using more advanced materials (e.g., with textures) is untested.

=== Multithreading Support ===
* Both appleseed and librt are capable of multithreaded rendering, but at the moment, the plugin will only work on a single thread. At some point, multithreading support should be implemented in order to fully take advantage of appleseed/librt capabilities.

=== Refining CMake ===
* Setting up the appleseed project requires a lot of hacky and manual work due to relying on a pre-built binary of Appleseed.  The CMake build needs to compile Appleseed and all its dependencies using CMake's External_ProjectAdd feature in order to make the build process easier for all platforms and in order to ensure 'art' is always enabled.


== Compiling 'art' ==

To compile the 'art' application in BRL-CAD, follow these steps:

# [[Compiling|Download and compile BRL-CAD]]
# [https://appleseedhq.net Download and install a pre-compiled appleseed]
# Run appleseed.studio to determine version of Boost needed under Help->About (likely 1.69.0 or 1.70.0)
# Install Boost
## For Windows, [https://www.boost.org/users/download/ download and install 'Prebuilt Windows binaries'] matching Help->About
## For Mac, run "brew install boost"
## For other platforms, use your system's preferred package management system
# Create a fresh BRL-CAD build dir (e.g., 'build.appleseed')
# Run CMake GUI (cmake CLI can be used, but instructions below are for GUI)
## Specify path to BRL-CAD sources
## Specify path to the fresh BRL-CAD build dir
## Check "Advanced"
## Select "+ Add Entry", define Appleseed_ROOT=/path/to/appleseed
## Select "+ Add Entry", define BOOST_ROOT=/path/to/boost
## Select "Configure"
## Edit Boost_* component variables to have 'lib' prefix (e.g., libboost_atomic... instead of boost_atomic...)
## Select "Configure" again, confirm output says Appleseed found and Boost found
## Select "Generate"
## Select "Open Project"
# Navigate to BRL-CAD Executables ->  Rt -> art, right-click and select Build
# IFF on Windows, copy appleseed.dll from appleseed's bin folder to where art.exe resides (e.g., build/Debug/bin)
# If 0 build errors compiling art
## open a cmd.exe or git bash terminal window
## navigate to build.appleseed folder
## run art without args (e.g., type "Debug/bin/art.exe" on Windows and confirm a usage statement is displayed)
# Compile rest of BRL-CAD (compile the ALL_BUILD target on Windows)
# If 0 build errors compiling ALL_BUILD
## run art with args (e.g., "Debug/bin/art.exe Debug/share/db/moss.g all.g" on Windows)
# IFF you get a Heap error,
## edit src/libbu/linebuf.c and add a "return;" as the very first line of bu_setlinebuf()
## Navigate to BRL-CAD Executables ->  Rt -> art, right-click and select Build
## run art with args (e.g., "Debug/bin/art.exe Debug/share/db/moss.g all.g" on Windows)

If art has a log message saying "image saved to output/art.png" near the end of logged output, then it ran successfully (even if you still get a Heap error on Windows).
@@ Line 15: / Line 15: @@
 == To-Do ==
+=== Separating Regions ===
+* The custom BRL-CAD plugin currently tracks all BRL-CAD regions and their mappings to Appleseed instances via a single "ray trace instance pointer" (rtip).  It uses a string comparison to determine if a hit is on a corresponding appleseed instance.  While this works, it's incredibly inefficient.  It either needs a separate rtip per object (ideal) or it needs to use pointers/integers to determine if we hit the Appleseed instance.
 === Colors/Materials ===
 * BRL-CAD objects are rendered by appleseed individually and can have different colors and/or materials assigned to each instance.  However, there is no automatic mapping from BRL-CAD shader settings to Appleseed settings.  PBR shaders are supported via BRL-CAD 'material' objects (see 'material' command and gltf import). Using more advanced materials (e.g., with textures) is untested.
+=== Multithreading Support ===
+* Both appleseed and librt are capable of multithreaded rendering, but at the moment, the plugin will only work on a single thread. At some point, multithreading support should be implemented in order to fully take advantage of appleseed/librt capabilities.
 === Refining CMake ===
 * Setting up the appleseed project requires a lot of hacky and manual work due to relying on a pre-built binary of Appleseed.  The CMake build needs to compile Appleseed and all its dependencies using CMake's External_ProjectAdd feature in order to make the build process easier for all platforms and in order to ensure 'art' is always enabled.
 == Compiling 'art' ==
@@ Line 59: / Line 66: @@
 If art has a log message saying "image saved to output/art.png" near the end of logged output, then it ran successfully (even if you still get a Heap error on Windows).
-== Building 'art' and Appleseed from source ==
-To compile the 'art' application in BRL-CAD on Linux, follow these steps:
-# git clone https://github.com/BRL-CAD/brlcad
-# cd brlcad && rm -rf misc/tools/ext src/other
-# cd .. && mkdir brlcad_art_build && cd brlcad_art_build
-# cmake ../brlcad -DCMAKE_BUILD_TYPE=Debug -DENABLE_ALL=ON -DBRLCAD_ENABLE_APPLESEED=ON
-# cmake --build . --config Debug --parallel 8
-# ./bin/art share/db/moss.g all.g
-If everything worked, you should get an output file: output/art.png
-Note that Windows is still a work in progress with this build configuration.  You might try Release instead of Debug - a couple of the known issues at the moment pertain to properly specifying Debug configs to subbuilds.