HACKING BRL-CAD

BRL-CAD (pronounced be-are-el-cad) is a powerful, cross-platform, open source solid modeling system that includes interactive three-dimensional (3D) solid geometry editing, high-performance ray tracing support for rendering and geometric analysis, network-distributed framebuffer support, image and signal-processing tools, path tracing and photon mapping support for realistic image synthesis, a system performance analysis benchmark suite, an embedded scripting interface, and libraries for robust high-performance geometric representation and analysis.

For more than two decades, BRL-CAD has been the primary solid modeling CAD package used by the U.S. government to help model military systems. The package has also been used in a wide range of military, academic, and industrial applications, including the design and analysis of vehicles, mechanical parts, and architecture. Other uses have included radiation dose planning, medical visualization, terrain modeling, constructive solid geometry (CSG), modeling concepts, computer graphics education and system performance benchmark testing.

BRL-CAD supports a wide variety of geometric representations, including an extensive set of traditional implicit "primitive shapes" (such as boxes, ellipsoids, cones, and tori) as well as explicit primitives made from collections of uniform B-spline surfaces, non-uniform rational B-spline (NURBS) surfaces, n-manifold geometry (NMG), and purely faceted polygonal mesh geometry. All geometric objects may be combined using boolean set-theoretic CSG operations such as union, intersection and difference.

Overall, BRL-CAD contains more than 400 tools, utilities, and applications and has been designed to operate on many common operating system environments, including BSD, Linux, Solaris, Mac OS X, and Windows. The package is distributed in binary and source code form as Free Open Source Software (FOSS), provided under Open Source Initiative (OSI) approved license terms.

BRL-CAD was originally conceived and written by the late Michael Muuss, the inventor of the popular PING network program. In 1979, the U.S. Army Ballistic Research Laboratory (BRL) (the agency responsible for creating ENIAC, the world’s first general-purpose electronic computer in the 1940s) identified a need for tools that could assist with the computer simulations and analysis of combat vehicle systems and environments. When no existing CAD package was found to be adequate for this specialized purpose, Mike and fellow software developers began developing and assembling a unique suite of utilities capable of interactively displaying, editing, and interrogating geometric models. Those early efforts subsequently became the foundation on which BRL-CAD was built.

Development of BRL-CAD as a unified software package began in 1983, and its first public release came in 1984. Then, in 2004, BRL-CAD was converted from a limited-distribution U.S. government-controlled code to an open source project, with portions licensed under the LGPL and BSD licenses.

Today, the package’s source code repository is credited as being the world’s oldest, continuously developed open source repository. As a project, pride is taken in preserving all history and contributions.

The ongoing vision for BRL-CAD development is to provide a robust, powerful, flexible, and comprehensive solid modeling system that includes:

All CAD packages are not alike. Among the many strengths of the BRL-CAD package are the following:

With BRL-CAD being a part of the open source community since 2004, contributors from all over the world are able to enhance the features and functions of the package in many different ways. In return, these contributors have had a unique opportunity to:

If you would like to be a BRL-CAD contributor, the primary areas currently identified for future development and enhancement include the following:

Let the contributions begin!

BRL-CAD focuses on solid modeling CAD. Solid modeling is distinguished from other forms of geometric modeling by an emphasis on being physically accurate, fully describing 3D space. Shown is a 3D model of a Goliath tracked mine, a German-engineered remote controlled vehicle used during World War II. This model was created by students new to BRL-CAD in the span of about 2 weeks, starting from actual measurements in a museum.

Raytracing is central to BRL-CAD as a means for performing geometric analysis (e.g., calculating weights and moments of inertia) and for rendering images for visualization purposes. The image shown is a BRL-CAD 2D framebuffer screenshot displaying the rendering of a ball bearing. The bearing is modeled with a material appearance resembling acrylic glass, and this raytracing result shows reflection, refraction, shadowing, and some caustic effects.

As shown, a BRL-CAD target description can be converted to a finite element mesh (FEM) using the BRL-CAD g-sat exporter and Cubit from Sandia National Laboratories.

This screenshot shows a model imported from the Rhino3D 3DM file format into BRL-CAD as NURBS boundary representation geometry, visualized via OpenGL.

BRL-CAD provides a comprehensive procedural geometry interface as a means for creating models algorithmically instead of manually. This screenshot shows a classic "Sphere Flake" model with five levels of recursion, specular reflections, multiple light sources, environment mapping, checkered texture synthesis, ambient occlusion, and soft shadows.

Boundary representation NURBS surface geometry is one of the dominant geometric representation formats in CAD. BRL-CAD is one of the few 3D solid modeling systems that not only support geometry in boundary representation NURBS format but also provide extensive support for robust solid ray tracing of NURBS geometry. The image shown is the classic computer graphics Utah teapot model prepared for 3D printing and rendered via BRL-CAD ray tracing.

Representing more than 8 trillion rays fired at this 11-million-polygon scene (amounting to more than 20 million rays per second on 2004 hardware), this figure signifies the path tracing capability of BRL-CAD. A full light simulation was computed to generate the image with all exterior and interior vehicle detail, including every nut, bolt, wire, and component inside the vehicle and every leaf and blade of grass modeled as actual geometry (with no textures and no procedural geometry).

While now a fully hybrid modeling system, BRL-CAD has its roots in CSG modeling with implicit primitives. This image, provided courtesy of GSI Solutions, Inc., depicts a detailed M1A1 tank on a pedestal in a mirrored showcase room. The model is entirely constructed from implicit primitives and CSG boolean operations.

This raytrace image is a multiple-view hidden line rendering of an Mi28 Havoc Russian attack helicopter using BRL-CAD’s rtedge utility. The model is entirely composed of implicit primitives combined together with CSG boolean operations.

BRL-CAD can run series of commands piped in or redirected to it via standard input, and it is considerably more efficient to batch multiple BRL-CAD commands together via standard input instead of re-invoking BRL-CAD for each command. The image demonstrates the output of a shell script that uses BRL-CAD tools to procedurally create and render the SGI Cube. For more information, go to http://brlcad.org/wiki/SGI_Cube.

Not all of BRL-CAD’s capabilities lend themselves well to pretty pictures, but some are definitely worth mentioning. Among the thousands of features in BRL-CAD, here are some additional capabilities that are central to our project ethos.

The source code and most project data are stored in a Git^[4] version control system for change tracking and collaborative development. Primary development in the "main" branch is generally stable, but cross-platform compilation is not guaranteed. A separate branch (named STABLE) provides a higher level of quality assurance. Every released version of BRL-CAD is tested and tagged.

The project aims for an It Just Works approach to compilation whereby a functional build of BRL-CAD is possible without needing to install more than a compiler, CMake, and a build environment—​for example, GNU Make or Microsoft Visual Studio. BRL-CAD provides all of the necessary third-party dependencies for download and compilation convenience within source distributions but by default will build using system versions of those dependencies if available.

As with any large system that has been under development for a number of years, there are vast sections of code that may be unfamiliar, uninteresting, or even daunting. Don’t panic. BRL-CAD has been intentionally designed with layering and modularity in mind.

You can generally focus in on the enhancement or change that interests you without being too concerned with other portions of the code. You should, however, do some basic research to make sure what you plan to contribute isn’t already in the BRL-CAD code base.

The basic layout of BRL-CAD’s source code places public API headers in the top-level include directory and source code for both applications and libraries in the src directory. The following is a partial listing of how the code is organized in a checkout or source distribution. Note that some subdirectories contain a README file with more details on the content in that directory.

BRL-CAD has a STABLE branch in Git that should always compile and run on all supported platforms. The primary development branch, main, unlike STABLE, is generally expected to compile but may occasionally fail to do so during active development.

These tasks have roughly the same complexity and require no prior experience with BRL-CAD experience to complete. They’re a great starting point for anyone interested in getting involved in the development process of BRL-CAD, as they can be completed in just a couple of hours.

Check out our list of available mini tasks that we call deuces and quickies. Each task has a labelled level of difficulty: easy, medium, and hard. Although the hard ones are math intense, don’t let them scare you away.

If you have few hours to spare each day, check the TODO file included in each source distribution. These tasks can help potential developers make modifications and submit pull requests to gain familiarity with our code repository. You should be able to complete the tasks on this list within 14 days. Before starting on a task, however, you should discuss it with other developers on Zulip chat or in our GitHub Discussions.

We also have a BUGS file, included in each binary and source distribution, which lists the application bugs that developers are invited to fix. If you plan to tackle a bug, remember to report it in our issue tracker.

If you want to become more deeply involved in the BRL-CAD project, then you should take the time to check our ideas page (http://brlcad.org/~sean/ideas.html). Students who are participating in Google Summer Of Code should explore our projects page (http://brlcad.org/~sean/ideas.html) and the ideas page to get a feel for the tasks that are available. These tasks should take about 60 days to complete.

You can get the development code for BRL-CAD from our Git code repository using the following command:

git clone https://github.com/BRL-CAD/brlcad

The code will be saved into a brlcad directory, and you can compile it by following the instructions in the HACKING file located in the top-level source directory. That said, the following are a few useful tips to help get you going.

After obtaining the source code, you should join the BRL-CAD community on Zulip chat, our primary discussion venue. For longer-form questions and answers, use GitHub Discussions. A secondary, legacy IRC channel named #brlcad is also available on irc.libera.chat.

Joining the discussion helps introduce yourself to the BRL-CAD community and gives you the opportunity to regularly communicate with other experienced contributors. You can ask questions on Zulip, in GitHub Discussions, or on IRC.

Note that BRL-CAD contributors have a set of rules that they try to respect and follow to enable collaboration and communication. We strongly encourage new contributors to be creative and to be specific when asking questions. We also strongly advise you to use interleaved posting when replying on any communication channel. And never be afraid to ask questions.

Finally, when modifying code, it’s advisable to regularly consult with experienced developers and to follow these rules of thumb when adding changes:

AsciiDoc is a lightweight, human-readable plain-text markup language for writing structured technical documentation. Unlike markup that relies on verbose tags, AsciiDoc source is easy to read and edit directly in any text editor, yet it is expressive enough to describe the content and structure of complex documents such as articles, books, and manual pages. BRL-CAD’s AsciiDoc sources use the conventional .adoc file extension. For a concise introduction to the syntax, see the AsciiDoc project site and the AsciiDoc language documentation.

Because AsciiDoc source is plain text, you can author and edit it with any text editor. No specialized editing tool is required, though many editors offer AsciiDoc syntax highlighting and live preview.

The ability to render documentation and report formatting problems is built into the BRL-CAD compilation process. BRL-CAD ships with a self-contained AsciiDoc processor named asciiquack (in misc/tools/asciiquack), so no external documentation tools need to be installed to build the documentation. Documentation is built only when CMake is configured with BRLCAD_EXTRADOCS=ON. When that option is enabled, asciiquack renders each .adoc source to HTML (and, for man-page sources, to nroff man pages) as part of the normal build.

The AsciiDoc sources live under doc/asciidoc/, organized by document type into the following subdirectories:

For more information, see the file doc/asciidoc/README.adoc in the BRL-CAD source code archive.

A few constructs cover the majority of everyday documentation editing:

Adding a new document is straightforward: create the AsciiDoc source, then register it with the build system so BRL-CAD renders it.

For example, if you are writing a new article about the ellipsoid, start by copying the article template to the filename ellipsoid.adoc in the articles directory:

~/brlcad$ cp doc/asciidoc/articles/TEMPLATE.adoc doc/asciidoc/articles/ellipsoid.adoc

Next, open the file doc/asciidoc/articles/CMakeLists.txt in a text editor and add the name of the new document to the list of article sources so the build system knows about it:

Reconfigure and build with documentation enabled (in this example, the build output directory is called build):

~/brlcad/build$ cmake .. -DBRLCAD_EXTRADOCS=ON

~/brlcad/build$ cmake --build . --target doc

The asciiquack processor renders the article to:

build/share/doc/html/articles/ellipsoid.html

Open this file in a web browser to view the HTML output.

Now that all the pieces are in place, you can begin the documentation cycle:

Some BRL-CAD documents have been translated into languages other than English. Because AsciiDoc source is Unicode-aware, you are not limited to the ASCII character set; you can write freely in the target language. When maintaining translations, follow the naming and organization conventions already used by the existing translated sources in the relevant subdirectory, and register each translated .adoc file in that directory’s CMakeLists.txt just as you would an English document.

BRL-CAD produces HTML documentation and, for manual-page sources, UNIX man pages. All documentation output is gated on a single CMake option; man pages are additionally skipped on platforms where they are of little use.

You can use the following configuration options to turn documentation compilation on and off:

The documentation is only built when BRLCAD_EXTRADOCS is enabled, because rendering the full documentation set adds noticeably to configuration and compilation time. It defaults to ON for a standard full build and to OFF when a reduced set of build targets is selected. If your build has documentation disabled, enable it explicitly with -DBRLCAD_EXTRADOCS=ON whenever you are editing or verifying documentation.

Different documents that serve different needs will often need to share common content. AsciiDoc supports this with the include:: directive, which pulls the contents of one source file into another at render time:

You can include an entire file or, by tagging regions of the source, a specific portion of it. Tag a region in the included file with // tag::name[] and // end::name[] comment markers, then reference that region from the including document:

The drawbacks to this mechanism are that:

Now that you have an idea about how documentation is written and built for the BRL-CAD project, let’s take a look at the types of documentation that the project maintains.

The easiest way to contribute as a documenter is through BRL-CAD’s wiki (a website that users can edit) at http://brlcad.org/wiki/Main_Page. The wiki is not currently integrated with any of the other documentation systems in BRL-CAD, although this remains one of BRL-CAD’s project goals.

Man pages are command-specific or program-specific documentation which thoroughly document and demonstrate the use of that command or program. Man pages may reference other man pages, but they are intended to be the primary source of documentation for a specific tool and should be written with a very tight focus.

Most of the project’s documentation is maintained in the BRL-CAD source code repository as AsciiDoc files (see the chapter Working with Our Documentation for more information about AsciiDoc). API documentation, on the other hand, is automatically generated from the headers in the application’s source code. Specially formatted source code comments in the headers are converted to HTML documentation by Doxygen (http://www.doxygen.org), a tool for generating source code documentation.

API documentation is the lowest level, most authoritative documentation of BRL-CAD’s programming interfaces. However, it does not address user-level programs or commands.

Lessons are documents that are used to train a user to master a particular aspect of BRL-CAD. Unlike other documents, lessons focus on step-by-step teaching.

These can be technical reports, journal articles, conference papers, and/or similar focused descriptions of specific aspects of the package. Unlike lessons, reports and articles are primarily designed to inform rather than train. They are generally less comprehensive in scope and/or detail than a full-blown book.

Books are typically large documents that cover many aspects of BRL-CAD. In some cases, books can be collections of lessons, reports, articles, and/or other forms of documentation that are compiled between one set of covers.

Specifications are formal documents that define formats or protocols that others can independently implement. Currently, the only specification in the BRL-CAD documentation set is a draft specification of the .g file format.

Presentations can range from an overview of the entire BRL-CAD package to an in-depth review of a specific feature or technical algorithm. Presentations are often used when marketing or explaining some aspect of BRL-CAD to people who are not familiar with it.

If you want to get started working on the BRL-CAD documentation immediately, one great way to do that is by helping to clean up the existing documentation. Take a look at the documentation and check the spelling or copy edit it to make the documentation more concise or to correct problems with grammar or punctuation. Alternatively, check out our list of documentation tasks (http://brlcad.org/wiki/Deuces#Documentation_and_Training) that you can complete in two hours or less.

If you have a little more time to devote to the documentation, we maintain a list of tasks that will take you anywhere from a few hours to a few days to complete. You can find that list on the BRL-CAD website (http://brlcad.org/wiki/Contributor_Quickies). These tasks have roughly the same complexity and require no prior experience with BRL-CAD.

We also have a list of bugs in our BUGS file. While most of the bugs in the list focus on the BRL-CAD code, there are a few related to the documentation. If you plan to tackle a documentation bug, remember to report it in our issue tracker (https://github.com/BRL-CAD/brlcad/issues).

If you are familiar with CAD in general and BRL-CAD in particular, then you might want to try creating some tutorial and training material. Check out our list of training material that we need (http://brlcad.org/wiki/Contributor_Quickies#Training).

The documentation and the toolchain required to generate the documentation is part of the software’s development code. You should download the source code from the Git version control system using the following command:

git clone https://github.com/BRL-CAD/brlcad

The brlcad directory should be kept separate from your build directory so that BRL-CAD’s build outputs don’t clutter the source tree.

BRL-CAD’s AsciiDoc documentation is rendered by the bundled asciiquack processor, so no additional documentation software needs to be installed. You only need a compiler, CMake, and a build environment.

You can find the source files for the documentation in the following directories in the BRL-CAD source code repository:

You can find more information about editing the documentation in the chapter Working with Our Documentation earlier in this book.

Remember to:

Before undertaking a documentation task, you should join the BRL-CAD community on Zulip chat and, for longer discussions, our GitHub Discussions. A secondary, legacy IRC channel named #brlcad is also available on irc.libera.chat.

Joining the discussion helps introduce you to the BRL-CAD community and gives you the opportunity to regularly communicate with other experienced contributors. You can ask questions on Zulip, in GitHub Discussions, or on IRC.

BRL-CAD contributors have a set of rules that they try to respect and follow to enable collaboration and communication. We strongly encourage new contributors to be creative and to be specific when asking questions. We also strongly advise you to use interleaved posting when replying on any communication channel. And once again, don’t be afraid to ask questions.

Finding bugs in software is often a challenging task for developers. If you find a problem with the software, file a bug report on BRL-CAD’s official issue tracker (https://github.com/BRL-CAD/brlcad/issues). Please remember to provide enough detail so that we can reproduce the problem. You can also raise the issue on Zulip chat or in our GitHub Discussions.

In addition, if you have a suggestion for a new feature, feel free to submit a request on the same issue tracker (https://github.com/BRL-CAD/brlcad/issues). You can also share the idea on Zulip chat or in our GitHub Discussions.

BRL-CAD has a large and passionate community of users and contributors. We need people to work with that community and to help with marketing and promoting the software.

As well, we need professional-quality artwork. Everything from logos to diagrams to icons. And just about anything in between. Your efforts will help give BRL-CAD a more polished look and will support our outreach and marketing efforts.

The preceding diagram was created to illustrate BRL-CAD’s coordinate system.

You can find a list of outreach and artwork tasks that will get you started at the BRL-CAD website (http://brlcad.org/wiki/Contributor_Quickies#Outreach).

Testing is a vital part of the software development process. As Eric Raymond said, "given enough eyeballs, all bugs are shallow." We need your eyeballs to help us ensure that the code for BRL-CAD is of the highest quality.

What can you do? Create testing frameworks and tests for specific portions of the code. Or go through BRL-CAD’s graphical user interface and find and report any bugs. You can help make BRL-CAD better by reporting any problems you encounter.

You can find a list of quality assurance tasks that will get you started at the BRL-CAD website (http://brlcad.org/wiki/Contributor_Quickies#Quality_Assurance).

BRL-CAD improves not just through rigorous coding and quality assurance but also through research. We need contributors who can study problems with the software and recommend solutions based on their research. This is an area which typically requires a solid level of technical ability, but contributions here can have an enormous positive impact on the software.

You can find a list of research tasks that will get you started at the BRL-CAD website (http://brlcad.org/wiki/Contributor_Quickies#Research).

We want to make BRL-CAD available to as many users as possible, regardless of what language they speak. To that end, we’re steadily making the software available in a number of languages. But there’s still work to do. If you have a knowledge or one or more languages other than English, we can use your skills.

You can find a list of translation tasks that will get you started at the BRL-CAD website (http://brlcad.org/wiki/Contributor_Quickies#Translation).

BRL-CAD is a large, powerful, and complex piece of software. And as with any software package, it can always be made more consistent, usable, and user friendly. If you’re willing to learn the user interface and to approach the package with a critical eye, then you can help make the BRL-CAD user interface friendlier and more consistent.

You can find a list of user experience tasks that will get you started at the BRL-CAD website (http://brlcad.org/wiki/Contributor_Quickies#User_Interface).