Difference between revisions of "Appleseed"

From BRL-CAD
(Add tasks to to-do list and begin progress section)
m (Building 'art' and Appleseed from source)
 
(16 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
= Appleseed Integration Project =
 
= Appleseed Integration Project =
Integration with appleseed (https://github.com/appleseedhq/appleseed) has been a long-standing BRL-CAD project. In essence, the idea is to render BRL-CAD geometry through a custom plugin to the appleseed renderer. The ultimate goal of the project is to be able to support as many rt features as possible.
+
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.
  
  
Line 8: Line 10:
 
* defining the render image pixel dimensions
 
* defining the render image pixel dimensions
 
* setting the azimuth/elevation and perspective angle
 
* 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.
  
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 ==
 +
=== 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.
 +
 
 +
=== 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).
  
== To-Do ==
+
== Building 'art' and Appleseed from source ==
=== Separating Regions ===
 
* The custom BRL-CAD plugin currently combines all the BRL-CAD regions into a single object. While this works to some extent, it would be more ideal to separate each region into a separate object. This would make other features, such as assigning region-specific colors, much easier to implement.
 
  
=== Colors/Materials ===
+
To compile the 'art' application in BRL-CAD on Linux, follow these steps:
* Right now, the entire BRL-CAD object is rendered by appleseed as a single hard-coded color. However, BRL-CAD geometry supports the use of different colors and materials for individual primitives/regions. After the custom plugin has been updated to separate BRL-CAD regions, implementing colors/materials would be a relatively high-priority feature.
 
  
=== Using Existing Functions ===
+
# git clone https://github.com/BRL-CAD/brlcad
* Although art supports setting azimuth/elevation, the current implementation was done as a bit of a hack; the function used to perform relevant calculations, do_ae(), was copied from the do.c file. It would be much preferred to directly use the function from do.c, but including do.c into the project also creates a lot of unresolved external symbol errors. This should be resolved soon.
+
# 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
  
=== Multithreading Support ===
+
If everything worked, you should get an output file: output/art.png
* 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 ===
+
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.
* Setting up the appleseed project requires a lot of hacky and manual work. Once the project has progressed further, the CMake should be updated to make this process easier for all platforms.
 

Latest revision as of 10:14, 29 March 2024

Appleseed Integration Project[edit]

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 appleseed began in 2014 after talks at the 10th-year GSoC summit. Appleseed devs created 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[edit]

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[edit]

Colors/Materials[edit]

  • 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.

Refining CMake[edit]

  • 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'[edit]

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

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

Building 'art' and Appleseed from source[edit]

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

  1. git clone https://github.com/BRL-CAD/brlcad
  2. cd brlcad && rm -rf misc/tools/ext src/other
  3. cd .. && mkdir brlcad_art_build && cd brlcad_art_build
  4. cmake ../brlcad -DCMAKE_BUILD_TYPE=Debug -DENABLE_ALL=ON -DBRLCAD_ENABLE_APPLESEED=ON
  5. cmake --build . --config Debug --parallel 8
  6. ./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.