Annotation raytracing as overlay

This was the initial attempt at non-scene-geometry annotation raytracing.
Squashed down to one commit for simpler diff review.

Clear Werror=subobject-linkage issue
use bu_strcmp
Make annotation intersections scale independent
Use relative parallel and determinant tests so valid annotations are not rejected after small model transforms.  Carry the caller's model tolerance into visibility decisions and cover both behaviors in the focused annotation semantics test.
Use a strict annotation hit ordering
Compare hit distances exactly before using the path as a tie breaker.  Approximate equality in a std::sort predicate is not transitive and can violate the strict weak ordering required by the C++ standard library.
Preserve hit distance in simple rt lightmodels
Record the first partition distance in viewit, matching colorview.  Annotation compositing uses this value to keep model-space marks behind foreground geometry for lightmodels 1, 2, 4, 5, and 6.
Defer NIRT annotation reporting
Remove the provisional useannot mode instead of emitting records outside NIRT's fmt system.  This preserves existing structured output contracts and avoids extending the public nirt_opt_vals layout until annotation records have a complete formatter design.
Use annotation line styles for render width
Remove the redundant object-wide render_width field, ANR2 payload, and --stroke-width option.  Ray renderers now rely on the established per-segment line_width style over an automatic base width, preserving the public primitive layout and avoiding another database extension.  Document and test the ray coverage behavior.
Name the ADRT model coordinate scale
Replace repeated 1000-to-1 load conversions with ADRT_MODEL_UNITS_PER_TIE_UNIT so geometry and annotation compositing share one documented coordinate convention.
Keep annotations out of the librender camera ABI
Replace camera-resident annotation fields with an additive render_camera_render_annotations entry point.  Per-render private state now carries the scene, coordinate scale, and derived view while the public render_camera_t and thread-data layouts remain unchanged.  Preserve primary rays before shaders mutate them so annotation compositing evaluates the intended sample.
Define ISST annotation scene ownership
Make GFile release its annotation scene and TIE data, destroy the render window before its GFile owner, and clear the renderer under its mutex before reloading.  Queued renders now reject cleared scenes after acquiring the context, preventing use-after-free during reload and shutdown.
Cache rt annotation preparation state
Keep annotation scene and view state private to do.c, expose read-only accessors to workers, and reuse prepared coverage when the database, selected paths, and tolerances are unchanged.  Explicitly invalidate on animation changes and centralize cleanup.
Add a NIRT annotation output format
Add opt-in NIRT annotation reporting
Document NIRT annotation diagnostics
Document annotation and view-object roles
Remove the unused ISST application meta-object
ISSTApp declares no signals, slots, properties, or invokable methods.  Avoid generating a redundant derived meta-object, which also prevents Qt 6 from rejecting the member main-window construction during application startup.
Use Qt 6 OpenGL dependencies for ISST
Qt6::OpenGL and Qt6::OpenGLWidgets already carry the platform OpenGL implementation.  Do not also link the independently discovered host OpenGL target, which can select a different GL ABI and bypass Qt's configured backend.
Keep ISST annotations out of NMG tessellation
ISST renders annotations through its dedicated annotation scene.  Exclude annotation-only roots from the geometry walk and replace annotation leaves in mixed trees with empty nodes so the independent NMG path does not report unsupported tessellation.
Share ADRT annotation tessellation filtering
Frame ISST views using annotation bounds
Gate ART annotation frame processing
Honor inherited colors in annotation renders
Make RTree ray queries const-safe
Composite ordered annotation coverage with RTree indices
Blend all annotation layers in image renderers
Test ordered annotation coverage and alpha blending
Test ADRT annotation filtering and scene framing
Document annotation layering and lookup design
Tighten annotation scene preparation
Test annotation combination color inheritance

.github/actions/prepare-bext/action.yml

@@ -0,0 +1,260 @@
+name: Prepare bext dependencies
+description: Restore a compatible bext production artifact or build the pinned revision.
+
+inputs:
+  platform-channel:
+    description: Published bext platform channel.
+    required: true
+  source-dir:
+    description: Absolute path to the BRL-CAD source tree.
+    required: true
+  output-dir:
+    description: Absolute path where the bext dependency tree will be prepared.
+    required: true
+  build-type:
+    description: BRL-CAD build configuration that will consume the dependency tree.
+    required: false
+    default: Release
+  artifact-token:
+    description: Token with Actions read access to BRL-CAD/bext.
+    required: false
+
+outputs:
+  bext-sha:
+    description: The bext revision in the prepared dependency tree.
+    value: ${{ steps.result.outputs.bext-sha }}
+  source:
+    description: Whether preparation used a production artifact, cache, or local build.
+    value: ${{ steps.result.outputs.source }}
+
+runs:
+  using: composite
+  steps:
+    - name: Resolve bext production artifact
+      id: resolve
+      shell: bash
+      env:
+        BEXT_BUILD_TYPE: ${{ inputs.build-type }}
+        BEXT_CHANNEL: ${{ inputs.platform-channel }}
+        BRLCAD_SOURCE_DIR: ${{ inputs.source-dir }}
+        GH_TOKEN: ${{ inputs.artifact-token }}
+      run: |
+        set -uo pipefail
+        source_dir="$BRLCAD_SOURCE_DIR"
+        if command -v cygpath >/dev/null 2>&1; then
+          source_dir="$(cygpath -u "$source_dir")"
+        fi
+        required_sha="$(awk -F'[()]' '/^[[:space:]]*brlcad_bext_init\([0-9a-fA-F]{40}\)/ { print tolower($2) }' "$source_dir/CMakeLists.txt")"
+        if [[ ! "$required_sha" =~ ^[0-9a-f]{40}$ ]]; then
+          echo "Expected exactly one brlcad_bext_init(<sha>) call in $source_dir/CMakeLists.txt" >&2
+          exit 1
+        fi
+
+        repository='BRL-CAD/bext'
+        marker_name="bext-production-$required_sha"
+        marker_info="$(gh api "repos/$repository/actions/artifacts?name=$marker_name&per_page=100" \
+          --jq '[.artifacts[] | select(.expired == false and .name == "'"$marker_name"'")] | sort_by(.created_at) | last | select(. != null) | [.name, .workflow_run.id] | @tsv' 2>/dev/null)" || marker_info=''
+
+        selected_sha=''
+        run_id=''
+        if [[ -n "$marker_info" ]]; then
+          selected_sha="$required_sha"
+          IFS=$'\t' read -r _ run_id <<< "$marker_info"
+          echo "Found complete bext production artifacts for pinned revision $required_sha."
+        else
+          marker_info="$(gh api "repos/$repository/actions/artifacts?per_page=100" \
+            --jq '[.artifacts[] | select(.expired == false and (.name | test("^bext-production-[0-9a-f]{40}$")))] | sort_by(.created_at) | last | select(. != null) | [.name, .workflow_run.id] | @tsv' 2>/dev/null)" || marker_info=''
+          if [[ -n "$marker_info" ]]; then
+            IFS=$'\t' read -r latest_marker run_id <<< "$marker_info"
+            selected_sha="${latest_marker#bext-production-}"
+            comparison="$(gh api "repos/$repository/compare/$required_sha...$selected_sha" --jq '.status' 2>/dev/null)" || comparison=''
+            if [[ "$comparison" == 'ahead' || "$comparison" == 'identical' ]]; then
+              echo "::warning::Using newer successful bext revision $selected_sha instead of BRL-CAD's pinned revision $required_sha."
+            else
+              selected_sha=''
+              run_id=''
+            fi
+          fi
+        fi
+
+        artifact_ready=false
+        artifact_name=''
+        if [[ "$RUNNER_OS" == 'Windows' && "$BEXT_BUILD_TYPE" == 'Debug' ]]; then
+          echo 'Windows Debug requires a Debug bext build; skipping Release production artifacts.'
+          selected_sha=''
+          run_id=''
+        elif [[ -n "$selected_sha" ]]; then
+          artifact_name="bext-$BEXT_CHANNEL-$selected_sha"
+          artifact_count="$(gh api "repos/$repository/actions/runs/$run_id/artifacts?name=$artifact_name&per_page=100" \
+            --jq '[.artifacts[] | select(.expired == false and .name == "'"$artifact_name"'")] | length' 2>/dev/null)" || artifact_count=0
+          if [[ "$artifact_count" == '1' ]]; then
+            artifact_ready=true
+          else
+            selected_sha=''
+            run_id=''
+            artifact_name=''
+          fi
+        fi
+
+        cache_schema=1
+        image_version="${ImageVersion:-unknown}"
+        runner_arch="${RUNNER_ARCH:-unknown}"
+        fallback_cache_key="bext-$cache_schema-$BEXT_CHANNEL-$BEXT_BUILD_TYPE-$required_sha-$image_version-$runner_arch"
+        production_cache_key="bext-$cache_schema-$BEXT_CHANNEL-Release-$selected_sha"
+        if [[ "$artifact_ready" != 'true' ]]; then
+          echo "No compatible production artifact is available; using the cache/build fallback for $required_sha."
+        fi
+
+        echo "required-sha=$required_sha" >> "$GITHUB_OUTPUT"
+        echo "selected-sha=$selected_sha" >> "$GITHUB_OUTPUT"
+        echo "run-id=$run_id" >> "$GITHUB_OUTPUT"
+        echo "artifact-name=$artifact_name" >> "$GITHUB_OUTPUT"
+        echo "artifact-ready=$artifact_ready" >> "$GITHUB_OUTPUT"
+        echo "production-cache-key=$production_cache_key" >> "$GITHUB_OUTPUT"
+        echo "fallback-cache-key=$fallback_cache_key" >> "$GITHUB_OUTPUT"
+
+    - name: Restore production artifact cache
+      if: steps.resolve.outputs.artifact-ready == 'true'
+      id: production-cache
+      uses: actions/cache/restore@v6
+      with:
+        path: ${{ inputs.output-dir }}
+        key: ${{ steps.resolve.outputs.production-cache-key }}
+
+    - name: Download bext production artifact
+      if: steps.resolve.outputs.artifact-ready == 'true' && steps.production-cache.outputs.cache-hit != 'true'
+      id: download
+      shell: bash
+      env:
+        ARTIFACT_NAME: ${{ steps.resolve.outputs.artifact-name }}
+        BEXT_CHANNEL: ${{ inputs.platform-channel }}
+        BEXT_OUTPUT_DIR: ${{ inputs.output-dir }}
+        BEXT_RUN_ID: ${{ steps.resolve.outputs.run-id }}
+        GH_TOKEN: ${{ inputs.artifact-token }}
+      run: |
+        set -uo pipefail
+        output_dir="$BEXT_OUTPUT_DIR"
+        if command -v cygpath >/dev/null 2>&1; then
+          output_dir="$(cygpath -u "$output_dir")"
+        fi
+        download_dir="$RUNNER_TEMP/bext-download-$BEXT_RUN_ID-$BEXT_CHANNEL"
+        cmake -E rm -rf "$download_dir" "$output_dir"
+        cmake -E make_directory "$download_dir" "$output_dir"
+
+        ready=false
+        if gh run download "$BEXT_RUN_ID" --repo BRL-CAD/bext --name "$ARTIFACT_NAME" --dir "$download_dir"; then
+          archive="$download_dir/bext-$BEXT_CHANNEL.tar.gz"
+          if (cd "$output_dir" && cmake -E tar xzf "$archive") && \
+             [[ -d "$output_dir/install" && -d "$output_dir/noinstall" && -f "$output_dir/bext-install-manifest.json" ]]; then
+            ready=true
+          fi
+        fi
+        cmake -E rm -rf "$download_dir"
+        if [[ "$ready" != 'true' ]]; then
+          cmake -E rm -rf "$output_dir"
+          echo '::warning::Unable to download or validate the bext production artifact; using the pinned cache/build fallback.'
+        fi
+        echo "ready=$ready" >> "$GITHUB_OUTPUT"
+
+    - name: Restore fallback bext cache
+      if: steps.production-cache.outputs.cache-hit != 'true' && steps.download.outputs.ready != 'true'
+      id: fallback-cache
+      uses: actions/cache/restore@v6
+      with:
+        path: ${{ inputs.output-dir }}
+        key: ${{ steps.resolve.outputs.fallback-cache-key }}
+
+    - name: Build pinned bext revision
+      if: steps.production-cache.outputs.cache-hit != 'true' && steps.download.outputs.ready != 'true' && steps.fallback-cache.outputs.cache-hit != 'true'
+      shell: bash
+      env:
+        BEXT_BUILD_TYPE: ${{ inputs.build-type }}
+        BEXT_OUTPUT_DIR: ${{ inputs.output-dir }}
+        BEXT_SHA: ${{ steps.resolve.outputs.required-sha }}
+      run: |
+        set -euo pipefail
+        output_dir="$BEXT_OUTPUT_DIR"
+        if command -v cygpath >/dev/null 2>&1; then
+          output_dir="$(cygpath -u "$output_dir")"
+        fi
+        source_dir="$RUNNER_TEMP/bext-src"
+        build_dir="$RUNNER_TEMP/bext-build"
+        cleanup() {
+          cmake -E rm -rf "$source_dir" "$build_dir"
+        }
+        trap cleanup EXIT
+        cleanup
+        cmake -E rm -rf "$output_dir"
+
+        git clone --filter=blob:none https://github.com/BRL-CAD/bext.git "$source_dir"
+        git -C "$source_dir" -c advice.detachedHead=false checkout "$BEXT_SHA"
+        configure_args=(-S "$source_dir" -B "$build_dir" -G Ninja -DENABLE_ALL=ON -DGIT_SHALLOW_CLONE=ON "-DCMAKE_BUILD_TYPE=$BEXT_BUILD_TYPE" "-DCMAKE_INSTALL_PREFIX=$output_dir")
+        if [[ "$RUNNER_OS" == 'Windows' ]]; then
+          configure_args+=(-DCMAKE_C_COMPILER=cl.exe -DCMAKE_CXX_COMPILER=cl.exe)
+        elif [[ "$RUNNER_OS" == 'macOS' ]]; then
+          export CC=clang
+          export CXX=clang++
+        fi
+        cmake "${configure_args[@]}"
+        cmake --build "$build_dir" --config "$BEXT_BUILD_TYPE" --parallel 2
+
+    - name: Validate bext dependency tree
+      shell: bash
+      env:
+        BEXT_OUTPUT_DIR: ${{ inputs.output-dir }}
+      run: |
+        set -euo pipefail
+        output_dir="$BEXT_OUTPUT_DIR"
+        if command -v cygpath >/dev/null 2>&1; then
+          output_dir="$(cygpath -u "$output_dir")"
+        fi
+        [[ -d "$output_dir/install" && -d "$output_dir/noinstall" && -f "$output_dir/bext-install-manifest.json" ]]
+        tool="$output_dir/noinstall/bin/strclear"
+        if [[ "$RUNNER_OS" == 'Windows' ]]; then
+          [[ -f "$tool.exe" ]]
+        else
+          [[ -x "$tool" ]]
+        fi
+
+    - name: Save production artifact cache
+      if: steps.download.outputs.ready == 'true'
+      uses: actions/cache/save@v6
+      with:
+        path: ${{ inputs.output-dir }}
+        key: ${{ steps.resolve.outputs.production-cache-key }}
+
+    - name: Save fallback bext cache
+      if: steps.production-cache.outputs.cache-hit != 'true' && steps.download.outputs.ready != 'true' && steps.fallback-cache.outputs.cache-hit != 'true'
+      uses: actions/cache/save@v6
+      with:
+        path: ${{ inputs.output-dir }}
+        key: ${{ steps.resolve.outputs.fallback-cache-key }}
+
+    - name: Report bext source
+      id: result
+      shell: bash
+      env:
+        ARTIFACT_READY: ${{ steps.resolve.outputs.artifact-ready }}
+        ARTIFACT_SHA: ${{ steps.resolve.outputs.selected-sha }}
+        DOWNLOAD_READY: ${{ steps.download.outputs.ready }}
+        FALLBACK_CACHE_HIT: ${{ steps.fallback-cache.outputs.cache-hit }}
+        PRODUCTION_CACHE_HIT: ${{ steps.production-cache.outputs.cache-hit }}
+        REQUIRED_SHA: ${{ steps.resolve.outputs.required-sha }}
+      run: |
+        if [[ "$PRODUCTION_CACHE_HIT" == 'true' ]]; then
+          source=production-cache
+        elif [[ "$DOWNLOAD_READY" == 'true' ]]; then
+          source=production-artifact
+        elif [[ "$FALLBACK_CACHE_HIT" == 'true' ]]; then
+          source=fallback-cache
+        else
+          source=local-build
+        fi
+        if [[ "$ARTIFACT_READY" == 'true' && ( "$PRODUCTION_CACHE_HIT" == 'true' || "$DOWNLOAD_READY" == 'true' ) ]]; then
+          sha="$ARTIFACT_SHA"
+        else
+          sha="$REQUIRED_SHA"
+        fi
+        echo "source=$source" >> "$GITHUB_OUTPUT"
+        echo "bext-sha=$sha" >> "$GITHUB_OUTPUT"
+        echo "Prepared bext $sha from $source."

.github/workflows/distcheck.yml

@@ -1,9 +1,8 @@
 # BRL-CAD's primary distcheck target runs too long and does too much work to
 # be suitable as a CI target, even occasionally.  To achieve essentially the
 # same result, we define individual jobs for each distcheck sub-target and
-# run them in singletons.  To avoid the list of targets going stale, we
-# define this header and then autogenerate the actual build target jobs
-# to append to it from the CMake logic.
+# distribute them across five serial queues.  To avoid the target list going
+# stale, this header is followed by jobs generated from the CMake logic.
 
 name: Distcheck
 
@@ -14,21 +13,14 @@ on:
 
 jobs:
   bext:
-    name: Prepare bext (cached)
-    runs-on: ubuntu-latest
+    name: Prepare bext
+    runs-on: ubuntu-24.04
     env:
       DEBIAN_FRONTEND: noninteractive
     steps:
       - name: Setup - CMake
         uses: lukka/get-cmake@latest
 
-      - name: Cache apt packages
-        uses: actions/cache@v4
-        with:
-          path: |
-            /var/cache/apt/archives
-          key: ${{ runner.os }}-apt-${{ hashFiles('.github/workflows/check.yml') }}
-
       - name: Install apt dependencies
         run: |
           sudo apt-get update
@@ -45,54 +37,30 @@ jobs:
           sudo apt-get install libgl-dev
           sudo apt-get install libinput-dev
 
-      - name: Clone bext
-        run: git clone https://github.com/BRL-CAD/bext.git
-
-      - name: Get bext commit SHA
-        id: bext-sha
-        run: |
-          cd bext
-          echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
-
-      - name: Compute bext cache discriminator
-        id: cachekey
-        shell: bash
-        run: |
-          info="${{ steps.bext-sha.outputs.sha }}-$(uname -s)-$(uname -r)-$(gcc --version | head -n 1)"
-          echo "hash=$(echo -n "$info" | sha1sum | awk '{print $1}')" >> $GITHUB_OUTPUT
-
-      - name: Cache bext build outputs
-        id: cache-bext
-        uses: actions/cache@v4
+      - name: Checkout
+        uses: actions/checkout@v6
         with:
-          path: ${{ github.workspace }}/bext_output
-          key: ${{ runner.os }}-bext-${{ steps.cachekey.outputs.hash }}
+          path: brlcad
 
-      - name: Build bext (if cache miss)
-        if: steps.cache-bext.outputs.cache-hit != 'true'
-        run: |
-          cmake -E make_directory bext_build
-          cmake -S bext -B bext_build -DCMAKE_BUILD_TYPE=Release -DENABLE_ALL=ON -DCMAKE_INSTALL_PREFIX=${{ github.workspace }}/bext_output
-          cmake --build bext_build --config Release -j 2
-          cmake -E rm -rf bext
-          cmake -E rm -rf bext_build
+      - name: Prepare bext dependencies
+        uses: ./brlcad/.github/actions/prepare-bext
+        with:
+          platform-channel: ubuntu-24.04-${{ runner.arch }}-release
+          source-dir: ${{ github.workspace }}/brlcad
+          output-dir: ${{ runner.temp }}/bext_output
+          build-type: Release
+          artifact-token: ${{ secrets.BEXT_ARTIFACT_TOKEN }}
 
   distcheck-default_build_type:
     name: distcheck-default_build_type
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     needs: [bext]
     env:
       DEBIAN_FRONTEND: noninteractive
-    if: github.ref == 'refs/heads/main'
+    if: ${{ !cancelled() && github.ref == 'refs/heads/main' }}
     steps:
       - name: Setup - CMake
         uses: lukka/get-cmake@latest
-      - name: Cache apt packages
-        uses: actions/cache@v4
-        with:
-          path: |
-            /var/cache/apt/archives
-          key: ${{ runner.os }}-apt-${{ hashFiles('.github/workflows/check.yml') }}
       - name: Install apt dependencies
         run: |
           sudo apt-get update
@@ -100,52 +68,38 @@ jobs:
           sudo apt-get install astyle re2c
           sudo apt-get install zlib1g-dev libpng-dev libjpeg-dev libtiff-dev libeigen3-dev libgdal-dev libassimp-dev libopencv-dev tcl-dev tk-dev libgl-dev libinput-dev
 
-      - name: Setup - bext
-        run: |
-          git clone https://github.com/BRL-CAD/bext.git
-          cd bext
-          echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
-          cd ..
-
-      - name: Cache bext build outputs
-        id: cache-bext
-        uses: actions/cache@v4
-        with:
-          path: ${{ github.workspace }}/bext_output
-          key: ${{ runner.os }}-bext-${{ steps.bext-sha.outputs.sha }}
       - name: Checkout
         uses: actions/checkout@v6
         with:
           path: brlcad
+      - name: Prepare bext dependencies
+        uses: ./brlcad/.github/actions/prepare-bext
+        with:
+          platform-channel: ubuntu-24.04-${{ runner.arch }}-release
+          source-dir: ${{ github.workspace }}/brlcad
+          output-dir: ${{ runner.temp }}/bext_output
+          build-type: Release
+          artifact-token: ${{ secrets.BEXT_ARTIFACT_TOKEN }}
       - name: Directory setup
         run: cmake -E make_directory build_distcheck-default_build_type
       - name: Configure
-        run: cmake -S brlcad -B build_distcheck-default_build_type -G Ninja -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_DIR=${{ github.workspace }}/bext_output
+        run: cmake -S brlcad -B build_distcheck-default_build_type -G Ninja -DBRLCAD_EXT_DIR=${{ runner.temp }}/bext_output
       - name: Build
-        run: cmake --build build_distcheck-default_build_type --config Release --target distcheck-default_build_type
+        run: cmake --build build_distcheck-default_build_type --target distcheck-default_build_type
       - name: Log
         if: always()
         run: cat build_distcheck-default_build_type/distcheck-default_build_type.log
-      - name: Debug if failure
-        if: failure()
-        uses: mxschmitt/action-tmate@v3
 
   distcheck-debug:
     name: distcheck-debug
-    runs-on: ubuntu-latest
-    needs: [distcheck-default_build_type]
+    runs-on: ubuntu-24.04
+    needs: [bext]
     env:
       DEBIAN_FRONTEND: noninteractive
-    if: github.ref == 'refs/heads/main'
+    if: ${{ !cancelled() && github.ref == 'refs/heads/main' }}
     steps:
       - name: Setup - CMake
         uses: lukka/get-cmake@latest
-      - name: Cache apt packages
-        uses: actions/cache@v4
-        with:
-          path: |
-            /var/cache/apt/archives
-          key: ${{ runner.os }}-apt-${{ hashFiles('.github/workflows/check.yml') }}
       - name: Install apt dependencies
         run: |
           sudo apt-get update
@@ -153,52 +107,38 @@ jobs:
           sudo apt-get install astyle re2c
           sudo apt-get install zlib1g-dev libpng-dev libjpeg-dev libtiff-dev libeigen3-dev libgdal-dev libassimp-dev libopencv-dev tcl-dev tk-dev libgl-dev libinput-dev
 
-      - name: Setup - bext
-        run: |
-          git clone https://github.com/BRL-CAD/bext.git
-          cd bext
-          echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
-          cd ..
-
-      - name: Cache bext build outputs
-        id: cache-bext
-        uses: actions/cache@v4
-        with:
-          path: ${{ github.workspace }}/bext_output
-          key: ${{ runner.os }}-bext-${{ steps.bext-sha.outputs.sha }}
       - name: Checkout
         uses: actions/checkout@v6
         with:
           path: brlcad
+      - name: Prepare bext dependencies
+        uses: ./brlcad/.github/actions/prepare-bext
+        with:
+          platform-channel: ubuntu-24.04-${{ runner.arch }}-release
+          source-dir: ${{ github.workspace }}/brlcad
+          output-dir: ${{ runner.temp }}/bext_output
+          build-type: Release
+          artifact-token: ${{ secrets.BEXT_ARTIFACT_TOKEN }}
       - name: Directory setup
         run: cmake -E make_directory build_distcheck-debug
       - name: Configure
-        run: cmake -S brlcad -B build_distcheck-debug -G Ninja -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_DIR=${{ github.workspace }}/bext_output
+        run: cmake -S brlcad -B build_distcheck-debug -G Ninja -DCMAKE_BUILD_TYPE=Debug -DBRLCAD_EXT_DIR=${{ runner.temp }}/bext_output
       - name: Build
-        run: cmake --build build_distcheck-debug --config Release --target distcheck-debug
+        run: cmake --build build_distcheck-debug --config Debug --target distcheck-debug
       - name: Log
         if: always()
         run: cat build_distcheck-debug/distcheck-debug.log
-      - name: Debug if failure
-        if: failure()
-        uses: mxschmitt/action-tmate@v3
 
   distcheck-release:
     name: distcheck-release
-    runs-on: ubuntu-latest
-    needs: [distcheck-debug]
+    runs-on: ubuntu-24.04
+    needs: [bext]
     env:
       DEBIAN_FRONTEND: noninteractive
-    if: github.ref == 'refs/heads/main'
+    if: ${{ !cancelled() && github.ref == 'refs/heads/main' }}
     steps:
       - name: Setup - CMake
         uses: lukka/get-cmake@latest
-      - name: Cache apt packages
-        uses: actions/cache@v4
-        with:
-          path: |
-            /var/cache/apt/archives
-          key: ${{ runner.os }}-apt-${{ hashFiles('.github/workflows/check.yml') }}
       - name: Install apt dependencies
         run: |
           sudo apt-get update
@@ -206,52 +146,116 @@ jobs:
           sudo apt-get install astyle re2c
           sudo apt-get install zlib1g-dev libpng-dev libjpeg-dev libtiff-dev libeigen3-dev libgdal-dev libassimp-dev libopencv-dev tcl-dev tk-dev libgl-dev libinput-dev
 
-      - name: Setup - bext
-        run: |
-          git clone https://github.com/BRL-CAD/bext.git
-          cd bext
-          echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
-          cd ..
-
-      - name: Cache bext build outputs
-        id: cache-bext
-        uses: actions/cache@v4
-        with:
-          path: ${{ github.workspace }}/bext_output
-          key: ${{ runner.os }}-bext-${{ steps.bext-sha.outputs.sha }}
       - name: Checkout
         uses: actions/checkout@v6
         with:
           path: brlcad
+      - name: Prepare bext dependencies
+        uses: ./brlcad/.github/actions/prepare-bext
+        with:
+          platform-channel: ubuntu-24.04-${{ runner.arch }}-release
+          source-dir: ${{ github.workspace }}/brlcad
+          output-dir: ${{ runner.temp }}/bext_output
+          build-type: Release
+          artifact-token: ${{ secrets.BEXT_ARTIFACT_TOKEN }}
       - name: Directory setup
         run: cmake -E make_directory build_distcheck-release
       - name: Configure
-        run: cmake -S brlcad -B build_distcheck-release -G Ninja -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_DIR=${{ github.workspace }}/bext_output
+        run: cmake -S brlcad -B build_distcheck-release -G Ninja -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_DIR=${{ runner.temp }}/bext_output
       - name: Build
         run: cmake --build build_distcheck-release --config Release --target distcheck-release
       - name: Log
         if: always()
         run: cat build_distcheck-release/distcheck-release.log
-      - name: Debug if failure
-        if: failure()
-        uses: mxschmitt/action-tmate@v3
+
+  distcheck-no_unity_debug:
+    name: distcheck-no_unity_debug
+    runs-on: ubuntu-24.04
+    needs: [bext]
+    env:
+      DEBIAN_FRONTEND: noninteractive
+    if: ${{ !cancelled() && github.ref == 'refs/heads/main' }}
+    steps:
+      - name: Setup - CMake
+        uses: lukka/get-cmake@latest
+      - name: Install apt dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install xserver-xorg-dev libx11-dev libxi-dev libxext-dev libglu1-mesa-dev libfontconfig-dev
+          sudo apt-get install astyle re2c
+          sudo apt-get install zlib1g-dev libpng-dev libjpeg-dev libtiff-dev libeigen3-dev libgdal-dev libassimp-dev libopencv-dev tcl-dev tk-dev libgl-dev libinput-dev
+
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          path: brlcad
+      - name: Prepare bext dependencies
+        uses: ./brlcad/.github/actions/prepare-bext
+        with:
+          platform-channel: ubuntu-24.04-${{ runner.arch }}-release
+          source-dir: ${{ github.workspace }}/brlcad
+          output-dir: ${{ runner.temp }}/bext_output
+          build-type: Release
+          artifact-token: ${{ secrets.BEXT_ARTIFACT_TOKEN }}
+      - name: Directory setup
+        run: cmake -E make_directory build_distcheck-no_unity_debug
+      - name: Configure
+        run: cmake -S brlcad -B build_distcheck-no_unity_debug -G Ninja -DCMAKE_BUILD_TYPE=Debug -DBRLCAD_EXT_DIR=${{ runner.temp }}/bext_output -DBRLCAD_ENABLE_UNITY_BUILD=OFF
+      - name: Build
+        run: cmake --build build_distcheck-no_unity_debug --config Debug --target distcheck-no_unity_debug
+      - name: Log
+        if: always()
+        run: cat build_distcheck-no_unity_debug/distcheck-no_unity_debug.log
+
+  distcheck-no_unity_release:
+    name: distcheck-no_unity_release
+    runs-on: ubuntu-24.04
+    needs: [bext]
+    env:
+      DEBIAN_FRONTEND: noninteractive
+    if: ${{ !cancelled() && github.ref == 'refs/heads/main' }}
+    steps:
+      - name: Setup - CMake
+        uses: lukka/get-cmake@latest
+      - name: Install apt dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install xserver-xorg-dev libx11-dev libxi-dev libxext-dev libglu1-mesa-dev libfontconfig-dev
+          sudo apt-get install astyle re2c
+          sudo apt-get install zlib1g-dev libpng-dev libjpeg-dev libtiff-dev libeigen3-dev libgdal-dev libassimp-dev libopencv-dev tcl-dev tk-dev libgl-dev libinput-dev
+
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          path: brlcad
+      - name: Prepare bext dependencies
+        uses: ./brlcad/.github/actions/prepare-bext
+        with:
+          platform-channel: ubuntu-24.04-${{ runner.arch }}-release
+          source-dir: ${{ github.workspace }}/brlcad
+          output-dir: ${{ runner.temp }}/bext_output
+          build-type: Release
+          artifact-token: ${{ secrets.BEXT_ARTIFACT_TOKEN }}
+      - name: Directory setup
+        run: cmake -E make_directory build_distcheck-no_unity_release
+      - name: Configure
+        run: cmake -S brlcad -B build_distcheck-no_unity_release -G Ninja -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_DIR=${{ runner.temp }}/bext_output -DBRLCAD_ENABLE_UNITY_BUILD=OFF
+      - name: Build
+        run: cmake --build build_distcheck-no_unity_release --config Release --target distcheck-no_unity_release
+      - name: Log
+        if: always()
+        run: cat build_distcheck-no_unity_release/distcheck-no_unity_release.log
 
   distcheck-enableall_debug:
     name: distcheck-enableall_debug
-    runs-on: ubuntu-latest
-    needs: [distcheck-release]
+    runs-on: ubuntu-24.04
+    needs: [distcheck-default_build_type]
     env:
       DEBIAN_FRONTEND: noninteractive
-    if: github.ref == 'refs/heads/main'
+    if: ${{ !cancelled() && github.ref == 'refs/heads/main' }}
     steps:
       - name: Setup - CMake
         uses: lukka/get-cmake@latest
-      - name: Cache apt packages
-        uses: actions/cache@v4
-        with:
-          path: |
-            /var/cache/apt/archives
-          key: ${{ runner.os }}-apt-${{ hashFiles('.github/workflows/check.yml') }}
       - name: Install apt dependencies
         run: |
           sudo apt-get update
@@ -259,52 +263,38 @@ jobs:
           sudo apt-get install astyle re2c
           sudo apt-get install zlib1g-dev libpng-dev libjpeg-dev libtiff-dev libeigen3-dev libgdal-dev libassimp-dev libopencv-dev tcl-dev tk-dev libgl-dev libinput-dev
 
-      - name: Setup - bext
-        run: |
-          git clone https://github.com/BRL-CAD/bext.git
-          cd bext
-          echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
-          cd ..
-
-      - name: Cache bext build outputs
-        id: cache-bext
-        uses: actions/cache@v4
-        with:
-          path: ${{ github.workspace }}/bext_output
-          key: ${{ runner.os }}-bext-${{ steps.bext-sha.outputs.sha }}
       - name: Checkout
         uses: actions/checkout@v6
         with:
           path: brlcad
+      - name: Prepare bext dependencies
+        uses: ./brlcad/.github/actions/prepare-bext
+        with:
+          platform-channel: ubuntu-24.04-${{ runner.arch }}-release
+          source-dir: ${{ github.workspace }}/brlcad
+          output-dir: ${{ runner.temp }}/bext_output
+          build-type: Release
+          artifact-token: ${{ secrets.BEXT_ARTIFACT_TOKEN }}
       - name: Directory setup
         run: cmake -E make_directory build_distcheck-enableall_debug
       - name: Configure
-        run: cmake -S brlcad -B build_distcheck-enableall_debug -G Ninja -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_DIR=${{ github.workspace }}/bext_output
+        run: cmake -S brlcad -B build_distcheck-enableall_debug -G Ninja -DCMAKE_BUILD_TYPE=Debug -DENABLE_ALL=ON -DBRLCAD_EXT_DIR=${{ runner.temp }}/bext_output
       - name: Build
-        run: cmake --build build_distcheck-enableall_debug --config Release --target distcheck-enableall_debug
+        run: cmake --build build_distcheck-enableall_debug --config Debug --target distcheck-enableall_debug
       - name: Log
         if: always()
         run: cat build_distcheck-enableall_debug/distcheck-enableall_debug.log
-      - name: Debug if failure
-        if: failure()
-        uses: mxschmitt/action-tmate@v3
 
   distcheck-enableall_release:
     name: distcheck-enableall_release
-    runs-on: ubuntu-latest
-    needs: [distcheck-enableall_debug]
+    runs-on: ubuntu-24.04
+    needs: [distcheck-debug]
     env:
       DEBIAN_FRONTEND: noninteractive
-    if: github.ref == 'refs/heads/main'
+    if: ${{ !cancelled() && github.ref == 'refs/heads/main' }}
     steps:
       - name: Setup - CMake
         uses: lukka/get-cmake@latest
-      - name: Cache apt packages
-        uses: actions/cache@v4
-        with:
-          path: |
-            /var/cache/apt/archives
-          key: ${{ runner.os }}-apt-${{ hashFiles('.github/workflows/check.yml') }}
       - name: Install apt dependencies
         run: |
           sudo apt-get update
@@ -312,52 +302,38 @@ jobs:
           sudo apt-get install astyle re2c
           sudo apt-get install zlib1g-dev libpng-dev libjpeg-dev libtiff-dev libeigen3-dev libgdal-dev libassimp-dev libopencv-dev tcl-dev tk-dev libgl-dev libinput-dev
 
-      - name: Setup - bext
-        run: |
-          git clone https://github.com/BRL-CAD/bext.git
-          cd bext
-          echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
-          cd ..
-
-      - name: Cache bext build outputs
-        id: cache-bext
-        uses: actions/cache@v4
-        with:
-          path: ${{ github.workspace }}/bext_output
-          key: ${{ runner.os }}-bext-${{ steps.bext-sha.outputs.sha }}
       - name: Checkout
         uses: actions/checkout@v6
         with:
           path: brlcad
+      - name: Prepare bext dependencies
+        uses: ./brlcad/.github/actions/prepare-bext
+        with:
+          platform-channel: ubuntu-24.04-${{ runner.arch }}-release
+          source-dir: ${{ github.workspace }}/brlcad
+          output-dir: ${{ runner.temp }}/bext_output
+          build-type: Release
+          artifact-token: ${{ secrets.BEXT_ARTIFACT_TOKEN }}
       - name: Directory setup
         run: cmake -E make_directory build_distcheck-enableall_release
       - name: Configure
-        run: cmake -S brlcad -B build_distcheck-enableall_release -G Ninja -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_DIR=${{ github.workspace }}/bext_output
+        run: cmake -S brlcad -B build_distcheck-enableall_release -G Ninja -DCMAKE_BUILD_TYPE=Release -DENABLE_ALL=ON -DBRLCAD_EXT_DIR=${{ runner.temp }}/bext_output
       - name: Build
         run: cmake --build build_distcheck-enableall_release --config Release --target distcheck-enableall_release
       - name: Log
         if: always()
         run: cat build_distcheck-enableall_release/distcheck-enableall_release.log
-      - name: Debug if failure
-        if: failure()
-        uses: mxschmitt/action-tmate@v3
 
   distcheck-prepared_debug:
     name: distcheck-prepared_debug
-    runs-on: ubuntu-latest
-    needs: [distcheck-enableall_release]
+    runs-on: ubuntu-24.04
+    needs: [distcheck-release]
     env:
       DEBIAN_FRONTEND: noninteractive
-    if: github.ref == 'refs/heads/main'
+    if: ${{ !cancelled() && github.ref == 'refs/heads/main' }}
     steps:
       - name: Setup - CMake
         uses: lukka/get-cmake@latest
-      - name: Cache apt packages
-        uses: actions/cache@v4
-        with:
-          path: |
-            /var/cache/apt/archives
-          key: ${{ runner.os }}-apt-${{ hashFiles('.github/workflows/check.yml') }}
       - name: Install apt dependencies
         run: |
           sudo apt-get update
@@ -365,52 +341,38 @@ jobs:
           sudo apt-get install astyle re2c
           sudo apt-get install zlib1g-dev libpng-dev libjpeg-dev libtiff-dev libeigen3-dev libgdal-dev libassimp-dev libopencv-dev tcl-dev tk-dev libgl-dev libinput-dev
 
-      - name: Setup - bext
-        run: |
-          git clone https://github.com/BRL-CAD/bext.git
-          cd bext
-          echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
-          cd ..
-
-      - name: Cache bext build outputs
-        id: cache-bext
-        uses: actions/cache@v4
-        with:
-          path: ${{ github.workspace }}/bext_output
-          key: ${{ runner.os }}-bext-${{ steps.bext-sha.outputs.sha }}
       - name: Checkout
         uses: actions/checkout@v6
         with:
           path: brlcad
+      - name: Prepare bext dependencies
+        uses: ./brlcad/.github/actions/prepare-bext
+        with:
+          platform-channel: ubuntu-24.04-${{ runner.arch }}-release
+          source-dir: ${{ github.workspace }}/brlcad
+          output-dir: ${{ runner.temp }}/bext_output
+          build-type: Release
+          artifact-token: ${{ secrets.BEXT_ARTIFACT_TOKEN }}
       - name: Directory setup
         run: cmake -E make_directory build_distcheck-prepared_debug
       - name: Configure
-        run: cmake -S brlcad -B build_distcheck-prepared_debug -G Ninja -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_DIR=${{ github.workspace }}/bext_output
+        run: cmake -S brlcad -B build_distcheck-prepared_debug -G Ninja -DCMAKE_BUILD_TYPE=Debug -DBRLCAD_EXT_DIR=${{ runner.temp }}/bext_output
       - name: Build
-        run: cmake --build build_distcheck-prepared_debug --config Release --target distcheck-prepared_debug
+        run: cmake --build build_distcheck-prepared_debug --config Debug --target distcheck-prepared_debug
       - name: Log
         if: always()
         run: cat build_distcheck-prepared_debug/distcheck-prepared_debug.log
-      - name: Debug if failure
-        if: failure()
-        uses: mxschmitt/action-tmate@v3
 
   distcheck-prepared_release:
     name: distcheck-prepared_release
-    runs-on: ubuntu-latest
-    needs: [distcheck-prepared_debug]
+    runs-on: ubuntu-24.04
+    needs: [distcheck-no_unity_debug]
     env:
       DEBIAN_FRONTEND: noninteractive
-    if: github.ref == 'refs/heads/main'
+    if: ${{ !cancelled() && github.ref == 'refs/heads/main' }}
     steps:
       - name: Setup - CMake
         uses: lukka/get-cmake@latest
-      - name: Cache apt packages
-        uses: actions/cache@v4
-        with:
-          path: |
-            /var/cache/apt/archives
-          key: ${{ runner.os }}-apt-${{ hashFiles('.github/workflows/check.yml') }}
       - name: Install apt dependencies
         run: |
           sudo apt-get update
@@ -418,52 +380,38 @@ jobs:
           sudo apt-get install astyle re2c
           sudo apt-get install zlib1g-dev libpng-dev libjpeg-dev libtiff-dev libeigen3-dev libgdal-dev libassimp-dev libopencv-dev tcl-dev tk-dev libgl-dev libinput-dev
 
-      - name: Setup - bext
-        run: |
-          git clone https://github.com/BRL-CAD/bext.git
-          cd bext
-          echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
-          cd ..
-
-      - name: Cache bext build outputs
-        id: cache-bext
-        uses: actions/cache@v4
-        with:
-          path: ${{ github.workspace }}/bext_output
-          key: ${{ runner.os }}-bext-${{ steps.bext-sha.outputs.sha }}
       - name: Checkout
         uses: actions/checkout@v6
         with:
           path: brlcad
+      - name: Prepare bext dependencies
+        uses: ./brlcad/.github/actions/prepare-bext
+        with:
+          platform-channel: ubuntu-24.04-${{ runner.arch }}-release
+          source-dir: ${{ github.workspace }}/brlcad
+          output-dir: ${{ runner.temp }}/bext_output
+          build-type: Release
+          artifact-token: ${{ secrets.BEXT_ARTIFACT_TOKEN }}
       - name: Directory setup
         run: cmake -E make_directory build_distcheck-prepared_release
       - name: Configure
-        run: cmake -S brlcad -B build_distcheck-prepared_release -G Ninja -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_DIR=${{ github.workspace }}/bext_output
+        run: cmake -S brlcad -B build_distcheck-prepared_release -G Ninja -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_DIR=${{ runner.temp }}/bext_output
       - name: Build
         run: cmake --build build_distcheck-prepared_release --config Release --target distcheck-prepared_release
       - name: Log
         if: always()
         run: cat build_distcheck-prepared_release/distcheck-prepared_release.log
-      - name: Debug if failure
-        if: failure()
-        uses: mxschmitt/action-tmate@v3
 
   distcheck-no_tcl:
     name: distcheck-no_tcl
-    runs-on: ubuntu-latest
-    needs: [distcheck-prepared_release]
+    runs-on: ubuntu-24.04
+    needs: [distcheck-no_unity_release]
     env:
       DEBIAN_FRONTEND: noninteractive
-    if: github.ref == 'refs/heads/main'
+    if: ${{ !cancelled() && github.ref == 'refs/heads/main' }}
     steps:
       - name: Setup - CMake
         uses: lukka/get-cmake@latest
-      - name: Cache apt packages
-        uses: actions/cache@v4
-        with:
-          path: |
-            /var/cache/apt/archives
-          key: ${{ runner.os }}-apt-${{ hashFiles('.github/workflows/check.yml') }}
       - name: Install apt dependencies
         run: |
           sudo apt-get update
@@ -471,52 +419,38 @@ jobs:
           sudo apt-get install astyle re2c
           sudo apt-get install zlib1g-dev libpng-dev libjpeg-dev libtiff-dev libeigen3-dev libgdal-dev libassimp-dev libopencv-dev tcl-dev tk-dev libgl-dev libinput-dev
 
-      - name: Setup - bext
-        run: |
-          git clone https://github.com/BRL-CAD/bext.git
-          cd bext
-          echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
-          cd ..
-
-      - name: Cache bext build outputs
-        id: cache-bext
-        uses: actions/cache@v4
-        with:
-          path: ${{ github.workspace }}/bext_output
-          key: ${{ runner.os }}-bext-${{ steps.bext-sha.outputs.sha }}
       - name: Checkout
         uses: actions/checkout@v6
         with:
           path: brlcad
+      - name: Prepare bext dependencies
+        uses: ./brlcad/.github/actions/prepare-bext
+        with:
+          platform-channel: ubuntu-24.04-${{ runner.arch }}-release
+          source-dir: ${{ github.workspace }}/brlcad
+          output-dir: ${{ runner.temp }}/bext_output
+          build-type: Release
+          artifact-token: ${{ secrets.BEXT_ARTIFACT_TOKEN }}
       - name: Directory setup
         run: cmake -E make_directory build_distcheck-no_tcl
       - name: Configure
-        run: cmake -S brlcad -B build_distcheck-no_tcl -G Ninja -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_DIR=${{ github.workspace }}/bext_output
+        run: cmake -S brlcad -B build_distcheck-no_tcl -G Ninja -DCMAKE_BUILD_TYPE=Debug -DBRLCAD_EXT_DIR=${{ runner.temp }}/bext_output -DBRLCAD_ENABLE_TCL=OFF
       - name: Build
-        run: cmake --build build_distcheck-no_tcl --config Release --target distcheck-no_tcl
+        run: cmake --build build_distcheck-no_tcl --config Debug --target distcheck-no_tcl
       - name: Log
         if: always()
         run: cat build_distcheck-no_tcl/distcheck-no_tcl.log
-      - name: Debug if failure
-        if: failure()
-        uses: mxschmitt/action-tmate@v3
 
   distcheck-no_tk:
     name: distcheck-no_tk
-    runs-on: ubuntu-latest
-    needs: [distcheck-no_tcl]
+    runs-on: ubuntu-24.04
+    needs: [distcheck-enableall_debug]
     env:
       DEBIAN_FRONTEND: noninteractive
-    if: github.ref == 'refs/heads/main'
+    if: ${{ !cancelled() && github.ref == 'refs/heads/main' }}
     steps:
       - name: Setup - CMake
         uses: lukka/get-cmake@latest
-      - name: Cache apt packages
-        uses: actions/cache@v4
-        with:
-          path: |
-            /var/cache/apt/archives
-          key: ${{ runner.os }}-apt-${{ hashFiles('.github/workflows/check.yml') }}
       - name: Install apt dependencies
         run: |
           sudo apt-get update
@@ -524,52 +458,38 @@ jobs:
           sudo apt-get install astyle re2c
           sudo apt-get install zlib1g-dev libpng-dev libjpeg-dev libtiff-dev libeigen3-dev libgdal-dev libassimp-dev libopencv-dev libgl-dev libinput-dev
 
-      - name: Setup - bext
-        run: |
-          git clone https://github.com/BRL-CAD/bext.git
-          cd bext
-          echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
-          cd ..
-
-      - name: Cache bext build outputs
-        id: cache-bext
-        uses: actions/cache@v4
-        with:
-          path: ${{ github.workspace }}/bext_output
-          key: ${{ runner.os }}-bext-${{ steps.bext-sha.outputs.sha }}
       - name: Checkout
         uses: actions/checkout@v6
         with:
           path: brlcad
+      - name: Prepare bext dependencies
+        uses: ./brlcad/.github/actions/prepare-bext
+        with:
+          platform-channel: ubuntu-24.04-${{ runner.arch }}-release
+          source-dir: ${{ github.workspace }}/brlcad
+          output-dir: ${{ runner.temp }}/bext_output
+          build-type: Release
+          artifact-token: ${{ secrets.BEXT_ARTIFACT_TOKEN }}
       - name: Directory setup
         run: cmake -E make_directory build_distcheck-no_tk
       - name: Configure
-        run: cmake -S brlcad -B build_distcheck-no_tk -G Ninja -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_DIR=${{ github.workspace }}/bext_output
+        run: cmake -S brlcad -B build_distcheck-no_tk -G Ninja -DCMAKE_BUILD_TYPE=Debug -DBRLCAD_EXT_DIR=${{ runner.temp }}/bext_output -DBRLCAD_ENABLE_TK=OFF
       - name: Build
-        run: cmake --build build_distcheck-no_tk --config Release --target distcheck-no_tk
+        run: cmake --build build_distcheck-no_tk --config Debug --target distcheck-no_tk
       - name: Log
         if: always()
         run: cat build_distcheck-no_tk/distcheck-no_tk.log
-      - name: Debug if failure
-        if: failure()
-        uses: mxschmitt/action-tmate@v3
 
   distcheck-no_strict:
     name: distcheck-no_strict
-    runs-on: ubuntu-latest
-    needs: [distcheck-no_tk]
+    runs-on: ubuntu-24.04
+    needs: [distcheck-enableall_release]
     env:
       DEBIAN_FRONTEND: noninteractive
-    if: github.ref == 'refs/heads/main'
+    if: ${{ !cancelled() && github.ref == 'refs/heads/main' }}
     steps:
       - name: Setup - CMake
         uses: lukka/get-cmake@latest
-      - name: Cache apt packages
-        uses: actions/cache@v4
-        with:
-          path: |
-            /var/cache/apt/archives
-          key: ${{ runner.os }}-apt-${{ hashFiles('.github/workflows/check.yml') }}
       - name: Install apt dependencies
         run: |
           sudo apt-get update
@@ -577,52 +497,38 @@ jobs:
           sudo apt-get install astyle re2c
           sudo apt-get install zlib1g-dev libpng-dev libjpeg-dev libtiff-dev libeigen3-dev libgdal-dev libassimp-dev libopencv-dev tcl-dev tk-dev libgl-dev libinput-dev
 
-      - name: Setup - bext
-        run: |
-          git clone https://github.com/BRL-CAD/bext.git
-          cd bext
-          echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
-          cd ..
-
-      - name: Cache bext build outputs
-        id: cache-bext
-        uses: actions/cache@v4
-        with:
-          path: ${{ github.workspace }}/bext_output
-          key: ${{ runner.os }}-bext-${{ steps.bext-sha.outputs.sha }}
       - name: Checkout
         uses: actions/checkout@v6
         with:
           path: brlcad
+      - name: Prepare bext dependencies
+        uses: ./brlcad/.github/actions/prepare-bext
+        with:
+          platform-channel: ubuntu-24.04-${{ runner.arch }}-release
+          source-dir: ${{ github.workspace }}/brlcad
+          output-dir: ${{ runner.temp }}/bext_output
+          build-type: Release
+          artifact-token: ${{ secrets.BEXT_ARTIFACT_TOKEN }}
       - name: Directory setup
         run: cmake -E make_directory build_distcheck-no_strict
       - name: Configure
-        run: cmake -S brlcad -B build_distcheck-no_strict -G Ninja -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_DIR=${{ github.workspace }}/bext_output
+        run: cmake -S brlcad -B build_distcheck-no_strict -G Ninja -DCMAKE_BUILD_TYPE=Debug -DBRLCAD_EXT_DIR=${{ runner.temp }}/bext_output -DBRLCAD_ENABLE_STRICT=OFF
       - name: Build
-        run: cmake --build build_distcheck-no_strict --config Release --target distcheck-no_strict
+        run: cmake --build build_distcheck-no_strict --config Debug --target distcheck-no_strict
       - name: Log
         if: always()
         run: cat build_distcheck-no_strict/distcheck-no_strict.log
-      - name: Debug if failure
-        if: failure()
-        uses: mxschmitt/action-tmate@v3
 
   distcheck-no_object:
     name: distcheck-no_object
-    runs-on: ubuntu-latest
-    needs: [distcheck-no_strict]
+    runs-on: ubuntu-24.04
+    needs: [distcheck-prepared_debug]
     env:
       DEBIAN_FRONTEND: noninteractive
-    if: github.ref == 'refs/heads/main'
+    if: ${{ !cancelled() && github.ref == 'refs/heads/main' }}
     steps:
       - name: Setup - CMake
         uses: lukka/get-cmake@latest
-      - name: Cache apt packages
-        uses: actions/cache@v4
-        with:
-          path: |
-            /var/cache/apt/archives
-          key: ${{ runner.os }}-apt-${{ hashFiles('.github/workflows/check.yml') }}
       - name: Install apt dependencies
         run: |
           sudo apt-get update
@@ -630,52 +536,38 @@ jobs:
           sudo apt-get install astyle re2c
           sudo apt-get install zlib1g-dev libpng-dev libjpeg-dev libtiff-dev libeigen3-dev libgdal-dev libassimp-dev libopencv-dev tcl-dev tk-dev libgl-dev libinput-dev
 
-      - name: Setup - bext
-        run: |
-          git clone https://github.com/BRL-CAD/bext.git
-          cd bext
-          echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
-          cd ..
-
-      - name: Cache bext build outputs
-        id: cache-bext
-        uses: actions/cache@v4
-        with:
-          path: ${{ github.workspace }}/bext_output
-          key: ${{ runner.os }}-bext-${{ steps.bext-sha.outputs.sha }}
       - name: Checkout
         uses: actions/checkout@v6
         with:
           path: brlcad
+      - name: Prepare bext dependencies
+        uses: ./brlcad/.github/actions/prepare-bext
+        with:
+          platform-channel: ubuntu-24.04-${{ runner.arch }}-release
+          source-dir: ${{ github.workspace }}/brlcad
+          output-dir: ${{ runner.temp }}/bext_output
+          build-type: Release
+          artifact-token: ${{ secrets.BEXT_ARTIFACT_TOKEN }}
       - name: Directory setup
         run: cmake -E make_directory build_distcheck-no_object
       - name: Configure
-        run: cmake -S brlcad -B build_distcheck-no_object -G Ninja -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_DIR=${{ github.workspace }}/bext_output
+        run: cmake -S brlcad -B build_distcheck-no_object -G Ninja -DCMAKE_BUILD_TYPE=Debug -DBRLCAD_EXT_DIR=${{ runner.temp }}/bext_output -DUSE_OBJECT_LIBS=OFF
       - name: Build
-        run: cmake --build build_distcheck-no_object --config Release --target distcheck-no_object
+        run: cmake --build build_distcheck-no_object --config Debug --target distcheck-no_object
       - name: Log
         if: always()
         run: cat build_distcheck-no_object/distcheck-no_object.log
-      - name: Debug if failure
-        if: failure()
-        uses: mxschmitt/action-tmate@v3
 
   distcheck-odd_pathnames:
     name: distcheck-odd_pathnames
-    runs-on: ubuntu-latest
-    needs: [distcheck-no_object]
+    runs-on: ubuntu-24.04
+    needs: [distcheck-prepared_release]
     env:
       DEBIAN_FRONTEND: noninteractive
-    if: github.ref == 'refs/heads/main'
+    if: ${{ !cancelled() && github.ref == 'refs/heads/main' }}
     steps:
       - name: Setup - CMake
         uses: lukka/get-cmake@latest
-      - name: Cache apt packages
-        uses: actions/cache@v4
-        with:
-          path: |
-            /var/cache/apt/archives
-          key: ${{ runner.os }}-apt-${{ hashFiles('.github/workflows/check.yml') }}
       - name: Install apt dependencies
         run: |
           sudo apt-get update
@@ -683,52 +575,38 @@ jobs:
           sudo apt-get install astyle re2c
           sudo apt-get install zlib1g-dev libpng-dev libjpeg-dev libtiff-dev libeigen3-dev libgdal-dev libassimp-dev libopencv-dev tcl-dev tk-dev libgl-dev libinput-dev
 
-      - name: Setup - bext
-        run: |
-          git clone https://github.com/BRL-CAD/bext.git
-          cd bext
-          echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
-          cd ..
-
-      - name: Cache bext build outputs
-        id: cache-bext
-        uses: actions/cache@v4
-        with:
-          path: ${{ github.workspace }}/bext_output
-          key: ${{ runner.os }}-bext-${{ steps.bext-sha.outputs.sha }}
       - name: Checkout
         uses: actions/checkout@v6
         with:
           path: brlcad
+      - name: Prepare bext dependencies
+        uses: ./brlcad/.github/actions/prepare-bext
+        with:
+          platform-channel: ubuntu-24.04-${{ runner.arch }}-release
+          source-dir: ${{ github.workspace }}/brlcad
+          output-dir: ${{ runner.temp }}/bext_output
+          build-type: Release
+          artifact-token: ${{ secrets.BEXT_ARTIFACT_TOKEN }}
       - name: Directory setup
         run: cmake -E make_directory build_distcheck-odd_pathnames
       - name: Configure
-        run: cmake -S brlcad -B build_distcheck-odd_pathnames -G Ninja -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_DIR=${{ github.workspace }}/bext_output
+        run: cmake -S brlcad -B build_distcheck-odd_pathnames -G Ninja -DCMAKE_BUILD_TYPE=Debug -DBRLCAD_EXT_DIR=${{ runner.temp }}/bext_output
       - name: Build
-        run: cmake --build build_distcheck-odd_pathnames --config Release --target distcheck-odd_pathnames
+        run: cmake --build build_distcheck-odd_pathnames --config Debug --target distcheck-odd_pathnames
       - name: Log
         if: always()
         run: cat build_distcheck-odd_pathnames/distcheck-odd_pathnames.log
-      - name: Debug if failure
-        if: failure()
-        uses: mxschmitt/action-tmate@v3
 
   distcheck-in_src_dir:
     name: distcheck-in_src_dir
-    runs-on: ubuntu-latest
-    needs: [distcheck-odd_pathnames]
+    runs-on: ubuntu-24.04
+    needs: [distcheck-no_tcl]
     env:
       DEBIAN_FRONTEND: noninteractive
-    if: github.ref == 'refs/heads/main'
+    if: ${{ !cancelled() && github.ref == 'refs/heads/main' }}
     steps:
       - name: Setup - CMake
         uses: lukka/get-cmake@latest
-      - name: Cache apt packages
-        uses: actions/cache@v4
-        with:
-          path: |
-            /var/cache/apt/archives
-          key: ${{ runner.os }}-apt-${{ hashFiles('.github/workflows/check.yml') }}
       - name: Install apt dependencies
         run: |
           sudo apt-get update
@@ -736,33 +614,24 @@ jobs:
           sudo apt-get install astyle re2c
           sudo apt-get install zlib1g-dev libpng-dev libjpeg-dev libtiff-dev libeigen3-dev libgdal-dev libassimp-dev libopencv-dev tcl-dev tk-dev libgl-dev libinput-dev
 
-      - name: Setup - bext
-        run: |
-          git clone https://github.com/BRL-CAD/bext.git
-          cd bext
-          echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
-          cd ..
-
-      - name: Cache bext build outputs
-        id: cache-bext
-        uses: actions/cache@v4
-        with:
-          path: ${{ github.workspace }}/bext_output
-          key: ${{ runner.os }}-bext-${{ steps.bext-sha.outputs.sha }}
       - name: Checkout
         uses: actions/checkout@v6
         with:
           path: brlcad
+      - name: Prepare bext dependencies
+        uses: ./brlcad/.github/actions/prepare-bext
+        with:
+          platform-channel: ubuntu-24.04-${{ runner.arch }}-release
+          source-dir: ${{ github.workspace }}/brlcad
+          output-dir: ${{ runner.temp }}/bext_output
+          build-type: Release
+          artifact-token: ${{ secrets.BEXT_ARTIFACT_TOKEN }}
       - name: Directory setup
         run: cmake -E make_directory build_distcheck-in_src_dir
       - name: Configure
-        run: cmake -S brlcad -B build_distcheck-in_src_dir -G Ninja -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_DIR=${{ github.workspace }}/bext_output
+        run: cmake -S brlcad -B build_distcheck-in_src_dir -G Ninja -DCMAKE_BUILD_TYPE=Debug -DBRLCAD_EXT_DIR=${{ runner.temp }}/bext_output
       - name: Build
-        run: cmake --build build_distcheck-in_src_dir --config Release --target distcheck-in_src_dir
+        run: cmake --build build_distcheck-in_src_dir --config Debug --target distcheck-in_src_dir
       - name: Log
         if: always()
         run: cat build_distcheck-in_src_dir/distcheck-in_src_dir.log
-      - name: Debug if failure
-        if: failure()
-        uses: mxschmitt/action-tmate@v3
-

.github/workflows/linux_interactive.yml

@@ -69,12 +69,12 @@ jobs:
 
       - name: Configure
         run: |
-          export PATH=$ENV{GITHUB_WORKSPACE}:$PATH
+          export PATH=$GITHUB_WORKSPACE:$PATH
           cmake -S . -G Ninja -B build_linux -DBRLCAD_EXT_PARALLEL=1 -DBRLCAD_COMPONENTS=libged -DBRLCAD_EXTRADOCS=OFF
 
       - name: Build
         run: |
-          export PATH=$ENV{GITHUB_WORKSPACE}:$PATH
+          export PATH=$GITHUB_WORKSPACE:$PATH
           cmake --build build_linux --config Release --target check
 
       - name: Debugging - tmate session

.github/workflows/push.yml

@@ -23,7 +23,7 @@ jobs:
 
   linux:
     name: Ubuntu GCC
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     strategy:
       fail-fast: true
     env:
@@ -33,14 +33,6 @@ jobs:
       - name: Setup - CMake
         uses: lukka/get-cmake@latest
 
-      # Cache apt package downloads (not installed pkgs)
-      - name: Cache apt packages
-        uses: actions/cache@v4
-        with:
-          path: |
-            /var/cache/apt/archives
-          key: ${{ runner.os }}-apt-${{ hashFiles('.github/workflows/push.yml') }}
-
       # Install system dependencies
       - name: Install apt dependencies
         run: |
@@ -58,44 +50,20 @@ jobs:
           sudo apt-get install libgl-dev
           sudo apt-get install libinput-dev
 
-      # Prepare bext cache key
-      - name: Clone bext
-        run: git clone https://github.com/BRL-CAD/bext.git
-
-      - name: Get bext commit SHA
-        id: bext-sha
-        run: |
-          cd bext
-          echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
-
-      - name: Compute bext cache discriminator
-        id: cachekey
-        shell: bash
-        run: |
-          info="${{ steps.bext-sha.outputs.sha }}-$(uname -s)-$(uname -r)-$(gcc --version | head -n 1)"
-          echo "hash=$(echo -n "$info" | sha1sum | awk '{print $1}')" >> $GITHUB_OUTPUT
-
-      - name: Cache bext build outputs
-        id: cache-bext
-        uses: actions/cache@v4
-        with:
-          path: ${{ github.workspace }}/bext_output
-          key: ${{ runner.os }}-bext-${{ steps.cachekey.outputs.hash }}
-
-      - name: Build bext (if cache miss)
-        if: steps.cache-bext.outputs.cache-hit != 'true'
-        run: |
-          cmake -E make_directory bext_build
-          cmake -S bext -B bext_build -DCMAKE_BUILD_TYPE=Release -DENABLE_ALL=ON -DCMAKE_INSTALL_PREFIX=${{ github.workspace }}/bext_output
-          cmake --build bext_build --config Release -j 2
-          cmake -E rm -rf bext
-          cmake -E rm -rf bext_build
-
       - name: Checkout
         uses: actions/checkout@v6
         with:
           path: brlcad
 
+      - name: Prepare bext dependencies
+        uses: ./brlcad/.github/actions/prepare-bext
+        with:
+          platform-channel: ubuntu-24.04-${{ runner.arch }}-release
+          source-dir: ${{ github.workspace }}/brlcad
+          output-dir: ${{ runner.temp }}/bext_output
+          build-type: Release
+          artifact-token: ${{ secrets.BEXT_ARTIFACT_TOKEN }}
+
       - name: Directory setup
         run: |
           cmake -E make_directory ./build_linux
@@ -105,7 +73,7 @@ jobs:
       - name: Configure
         run: |
           export PATH=$GITHUB_WORKSPACE:$PATH
-          cmake -S brlcad -B build_linux -G Ninja -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_DIR=${{ github.workspace }}/bext_output -DBRLCAD_ENABLE_QT=ON
+          cmake -S brlcad -B build_linux -G Ninja -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_DIR=${{ runner.temp }}/bext_output -DBRLCAD_ENABLE_QT=ON
 
       - name: Build
         id: build_parallel
@@ -126,7 +94,7 @@ jobs:
   # repository integrity check and make sure we can build source archives.
   archives:
     name: Source Archives
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     needs: [linux]
     strategy:
       fail-fast: true
@@ -137,13 +105,6 @@ jobs:
       - name: Setup - CMake
         uses: lukka/get-cmake@latest
 
-      - name: Cache apt packages
-        uses: actions/cache@v4
-        with:
-          path: |
-            /var/cache/apt/archives
-          key: ${{ runner.os }}-apt-${{ hashFiles('.github/workflows/push.yml') }}
-
       # Install system dependencies - we do the full setup here, even though
       # source archives isn't intended to build the main BRL-CAD, in case
       # this check is the one where the bext dependency cache check gets a miss.
@@ -165,52 +126,83 @@ jobs:
           sudo apt-get install libgl-dev
           sudo apt-get install libinput-dev
 
-      - name: Clone bext
-        run: git clone https://github.com/BRL-CAD/bext.git
-
-      - name: Get bext commit SHA
-        id: bext-sha
-        run: |
-          cd bext
-          echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
-
-      - name: Compute bext cache discriminator
-        id: cachekey
-        shell: bash
-        run: |
-          info="${{ steps.bext-sha.outputs.sha }}-$(uname -s)-$(uname -r)-$(gcc --version | head -n 1)"
-          echo "hash=$(echo -n "$info" | sha1sum | awk '{print $1}')" >> $GITHUB_OUTPUT
-
-      - name: Cache bext build outputs
-        id: cache-bext
-        uses: actions/cache@v4
+      - name: Checkout
+        uses: actions/checkout@v6
         with:
-          path: ${{ github.workspace }}/bext_output
-          key: ${{ runner.os }}-bext-${{ steps.cachekey.outputs.hash }}
+          path: brlcad
 
-      - name: Build bext (if cache miss)
-        if: steps.cache-bext.outputs.cache-hit != 'true'
+      - name: Prepare bext dependencies
+        uses: ./brlcad/.github/actions/prepare-bext
+        with:
+          platform-channel: ubuntu-24.04-${{ runner.arch }}-release
+          source-dir: ${{ github.workspace }}/brlcad
+          output-dir: ${{ runner.temp }}/bext_output
+          build-type: Release
+          artifact-token: ${{ secrets.BEXT_ARTIFACT_TOKEN }}
+
+      - name: Build
         run: |
-          cmake -E make_directory bext_build
-          cmake -S bext -B bext_build -DCMAKE_BUILD_TYPE=Release -DENABLE_ALL=ON -DCMAKE_INSTALL_PREFIX=${{ github.workspace }}/bext_output
-          cmake --build bext_build --config Release -j2
-          rm -rf bext
-          rm -rf bext_build
+          cmake -E make_directory build_archives
+          cmake -S brlcad -B build_archives -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_PARALLEL=1 -DBRLCAD_EXT_DIR=${{ runner.temp }}/bext_output
+          cmake --build build_archives --config Release --target distcheck-source_archives
+
+  # A full bext build every time we push is too much, but we can exercise the
+  # basic bext mechanisms and also the BRLCAD_COMPONENTS subbuild at the same
+  # time if we do a local bext build of *just* the libbg subset of BRL-CAD.  If
+  # the COMPONENTS mechanism works as it should it won't trigger a full bext
+  # build, and we'll only be compiling what libbg needs.
+  componentbext:
+    name: BRLCAD_COMPONENTS
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+    env:
+      DEBIAN_FRONTEND: noninteractive
+    if: github.event_name == 'push'
+    steps:
+      - name: Setup - CMake
+        uses: lukka/get-cmake@latest
+
+      # Install system dependencies - we do the full setup here, even though
+      # source archives isn't intended to build the main BRL-CAD, in case
+      # this check is the one where the bext dependency cache check gets a miss.
+      # In that case, this check will have to build bext to proceed - and it will
+      # need the bext environment set up to do so.
+      - name: Install apt dependencies
+        run: |
+          sudo apt-get update
+          # Install X/OpenGL dev pkgs
+          sudo apt-get install xserver-xorg-dev libx11-dev libxi-dev libxext-dev libglu1-mesa-dev libfontconfig-dev
+          # Install tools
+          sudo apt-get install astyle re2c xsltproc libxml2-utils
+          # Install dependency dev pkgs
+          sudo apt-get install zlib1g-dev libpng-dev libjpeg-dev libtiff-dev libeigen3-dev libgdal-dev libassimp-dev libopencv-dev tcl-dev tk-dev
+          # Install XCB/OpenGL dev pkgs for Qt - see:
+          # https://wiki.qt.io/Building_Qt_6_from_Git
+          # https://doc.qt.io/qt-6/linux-requirements.html
+          sudo apt-get install libfontconfig1-dev libfreetype6-dev libx11-dev libx11-xcb-dev libxext-dev libxfixes-dev libxi-dev libxrender-dev libxcb1-dev libxcb-cursor-dev libxcb-glx0-dev libxcb-keysyms1-dev libxcb-image0-dev libxcb-shm0-dev libxcb-icccm4-dev libxcb-sync-dev libxcb-xfixes0-dev libxcb-shape0-dev libxcb-randr0-dev libxcb-render-util0-dev libxcb-util-dev libxcb-xinerama0-dev libxcb-xkb-dev libxcb-xinput-dev libxcb-xrm-dev libxkbcommon-dev libxkbcommon-x11-dev
+          sudo apt-get install libgl-dev
+          sudo apt-get install libinput-dev
 
       - name: Checkout
         uses: actions/checkout@v6
         with:
           path: brlcad
 
+      - name: Directory setup
+        run: |
+          cmake -E make_directory build_components
+          cmake -E make_directory $HOME/.cache
+          cmake -E make_directory $HOME/.cache/BRL-CAD
+
       - name: Build
         run: |
-          cmake -E make_directory build_archives
-          cmake -S brlcad -B build_archives -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_PARALLEL=1 -DBRLCAD_EXT_DIR=${{ github.workspace }}/bext_output
-          cmake --build build_archives --config Release --target distcheck-source_archives
+          cmake -S brlcad -B build_components -DCMAKE_BUILD_TYPE=Release -DBRLCAD_COMPONENTS=libbg
+          cmake --build build_components --config Release
 
   windows:
     name: MSVC - Ninja
-    runs-on: windows-latest
+    runs-on: windows-2025
     strategy:
       fail-fast: true
     if: github.event_name == 'push'
@@ -219,7 +211,7 @@ jobs:
         uses: lukka/get-cmake@latest
 
       - name: Add msbuild to PATH
-        uses: microsoft/setup-msbuild@v2
+        uses: microsoft/setup-msbuild@v3
 
       - name: Add cl.exe to PATH
         uses: ilammy/msvc-dev-cmd@v1
@@ -228,66 +220,27 @@ jobs:
         shell: pwsh
         run: Add-Content -Path $env:GITHUB_PATH -Value $env:GITHUB_WORKSPACE
 
-      - name: Clone bext
-        # Note - this will not check out any of the submodules unless we need
-        # them for building, so it should be a very small disk space hit.
-        # Consequently, we don't worry about deleting it unless we end up
-        # having to build it.  The bext source directory is not one of the
-        # cached directories, so a straight git clone is fine - no need to
-        # worry about colliding with a previous clone.
-        run: git clone https://github.com/BRL-CAD/bext.git
-
-      - name: Get bext commit SHA
-        id: bext-sha
-        shell: powershell
-        run: |
-          cd bext
-          echo "sha=$(git rev-parse HEAD)" >> $env:GITHUB_OUTPUT
-
-      - name: Compute bext cache discriminator
-        id: cachekey
-        shell: bash
-        run: |
-          clver=""
-          if command -v cl.exe &> /dev/null; then
-            clver="$(cl.exe 2>&1 | head -n 1)"
-          fi
-          info="${{ steps.bext-sha.outputs.sha }}-$(uname -s)-$(uname -r)-$clver"
-          echo "hash=$(echo -n "$info" | sha1sum | awk '{print $1}')" >> $GITHUB_OUTPUT
-
-      - name: Cache bext build outputs
-        id: cache-bext
-        uses: actions/cache@v4
-        with:
-          path: ${{ github.workspace }}\bext_output
-          key: windows-bext-${{ steps.cachekey.outputs.hash }}
-
-      - name: Build bext (if cache miss)
-        if: steps.cache-bext.outputs.cache-hit != 'true'
-        shell: powershell
-        run: |
-          cmake -E make_directory bext_build
-          cmake -S bext -B bext_build -DCMAKE_BUILD_TYPE=Release -DENABLE_ALL=ON -DCMAKE_INSTALL_PREFIX=${{ github.workspace }}\bext_output
-          cmake --build bext_build --config Release -j2
-          # If we have had to build, the submodules are populated and the build
-          # directory will have a lot in it.  We only need the build ouputs
-          # (bext_output) after this point, so clean up to save space for the
-          # main BRL-CAD build.
-          cmake -E rm -rf bext
-          cmake -E rm -rf bext_build
-
       - name: Checkout
         uses: actions/checkout@v6
         with:
           path: brlcad
 
+      - name: Prepare bext dependencies
+        uses: ./brlcad/.github/actions/prepare-bext
+        with:
+          platform-channel: windows-2025-${{ runner.arch }}-release
+          source-dir: ${{ github.workspace }}/brlcad
+          output-dir: ${{ runner.temp }}/bext_output
+          build-type: Release
+          artifact-token: ${{ secrets.BEXT_ARTIFACT_TOKEN }}
+
       - name: Build Directory setup
         run: cmake -E make_directory ./build_winninja
 
       - name: Configure
         shell: powershell
         run: |
-          cmake -S brlcad -B build_winninja -G Ninja -DCMAKE_C_COMPILER="cl.exe" -DCMAKE_CXX_COMPILER="cl.exe" -DBRLCAD_EXT_DIR=${{ github.workspace }}\bext_output -DCMAKE_BUILD_TYPE=Release -DBRLCAD_ENABLE_QT=ON
+          cmake -S brlcad -B build_winninja -G Ninja -DCMAKE_C_COMPILER="cl.exe" -DCMAKE_CXX_COMPILER="cl.exe" -DBRLCAD_EXT_DIR=${{ runner.temp }}\bext_output -DCMAKE_BUILD_TYPE=Release -DBRLCAD_ENABLE_QT=ON
 
       - name: Build
         id: build_parallel
@@ -319,7 +272,7 @@ jobs:
   windows_std_tools:
     name: MSVC - Standard Tools
     needs: [windows]
-    runs-on: windows-latest
+    runs-on: windows-2025
     strategy:
       fail-fast: true
     if: github.event_name == 'push'
@@ -328,71 +281,25 @@ jobs:
         uses: lukka/get-cmake@latest
 
       - name: Add msbuild to PATH
-        uses: microsoft/setup-msbuild@v2
+        uses: microsoft/setup-msbuild@v3
 
       - name: Add cl.exe to PATH
         uses: ilammy/msvc-dev-cmd@v1
 
-      - name: Clone bext
-        # Note - this will not check out any of the submodules unless we need
-        # them for building, so it should be a very small disk space hit.
-        # Consequently, we don't worry about deleting it unless we end up
-        # having to build it.  The bext source directory is not one of the
-        # cached directories, so a straight git clone is fine - no need to
-        # worry about colliding with a previous clone.
-        #
-        # In theory we could rely on the windows Ninja test for this, since we
-        # depend on it, but we define each test to be potentially stand-alone
-        # in case we end up removing the other windows test(s) for any reason.
-        run: git clone https://github.com/BRL-CAD/bext.git
-
-      - name: Get bext commit SHA
-        id: bext-sha
-        shell: pwsh
-        run: |
-          cd bext
-          echo "sha=$(git rev-parse HEAD)" >> $env:GITHUB_OUTPUT
-
-      - name: Compute bext cache discriminator
-        id: cachekey
-        shell: bash
-        run: |
-          clver=""
-          if command -v cl.exe &> /dev/null; then
-            clver="$(cl.exe 2>&1 | head -n 1)"
-          fi
-          info="${{ steps.bext-sha.outputs.sha }}-$(uname -s)-$(uname -r)-$clver"
-          echo "hash=$(echo -n "$info" | sha1sum | awk '{print $1}')" >> $GITHUB_OUTPUT
-
-      - name: Cache bext build outputs
-        id: cache-bext
-        uses: actions/cache@v4
-        with:
-          path: ${{ github.workspace }}\bext_output
-          key: windows-bext-${{ steps.cachekey.outputs.hash }}
-
-      - name: Build bext (if cache miss)
-        # Note - most of windows_std_tools builds using cmd and avoids ninja,
-        # but for the bext build if we need to do it) we want to match the
-        # behavior of the ninja build so we have consistent inputs.
-        if: steps.cache-bext.outputs.cache-hit != 'true'
-        shell: powershell
-        run: |
-          cmake -E make_directory bext_build
-          cmake -S bext -B bext_build -DCMAKE_BUILD_TYPE=Release -DENABLE_ALL=ON -DCMAKE_INSTALL_PREFIX=${{ github.workspace }}\bext_output
-          cmake --build bext_build --config Release -j2
-          # If we have had to build, the submodules are populated and the build
-          # directory will have a lot in it.  We only need the build ouputs
-          # (bext_output) after this point, so clean up to save space for the
-          # main BRL-CAD build.
-          cmake -E rm -rf bext
-          cmake -E rm -rf bext_build
-
       - name: Checkout
         uses: actions/checkout@v6
         with:
           path: brlcad
 
+      - name: Prepare bext dependencies
+        uses: ./brlcad/.github/actions/prepare-bext
+        with:
+          platform-channel: windows-2025-${{ runner.arch }}-release
+          source-dir: ${{ github.workspace }}/brlcad
+          output-dir: ${{ runner.temp }}/bext_output
+          build-type: Release
+          artifact-token: ${{ secrets.BEXT_ARTIFACT_TOKEN }}
+
       - name: Build Directory setup
         run: |
           cmake -E make_directory ./build_winstd
@@ -413,7 +320,7 @@ jobs:
       - name: Configure
         shell: cmd
         run: |
-          cmake -S brlcad -B build_winstd -DBRLCAD_EXT_PARALLEL=1 -DBRLCAD_BUNDLED_LIBS=Bundled -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_DIR=%GITHUB_WORKSPACE%\bext_output -DBRLCAD_ENABLE_QT=ON -DBRLCAD_CONFIG_PROBE_DIAGNOSTICS=ON -DBRLCAD_PROBE_SNAPSHOT_FILE=%GITHUB_WORKSPACE%\build_winstd\parallel-probes.txt
+          cmake -S brlcad -B build_winstd -DBRLCAD_EXT_PARALLEL=1 -DBRLCAD_BUNDLED_LIBS=Bundled -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_DIR=%RUNNER_TEMP%\bext_output -DBRLCAD_ENABLE_QT=ON -DBRLCAD_CONFIG_PROBE_DIAGNOSTICS=ON -DBRLCAD_PROBE_SNAPSHOT_FILE=%GITHUB_WORKSPACE%\build_winstd\parallel-probes.txt
 
       - name: Configure probe diagnostics
         if: always()
@@ -488,48 +395,20 @@ jobs:
         run: |
           brew install xquartz --cask
 
-      - name: Clone bext
-        run: git clone https://github.com/BRL-CAD/bext.git
-
-      - name: Get bext commit SHA
-        id: bext-sha
-        run: |
-          cd bext
-          echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
-
-      - name: Compute bext cache discriminator
-        id: cachekey
-        shell: bash
-        run: |
-          xcodever="$(xcodebuild -version | head -n 1 | awk '{print $2}')"
-          clangver="$(clang --version | head -n 1)"
-          info="${{ steps.bext-sha.outputs.sha }}-$(uname -s)-$(uname -r)-$xcodever-$clangver"
-          echo "hash=$(echo -n "$info" | sha1sum | awk '{print $1}')" >> $GITHUB_OUTPUT
-
-      - name: Cache bext build outputs
-        id: cache-bext
-        uses: actions/cache@v4
-        with:
-          path: ${{ github.workspace }}/bext_output
-          key: macos-bext-${{ steps.cachekey.outputs.hash }}
-
-      - name: Build bext (if cache miss)
-        if: steps.cache-bext.outputs.cache-hit != 'true'
-        run: |
-          cmake -E make_directory bext_build
-          export CC=clang
-          export CXX=clang++
-          # Right now on OSX we need ENABLE_ALL, because Mac system Tcl/Tk won't work
-          cmake -S bext -B bext_build -DENABLE_ALL=ON -DCMAKE_INSTALL_PREFIX=${{ github.workspace }}/bext_output -DCMAKE_BUILD_TYPE=Release
-          cmake --build bext_build -j 2
-          cmake -E rm -rf bext
-          cmake -E rm -rf bext_build
-
       - name: Checkout
         uses: actions/checkout@v6
         with:
           path: brlcad
 
+      - name: Prepare bext dependencies
+        uses: ./brlcad/.github/actions/prepare-bext
+        with:
+          platform-channel: macos-14-${{ runner.arch }}-release
+          source-dir: ${{ github.workspace }}/brlcad
+          output-dir: ${{ runner.temp }}/bext_output
+          build-type: Release
+          artifact-token: ${{ secrets.BEXT_ARTIFACT_TOKEN }}
+
       - name: Build Directory setup
         run: |
           cmake -E make_directory build_osx
@@ -541,7 +420,7 @@ jobs:
           export PATH=$GITHUB_WORKSPACE:$PATH
           export CC=clang
           export CXX=clang++
-          cmake -S brlcad -B build_osx -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_DIR=${{ github.workspace }}/bext_output -DBRLCAD_ENABLE_QT=ON
+          cmake -S brlcad -B build_osx -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_DIR=${{ runner.temp }}/bext_output -DBRLCAD_ENABLE_QT=ON
 
       - name: Build
         id: build_parallel

.github/workflows/scheduled.yml

@@ -25,19 +25,10 @@ jobs:
       fail-fast: true
     env:
       DEBIAN_FRONTEND: noninteractive
-    if: github.event_name == 'schedule'
     steps:
       - name: Setup - CMake
         uses: lukka/get-cmake@latest
 
-      # Cache apt package downloads (not installed pkgs)
-      - name: Cache apt packages
-        uses: actions/cache@v4
-        with:
-          path: |
-            /var/cache/apt/archives
-          key: ${{ runner.os }}-apt-${{ hashFiles('.github/workflows/check.yml') }}
-
       # Install system dependencies
       - name: Install apt dependencies
         run: |
@@ -83,13 +74,13 @@ jobs:
     runs-on: windows-latest
     strategy:
       fail-fast: true
-    if: github.event_name == 'schedule'
+    if: ${{ !cancelled() }}
     steps:
       - name: Setup - CMake
         uses: lukka/get-cmake@latest
 
       - name: Add msbuild to PATH
-        uses: microsoft/setup-msbuild@v2
+        uses: microsoft/setup-msbuild@v3
 
       - name: Add cl.exe to PATH
         uses: ilammy/msvc-dev-cmd@v1
@@ -135,13 +126,13 @@ jobs:
     runs-on: windows-latest
     strategy:
       fail-fast: true
-    if: github.event_name == 'schedule'
+    if: ${{ !cancelled() }}
     steps:
       - name: Setup - CMake
         uses: lukka/get-cmake@latest
 
       - name: Add msbuild to PATH
-        uses: microsoft/setup-msbuild@v2
+        uses: microsoft/setup-msbuild@v3
 
       - name: Add cl.exe to PATH
         uses: ilammy/msvc-dev-cmd@v1
@@ -166,7 +157,7 @@ jobs:
           where ninja
           where cl.exe
           where msbuild
-          cmake -S brlcad -B build_winstd -DBRLCAD_EXT_PARALLEL=1 -DBRLCAD_BUNDLED_LIBS=Bundled -DBRLCAD_EXT_PARALLEL=1 -DCMAKE_BUILD_TYPE=Release -DBRLCAD_BEXT_CLEANUP=ON -DBRLCAD_ENABLE_QT=ON
+          cmake -S brlcad -B build_winstd -DBRLCAD_EXT_PARALLEL=1 -DBRLCAD_BUNDLED_LIBS=Bundled -DCMAKE_BUILD_TYPE=Release -DBRLCAD_BEXT_CLEANUP=ON -DBRLCAD_ENABLE_QT=ON
 
       - name: Build
         shell: cmd
@@ -189,7 +180,7 @@ jobs:
     runs-on: macos-14
     strategy:
       fail-fast: true
-    if: github.event_name == 'schedule'
+    if: ${{ !cancelled() }}
     steps:
       - name: Setup - CMake
         uses: lukka/get-cmake@latest
@@ -234,23 +225,16 @@ jobs:
   linux_static:
     name: Clang Static Analyser
     needs: [linux_bext]
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     strategy:
       fail-fast: true
     env:
       DEBIAN_FRONTEND: noninteractive
-    if: github.event_name == 'schedule' && github.ref == 'refs/heads/main'
+    if: ${{ !cancelled() && github.ref == 'refs/heads/main' }}
     steps:
       - name: Setup - CMake
         uses: lukka/get-cmake@latest
 
-      - name: Cache apt packages
-        uses: actions/cache@v4
-        with:
-          path: |
-            /var/cache/apt/archives
-          key: ${{ runner.os }}-apt-${{ hashFiles('.github/workflows/check.yml') }}
-
      # Setup hint from https://github.com/darktable-org/rawspeed/blob/develop/.github/workflows/ci-static-analysis.yml
       - name: Clang Static Analyzer Setup
         run: |
@@ -269,43 +253,20 @@ jobs:
           sudo apt-get install libgl-dev
           sudo apt-get install libinput-dev          # Cleanup
 
-      - name: Clone bext
-        run: git clone https://github.com/BRL-CAD/bext.git
-
-      - name: Get bext commit SHA
-        id: bext-sha
-        run: |
-          cd bext
-          echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
-
-      - name: Compute bext cache discriminator
-        id: cachekey
-        shell: bash
-        run: |
-          info="${{ steps.bext-sha.outputs.sha }}-$(uname -s)-$(uname -r)-$(gcc --version | head -n 1)"
-          echo "hash=$(echo -n "$info" | sha1sum | awk '{print $1}')" >> $GITHUB_OUTPUT
-
-      - name: Cache bext build outputs
-        id: cache-bext
-        uses: actions/cache@v4
-        with:
-          path: ${{ github.workspace }}/bext_output
-          key: ${{ runner.os }}-bext-${{ steps.cachekey.outputs.hash }}
-
-      - name: Build bext (if cache miss)
-        if: steps.cache-bext.outputs.cache-hit != 'true'
-        run: |
-          cmake -E make_directory bext_build
-          cmake -S bext -B bext_build -DCMAKE_BUILD_TYPE=Release -DENABLE_ALL=ON -DCMAKE_INSTALL_PREFIX=${{ github.workspace }}/bext_output
-          cmake --build bext_build --config Release -j 2
-          cmake -E rm -rf bext
-          cmake -E rm -rf bext_build
-
       - name: Checkout
         uses: actions/checkout@v6
         with:
           path: brlcad
 
+      - name: Prepare bext dependencies
+        uses: ./brlcad/.github/actions/prepare-bext
+        with:
+          platform-channel: ubuntu-24.04-${{ runner.arch }}-release
+          source-dir: ${{ github.workspace }}/brlcad
+          output-dir: ${{ runner.temp }}/bext_output
+          build-type: Release
+          artifact-token: ${{ secrets.BEXT_ARTIFACT_TOKEN }}
+
       - name: Directory setup
         run: |
           cmake -E make_directory build_clangstatic
@@ -314,6 +275,8 @@ jobs:
         working-directory: ${{ github.workspace }}/brlcad
 
       - name: Run Analyzer
+        env:
+          BRLCAD_EXT_DIR: ${{ runner.temp }}/bext_output
         run: |
           export PATH=$GITHUB_WORKSPACE:/usr/share/clang/scan-build-18/bin:/usr/share/clang/scan-build-18/libexec:$PATH
           cp $GITHUB_WORKSPACE/brlcad/misc/clang-static-analyzer-run.sh .
@@ -332,28 +295,21 @@ jobs:
   linux_cov:
     name: LCOV Coverage testing
     needs: [linux_bext]
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     strategy:
       fail-fast: true
     env:
       DEBIAN_FRONTEND: noninteractive
-    if: github.event_name == 'schedule' && github.ref == 'refs/heads/main'
+    if: ${{ !cancelled() && github.ref == 'refs/heads/main' }}
     steps:
       - name: Setup - CMake
         uses: lukka/get-cmake@latest
 
-      - name: Cache apt packages
-        uses: actions/cache@v4
-        with:
-          path: |
-            /var/cache/apt/archives
-          key: ${{ runner.os }}-apt-${{ hashFiles('.github/workflows/check.yml') }}
-
       - name: Setup - System
         run: |
           sudo apt-get update
           # Get the lcov tool and its dependencies
-          sudo apt-get install lcov
+          sudo apt-get install lcov gdb
           # Install X/OpenGL dev pkgs
           sudo apt-get install xserver-xorg-dev libx11-dev libxi-dev libxext-dev libglu1-mesa-dev libfontconfig-dev
           # Install tools
@@ -367,43 +323,20 @@ jobs:
           sudo apt-get install libgl-dev
           sudo apt-get install libinput-dev
 
-      - name: Clone bext
-        run: git clone https://github.com/BRL-CAD/bext.git
-
-      - name: Get bext commit SHA
-        id: bext-sha
-        run: |
-          cd bext
-          echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
-
-      - name: Compute bext cache discriminator
-        id: cachekey
-        shell: bash
-        run: |
-          info="${{ steps.bext-sha.outputs.sha }}-$(uname -s)-$(uname -r)-$(gcc --version | head -n 1)"
-          echo "hash=$(echo -n "$info" | sha1sum | awk '{print $1}')" >> $GITHUB_OUTPUT
-
-      - name: Cache bext build outputs
-        id: cache-bext
-        uses: actions/cache@v4
-        with:
-          path: ${{ github.workspace }}/bext_output
-          key: ${{ runner.os }}-bext-${{ steps.cachekey.outputs.hash }}
-
-      - name: Build bext (if cache miss)
-        if: steps.cache-bext.outputs.cache-hit != 'true'
-        run: |
-          cmake -E make_directory bext_build
-          cmake -S bext -B bext_build -DCMAKE_BUILD_TYPE=Release -DENABLE_ALL=ON -DCMAKE_INSTALL_PREFIX=${{ github.workspace }}/bext_output
-          cmake --build bext_build --config Release -j 2
-          cmake -E rm -rf bext
-          cmake -E rm -rf bext_build
-
       - name: Checkout
         uses: actions/checkout@v6
         with:
           path: brlcad
 
+      - name: Prepare bext dependencies
+        uses: ./brlcad/.github/actions/prepare-bext
+        with:
+          platform-channel: ubuntu-24.04-${{ runner.arch }}-release
+          source-dir: ${{ github.workspace }}/brlcad
+          output-dir: ${{ runner.temp }}/bext_output
+          build-type: Release
+          artifact-token: ${{ secrets.BEXT_ARTIFACT_TOKEN }}
+
       - name: Directory setup
         run: |
           cmake -E make_directory build_lcov
@@ -413,24 +346,46 @@ jobs:
       - name: Configure
         run: |
           export PATH=$GITHUB_WORKSPACE:$PATH
-          cmake -S brlcad -B build_lcov -DBRLCAD_ENABLE_COVERAGE=ON -DCMAKE_BUILD_TYPE=Debug -DBRLCAD_EXT_DIR=${{ github.workspace }}/bext_output -DBRLCAD_ENABLE_QT=ON
+          cmake -S brlcad -B build_lcov -DBRLCAD_ENABLE_COVERAGE=ON -DCMAKE_BUILD_TYPE=Debug -DBRLCAD_EXT_DIR=${{ runner.temp }}/bext_output -DBRLCAD_ENABLE_QT=ON
 
       - name: Build
+        id: build_parallel
         run: |
           export PATH=$GITHUB_WORKSPACE:$PATH
           cmake --build build_lcov -j2
+        continue-on-error: true
 
       - name: Build (serial for diagnostics)
         if: steps.build_parallel.outcome == 'failure'
         run: |
           export PATH=$GITHUB_WORKSPACE:$PATH
           cmake --build build_lcov -j1
-        continue-on-error: true
 
-      - name: Run Coverage Test
+      - name: Run Tests
+        id: coverage_tests
         run: |
           find . -name '*.gcda' -exec rm {} \;
-          make check
+          cmake --build . --target check
+        working-directory: ${{ github.workspace }}/build_lcov
+
+      - name: Diagnose failed annotation test
+        if: failure() && steps.coverage_tests.outcome == 'failure'
+        continue-on-error: true
+        run: |
+          set +e
+          ctest -R '^rt_datum_annot_semantics$' -VV
+          cat Testing/Temporary/LastTest.log
+          if command -v gdb >/dev/null 2>&1; then
+            gdb --quiet --batch \
+              -ex 'set pagination off' \
+              -ex run \
+              -ex 'thread apply all bt full' \
+              --args ./src/librt/tests/rt_datum_annot_semantics
+          fi
+        working-directory: ${{ github.workspace }}/build_lcov
+
+      - name: Capture Coverage
+        run: |
           lcov --capture --directory . --output-file coverage.info
           lcov -r coverage.info \*\/bext_output\/\* > coverage-2.info
           lcov -r coverage-2.info \/usr\/\* > coverage_cad.info

.gitignore

@@ -36,5 +36,6 @@ CMakeLists.txt.user
 
 # Misc
 .clang-format
+*__pycache__*
 
 

AGENTS.md

@@ -0,0 +1,32 @@
+# Code Quality Standards
+
+Write code as a senior engineer would for long-term maintenance. These are non-negotiable defaults, not suggestions to apply when asked.
+
+## Principles
+
+- **DRY.** Extract duplicate logic. Refactor. Once and only once.
+- **Minimize surprises.** Preserve existing style and conventions. Test when you can.
+- **No magic values.** Use named constants, enums, or configuration. Every literal needs justification.
+- **Minimize scope.** Prefer tightest scope that works - local variables, parameters, encapsulation. Broader scope needs justification.
+- **No dead code.** Delete commented-out code, unused variables, unreachable branches. Version control remembers.
+- **Comments explain why.** Document intent, constraints, and non-obvious decisions. Use "what" summaries only for complex or non-obvious algorithms. If routine code needs a comment to explain it, the code should be clearer.
+- **Clean up what you touch.** Improve code you are changing: rename unclear variables, extract functions, simplify conditionals. Do not mix unrelated cleanup with logic changes - separate concerns, separate commits.
+- **Handle errors deliberately.** Whether failing loudly or quietly, make it an intentional choice. No accidental swallowing.
+- **YAGNI.** Do not add speculative abstractions, unused parameters, or unplanned extension points. Build what is needed now. Refactor when requirements actually change.
+- **Perfection is when there is nothing left to take away.** Prefer reduction over addition, simpler is better. Too clever to debug easily is too clever.
+
+## Before Finishing
+
+Review your changes for code smells, duplicated logic, hardcoded values, overly broad scope, unclear names, missing error handling, unnecessary complexity, etc. Fix issues in the same pass - do not defer cleanup.
+
+## Git
+
+Never commit without permission (ask every time).  Never push to remote.  Never use `codex`, `chatgpt`, `openai`, `gemini`, `antigravity`, `copilot`, `claude`, `llm`, `ai`, or similar terms in branch names, tag names, commits, PRs, comments, and other metadata.  Do not add generated-by notices or otherwise indicate authorship unless user explicitly requests.  Do not include specific machine information - full file system paths, machine names, IP addresses, or other identifiable information in commit messages, code, comments or documentation.
+
+## Repository Coding Conventions
+
+The HACKING file in the root of the source tree defines coding conventions specific to BRL-CAD, including versions of common functions that are used in our code base instead of raw standard functions.  Review this file before writing code so your changes and additions adhere to BRL-CAD standards.
+
+BRL-CAD code should typically use our ZERO and EQUAL macros rather than raw floating-point equality comparisons to avoid Werror=float-equal compilation failures on expressions such as a == 0.0 (should be ZERO(a)) or b != c (should be !EQUAL(b, c)).
+
+When completing a code change (not for intermediate iterations, but when preparing to hand back a finalized change) use our regress-repository and regress-licenses build targets to check that the result satisfies our internal checkers.

AUTHORS

@@ -393,6 +393,11 @@ Sieu, Jeff
 2017 December
 Open Source (GCI)
 
+Baker, Josh
+nicknames joshbaker22
+2023 August
+U.S. Army Research Laboratory
+
 
 CODE CONTRIBUTIONS
 ------------------
@@ -1085,6 +1090,15 @@ Reel, Samuel (Sammy)
 2024 March
 Texas A&M University
 
+Rupesh
+nicknames rupes, rupeshca007
+2026 March
+Open Source
+
+nicknames laithaldaeef
+2026 March
+Open Source
+
 
 SPECIAL THANKS
 --------------

BUGS

@@ -21,25 +21,9 @@ Recent Bugs
   Something is concatenating EXEPATH and/or fbserv silently fails with
   return codes (e.g., when not specifying -F, only giving the port.)
 
-* rt -H hypersample, -J jitter, and -j# for sub-grid-mode assumes a
-  framebuffer, causing pix data to get written to the -o file (e.g.,
-  even with -o file.png).  See view_pixel() near src/rt/view.c:472 for
-  problem area with -j but there are likely call sites..  Need to
-  scrub all fb_write() and ideally make this a non-issue via icv API.
-
-* obj-g and gcv converters choke and crash on obj with unnamed g line.
-  spec wording on whether that's valid is unclear, but encountered in
-  wild.
-
 * recursive bu_parallel() failure, tbd whether cpp11 or pthread impl,
   likely because IDs are exceeding MAX_PSW, causing mayhem and chaos.
 
-* Archer was observed to mangle the structure of a comb tree when assigning
-  a color from the dialog panel.  MGED is able to assign the color fine,
-  so there appears to be something specific to Archer's comb tree handling
-  that is flawed.  Not all combs are handled incorrectly. Issue appears to
-  be long standing - observed as far back as at least version 7.28.
-
 * rtcheck_handler_cleanup() throws 'invalid handle specified' on Windows
   in closing of STDOUT (see FIXME comment). Does not affect normal running,
   but a debug build complains.
@@ -68,20 +52,12 @@ Recent Bugs
   Backtrace indicates write buffer is full, likely because no output
   is going to terminal. (Observed on Mac)
 
-* gcv on a glTF file (at least a binary .glb) crashes hard with a NULL
-  pointer bomb (workaround: gltf-g succeeds albeit incomplete
-  conversion).  Takes out the entire Terminal app on Mac for some
-  reason (consistently).
-
 * Running"mged -c test.g" exits automatically on default prompt:
   ...
   Create new database (y|n)[n]? 
   Warning: no database is currently open!
   morrison@Miniagua .build %
 
-* TGC tess fails when we have a near-zero c axis and a larger d
-  axis, or vice versa.
-
 * MGED crashes trying to open the repository file
   doc/docbook/resources/other/standard/xsl/images/important.tif
   It is mis-identified as a v4 .g file due to the file header's
@@ -102,12 +78,6 @@ Recent Bugs
   > e -S -m1 boxes.r
   box1 is not drawn
 
-* When run inside mged, invalid syntax reported on "gqa -p prefix"
-  despite it being documented as the correct form (and working outside
-  mged).  specifying gqa -pprefix appears to be workaround, though
-  unintuitive.  specifying gqa -p"" annoyingly outputs ""exp_air.plot3
-  with quotes embedded in the name.
-
 * raytracing a revolved sketch seems to work fine, but rtarea and gqa
   seem to be crashing on that same revolve.  curiously, the brep
   revolve from the csgbrep proc-db has the same failure as well as the
@@ -124,11 +94,6 @@ Recent Bugs
 
 * killtree / crashes
 
-* killtree reports spurious db_lookup failures saying object does not
-  exist as it previously deleted it.  should keep track of what it
-  deletes to not output spuriously, or (better) delete transactionally
-  so it only attempts to lookup and delete once per object.
-
 * object names with a / or \ in them make ls or underlying directory
   parsing logic display them incorrectly.
 
@@ -147,12 +112,6 @@ Recent Bugs
 * apparently all four BRL-CAD Tutorial Series volumes are missing from
   our bibliography...
 
-* Tessellating an ETO with a normal tolerance results in stack
-  smashing due to bad logic in recursive algorithm: set norm 2;
-  facetize my.eto my.bot;. Observed infinite recursion in both
-  make_ellipse4() in eto.c and (after adding max recursion test) in
-  paint_face() in manif.c:190
-
 * mater -d information stored in the .g file doesn't survive a
   garbage collection operation.
 
@@ -168,16 +127,10 @@ Recent Bugs
   still being displayed.  this causes 'rt' to fly into an infinite
   loop, presumably trying to increment rays from the eye position.
 
-* icv dpix support is not cross-platform (it writes out native, reads
-  in assuming same encoding).  regression tests fail on big endian.
-
 * creating an object with a slashes in the name (e.g., cp foo foo/R)
   results in an object that cannot be deleted/renamed.  bad behavior
   presumably extends to any name with path separators.
 
-* rtsil uses fixed hit and miss pixel values and does not provide
-  foreground or background color options.
-
 * If we draw any form, then trace it using rt, then change of database
   (by clicking file>open and selecting another database), badness
   ensues.  One report has quitting the rt window causing a segfault.
@@ -191,15 +144,6 @@ Recent Bugs
   in ann3.s annot 0 0 0 1 10 10 3 1
   # using numbers for a label results in no label
 
-* make eto eto
-  tol norm 1
-  facetize eto.bot eto
-  [crashes due to excessive recursion]
-
-* crash in rt_bot_xform() due to a bot being marked as having face
-  normals, but didn't.  bot probably written wrong via conversion
-  to/from obj or asc.  found importing teapot.
-
 * rtedge with perspective is wrong.  it fills in nearly entire faces,
   vertically in particular.  it's worse on small sized renders, and
   gets better the larger the render size (indicating there's some
@@ -227,13 +171,6 @@ Recent Bugs
 * Recursive submodel predictably goes infinite, need stack-based
   db_walk_tree(): mged> in submodel submodel submodel grid test.g
 
-* running rt -s20 -F file.pix ... does not result in an 20x20 image
-  being written out.  it ends up being 512x512.
-
-* running rt -C255/0/0 -o file.pix ... does not result in the
-  background color getting used.  It does work with -F file.pix, going
-  through libfb instead of libicv.
-
 * ogl display manager and framebuffer are creating windows with
   transparent backgrounds (the glClear color is not being drawn) on
   Linux.  Presumably a driver-related issue, alpha channel, or expose
@@ -242,9 +179,6 @@ Recent Bugs
   private memory -- looks like private memory is not initialized
   (observed on Mac 10.6, Windows, and Ubuntu Linux using 7.26).
 
-* pixdiff on Windows is reporting no differences with a pair of files
-  that pixcmp can see differences in.
-
 * fblabel seems quite busted, at least talking to a /dev/X fbserv, in
   that it only draws the first character and eventually displays
   rem_read() failures when run in -d debug mode.
@@ -253,12 +187,6 @@ Recent Bugs
   after doing an overlay render.  it does draw, though, as confirmed
   by a forced fb-fb refresh.
 
-* pixborder doesn't account for an edge case where the right edge of
-  an image is expected to be colored (except for one pixel on the top
-  edge).  Example:
-
-  pixborder -b "255 0 0" -t "255 255 255" < pix/moss.pix | pix-fb
-
 * typing 'comb -f -r assembly_name' shuts down mged with the error:
   ERROR: bad pointer 0000000000B4CA50: s/b bu_external(x768dbbd0), was bu_vls(x89333bbb), file ..\..\..\brlcad_src\src\libbu\parse.c, line 2443"
   And on the mged command line:
@@ -272,11 +200,6 @@ Recent Bugs
 * wgl framebuffer is not lingering on windows (regardless of using
   wgll or default) when it should
 
-* calling "attr set obj key value" should always result in key getting
-  set to value, no matter what, as it is the lowest-level attribute
-  management interface and what the command (correctly) documents.
-  example demonstrated to not work was: attr set obj rgb 123/123/123
-
 * report of LIBBU not working when accessed by a multithreaded
   application on Windows.  reportedly due to some problem with the
   debug memory queue.
@@ -324,12 +247,6 @@ Recent Bugs
   book-keeping is fuxored or the db_lookup is returning NULL (or isn't
   yet performed).
 
-* src/librt/primitives/bot/g_bot_include.c:rt_bot_bbox() routine isn't
-  calculating the bbox correctly
-
-* rtxray crashes if you specify a -o *.bw output file due to
-  assumptions in the rt front-end that all output files are .pix
-
 * encountered a crash during rtarea on a (default) facetized version
   of the hyp from the proc-db csgbrep tool.
 
@@ -344,9 +261,6 @@ Recent Bugs
 * torus with a near zero inner diameter results in zero-length edges
   during tessellation.
 
-* bu_log() with a width specifier does not align like printf().
-  Example: bu_log("%24s", str);
-
 * report that "keep" sometimes results in a .g file with unknown units;
   dbconcat also is reported to set the units to unknown if concatting
   a file with unknown units.
@@ -374,10 +288,6 @@ Recent Bugs
 
 * rt -i -s4096 -H16 -F/dev/null boolean-ops.g all
 
-* asc2g of a .asc file containing the first line as a "#" comment
-  results in a bu_malloc(0) bomb.  comment lines should be valid in
-  .asc files.
-
 * compilation reportedly fails when building Tcl if the path to the
   source directory includes a space.
 
@@ -502,11 +412,6 @@ Recent Bugs
 * running 'keep' on too many objects (hundreds is causing a usage
   statement (and not doing the keep)
 
-* rtwizard won't display a line overlay if you line object is obscured
-  by another.  Example being to display a vehicle as ghost, crew as
-  solid, and crew as line.  confirmed even when using the other line
-  occlusion settings.
-
 * fbserv is receiving image data very slowly if the framebuffer is a
   remote X24 interface.  could reproduce on mac with the following:
 
@@ -566,9 +471,6 @@ Recent Bugs
   ubuntu linux.  key events go to the command window even with the
   graphics window has focus.
 
-* MGED File->Preferences->Fonts results in error "named font "button
-  _font" doesn't exist on Linux.
-
 * mged tab-completion doesn't work if the object names have spaces
 
 * Open dialog in MGED seems rather busted for scrolling and selection
@@ -606,13 +508,6 @@ Recent Bugs
 * dsp primitive is going into what seems to be an unbounded memory
   allocation loop during prep, inside dsp_layers().
 
-* libfb cannot utilize standard output/error "device" files without
-  path trickery.  it recognizes the /dev/ prefix and presumes it's a
-  libfb device instead of a filesystem device.
-
-   OK: rt -F/./dev/stdout
-  BAD: rt -F/dev/stdout
-
 * libfb cannot open a file descriptor when piping/redirecting output.
 
    OK: rt -F/./dev/stdout moss.g all.g
@@ -635,8 +530,6 @@ Recent Bugs
 * triangulation of some pipe in toyjeep.g fails (rather reliably) on
   some given bend.  fails in nmg_triangulate model().
 
-* fbhelp sends some of the output to stdout and some to stderr...
-
 * debugbu 2 immediately reports a bu_vls_free() error.. apparently
   been a problem since 4.5 days.  this occurs because
   bu_memdebug_add() is not called unless memory checking is enabled
@@ -653,9 +546,6 @@ Recent Bugs
 
 * Create menu.. create "part" boo hiss..
 
-* wavelet isn't working correctly on a simple image decomposition &
-  reconstruction.
-
 * fbed is looking for /usr/lib/vfont/nonie.r.12
 
 * mged doesn't check if html_dir does not exist when searching for
@@ -675,11 +565,6 @@ Recent Bugs
 
 * concave arbs give correct wireframe but do not raytrace correctly.
 
-* rtwizard/rtedge creates incorrect "fuzzy" edge overlay when creating
-  a "Ghost Image with Insert and Lines" that includes a light source
-  and object close to surface (e.g. moss.g; select plane, light, and
-  cone for ghost; select cone for insert and lines.)
-
 * mged's solid illuminate doesn't work when Lighting is turned on
 
 * raytrace of zoomed images (e.g., -s64) doesn't work for if_X24
@@ -721,9 +606,6 @@ Recent Bugs
 * sketches extruded with non-square AB vectors results in inner sketch
   components not getting scaled properly.
 
-* rtcheck is ignoring fastgen tagged geometry since no multioverlap
-  handler is set.
-
 * bot-bldxf fails in db_walk_tree(), interface may have changed
 
 

CMakeLists.txt

@@ -231,7 +231,7 @@ set(CMAKE_FIND_USE_PACKAGE_REGISTRY FALSE)
 # Prepare to manage and build BRL-CAD's external dependencies. Specifies a
 # specific commit hash to use in the 'bext' repository.
 include(BRLCAD_ExternalDeps)
-brlcad_bext_init(4f151ba7f3afdc14d66570e9cb322a5bab6ba293)
+brlcad_bext_init(12115e6c5922e2db27a9b88e00dd714af5315f69)
 
 #---------------------------------------------------------------------
 # Define various utilities.
@@ -930,7 +930,228 @@ _brlcad_srccompile_probe(HAVE_FLATTEN_ATTRIBUTE
 # serially).
 _brlcad_run_probe_batch(SRCCOMPILE)
 
-# Second flag-batch pre-warm (optimization, sanitizer and warning flags).
+# Return compiler flags to try, in preference order, for the selected LTO
+# mode.  GCC's "auto" controls parallel LTRANS jobs and still performs its
+# full-program LTO pipeline; Clang's identically named mode means Full LTO, so
+# AUTO prefers ThinLTO before falling back to Full LTO.
+macro(_BRLCAD_LTO_FLAG_CANDIDATES _language _output)
+  set(${_output})
+  set(_brlcad_lto_compiler_id "${CMAKE_${_language}_COMPILER_ID}")
+  set(_brlcad_lto_compiler_version "${CMAKE_${_language}_COMPILER_VERSION}")
+
+  if(BRLCAD_LTO_MODE MATCHES "^OFF$")
+    # No LTO compiler flag requested.
+  elseif(_brlcad_lto_compiler_id STREQUAL "GNU")
+    if(_brlcad_lto_compiler_version VERSION_LESS 4.9)
+      if(NOT BRLCAD_LTO_MODE MATCHES "^AUTO$")
+        message(
+          FATAL_ERROR
+          "BRLCAD_LTO_MODE=${BRLCAD_LTO_MODE} is not supported by GCC ${_brlcad_lto_compiler_version}; GCC versions before 4.9 have known BRL-CAD LTO failures."
+        )
+      endif()
+    elseif(BRLCAD_LTO_MODE MATCHES "^THIN$")
+      message(FATAL_ERROR "BRLCAD_LTO_MODE=THIN requires a Clang-family compiler; GCC does not implement LLVM ThinLTO.")
+    else()
+      # GCC LTO is full-program LTO.  Prefer automatic jobserver/CPU-count
+      # parallelism, retaining plain -flto as a compatibility fallback.
+      set(${_output} flto=auto flto)
+    endif()
+  elseif(_brlcad_lto_compiler_id MATCHES "Clang")
+    if(BRLCAD_LTO_MODE MATCHES "^AUTO$")
+      set(${_output} flto=thin flto=full flto)
+    elseif(BRLCAD_LTO_MODE MATCHES "^THIN$")
+      set(${_output} flto=thin)
+    else()
+      set(${_output} flto=full flto)
+    endif()
+  elseif(BRLCAD_LTO_MODE MATCHES "^THIN$")
+    set(${_output} flto=thin)
+  elseif(BRLCAD_LTO_MODE MATCHES "^FULL$")
+    set(${_output} flto=full flto)
+  else()
+    set(${_output} flto=auto flto)
+  endif()
+
+  unset(_brlcad_lto_compiler_id)
+  unset(_brlcad_lto_compiler_version)
+endmacro()
+
+# Test the complete LTO pipeline used by BRL-CAD: compile an archive member,
+# create and index a static library with the configured archiver tools, and
+# link a consumer that must extract that member.  A compile-only flag check or
+# a single-object executable does not detect incompatible ar/ranlib tooling.
+function(_BRLCAD_CHECK_LTO_FLAG _language _candidate _output)
+  string(TOUPPER "${_candidate}" _brlcad_lto_probe_name)
+  string(REGEX REPLACE "[^a-zA-Z0-9]" "_" _brlcad_lto_probe_name "${_brlcad_lto_probe_name}")
+  set(_brlcad_lto_probe_var "BRLCAD_LTO_${_brlcad_lto_probe_name}_${_language}_PIPELINE_WORKS")
+
+  if(NOT DEFINED ${_brlcad_lto_probe_var})
+    if("${_language}" STREQUAL "C")
+      set(_brlcad_lto_source_extension "c")
+    elseif("${_language}" STREQUAL "CXX")
+      set(_brlcad_lto_source_extension "cpp")
+    else()
+      message(FATAL_ERROR "Unsupported LTO probe language: ${_language}")
+    endif()
+
+    set(_brlcad_lto_source_dir "${CMAKE_BINARY_DIR}/CMakeTmp/LTO_${_language}_${_brlcad_lto_probe_name}_sources")
+    set(_brlcad_lto_build_dir "${CMAKE_BINARY_DIR}/CMakeTmp/LTO_${_language}_${_brlcad_lto_probe_name}_build")
+    file(MAKE_DIRECTORY "${_brlcad_lto_source_dir}")
+    file(REMOVE_RECURSE "${_brlcad_lto_build_dir}")
+    file(WRITE "${_brlcad_lto_source_dir}/archive.${_brlcad_lto_source_extension}"
+      "int brlcad_lto_archive_value(void) { return 0; }\n"
+    )
+    file(WRITE "${_brlcad_lto_source_dir}/main.${_brlcad_lto_source_extension}"
+      "int brlcad_lto_archive_value(void);\n"
+      "int main(void) { return brlcad_lto_archive_value(); }\n"
+    )
+    file(WRITE "${_brlcad_lto_source_dir}/CMakeLists.txt"
+      "cmake_minimum_required(VERSION ${CMAKE_MINIMUM_REQUIRED_VERSION})\n"
+      "if(BRLCAD_LTO_AR)\n"
+      "  set(CMAKE_AR \"\${BRLCAD_LTO_AR}\" CACHE FILEPATH \"Archiver used by the LTO probe\" FORCE)\n"
+      "endif()\n"
+      "if(BRLCAD_LTO_RANLIB)\n"
+      "  set(CMAKE_RANLIB \"\${BRLCAD_LTO_RANLIB}\" CACHE FILEPATH \"Ranlib used by the LTO probe\" FORCE)\n"
+      "endif()\n"
+      "project(BRLCADLTOProbe LANGUAGES ${_language})\n"
+      "if(BRLCAD_LTO_AR)\n"
+      "  set(CMAKE_AR \"\${BRLCAD_LTO_AR}\")\n"
+      "endif()\n"
+      "if(BRLCAD_LTO_RANLIB)\n"
+      "  set(CMAKE_RANLIB \"\${BRLCAD_LTO_RANLIB}\")\n"
+      "endif()\n"
+      "set(CMAKE_VERBOSE_MAKEFILE ON)\n"
+      "add_library(brlcad_lto_archive STATIC archive.${_brlcad_lto_source_extension})\n"
+      "target_compile_options(brlcad_lto_archive PRIVATE -${_candidate})\n"
+      "add_executable(brlcad_lto_executable main.${_brlcad_lto_source_extension})\n"
+      "target_compile_options(brlcad_lto_executable PRIVATE -${_candidate})\n"
+      "target_link_options(brlcad_lto_executable PRIVATE -${_candidate})\n"
+      "target_link_libraries(brlcad_lto_executable PRIVATE brlcad_lto_archive)\n"
+    )
+
+    set(
+      _brlcad_lto_forward_vars
+      CMAKE_${_language}_COMPILER
+      CMAKE_${_language}_COMPILER_AR
+      CMAKE_${_language}_COMPILER_RANLIB
+      CMAKE_${_language}_COMPILER_EXTERNAL_TOOLCHAIN
+      CMAKE_${_language}_COMPILER_TARGET
+      CMAKE_${_language}_FLAGS
+      CMAKE_BUILD_TYPE
+      CMAKE_EXE_LINKER_FLAGS
+      CMAKE_FIND_ROOT_PATH
+      CMAKE_OSX_ARCHITECTURES
+      CMAKE_OSX_DEPLOYMENT_TARGET
+      CMAKE_OSX_SYSROOT
+      CMAKE_POSITION_INDEPENDENT_CODE
+      CMAKE_STATIC_LINKER_FLAGS
+      CMAKE_SYSROOT
+      CMAKE_SYSROOT_COMPILE
+      CMAKE_SYSROOT_LINK
+      CMAKE_SYSTEM_NAME
+      CMAKE_SYSTEM_PROCESSOR
+      CMAKE_TOOLCHAIN_FILE
+    )
+    if(CMAKE_BUILD_TYPE)
+      string(TOUPPER "${CMAKE_BUILD_TYPE}" _brlcad_lto_build_type)
+      list(APPEND _brlcad_lto_forward_vars
+        CMAKE_${_language}_FLAGS_${_brlcad_lto_build_type}
+        CMAKE_EXE_LINKER_FLAGS_${_brlcad_lto_build_type}
+        CMAKE_STATIC_LINKER_FLAGS_${_brlcad_lto_build_type}
+      )
+    endif()
+
+    set(_brlcad_lto_cmake_flags)
+    foreach(_brlcad_lto_forward_var IN LISTS _brlcad_lto_forward_vars)
+      if(DEFINED ${_brlcad_lto_forward_var})
+        string(REPLACE ";" "\\;" _brlcad_lto_forward_value "${${_brlcad_lto_forward_var}}")
+        list(APPEND _brlcad_lto_cmake_flags "-D${_brlcad_lto_forward_var}:STRING=${_brlcad_lto_forward_value}")
+      endif()
+    endforeach()
+    foreach(_brlcad_lto_tool IN ITEMS AR RANLIB)
+      if(CMAKE_${_brlcad_lto_tool})
+        string(REPLACE ";" "\\;" _brlcad_lto_tool_value "${CMAKE_${_brlcad_lto_tool}}")
+        list(APPEND _brlcad_lto_cmake_flags "-DBRLCAD_LTO_${_brlcad_lto_tool}:FILEPATH=${_brlcad_lto_tool_value}")
+      endif()
+    endforeach()
+
+    message(STATUS "Performing Test ${_brlcad_lto_probe_var}")
+    try_compile(
+      ${_brlcad_lto_probe_var}
+      "${_brlcad_lto_build_dir}"
+      "${_brlcad_lto_source_dir}"
+      BRLCADLTOProbe
+      brlcad_lto_executable
+      CMAKE_FLAGS ${_brlcad_lto_cmake_flags}
+      OUTPUT_VARIABLE _brlcad_lto_probe_output
+    )
+    set(
+      ${_brlcad_lto_probe_var} "${${_brlcad_lto_probe_var}}"
+      CACHE INTERNAL "LTO archive pipeline test for -${_candidate} with ${_language}" FORCE
+    )
+    if(${_brlcad_lto_probe_var})
+      message(STATUS "Performing Test ${_brlcad_lto_probe_var} - Success")
+    else()
+      message(STATUS "Performing Test ${_brlcad_lto_probe_var} - Failed")
+      file(APPEND "${CMAKE_BINARY_DIR}/CMakeFiles/CMakeError.log"
+        "=== LTO ARCHIVE PIPELINE TEST: ${_language} -${_candidate} ===\n${_brlcad_lto_probe_output}\n"
+      )
+    endif()
+    _brlcad_probe_diagnostic(
+      "LTO_${_language}_${_brlcad_lto_probe_name}"
+      "=== LTO ARCHIVE PIPELINE TEST: ${_language} -${_candidate} ===\n${_brlcad_lto_probe_output}\n"
+    )
+  endif()
+
+  set(${_output} "${${_brlcad_lto_probe_var}}" PARENT_SCOPE)
+endfunction()
+
+# Select the first supported flag and append only that flag to the requested
+# optimization group.  Explicit modes fail rather than silently producing a
+# non-LTO build when the compiler, archiver, and linker cannot honor the
+# request.
+macro(_BRLCAD_ENABLE_LTO_FLAG _language _flag_group)
+  _brlcad_lto_flag_candidates(${_language} _brlcad_lto_candidates)
+  if(_brlcad_lto_candidates)
+    string(JOIN ", " _brlcad_lto_candidates_report ${_brlcad_lto_candidates})
+    set(_brlcad_lto_flag_found FALSE)
+    foreach(_brlcad_lto_candidate IN LISTS _brlcad_lto_candidates)
+      if(NOT _brlcad_lto_flag_found)
+        set(_brlcad_lto_flag "-${_brlcad_lto_candidate}")
+        _brlcad_check_lto_flag(${_language} "${_brlcad_lto_candidate}" _brlcad_lto_candidate_works)
+        if(_brlcad_lto_candidate_works)
+          if(${_flag_group})
+            set(${_flag_group} "${${_flag_group}} ${_brlcad_lto_flag}")
+          else()
+            set(${_flag_group} "${_brlcad_lto_flag}")
+          endif()
+          set(_brlcad_lto_flag_found TRUE)
+        endif()
+      endif()
+    endforeach()
+    if(NOT _brlcad_lto_flag_found)
+      if(BRLCAD_LTO_MODE MATCHES "^AUTO$")
+        message(
+          STATUS
+          "LTO is unsupported by the ${_language} toolchain; continuing without it. Tried: ${_brlcad_lto_candidates_report}"
+        )
+      else()
+        message(
+          FATAL_ERROR
+          "BRLCAD_LTO_MODE=${BRLCAD_LTO_MODE} is unsupported by the ${_language} toolchain. Tried: ${_brlcad_lto_candidates_report}"
+        )
+      endif()
+    endif()
+  endif()
+  unset(_brlcad_lto_flag)
+  unset(_brlcad_lto_candidate)
+  unset(_brlcad_lto_candidate_works)
+  unset(_brlcad_lto_candidates)
+  unset(_brlcad_lto_candidates_report)
+  unset(_brlcad_lto_flag_found)
+endmacro()
+
+# Second flag-batch pre-warm (optimization and warning flags).
 # Unlike the first batch, every consumer of these flags lives under the
 # "if(NOT MSVC)" optimization/warning blocks below, so on MSVC the reference
 # build never tests them.  Keep this batch gated to non-MSVC to match that -
@@ -952,15 +1173,8 @@ if(BRLCAD_ENABLE_PARALLEL_CONFIG_PROBES AND NOT MSVC)
       _brlcad_register_flag_probe(CXX "${_brlcad_opt_flag}")
     endforeach()
 
-    if("${CMAKE_C_COMPILER_ID}" STREQUAL "GNU" AND CMAKE_C_COMPILER_VERSION VERSION_LESS 4.9)
-      # GCC versions before 4.9 have known LTO problems in this build.
-    else()
-      foreach(_brlcad_lto_flag IN ITEMS "flto=auto" flto)
-        _brlcad_register_flag_probe(C "${_brlcad_lto_flag}")
-        _brlcad_register_flag_probe(CXX "${_brlcad_lto_flag}")
-      endforeach()
-    endif()
-
+    # LTO candidates are intentionally checked separately because the batch
+    # compiler-flag probes do not apply their options during linking.
     if(NOT BRLCAD_PROFILING AND NOT BRLCAD_DEBUGGING)
       _brlcad_register_flag_probe(C fomit-frame-pointer)
       _brlcad_register_flag_probe(CXX fomit-frame-pointer)
@@ -977,23 +1191,6 @@ if(BRLCAD_ENABLE_PARALLEL_CONFIG_PROBES AND NOT MSVC)
     endforeach()
   endif()
 
-  if(BRLCAD_ENABLE_ADDRESS_SANITIZER AND ${BRLCAD_OPTIMIZED} MATCHES "OFF" AND BRLCAD_DEBUGGING)
-    foreach(_brlcad_asan_flag IN ITEMS
-        "fsanitize=address"
-        "fsanitize-address-use-after-return=always"
-        fsanitize-address-use-after-scope
-        fno-omit-frame-pointer
-      )
-      _brlcad_register_flag_probe(C "${_brlcad_asan_flag}")
-      _brlcad_register_flag_probe(CXX "${_brlcad_asan_flag}")
-    endforeach()
-  endif()
-
-  if(BRLCAD_SANITIZE_THREAD)
-    _brlcad_register_flag_probe(C "fsanitize=thread")
-    _brlcad_register_flag_probe(CXX "fsanitize=thread")
-  endif()
-
   if(BRLCAD_WARNINGS OR BRLCAD_ENABLE_STRICT)
     foreach(_brlcad_warning_flag IN ITEMS
         pedantic
@@ -1268,22 +1465,30 @@ if(NOT MSVC)
   # CHECK_C_FLAG("finline-limit=10000 --param inline-unit-growth=300 --param large-function-growth=300" GROUPS OPTIMIZE_C_FLAGS)
   # CHECK_CXX_FLAG("finline-limit=10000 --param inline-unit-growth=300 --param large-function-growth=300" GROUPS OPTIMIZE_CXX_FLAGS)
 
-  # link-time optimization (LTO) results in slower linking, more
-  # warnings, and better optimization, but requires newer versions of
-  # compilers to avoid common bugs.
-  if("${CMAKE_C_COMPILER_ID}" STREQUAL "GNU" AND CMAKE_C_COMPILER_VERSION VERSION_LESS 4.9)
-    # LTO bug in GCC 4.8.5 (__fread_chk_warn)
-  else()
-    # Try flto=auto first to avoid lto-wrapper serial compilation warnings
-    # https://stackoverflow.com/questions/72218980/gcc-v12-1-warning-about-serial-compilation
-    check_c_flag("flto=auto" GROUPS OPTIMIZE_C_FLAGS VARS flto_auto_c_flag_found)
-    if (NOT flto_auto_c_flag_found)
-      check_c_flag(flto GROUPS OPTIMIZE_C_FLAGS)
-    endif()
-    check_cxx_flag("flto=auto" GROUPS OPTIMIZE_CXX_FLAGS VARS flto_auto_cxx_flag_found)
-    if (NOT flto_auto_cxx_flag_found)
-      check_cxx_flag(flto GROUPS OPTIMIZE_CXX_FLAGS)
-    endif()
+  # GCC LTO objects require ar/ranlib wrappers or explicit plugin support.
+  # Select the wrappers before probing LTO so the archive pipeline test uses
+  # the same tools as the real build.
+  if(CMAKE_C_COMPILER_ID MATCHES "GNU" AND CMAKE_C_COMPILER_VERSION VERSION_GREATER 4.8)
+    find_program(GCC_AR_LTO ${CMAKE_C_COMPILER}-ar NAMES gcc-ar DOC "GNU ARchiver wrapper with LTO support")
+    if(GCC_AR_LTO)
+      set(CMAKE_AR "${GCC_AR_LTO}")
+      set(CMAKE_AR "${GCC_AR_LTO}" CACHE FILEPATH "Archiver" FORCE)
+    endif(GCC_AR_LTO)
+    find_program(GCC_RANLIB_LTO ${CMAKE_C_COMPILER}-ranlib NAMES gcc-ranlib DOC "GNU Ranlib wrapper with LTO support")
+    if(GCC_RANLIB_LTO)
+      set(CMAKE_RANLIB "${GCC_RANLIB_LTO}")
+      set(CMAKE_RANLIB "${GCC_RANLIB_LTO}" CACHE FILEPATH "Ranlib" FORCE)
+    endif(GCC_RANLIB_LTO)
+  endif(CMAKE_C_COMPILER_ID MATCHES "GNU" AND CMAKE_C_COMPILER_VERSION VERSION_GREATER 4.8)
+  mark_as_advanced(GCC_AR_LTO)
+  mark_as_advanced(GCC_RANLIB_LTO)
+
+  # Link-time optimization is selected independently from the other release
+  # flags, permitting optimized builds without LTO.  Probe it only when the
+  # optimization flag group will actually be used.
+  if(BRLCAD_OPTIMIZED)
+    _brlcad_enable_lto_flag(C OPTIMIZE_C_FLAGS)
+    _brlcad_enable_lto_flag(CXX OPTIMIZE_CXX_FLAGS)
 
     # When compiling with O3 + flto, GCC 6.3 (e.g. on Debian x64, and maybe
     # others, but I haven't tested) fails to link executables using libbrep.
@@ -1306,24 +1511,7 @@ if(NOT MSVC)
     # which switched to C++98 from C++11.
     #
     # CHECK_CXX_FLAG(fno-inline-small-functions GROUPS OPTIMIZE_CXX_FLAGS)
-  endif("${CMAKE_C_COMPILER_ID}" STREQUAL "GNU" AND CMAKE_C_COMPILER_VERSION VERSION_LESS 4.9)
-
-  # GCC 4.9+ introduced "thin" LTO object files that require special
-  # ar/ranlib handling via wrappers or plugin specification.  These
-  # wrappers work fine even if we're not using LTO, so just use them
-  # if found.
-  if(CMAKE_C_COMPILER_ID MATCHES "GNU" AND CMAKE_C_COMPILER_VERSION VERSION_GREATER 4.8)
-    find_program(GCC_AR_LTO ${CMAKE_C_COMPILER}-ar NAMES gcc-ar DOC "GNU ARchiver wrapper with LTO support")
-    if(GCC_AR_LTO)
-      set(CMAKE_AR "${GCC_AR_LTO}" CACHE FILEPATH "Archiver" FORCE)
-    endif(GCC_AR_LTO)
-    find_program(GCC_RANLIB_LTO ${CMAKE_C_COMPILER}-ranlib NAMES gcc-ranlib DOC "GNU Ranlib wrapper with LTO support")
-    if(GCC_RANLIB_LTO)
-      set(CMAKE_RANLIB "${GCC_RANLIB_LTO}" CACHE FILEPATH "Ranlib" FORCE)
-    endif(GCC_RANLIB_LTO)
-  endif(CMAKE_C_COMPILER_ID MATCHES "GNU" AND CMAKE_C_COMPILER_VERSION VERSION_GREATER 4.8)
-  mark_as_advanced(GCC_AR_LTO)
-  mark_as_advanced(GCC_RANLIB_LTO)
+  endif()
 
   # only omit the frame pointer if we have no interest in profiling or
   # debugging.
@@ -1359,14 +1547,6 @@ if(NOT MSVC)
     check_cxx_flag(qstackprotect)
   endif(${BRLCAD_OPTIMIZED} MATCHES "OFF" AND BRLCAD_DEBUGGING)
 
-  # Differently, enable the ThreadSanitizer race condition detector
-  # only as requested since it can incur a 5x-15x slowdown.  See
-  # https://code.google.com/p/thread-sanitizer/ for more info.
-  if(BRLCAD_SANITIZE_THREAD)
-    check_c_flag(fsanitize=thread)
-    check_cxx_flag(fsanitize=thread)
-  endif(BRLCAD_SANITIZE_THREAD)
-
   # verbose warning flags.  we intentionally try to turn on as many as
   # possible.  adding more is encouraged (as long as all issues are
   # fixed first).
@@ -1626,17 +1806,22 @@ brlcad_check_library(BSD c daemon)
 
 # Mark X11 as available if it is enabled and we find Xlib.h
 if(BRLCAD_ENABLE_X11)
-  message("X11 detected and enabled")
-  if(X11_Xlib_INCLUDE_PATH)
+  message("X11 provider ${BRLCAD_X11_PROVIDER_RESOLVED} detected and enabled")
+  if(BRLCAD_X11_PROVIDER_RESOLVED STREQUAL "XMIN")
     set(HAVE_X11_XLIB_H 1)
     brlcad_deferred_define("HAVE_X11_XLIB_H 1")
-    # message("Defining HAVE_X11_XLIB_H")
-  endif(X11_Xlib_INCLUDE_PATH)
-  if(X11_Xi_INCLUDE_PATH)
-    set(HAVE_X11_EXTENSIONS_XINPUT_H 1)
-    brlcad_deferred_define("HAVE_X11_EXTENSIONS_XINPUT_H 1")
-    # message("Defining HAVE_X11_EXTENSIONS_XINPUT_H")
-  endif(X11_Xi_INCLUDE_PATH)
+  else()
+    if(X11_Xlib_INCLUDE_PATH)
+      set(HAVE_X11_XLIB_H 1)
+      brlcad_deferred_define("HAVE_X11_XLIB_H 1")
+      # message("Defining HAVE_X11_XLIB_H")
+    endif(X11_Xlib_INCLUDE_PATH)
+    if(X11_Xi_INCLUDE_PATH)
+      set(HAVE_X11_EXTENSIONS_XINPUT_H 1)
+      brlcad_deferred_define("HAVE_X11_EXTENSIONS_XINPUT_H 1")
+      # message("Defining HAVE_X11_EXTENSIONS_XINPUT_H")
+    endif(X11_Xi_INCLUDE_PATH)
+  endif()
 endif(BRLCAD_ENABLE_X11)
 
 # math library
@@ -1772,6 +1957,7 @@ _brlcad_include_probe(sys/file.h HAVE_SYS_FILE_H)
 _brlcad_include_probe(sys/ioctl.h HAVE_SYS_IOCTL_H)
 _brlcad_include_probe(sys/ioctl_compat.h HAVE_SYS_IOCTL_COMPAT_H)
 _brlcad_include_probe(sys/ipc.h HAVE_SYS_IPC_H)
+_brlcad_include_probe(sys/kinfo.h HAVE_SYS_KINFO_H)
 _brlcad_include_probe(sys/machd.h HAVE_SYS_MACHD_H)
 _brlcad_include_probe(sys/mman.h HAVE_SYS_MMAN_H)
 _brlcad_include_probe(sys/mount.h HAVE_SYS_MOUNT_H)
@@ -1792,6 +1978,7 @@ _brlcad_include_probe(sys/times.h HAVE_SYS_TIMES_H)
 _brlcad_include_probe(sys/types.h HAVE_SYS_TYPES_H)
 _brlcad_include_probe(sys/uio.h HAVE_SYS_UIO_H)
 _brlcad_include_probe(sys/un.h HAVE_SYS_UN_H)
+_brlcad_include_probe(sys/user.h HAVE_SYS_USER_H)
 _brlcad_include_probe(sys/utsname.h HAVE_SYS_UTSNAME_H)
 _brlcad_include_probe(sys/wait.h HAVE_SYS_WAIT_H)
 _brlcad_include_probe(syslog.h HAVE_SYSLOG_H)
@@ -2446,10 +2633,18 @@ if(MSVC)
   set(CMAKE_MODULE_LINKER_FLAGS "${CMAKE_MODULE_LINKER_FLAGS} /STACK:10000000 /NOLOGO")
 endif(MSVC)
 
-# Enable AddressSanitizer only after the configure-time platform tests have
-# run.  Instrumenting try_run executables can make otherwise valid feature
-# checks fail when configuring under a debugger, tracer, or restricted runtime
-# where LeakSanitizer cannot inspect the process.
+# Enable sanitizers only after the configure-time platform tests have run.
+# Instrumenting try_run executables can make otherwise valid feature checks
+# fail when configuring under a debugger, tracer, or restricted runtime where
+# sanitizer runtimes cannot inspect the process.
+if(BRLCAD_ENABLE_THREAD_SANITIZER AND
+   (BRLCAD_ENABLE_ADDRESS_SANITIZER OR BRLCAD_ENABLE_UNDEFINED_SANITIZER))
+  message(FATAL_ERROR
+    "BRLCAD_ENABLE_THREAD_SANITIZER must use a separate build from "
+    "AddressSanitizer and UndefinedBehaviorSanitizer"
+  )
+endif()
+
 if(BRLCAD_ENABLE_ADDRESS_SANITIZER)
   if(MSVC)
     message(FATAL_ERROR "BRLCAD_ENABLE_ADDRESS_SANITIZER is not yet supported with MSVC")
@@ -2502,6 +2697,140 @@ if(BRLCAD_ENABLE_ADDRESS_SANITIZER)
   endif()
 endif()
 
+if(BRLCAD_ENABLE_UNDEFINED_SANITIZER)
+  if(MSVC)
+    message(FATAL_ERROR "BRLCAD_ENABLE_UNDEFINED_SANITIZER is not yet supported with MSVC")
+  endif()
+  if(BRLCAD_OPTIMIZED OR NOT BRLCAD_DEBUGGING)
+    message(FATAL_ERROR "BRLCAD_ENABLE_UNDEFINED_SANITIZER requires BRLCAD_OPTIMIZED=OFF and BRLCAD_DEBUGGING=ON")
+  endif()
+
+  cmake_push_check_state()
+  set(CMAKE_REQUIRED_FLAGS "-fsanitize=undefined")
+  list(APPEND CMAKE_REQUIRED_LINK_OPTIONS "-fsanitize=undefined")
+  check_c_compiler_flag("-fsanitize=undefined" BRLCAD_UBSAN_C_SUPPORTED)
+  check_cxx_compiler_flag("-fsanitize=undefined" BRLCAD_UBSAN_CXX_SUPPORTED)
+  check_c_compiler_flag("-fno-sanitize-recover=undefined" BRLCAD_UBSAN_C_NO_RECOVER_SUPPORTED)
+  check_cxx_compiler_flag("-fno-sanitize-recover=undefined" BRLCAD_UBSAN_CXX_NO_RECOVER_SUPPORTED)
+  check_c_compiler_flag("-fno-omit-frame-pointer" BRLCAD_UBSAN_C_FRAME_POINTER_SUPPORTED)
+  check_cxx_compiler_flag("-fno-omit-frame-pointer" BRLCAD_UBSAN_CXX_FRAME_POINTER_SUPPORTED)
+  cmake_pop_check_state()
+
+  if(NOT BRLCAD_UBSAN_C_SUPPORTED OR NOT BRLCAD_UBSAN_CXX_SUPPORTED)
+    message(FATAL_ERROR "BRLCAD_ENABLE_UNDEFINED_SANITIZER was requested, but the C/C++ compiler and linker do not support -fsanitize=undefined")
+  endif()
+  if(NOT BRLCAD_UBSAN_C_NO_RECOVER_SUPPORTED OR NOT BRLCAD_UBSAN_CXX_NO_RECOVER_SUPPORTED)
+    message(FATAL_ERROR "BRLCAD_ENABLE_UNDEFINED_SANITIZER requires C/C++ support for -fno-sanitize-recover=undefined")
+  endif()
+
+  add_compile_options(-fsanitize=undefined)
+  add_link_options(-fsanitize=undefined)
+  add_compile_options($<$<COMPILE_LANGUAGE:C>:-fno-sanitize-recover=undefined>)
+  add_compile_options($<$<COMPILE_LANGUAGE:CXX>:-fno-sanitize-recover=undefined>)
+  if(BRLCAD_UBSAN_C_FRAME_POINTER_SUPPORTED)
+    add_compile_options($<$<COMPILE_LANGUAGE:C>:-fno-omit-frame-pointer>)
+  endif()
+  if(BRLCAD_UBSAN_CXX_FRAME_POINTER_SUPPORTED)
+    add_compile_options($<$<COMPILE_LANGUAGE:CXX>:-fno-omit-frame-pointer>)
+  endif()
+endif()
+
+if(BRLCAD_ENABLE_THREAD_SANITIZER)
+  if(MSVC)
+    message(FATAL_ERROR "BRLCAD_ENABLE_THREAD_SANITIZER is not yet supported with MSVC")
+  endif()
+  if(BRLCAD_OPTIMIZED OR NOT BRLCAD_DEBUGGING)
+    message(FATAL_ERROR "BRLCAD_ENABLE_THREAD_SANITIZER requires BRLCAD_OPTIMIZED=OFF and BRLCAD_DEBUGGING=ON")
+  endif()
+
+  cmake_push_check_state()
+  set(CMAKE_REQUIRED_FLAGS "-fsanitize=thread")
+  list(APPEND CMAKE_REQUIRED_LINK_OPTIONS "-fsanitize=thread")
+  check_c_compiler_flag("-fsanitize=thread" BRLCAD_TSAN_C_SUPPORTED)
+  check_cxx_compiler_flag("-fsanitize=thread" BRLCAD_TSAN_CXX_SUPPORTED)
+  check_c_compiler_flag("-fno-omit-frame-pointer" BRLCAD_TSAN_C_FRAME_POINTER_SUPPORTED)
+  check_cxx_compiler_flag("-fno-omit-frame-pointer" BRLCAD_TSAN_CXX_FRAME_POINTER_SUPPORTED)
+  check_c_compiler_flag("-Wno-error=tsan" BRLCAD_TSAN_C_NO_ERROR_SUPPORTED)
+  check_cxx_compiler_flag("-Wno-error=tsan" BRLCAD_TSAN_CXX_NO_ERROR_SUPPORTED)
+  cmake_pop_check_state()
+
+  if(NOT BRLCAD_TSAN_C_SUPPORTED OR NOT BRLCAD_TSAN_CXX_SUPPORTED)
+    message(FATAL_ERROR "BRLCAD_ENABLE_THREAD_SANITIZER was requested, but the C/C++ compiler and linker do not support -fsanitize=thread")
+  endif()
+
+  add_compile_options(-fsanitize=thread)
+  add_link_options(-fsanitize=thread)
+  if(BRLCAD_TSAN_C_FRAME_POINTER_SUPPORTED)
+    add_compile_options($<$<COMPILE_LANGUAGE:C>:-fno-omit-frame-pointer>)
+  endif()
+  if(BRLCAD_TSAN_CXX_FRAME_POINTER_SUPPORTED)
+    add_compile_options($<$<COMPILE_LANGUAGE:CXX>:-fno-omit-frame-pointer>)
+  endif()
+  # GCC warns that ThreadSanitizer does not model atomic_thread_fence.  Keep
+  # that warning visible, but do not let BRL-CAD's global -Werror prevent a
+  # TSan build from reaching the runtime tests which characterize the impact.
+  if(BRLCAD_TSAN_C_NO_ERROR_SUPPORTED)
+    add_compile_options($<$<COMPILE_LANGUAGE:C>:-Wno-error=tsan>)
+  endif()
+  if(BRLCAD_TSAN_CXX_NO_ERROR_SUPPORTED)
+    add_compile_options($<$<COMPILE_LANGUAGE:CXX>:-Wno-error=tsan>)
+  endif()
+endif()
+
+# Instrumented executables can be substantially slower, especially when a
+# test drives geometry work through nested execute_process calls whose timeout
+# is not managed by CTest.  Supply a common multiplier for those scripts while
+# permitting CI and developers to tune it for their host.
+if(BRLCAD_ENABLE_ADDRESS_SANITIZER OR
+   BRLCAD_ENABLE_UNDEFINED_SANITIZER OR
+   BRLCAD_ENABLE_THREAD_SANITIZER)
+  set(_brlcad_test_timeout_scale_default 4)
+else()
+  set(_brlcad_test_timeout_scale_default 1)
+endif()
+set(
+  BRLCAD_TEST_TIMEOUT_SCALE "${_brlcad_test_timeout_scale_default}"
+  CACHE STRING "Multiplier for test-script subprocess timeouts"
+)
+mark_as_advanced(BRLCAD_TEST_TIMEOUT_SCALE)
+if(NOT BRLCAD_TEST_TIMEOUT_SCALE MATCHES "^[1-9][0-9]*$")
+  message(FATAL_ERROR "BRLCAD_TEST_TIMEOUT_SCALE must be a positive integer")
+endif()
+unset(_brlcad_test_timeout_scale_default)
+
+# Build-time scanners are implementation tools, not leak-test subjects.  An
+# instrumented scanner still needs to run while building, including under
+# ptrace-based CI/sandbox environments where LeakSanitizer cannot initialize.
+# GCC ThreadSanitizer on x86-64 Linux likewise needs address randomization
+# disabled before process startup to reserve its shadow address range.
+set(BRLCAD_SANITIZER_BUILD_TOOL_LAUNCHER)
+set(BRLCAD_SANITIZER_TEST_LAUNCHER)
+if(BRLCAD_ENABLE_ADDRESS_SANITIZER)
+  set(
+    BRLCAD_SANITIZER_BUILD_TOOL_LAUNCHER
+    ${CMAKE_COMMAND} -E env ASAN_OPTIONS=detect_leaks=0
+  )
+endif()
+if(BRLCAD_ENABLE_THREAD_SANITIZER AND CMAKE_SYSTEM_NAME STREQUAL "Linux" AND
+   CMAKE_SYSTEM_PROCESSOR MATCHES "^(x86_64|amd64|AMD64)$")
+  find_program(BRLCAD_SETARCH_EXECUTABLE NAMES setarch)
+  if(BRLCAD_SETARCH_EXECUTABLE)
+    set(
+      BRLCAD_SANITIZER_BUILD_TOOL_LAUNCHER
+      ${BRLCAD_SETARCH_EXECUTABLE} x86_64 -R
+    )
+    set(
+      BRLCAD_SANITIZER_TEST_LAUNCHER
+      ${BRLCAD_SETARCH_EXECUTABLE} x86_64 -R
+    )
+  else()
+    message(WARNING
+      "ThreadSanitizer build tools and tests may need to be run with "
+      "address randomization disabled, but setarch was not found"
+    )
+  endif()
+endif()
+
 #-----------------------------------------------------------------------------
 # Add misc/tools for tools that are used in BRL-CAD's build process or for
 # maintenance activities.
@@ -2547,6 +2876,23 @@ include(${CMAKE_SOURCE_DIR}/src/source_dirs.cmake)
 # Now we have the necessary info - trigger the primary management logic
 brlcad_bext_process()
 
+# Zlib is discovered indirectly by packages such as OpenVDB, OpenNURBS, and
+# PNG.  Select it now so none of those packages can create an imported target
+# from stale cache entries; a later lookup cannot replace an existing target.
+find_package_zlib()
+
+# OpenVDB may be supplied by bext, so it cannot be discovered until bext files
+# have been staged in the build directory.
+if(BRLCAD_ENABLE_OPENVDB)
+  find_package_reset(OpenVDB RESET_TP)
+  set(OpenVDB_ROOT "${CMAKE_BINARY_DIR}")
+  find_package(OpenVDB)
+  if(NOT OpenVDB_FOUND)
+    message("OpenVDB enablement requested, but OpenVDB is not found - disabling")
+    set(BRLCAD_ENABLE_OPENVDB OFF)
+  endif(NOT OpenVDB_FOUND)
+endif(BRLCAD_ENABLE_OPENVDB)
+
 # Define some Tcl related variables for libtclcad
 if(BRLCAD_ITCL_BUILD)
   config_h_append(BRLCAD "#cmakedefine ITCL_VERSION \"${ITCL_VERSION}\"\n")
@@ -2944,8 +3290,8 @@ include(BRLCAD_CPack)
 
 # Some files to ignore for distcheck.  The files and directories prefixed with
 # a "." character are "hidden" and may not be present, so check for them first.
-set(
-  hidden_files
+set(hidden_files
+  .github/actions/prepare-bext/action.yml
   .github/workflows/distcheck.yml
   .github/workflows/linux_interactive.yml
   .github/workflows/push.yml
@@ -2959,8 +3305,8 @@ foreach(hf ${hidden_files})
   endif(EXISTS ${CMAKE_SOURCE_DIR}/${hf})
 endforeach(hf ${hidden_files})
 
-set(
-  toplevel_ignore_files
+set(toplevel_ignore_files
+  AGENTS.md
   BUGS
   CMakeLists.txt
   ChangeLog

INSTALL

@@ -39,7 +39,7 @@ including instructions for building on Windows.
 
 Required tools:
   - Git must be 2.17 or later
-  - CMake must be 3.20 or later
+  - CMake must be 3.26 or later
   - Compiler must be C++17-compliant
     - If using Visual Studio, version 2019 (16.8+) or later
     - If using GCC/G++, version 7 or later
@@ -111,8 +111,8 @@ path) as described in the Quick Installation section.
 Validating checksums:
 
 The integrity of distributed files can be verified using checksums that are
-published with released files.  Files on SourceForge's file release system can
-be found by clicking the 'i' button at the end of each file's name.  If you
+published with released files.  Released files and their checksums are
+available from the GitHub releases page (https://github.com/BRL-CAD/brlcad/releases).  If you
 re-distribute BRL-CAD, checksums should be retained with the files so others
 can validate origination.
 
@@ -350,6 +350,35 @@ if it is, default is to enable.
 Aliases:  ENABLE_OPENGL
 
 
+--- BRLCAD_X11_PROVIDER ---
+
+Selects the X11 implementation used by BRL-CAD, Tk, Qt, and OpenGL.  Accepted
+values are AUTO, SYSTEM, and XMIN.  AUTO is the default and deliberately
+resolves to SYSTEM so installing Xmin cannot change an existing build.
+
+XMIN selects an installed Xmin client SDK for deterministic GUI testing
+without a host X server.  The SDK must provide Xmin::ToolkitX11; OpenGL builds
+also need Xmin::GL.  Set Xmin_ROOT to the SDK installation prefix.  Tk and Qt
+must be built for the same provider because their public X11 APIs conceal
+provider-private state; mixing Xmin and system client libraries is not ABI
+safe and is rejected during configuration.
+
+When BRL-CAD manages bext, it derives the matching bext SDK prefix from the
+selected Xmin package.  Bext then applies its version-matched Tk and Qt patches
+automatically to whichever bundled toolkits are selected.  No external patch
+paths are needed.
+
+A typical Xmin configuration is:
+
+  cmake .. -DBRLCAD_X11_PROVIDER=XMIN \
+    -DXmin_ROOT=/path/to/xmin-prefix
+
+Bext retains advanced TK_EXTRA_PATCHES, TK_CONFIGURE_ARGS, QT_EXTRA_PATCHES,
+and QT_XMIN_ROOT controls for custom profiles.  The standard BRL-CAD Xmin
+configuration does not need them.  Refer to bext's Xmin profile documentation
+before changing the bundled Tk or Qt revision.
+
+
 --- BRLCAD_COMPONENTS ---
 
 Semicolon separated list of components to enable for building - see
@@ -438,13 +467,10 @@ Aliases:  ENABLE_ALL_CXX
 --- BRLCAD_EXTRADOCS ---
 
 The core option that enables and disables building of BRL-CAD's
-DocBook based documentation (includes manuals and man pages for
-commands, among other things).  Defaults to ON, but only HTML and MAN
-formats are enabled by default - PDF must be enabled separately by use
-of this option or one of its aliases.  Note that you may set
-environment variable APACHE_FOP to point to your locally installed fop
-executable file (which on Linux is usually a shell script with 0755
-permissions).
+AsciiDoc based documentation (includes manuals and man pages for
+commands, among other things).  It is built with BRL-CAD's bundled
+asciiquack processor into HTML and man-page (troff) formats.  Defaults
+to ON for a full build and OFF for reduced target sets.
 
-Aliases:  ENABLE_DOCS, ENABLE_EXTRA_DOCS, ENABLE_DOCBOOK
+Aliases:  ENABLE_DOCS, ENABLE_EXTRA_DOCS
 

NEWS

@@ -13,10 +13,166 @@ changes made.  See document footer for additional details.
 --- 20XX-XX-XX  Release 7.46.0                                     ---
 ----------------------------------------------------------------------
 
+* updated MGED and Archer for Tcl 8.6.18 and Itcl/Itk 4 - Cliff Yapp
+* fixed writes to fileless geometry databases - Cliff Yapp
+* fixed nastran-g handling of large property IDs - Rupesh, Cliff Yapp
+* fixed dxf-g invalid polyface index crashes - Meghna45-code, Cliff Yapp
+* fixed Archer primitive editors under Itcl 4 - Cliff Yapp
+* fixed Archer shutdown menu cleanup errors - Cliff Yapp
+* fixed MGED Build Pattern dialog under Itcl 4 - Cliff Yapp
+* fixed TclCAD framebuffer listing and deletion - Cliff Yapp
+* fixed MGED Build Pattern progress updates - Cliff Yapp
+* fixed MGED search -exec reentry and Ctrl-C crashes - Cliff Yapp
+* fixed MGED asynchronous commands and clone progress - Cliff Yapp
+* accelerated large and repeated MGED path drawing - Cliff Yapp
+* fixed ARB7 inside solid construction - Cliff Yapp
+* fixed direct ARB face and edge-direction editing - Cliff Yapp
+* fixed rtwizard startup with framebuffer contention - Cliff Yapp
+* fixed Archer annotation line display updates - Cliff Yapp
+* fixed Archer sketch scale drift in non-mm databases - Cliff Yapp
+* fixed toggle arrow callbacks during setup - Cliff Yapp
+* fixed Tcl dialogs with multi-word titles and messages - Cliff Yapp
+* fixed Archer Tank Wizard gun generation - Cliff Yapp
+* fixed MGED and Archer sketch arc tangency editing - Cliff Yapp
+* fixed Archer ARB4 point 3 editing - Cliff Yapp
+* fixed ARB4 storage from make and mk_arb4 - Cliff Yapp
+* fixed ARB4 and ARB6 center point calculations - Cliff Yapp
+* fixed concurrent MGED and rtwizard framebuffer use - Cliff Yapp
+* fixed MGED ShotVis editing and reload failures - Cliff Yapp
+* fixed Tcl widget geometry and selection defects - Cliff Yapp
+* fixed MGED BoT editor property handling - Cliff Yapp
+* fixed MGED LOD dialog and adaptive BoT wireframes - Cliff Yapp
+* fixed MGED Plot, PostScript, and manual launch tools - Cliff Yapp
+* fixed MGED Overlap Tool multi-object result handling - Cliff Yapp
+* eliminated 16-fold redundant gchecker grid analysis - Cliff Yapp
+* fixed Archer tree handling for object names with spaces - Cliff Yapp
+* fixed RtWizard multi-object edge occlusion handling - Cliff Yapp
+* fixed RtWizard title, About, and preference handling - Cliff Yapp
+* fixed MGED startup file false legacy-syntax warnings - Cliff Yapp
+* fixed MGED saved-view deletion and collaboration sync - Cliff Yapp
+* fixed MGED font preferences apply and persistence - Cliff Yapp
+* fixed Archer combination edits changing Boolean trees - Cliff Yapp
+* fixed Archer command-line help startup crash - Cliff Yapp
+* fixed MGED Geometry Browser menu and close behavior - Cliff Yapp
+* fixed MGED collaboration view unshare crash - Cliff Yapp
+* added an override for Archer's preference file location - Cliff Yapp
+* fixed embedded Archer display and mode menus - Cliff Yapp
+* added Archer -h and --help command-line options - Cliff Yapp
+* fixed Archer Help opening the documentation menu - Sean Morrison
+* added arrange nest command for packing database objects - Sean Morrison
+* new mkbuilding tool for parametric/OSM/CityJSON models - Sean Morrison
+* cross-platform BINUNIF and DSP byte-order handling - Sean Morrison
+* improved several cv default behaviors (s, 32, 64, n) - Sean Morrison
+* fixed invalid bot handling bug applying matrices - Sean Morrison
+* improved glTF import robustness via gcv - Sean Morrison
+* fixed bot dump glTF/GLB export; -F is now rejected - Cliff Yapp
+* faster NMG solid ray tracing (10-20x faster) - Sean Morrison
+* preserved primitive colors in shaded BoT and B-Rep drawing - Cliff Yapp
+* preserved B-Rep attributes through in-place geometry edits - Cliff Yapp
+* fixed gcv filter arguments containing one-character values - Cliff Yapp
+* improved iges-g importer robustness - Cliff Yapp
+* expanded g-iges native CSG and B-Rep export support - Cliff Yapp
+* added IGES import and export support to gcv - Cliff Yapp
+* rt -b query option now supports a single value index - Sean Morrison
+* fixed .dpix file format portability and icv support - Sean Morrison
+* expanded pixscale support for piped image data - Sean Morrison
+* fixed HYP volume and ARBN totals reported by analyze - Cliff Yapp
+* corrected rtarea sampling and exposed-area calculations - Cliff Yapp
+* bot split now groups results and preserves mesh data - Cliff Yapp
+* bot decimate now preserves normals, UVs, and plate data - Cliff Yapp
+* added raytracing support for annotation objects - Cliff Yapp
+* fixed MGED X embedded framebuffer display manager crash - Cliff Yapp
+* added annotate command for managing annotation objects - Cliff Yapp
+* added repair command for supported invalid primitives - Cliff Yapp
+* changed default new-region material code from 1 to 0 - Keith Bowman
+* added comb support to bb -o oriented bounding boxes - Cliff Yapp
+* added -t tight bounding box option to bb command - Cliff Yapp
+* added az (-a) and el (-e) option implementations to gqa - Cliff Yapp
+* added center command support for centering on an object - Cliff Yapp
+* greatly expanded JT import and added basic JT export - Sean Morrison
+* added csg-g/g-scad OpenSCAD CSG importer/exporter - Erik Greenwald
+* improved art light, color, output, & region handling - Sean Morrison
+* added preliminary OpenSCAD import support - Sean Morrison
+* expanded IGES BREP/NURBS import and export support - Sean Morrison
+* expanded STEP AP203 import support with faceted BREP - Sean Morrison
+* added STEP AP203e2, AP214, and AP242 import/export - Cliff Yapp
+* added STEP CSG round trips and AP242 PMI import - Cliff Yapp
+* improved STEP assembly, topology repair, and reporting - Cliff Yapp
+* new adrt CLI utility with path, spall, and cut modes - Sean Morrison
+* new CLI+GUI prototype BRL-CAD application launcher - Sean Morrison
+* added option validation to image & framebuffer tools - Sean Morrison
+* added contributor, API, command, & raytracing guides - Sean Morrison
+* added and updated command and library manual pages - Sean Morrison
+* added parashot gravity trajectory path generator - Sean Morrison
+* added metaball point scaling (via metaball_move_pnt) - Sean Morrison
+* all raytracing apps now report object prep failures - Sean Morrison
+* improved fast4-g robustness and error reporting - Cliff Yapp
+* improved robustness of g-vrml plate mode handling - Cliff Yapp
+* fixed MGED ARB5 point, pipe, and sketch editing - Cliff Yapp
+* added pnts write -f xyz export option - Chris McGregor
+* added support for tick drawing on MGED model axis - Cliff Yapp
+* added naca456 left and paired wing generation - Cliff Yapp
+* added patch-g -j option, specify object thicknesses - Sean Morrison
+* fixed fbcolor color ramp bug drawing the last color - Sean Morrison
+* fixed gist -Q quick preview option - Sean Morrison
+* rt preserves eye_pt setting in command scripts - Sean Morrison
+* rt -l8 heat graphs now measure CPU time - Sean Morrison
+* documented gqa centroid & moments of inertia options - Sean Morrison
+* pixdiff now calculates pixel differences on bw files - Sean Morrison
+* fixed bwcrop single-axis crops and pixembed edge fill - Sean Morrison
+* fixed isize in non-mm databases - Josh Baker
+* fixed metaball adjust clearing points on errors - Sean Morrison
+* fixed benchmark+pixcmp correctness validation bug - Sean Morrison
+* fbhelp writes help to stdout and rest to stderr - Sean Morrison
+* FB now supports /dev/stdout and /dev/stderr devices - Sean Morrison
+* fixed mged rt -C + -o background color to file bug - Sean Morrison
+* fixed rt -C255/0/0 -o file.pix background color bug - Sean Morrison
+* added rtsil foreground & background -c set options - Sean Morrison
+* added rtsil -o support for bw output - Sean Morrison
+* added cutting plane animation generation to rtwizard - Cliff Yapp
+* fixed pixdiff bug on Windows - Sean Morrison
+* fixed MGED startup window placement on Windows - Chris McGregor
+* fixed pixborder utility right-side edge bug - Sean Morrison
+* fixed 'wavelet' image processing tool on Windows - Sean Morrison
+* quieted mged killtree spurious lookup failure output - Sean Morrison
+* fixed ray tracing small images to disk framebuffers - Sean Morrison
+* improved raytracing performance of CSG-heavy regions - Sean Morrison
+* fixed OBJ conversion bug importing unnamed groups - Sean Morrison
+* fixed k-g conversion of BoT vertex normals - laithaldaeef
 * new doc guide, a visual overview of BRL-CAD objects - Sean Morrison
+* improved triangle quality produced by bot remesh - Cliff Yapp
+* updated numerous manpage command references - Josh Baker
 * fixed submodel paths relative to parent databases - Sean Morrison
 * improved performance making huge combinations - Sean Morrison
+* added make -t primitive type listing - Chris McGregor
 * added gcv import conversion support for vrml/wrl 1.0 - Sean Morrison
+* fixed gcv appending to existing geometry databases - Sean Morrison
+* added CSS names, hex, HSL/HSV to libbu color parsing - Sean Morrison
+* improved OpenNURBS B-Rep import and adjustment safety - Cliff Yapp
+* improved Debian application menus and MIME associations - Jordi Sayol
+* updated Clipper2 dependency to v1.5.4 - Cliff Yapp
+* updated Eigen dependency to v5.0.1 - Cliff Yapp
+* updated GDAL dependency to v3.13.3 - Cliff Yapp
+* updated GeometricTools dependency to v8.2 - Cliff Yapp
+* updated Itk dependency to v4.2.7 - Cliff Yapp
+* updated LMDB dependency to v1.0.1 - Cliff Yapp
+* updated Manifold dependency to v3.5.3 - Cliff Yapp
+* updated OpenCV dependency to v5.0.0 - Cliff Yapp
+* updated OpenNURBS dependency to v8.34.26223.11001 - Cliff Yapp
+* updated PROJ dependency to v9.8.1 - Cliff Yapp
+* updated PoissonRecon dependency to v18.75 - Cliff Yapp
+* updated Tcl/Tk dependency to v8.6.18, using bundled Itcl - Cliff Yapp
+* updated libjpeg-turbo dependency to v3.2.0 - Cliff Yapp
+* updated libosmesa dependency to SHA1 bfa90de - Cliff Yapp
+* updated libpng dependency to v1.6.58 - Cliff Yapp
+* updated libtiff dependency to v4.7.2 - Cliff Yapp
+* updated netpbm dependency to v10.86.50 - Cliff Yapp
+* updated oneTBB dependency to v2023.1.0 - Cliff Yapp
+* updated pugixml dependency to v1.16 - Cliff Yapp
+* updated sqlite3 dependency to v3.53.4 - Cliff Yapp
+* updated stepcode dependency to SHA1 ed686ee1d - Cliff Yapp
+* updated tinygltf dependency to v3.0.1 - Cliff Yapp
+* updated zlib dependency to v1.3.2 - Cliff Yapp
 
 
 ----------------------------------------------------------------------

TODO

@@ -18,13 +18,20 @@ tasks as they are completed.
 THESE TASKS SHOULD HAPPEN BEFORE THE NEXT RELEASE
 -------------------------------------------------
 
-* coordinate with bext to have it produce a manifest of what
-  files need strclear/plief processing of various types so
-  we don't need to redo the characterization pass every time
-  we configure.  We have strclear and plief in bext, so that
-  repo should be capable of doing the work for us as a post
-  build step whenever bext changes.
+* revert the pixdiff/pixcmp change back to grayscale
 
+* coordinate with bext to have it produce a manifest of what files
+  need strclear/plief processing of various types so we don't need to
+  redo the characterization pass every time we configure.  We have
+  strclear and plief in bext, so that repo should be capable of doing
+  the work for us as a post build step whenever bext changes.
+
+* fix ARB5 move point 5 to actually move the point.
+
+* need extensive testing of MGED CSG editing with the shift to librt
+  based editing logic.
+
+* investigate gqa plotting display in MGED
 
 THESE TASKS SHOULD HAPPEN WITHIN TWO RELEASE ITERATIONS
 -------------------------------------------------------
@@ -38,14 +45,12 @@ THESE TASKS SHOULD HAPPEN WITHIN TWO RELEASE ITERATIONS
 
 * verify arb6 editing in cheese wedge tutorial
 
-* rtarea is sometimes missing regions on summary reporting, at least
-  on Windows, possibly a threading issue setting up the results
-  container.
-
-
 THESE ARE UNSCHEDULED BACKLOG TASKS
 -----------------------------------
 
+* reconcile VCOMB2, VBLEND2, and VADD2SCALE along with corresponding
+  3d/4d api consistency in vmath.h
+
 * make sph sph
   clone -i 1 -t 1000 0 0 -n 100 sph
   kill sph
@@ -75,10 +80,6 @@ THESE ARE UNSCHEDULED BACKLOG TASKS
   binary interface to analytic routines.  notable outliers include
   nirt_* (including CLI handling..), voxelize*, rt_gen*, rectangular*
 
-* ensure datum objects convert out via g2asc and back (currently
-  writes "a Tcl output routine for this type of object has not yet
-  been implemented")
-
 * fix recursive bu_parallel() to not have a hard-coded limit on the
   number of threads or to more aggressively abort when more that
   supported are dispatched.  currently supporting 64x64 threads and
@@ -342,17 +343,6 @@ lookup check to ensure none are missing.
   error.  code appears to be assuming both /dev/X framebuffer and uses
   /dev/null redirect to sink output.
 
-* rtwizard greys out the File->New and Open menu items when run with a
-  filename, which is very confusing.  Either menu should remain usable
-  or there should be some other indication that a file was specified
-  and is open.
-
-* the mged tutorials apparently do not mention the tops command (even
-  once), but really should as it's the starting point for discovering
-  what is in databases that are opened or imported.
-
-* add metaball scaling feature (presently in a tclscript)
-
 * ability to visualize metaball centerpoints and with/without
   translucency.
 
@@ -363,6 +353,8 @@ lookup check to ensure none are missing.
 
 * add script/command for changing metaball weights in masse
 
+* add a proper 'metaball' command with subcommands
+
 * gdiff in mged appears to be broken?  get "no primitives found" on
   second comb when specifying two combs (gdiff comb1 comb2).  UPDATE -
   this appears to be a consequence of how gdiff internally implements
@@ -372,9 +364,6 @@ lookup check to ensure none are missing.
   comb2 is shared with comb1.  A workaround is to keep out comb2 and
   dbconcat it back in, then gdiff comb1 with the imported tree.
 
-* pixscale doesn't seem to handle stdin (due to bu_seek) for very
-  long
-
 * The embedded framebuffer for the X display manager is not working
   with Tcl/Tk 8.6 - it brings down mged with an Xerror when it tries
   to XFlush after X24_blit.  Better solution is to replace the X dm/fb
@@ -499,10 +488,6 @@ lookup check to ensure none are missing.
 
 * add unit tests for primitive callback routines (e.g., bbox).
 
-* put bu_num_print() to use
-
-* use bu_gettime() in rt -l8 heatgraph visualization mode
-
 * fully implement analyze for all geometry objects
 
 * move analyze logic into libanalyze (with respective primitive logic
@@ -603,10 +588,6 @@ lookup check to ensure none are missing.
   libged command wrapper so it's consistent and available to any
   command.
 
-* mater command does not validate its arguments - fix that.  Also
-  properly document using "." to skip specifying something - not in
-  the man page currently.
-
 * bullet integration - need to expose restitution as an
   object parameter so we can configure behavior:
   http://www.bulletphysics.org/Bullet/phpBB3/viewtopic.php?p=&f=&t=3248
@@ -640,8 +621,6 @@ lookup check to ensure none are missing.
 * closing the graphics window brings down X11 on Mac due to a bad
   context.  fix or revert recent close window behavior.
 
-* V&V bwcrop, pixembed are behaving correctly, as documented
-
 * implement unit tests for bu dirent / stat API
 
 * convert src/util/terrain.c to src/shapes/terrain.c writing out the
@@ -657,8 +636,6 @@ lookup check to ensure none are missing.
   get_eyemodel to eye_pt to result in no change, modulo unit
   conversions.
 
-* make rt -b accept a pixel index in addition to x,y pixel coordinates
-
 * teach pixdiff and other tools that can/should support the capability
   to read/write (as appropriate) pixel index values or x,y coordinates
   and reproduce the ray fired to create that pixel. currently does -l
@@ -975,11 +952,6 @@ lookup check to ensure none are missing.
 
 * test tgf-g conversion with "ring-mode" geometry
 
-* fix metaball/adjust.. wipes out all metaball values with:
-  adjust metaball 1 1 1
-  just gives usage with:
-  adjust metaball 1 1
-
 * test for -msse3 requirement for __SSE.*__ definition
 
 * improve sse run-time detection so illegal instruction crashes are
@@ -998,11 +970,6 @@ lookup check to ensure none are missing.
   [FAN-OUT: yes -- per-file/per-converter sweep with a verification
   pass.]
 
-* pixdiff reports bytes, but reports incorrect (off-by-one) bytes for
-  .bw input files.  cause is due to tool assuming input is rgb
-  triplets (even though output is bytes, wtf?).  should probably
-  report pixels and/or have a -b option for handling byte/bw input.
-
 * investigate why epa primitive is so sensitive to coarse absolute
   value changes (run csgbrep, tol abs=1, facetize and get 321k poly)
 
@@ -1103,12 +1070,6 @@ lookup check to ensure none are missing.
   intersected with them) since, while bad practice, are valid
   geometrically.
 
-* make sure there are no getenv() non-NULL assumptions within the
-  code.  might want to see if there's a pattern of variables being
-  checked such that a libbu interface would be warranted (e.g.,
-  instead of checking HOME, having a bu_find_directory(BU_USER_HOME)
-  routine or similar facility) for finding common resource locations.
-
 * make db_open modes behave the same as the fopen() modes (i.e.,
   create the .g if one doesn't exist when write mode)
 
@@ -1761,12 +1722,6 @@ ATTRIBUTES
 * implement an option to "attr upgrade" for reading upgrade/downgrade
   plugins/instructions from an external file for 3rd party use.
 
-* prevent nirt from outputting a trailing space after values when
-  there are no attributes to be displayed.  the problem is in the nirt
-  format strings where they use " %s" for displaying any attributes.
-  need to left-pad a space conditionally, perhaps by supporting %*s
-  and sizeof(var).
-
 * add additional support for user-specified sorting for the attr
   command when new attribute attributes are added (e.g., creation
   date)
@@ -2585,8 +2540,6 @@ DOCUMENTATION
 
 * Need ability to search manual pages
 
-* rename MGED Help->Apropos to Help->Search Commands (apropos)
-
 * BRL-CAD Primitives
 	An overview of the various primitive object types in BRL-CAD,
 	their range of features, and a description of their input
@@ -2603,10 +2556,6 @@ DOCUMENTATION
   various image formats like png just by specifying an output file
   extension.
 
-* document gqa centroid and moments of inertia options
-
-* document the new NURBS/BREP primitive, capabilities and limitations
-
 
   Need to revisit utility of spherical mapping, used by sh_spm and
   sh_points, used for environment mapping (e.g., stars):
@@ -2646,13 +2595,6 @@ DOCUMENTATION
     tgf-g
 
 
-* write up some documentation on other build tools besides make -
-  CMake supports other generators, wouldn't hurt to detail how to
-  trigger builds in them (MSVC is partially covered, make sure to
-  coverage is complete - others include Eclipse, XCode once we get the
-  kinks ironed out there, CodeBlocks.  Ninja build tool and its
-  CMake support are worth documenting too.
-
 * all of the rt* tracers share common code and common options, but do
   not share common documentation.  refactor documentation to use
   include directives so that there is one place where all of the

annot_viewobj.txt

@@ -0,0 +1,246 @@
+Annotation and view-object rendering notes
+==========================================
+
+Scope
+-----
+
+BRL-CAD has two related, but deliberately distinct, ways to represent visual
+markup:
+
+* An annotation is an ID_ANNOT database primitive.  It is persistent model
+  content with enough semantic and presentation information to be reproduced
+  outside the application that created it.
+* A view object is application-owned scene state.  It is useful for interactive
+  construction and manipulation, but is intentionally not backed by a database
+  object.
+
+They share portions of the interactive display infrastructure, but they do not
+currently have interchangeable ownership, lifetime, or rendering semantics.
+
+
+Annotation capabilities
+-----------------------
+
+An rt_annot_internal stores a model-space anchor, a set of 2D vertices, and
+either a model plane basis or screen-space placement.  Its segment types cover
+lines, circular arcs, NURBS, Beziers, text, and filled polygons.  Segment style
+records include a semantic role, line pattern and width, RGBA color, font or
+symbol, text scaling, and decorative flags.
+
+The libged annotate command can create styled text, leaders, linear/angular/
+radius/diameter/ordinate dimensions, and bounding-box autodim groups.  It can
+regenerate derived annotations from saved attributes and associate them with
+source model objects without making them part of those objects' CSG trees.
+
+Annotations therefore have the properties needed for persistent markup:
+
+* database naming, paths, transforms, and instances;
+* survival across save/reopen and transfer to another application;
+* semantic segment roles and per-segment presentation data;
+* model-space and view-dependent screen-space placement; and
+* high-level generation metadata and source-object associations.
+
+An annotation is informational coverage, not a CSG solid.  The raytracing
+implementation preserves that distinction.  It prepares annotation coverage
+from active database paths and composites it on primary samples after ordinary
+geometry has established color and depth.  Model-space annotation coverage is
+occluded by nearer solid geometry.  Screen-space annotation coverage uses the
+render view and image dimensions.  Annotations do not acquire artificial
+volume, alter model bounds, cast shadows, or participate in reflection and
+refraction rays.
+
+Visible coverage is returned in back-to-front layers.  Model-space layers are
+ordered by ray distance, followed by view-space layers ordered by projected
+anchor depth; segment draw order breaks ties within an annotation.  This lets
+the image renderers apply source-over alpha consistently while retaining the
+single-frontmost-hit query for compatibility.  NIRT continues to report one
+frontmost segment per model-space annotation rather than exposing these
+presentation layers as solid partitions.
+
+Color follows normal database tree state.  An annotation segment with an
+explicit RGBA style wins; otherwise it inherits the resolved combination-path
+color; otherwise it is white.  The legacy region-ID color table is not applied
+to annotation display or coverage, since annotations are informational leaves
+rather than regions.
+
+Prepared coverage uses the existing libbg RTree implementation.  A 3D RTree
+culls model-space annotation instances and a 2D local RTree culls segments
+inside every annotation.  Screen-space instance extents cannot be placed in a
+static world-space index because they change with the view, so those instances
+remain in a compact list while still using their local segment RTree.  This
+avoids a new spatial data structure and keeps prepared scenes immutable and
+safe for concurrent sample queries.
+
+The rt, ART, and ADRT/ISST integrations follow this overlay model.  ERT invokes
+rt with the database, displayed database paths, and view, so database-backed
+annotations can follow that route as well.  ERT does not currently serialize
+or pass application-owned view objects to its subprocess.
+
+NIRT keeps annotation diagnostics opt-in.  `useannot 1` enables model-space
+annotation intersections, and the `fmt a` action reports them.  Default NIRT
+output is unchanged.  Screen-space annotations are deliberately omitted
+because a NIRT ray does not define an image size, pixel footprint, or complete
+model-to-view mapping.
+
+
+View-object capabilities
+------------------------
+
+The core representation is bv_scene_obj.  A view set owns shared view objects,
+and a particular bview can also own local objects.  Independent views force
+local ownership.  bv_obj_put recycles objects when their application lifetime
+ends; the objects are not written to the .g database.
+
+The `view obj` command exposes the principal markup types:
+
+* Lines are model-coordinate polylines represented by vlists.  Generic scene
+  rendering can add arrowheads to segment ends.
+* Labels have a model anchor and optional model-space target/leader.  Their text
+  is projected and drawn as screen-facing HUD text.  If the command omits Z,
+  screen X/Y coordinates are projected onto the current view plane at creation
+  time.
+* Polygons include general polygons, circles, ellipses, rectangles, and
+  squares.  Creation and editing operate on a saved view plane with a view-Z
+  offset.  Selection, movement, open/close, area, overlap, and 2D boolean
+  operations are supported.  A "fill" is currently a set of hatch lines, not
+  an opaque surface.  Polygons can be explicitly imported from or exported to
+  persistent sketch primitives.
+
+Scene objects also provide object color, transparency, pixel line width, dash
+style, and arrow dimensions.  Not all of these properties have a uniform
+command interface for every object type.
+
+There are other visual layers that should not be conflated with these objects.
+Legacy gv_tcl data/sdata arrows, axes, lines, labels, and polygons have a
+separate representation.  Faceplate/HUD elements are screen UI.  Database
+objects temporarily cloned for editing are also transient, but retain database
+primitive semantics and live in the database-object scene containers.
+
+
+Comparison
+----------
+
+Both annotations and view objects eventually produce display-manager pixels,
+often through bv_scene_obj and vlists.  That common final path does not make
+their source representations equivalent.
+
+Annotations are the canonical choice when markup must be saved, named in a
+database, instanced, shared, raytraced from a .g file, or understood by another
+program.  View objects are the right choice for application/session state that
+must be created and manipulated without changing the database.
+
+Some view objects have a direct annotation analogue, but conversion is not
+lossless without type-aware logic:
+
+* A view polyline maps naturally to line segments, including arrowhead style.
+* A polygon outline and its hatch lines can map to annotation coverage, but the
+  existing view "fill" must not silently become an opaque filled polygon.
+* A label is hybrid.  Its target and leader are model-space geometry while its
+  glyphs remain screen-facing at a projected model anchor.
+* Arbitrary vlist extraction is insufficient because display-matrix commands,
+  point and line sizes, child objects, glyph behavior, and semantic roles are
+  otherwise lost or ambiguous.
+
+View-object line width and annotation line width also need an explicit unit
+policy.  View-object widths are display pixels.  Screen-space annotation widths
+are view-dependent coverage widths.  A model-space annotation's line_width is
+used as a scale on the automatically selected model-space stroke width.  In
+other words, removing a separate raytracer "stroke-width" setting does not
+remove width control: the annotation's existing line_width/`--line-width`
+style remains the single user-facing control.  The renderer interprets it in
+the appropriate coordinate system rather than exposing a second competing
+knob.
+
+
+Recommended transient rendering design
+--------------------------------------
+
+Do not make librt or the raytracers depend on bv_scene_obj, libbv application
+containers, or libged.  Do not manufacture tubes, TGCs, meshes, or geometry
+just in front of the view plane.  Artificial geometry would affect bounds,
+depth, shadows, and secondary rays, and would make antialiasing and perspective
+behavior depend on a fabricated distance from the eye.
+
+If transient view objects need to appear in raytraced output, use an explicit
+application-to-renderer snapshot boundary:
+
+1. The GED/application layer snapshots selected live view objects when a render
+   is launched.  This is the only layer that owns their lifetime and semantics.
+2. A type-aware adapter in libged or libbv translates supported objects into a
+   renderer-neutral overlay/coverage description.  It should reuse annotation
+   coverage preparation through an in-memory annotation-instance interface,
+   rather than duplicate line, glyph, and arrow intersection algorithms.
+3. The snapshot travels with the exact view state: model-to-view transform,
+   perspective, image width and height, and sampling convention.  In-process
+   renderers can receive it directly; subprocess rt/ERT needs an explicit
+   serialized side channel.
+4. Raytracers composite this coverage only on primary image samples, after
+   geometry color and depth are known.  It remains outside CSG, model bounds,
+   shadows, reflections, and refractions.
+5. Initial support should be deliberately finite: polyline strokes and
+   arrowheads, label glyphs and leaders, polygon outlines, and polygon hatches.
+   Faceplate elements and legacy gv_tcl overlays should be separately specified
+   opt-in layers rather than being included accidentally.
+6. Snapshot records should preserve object name and type, RGBA, visibility,
+   local/shared ownership, presentation units, and source identity.  Unsupported
+   object types should produce a deliberate diagnostic or documented omission.
+
+Application-side compositing of the interactive display-manager layer over an
+ERT framebuffer is a viable smaller feature if only ERT screen captures need
+view objects.  It would closely reproduce the interactive view, but it would
+not make the objects available to standalone rt, ART, or ISST output and should
+not be presented as the general renderer solution.
+
+Conversion between the two systems should remain explicit.  Automatically
+turning view objects into database annotations would violate their deliberately
+transient contract.  A user command to promote selected view markup to a
+persistent annotation would be reasonable; polygon-to-sketch export is an
+existing precedent.  Conversely, a view-object editor may be used as a front
+end for constructing an annotation, provided the persistence action is clear.
+
+
+Maintenance findings before implementing the adapter
+----------------------------------------------------
+
+Several representation issues should be corrected before type-driven snapshot
+conversion is relied upon:
+
+* Container-selection flags (BV_DB_OBJS, BV_VIEW_OBJS, BV_LOCAL_OBJS, and
+  BV_CHILD_OBJS) reuse numeric bits also used for semantic s_type_flags
+  (BV_DBOBJ_BASED, BV_VIEWONLY, BV_LINES, and others).  bv_obj_create currently
+  assigns its type argument to s_type_flags.  A local view object consequently
+  acquires BV_LINES incidentally, while the line command does not explicitly
+  tag lines.  The namespaces should be separated and every object explicitly
+  typed.
+* Lines, labels, and polygons should have unambiguous type tags and per-type
+  lifecycle/extraction callbacks.  Snapshot conversion must inspect typed data,
+  not infer semantics from a rendered vlist.
+* Label construction should initialize every bv_label field deliberately,
+  including size, line_flag, anchor, arrow, and target.  Current construction
+  does not establish all of those values on every path.
+* The status of legacy gv_tcl overlay data should be decided explicitly:
+  migrate it, support it through a separate adapter, or document its exclusion.
+* Screen-space annotation display and raytrace units need a parity test.  The
+  legacy display-matrix vlist path and the ray coverage path currently express
+  screen offsets through different mechanisms; their apparent agreement must
+  be verified rather than assumed.
+* Per-segment annotation colors exceed the legacy interactive vlist object's
+  single-color model.  Uniform annotate-command colors work today, but true
+  multicolor interactive parity may require split scene objects or a richer
+  display representation.
+
+Tests for a future adapter should cover shared and local ownership, cleanup,
+label anchors and leaders, polygon holes/hatches/view-Z, perspective, pixel
+width, model-space occlusion, screen-space overlay, and serialization across
+the ERT subprocess boundary.
+
+
+Conclusion
+----------
+
+Persistent annotations and transient view objects should continue to coexist.
+The annotation coverage scene is the correct renderer-side abstraction for
+both saved annotations and a future snapshot of transient markup.  The
+application should perform the semantic conversion and transfer a view-complete
+snapshot; the renderer should treat it as primary-ray coverage, never as
+invented scene geometry.

bench/CMakeLists.txt

@@ -3,6 +3,12 @@ add_subdirectory(ref)
 add_definitions(-DCONSOLE)
 
 brlcad_addexec(pixcmp pixcmp.c libbu)
+brlcad_add_test(
+  NAME bench_pixcmp_tolerance
+  COMMAND
+    ${CMAKE_COMMAND} "-DPIXCMP=$<TARGET_FILE:pixcmp>" "-DTEST_DIR=${CMAKE_CURRENT_BINARY_DIR}"
+    -P "${CMAKE_CURRENT_SOURCE_DIR}/pixcmp_test.cmake"
+)
 set(BARK_SOURCES benchmark.c compute.c run.c clean.c)
 brlcad_addexec(bark "${BARK_SOURCES}" "libbu;${M_LIBRARY}" NO_STRICT NO_INSTALL TEST_USESDATA)
 
@@ -38,6 +44,7 @@ file(
 
 cmakefiles(
   CMakeLists.txt
+  pixcmp_test.cmake
   run.sh
   try.sh
   viewdiff.sh

bench/benchmark.c

@@ -237,7 +237,7 @@ set_if_unset(void (*echo)(const char *, ...), void (*verbose)(const char *, ...)
     }
 
     setval = getenv(var);
-    echo("Using [%s] for %s\n", setval, var);
+    echo("Using [%s] for %s\n", setval ? setval : "", var);
 }
 
 
@@ -589,6 +589,7 @@ main(int ac, char *av[])
     {
 	struct bu_vls v = BU_VLS_INIT_ZERO;
 	char rfc2822[1024] = {0};
+	const char *logfile = getenv("LOGFILE");
 #ifdef HAVE_SYS_UTSNAME_H
 	struct utsname n;
 	time_t t = time(NULL);
@@ -604,7 +605,7 @@ main(int ac, char *av[])
 	echo("B R L - C A D   B E N C H M A R K\n");
 	echo("=================================\n");
 	echo("Running %s on %s\n", av[0], rfc2822);
-	echo("Logging output to %s\n", getenv("LOGFILE"));
+	echo("Logging output to %s\n", logfile ? logfile : "disabled");
 	echo("%s\n\n", bu_vls_addr(&v));
     }
 
@@ -653,6 +654,7 @@ main(int ac, char *av[])
 	bu_setenv("PIX", bu_path_dirname(getenv("PIX")), 1);
     }
 
+    const char *pix_env = getenv("PIX");
     bu_vls_printf(&vp,
 		  "%s "
 		  "%s "
@@ -661,7 +663,7 @@ main(int ac, char *av[])
 		  "%s/../../pix "
 		  "%s/../../../pix "
 		  "./pix",
-		  getenv("PIX"), pix, thisp, thisp, thisp, thisp);
+		  pix_env ? pix_env : "", pix, thisp, thisp, thisp, thisp);
     bu_argv_from_string(argv, 32, bu_vls_addr(&vp));
     look_for(verbose_echo, directory, "a benchmark reference log directory", "LOG", (const char **)argv);
     bu_vls_trunc(&vp, 0);

bench/pixcmp.c

@@ -160,44 +160,38 @@ compare_rgb(int r1, int g1, int b1, int r2, int g2, int b2, size_t *matching, si
 	&& (b1 == b2 && b1 != -1))
     {
 	result = MATCHING;
-	(*matching)++;
     } else if (r1 == -1 || r2 == -1 || g1 == -1 || g2 == -1 || b1 == -1 || b2 == -1) {
 	/* image sizes don't match (or other I/O error) */
 	result = MISSING;
-	(*missing)++;
-    } else if (((r1 != r2) && (g1 == g2) && (b1 == b2))
-	       || ((r1 == r2) && (g1 != g2) && (b1 == b2))
-	       || ((r1 == r2) && (g1 == g2) && (b1 != b2)))
-    {
-	/* off by one channel */
+    } else {
+	/* at least this */
+	result = OFF_BY_ONE;
+
+	/* but maybe more */
 	if (r1 != r2) {
 	    if ((r1 > r2 ? r1 - r2 : r2 - r1) > 1) {
 		result = OFF_BY_MANY;
-		(*offmany)++;
-	    } else {
-		result = OFF_BY_ONE;
-		(*off1)++;
-	    }
-	} else if (g1 != g2) {
-	    if ((g1 > g2 ? g1 - g2 : g2 - g1) > 1) {
-		result = OFF_BY_MANY;
-		(*offmany)++;
-	    } else {
-		result = OFF_BY_ONE;
-		(*off1)++;
-	    }
-	} else if (b1 != b2) {
-	    if ((b1 > b2 ? b1 - b2 : b2 - b1) > 1) {
-		result = OFF_BY_MANY;
-		(*offmany)++;
-	    } else {
-		result = OFF_BY_ONE;
-		(*off1)++;
 	    }
 	}
-    } else {
-	result = OFF_BY_MANY;
+	if (g1 != g2) {
+	    if ((g1 > g2 ? g1 - g2 : g2 - g1) > 1) {
+		result = OFF_BY_MANY;
+	    }
+	}
+	if (b1 != b2) {
+	    if ((b1 > b2 ? b1 - b2 : b2 - b1) > 1) {
+		result = OFF_BY_MANY;
+	    }
+	}
+    }
+    if (result == OFF_BY_ONE) {
+	(*off1)++;
+    } else if (result == OFF_BY_MANY) {
 	(*offmany)++;
+    } else if (result == MATCHING) {
+	(*matching)++;
+    } else {
+	(*missing)++;
     }
 
     return result;
@@ -346,7 +340,7 @@ main(int argc, char *argv[])
 	bu_log("Warning - f2 fstat failed: %s\n", strerror(errno));
     }
 
-    bu_log("FILE1_size(%zu) FILE1_skip(%zu) FILE2_size(%zu) FILE2_skip(%zu)\n", (size_t)sf1.st_size, f1_skip, (size_t)sf2.st_size, f2_skip);
+    /* bu_log("FILE1_size(%zu) FILE1_skip(%zu) FILE2_size(%zu) FILE2_skip(%zu)\n", (size_t)sf1.st_size, f1_skip, (size_t)sf2.st_size, f2_skip); */
 
     if (!quiet && ((sf1.st_size - f1_skip) != (sf2.st_size - f2_skip))) {
 	bu_log("WARNING: Different image sizes detected\n");

bench/pixcmp_test.cmake

@@ -0,0 +1,80 @@
+# Exercise pixcmp's pixel tolerance and exit-status contract with small,
+# deliberately readable byte streams.
+
+if(NOT PIXCMP OR NOT TEST_DIR)
+  message(FATAL_ERROR "PIXCMP and TEST_DIR are required")
+endif()
+
+function(check_pixcmp name input1 input2 expected_status expected_summary)
+  set(file1 "${TEST_DIR}/pixcmp_${name}_1.pix")
+  set(file2 "${TEST_DIR}/pixcmp_${name}_2.pix")
+
+  file(WRITE "${file1}" "${input1}")
+  file(WRITE "${file2}" "${input2}")
+
+  execute_process(
+    COMMAND "${PIXCMP}" ${ARGN} "${file1}" "${file2}"
+    OUTPUT_VARIABLE output
+    ERROR_VARIABLE errors
+    RESULT_VARIABLE status
+  )
+
+  file(REMOVE "${file1}" "${file2}")
+
+  if(NOT "${status}" STREQUAL "${expected_status}")
+    message(
+      FATAL_ERROR
+      "${name}: pixcmp returned ${status}, expected ${expected_status}\nstdout: ${output}\nstderr: ${errors}"
+    )
+  endif()
+
+  string(REGEX REPLACE "[ \t\r\n]+" " " normalized_output "${output}")
+  string(STRIP "${normalized_output}" normalized_output)
+  string(FIND "${normalized_output}" "${expected_summary}" summary_position)
+  if(summary_position EQUAL -1)
+    message(
+      FATAL_ERROR
+      "${name}: expected summary '${expected_summary}'\nactual stdout: ${output}\nstderr: ${errors}"
+    )
+  endif()
+endfunction()
+
+set(exact_pixel "pixcmp pixels: 1 matching, 0 off by 1, 0 off by many")
+set(tolerated_pixel "pixcmp pixels: 0 matching, 1 off by 1, 0 off by many")
+set(rejected_pixel "pixcmp pixels: 0 matching, 0 off by 1, 1 off by many")
+
+check_pixcmp(exact "ABC" "ABC" 0 "${exact_pixel}")
+check_pixcmp(one_channel_within_tolerance "ABC" "BBC" 1 "${tolerated_pixel}")
+check_pixcmp(two_channels_within_tolerance "ABC" "BCC" 1 "${tolerated_pixel}")
+check_pixcmp(three_channels_within_tolerance "ABC" "@CB" 1 "${tolerated_pixel}")
+
+# Keep the tolerated channel first in two cases to catch short-circuiting that
+# would fail to inspect a later channel outside the tolerance.
+check_pixcmp(red_outside_tolerance "ABC" "CCD" 2 "${rejected_pixel}")
+check_pixcmp(green_outside_tolerance "ABC" "BDD" 2 "${rejected_pixel}")
+check_pixcmp(blue_outside_tolerance "ABC" "BCE" 2 "${rejected_pixel}")
+
+check_pixcmp(
+  missing_pixel
+  "ABC"
+  "ABCDEF"
+  2
+  "pixcmp pixels: 1 matching, 0 off by 1, 0 off by many, 1 missing"
+)
+
+check_pixcmp(
+  byte_within_tolerance
+  "A"
+  "B"
+  1
+  "pixcmp bytes: 0 matching, 1 off by 1, 0 off by many"
+  -b
+)
+check_pixcmp(
+  byte_outside_tolerance
+  "A"
+  "C"
+  2
+  "pixcmp bytes: 0 matching, 0 off by 1, 1 off by many"
+  -b
+)

bench/run.sh

@@ -750,9 +750,9 @@ run ( ) {
 	\"${DB}/${run_geomname}.g\" ${run_geometry} 1>&2 <<EOF
 $run_view
 EOF
-    retval=$?
-    $VERBOSE_ECHO "DEBUG: Running $RT returned $retval"
-    return $retval
+    run_retval=$?
+    $VERBOSE_ECHO "DEBUG: Running $RT returned $run_retval"
+    return $run_retval
 }
 
 
@@ -986,6 +986,7 @@ bench ( ) {
     bench_frame=0
     bench_rtfms=""
     bench_percent=100
+    bench_retval=0
     bench_start_time="`date '+%H %M %S'`"
     bench_overall_elapsed=-1
 
@@ -1009,7 +1010,10 @@ $bench_view
 start $bench_frame;
 end;
 EOF
-	    retval=$?
+	    bench_raytrace_retval=$?
+	    if test $bench_raytrace_retval != 0 ; then
+		bench_retval=$bench_raytrace_retval
+	    fi
 
 	    if test $bench_frame -ne 0 ; then
 		if test -f ${bench_testname}.pix.$bench_frame ; then
@@ -1083,7 +1087,7 @@ EOF
 	    fi
 
 	    # did we fail?
-	    if test $retval != 0 ; then
+	    if test $bench_raytrace_retval != 0 ; then
 		$ECHO "RAYTRACE ERROR"
 		break
 	    fi
@@ -1148,27 +1152,34 @@ EOF
 	ls -la *.pix*
     fi
     $VERBOSE_ECHO "DEBUG: $CMP $PIX/${bench_testname}.pix ${bench_testname}.pix"
-    cmp_result="`eval \\\"${CMP}\\\" \\\"${PIX}/${bench_testname}.pix\\\" ${bench_testname}.pix 2>&1 | grep pixels`"
-    ret=$?
+    cmp_result="`eval \\\"${CMP}\\\" \\\"${PIX}/${bench_testname}.pix\\\" ${bench_testname}.pix 2>&1`"
+    bench_cmp_retval=$?
 
-    $ECHO "$cmp_result"
+    pixels_result="`echo \\\"$cmp_result\\\" | grep pixels`"
+    if test "x$pixels_result" = "x" ; then
+	$ECHO "$cmp_result"
+    else
+	$ECHO "$pixels_result"
+    fi
 
-    if test $ret = 0 ; then
+    if test $bench_cmp_retval = 0 ; then
 	# perfect match
 	$ECHO ${bench_testname}.pix:  answers are RIGHT
-    elif test $ret = 1 ; then
+    elif test $bench_cmp_retval = 1 ; then
 	# off by one, acceptable
 	$ECHO ${bench_testname}.pix:  answers are RIGHT
-    elif test $ret = 2 ; then
+    elif test $bench_cmp_retval = 2 ; then
 	# off by many, unacceptable
 	$ECHO ${bench_testname}.pix:  WRONG WRONG WRONG WRONG WRONG WRONG
+	bench_retval=$bench_cmp_retval
     else
 	# some other failure
 	$ECHO ${bench_testname}.pix:  BENCHMARK COMPARISON FAILURE
+	bench_retval=$bench_cmp_retval
     fi
 
     $VERBOSE_ECHO "DEBUG: Done benchmark testing on $bench_testname"
-    return $retval
+    return $bench_retval
 }
 
 
@@ -1316,7 +1327,7 @@ perf ( ) {
 start="`date '+%H %M %S'`"
 $ECHO "Running the BRL-CAD Benchmark tests... please wait ..."
 $ECHO
-ret=0
+benchmark_retval=0
 
 bench moss all.g $RTARGS << EOF
 viewsize 1.572026215e+02;
@@ -1326,7 +1337,7 @@ viewrot -5.735764503e-01 8.191520572e-01 0.000000000e+00 0.000000000e+00
 	7.424039245e-01 5.198368430e-01 4.226182699e-01 0.000000000e+00
 	0.000000000e+00 0.000000000e+00 0.000000000e+00 1.000000000e+00 ;
 EOF
-ret=`expr $ret + $?`
+benchmark_retval=`expr $benchmark_retval + $?`
 
 bench world all.g $RTARGS << EOF
 viewsize 1.572026215e+02;
@@ -1336,7 +1347,7 @@ viewrot -5.735764503e-01 8.191520572e-01 0.000000000e+00 0.000000000e+00
 	7.424039245e-01 5.198368430e-01 4.226182699e-01 0.000000000e+00
 	0.000000000e+00 0.000000000e+00 0.000000000e+00 1.000000000e+00 ;
 EOF
-ret=`expr $ret + $?`
+benchmark_retval=`expr $benchmark_retval + $?`
 
 bench star all $RTARGS << EOF
 viewsize 2.500000000e+05;
@@ -1346,7 +1357,7 @@ viewrot -6.733560560e-01 6.130643360e-01 4.132114880e-01 0.000000000e+00
 	4.896120540e-01 7.885590550e-01 -3.720948210e-01 0.000000000e+00
 	0.000000000e+00 0.000000000e+00 0.000000000e+00 1.000000000e+00 ;
 EOF
-ret=`expr $ret + $?`
+benchmark_retval=`expr $benchmark_retval + $?`
 
 bench bldg391 all.g $RTARGS << EOF
 viewsize 1.800000000e+03;
@@ -1356,7 +1367,7 @@ viewrot -5.735764503e-01 8.191520572e-01 0.000000000e+00 0.000000000e+00
 	7.424039245e-01 5.198368430e-01 4.226182699e-01 0.000000000e+00
 	0.000000000e+00 0.000000000e+00 0.000000000e+00 1.000000000e+00;
 EOF
-ret=`expr $ret + $?`
+benchmark_retval=`expr $benchmark_retval + $?`
 
 bench m35 all.g $RTARGS <<EOF
 viewsize 6.787387985e+03;
@@ -1366,14 +1377,14 @@ viewrot -5.527838919e-01 8.332423558e-01 1.171090926e-02 0.000000000e+00
 	6.800964482e-01 4.429747496e-01 5.841593895e-01 0.000000000e+00
 	0.000000000e+00 0.000000000e+00 0.000000000e+00 1.000000000e+00 ;
 EOF
-ret=`expr $ret + $?`
+benchmark_retval=`expr $benchmark_retval + $?`
 
 bench sphflake scene.r $RTARGS <<EOF
 viewsize 2.556283261452611e+04;
 orientation 4.406810841785839e-01 4.005093234738861e-01 5.226451688385938e-01 6.101102288499644e-01;
 eye_pt 2.418500583758302e+04 -3.328563644344796e+03 8.489926952850350e+03;
 EOF
-ret=`expr $ret + $?`
+benchmark_retval=`expr $benchmark_retval + $?`
 
 $ECHO
 $ECHO "... Done."
@@ -1381,7 +1392,7 @@ $ECHO
 $ECHO "Total testing time elapsed: `eval \\\"$ELP\\\" $start`"
 
 # see if we fail
-if test ! "x$ret" = "x0" ; then
+if test ! "x$benchmark_retval" = "x0" ; then
     $ECHO
     $ECHO "THE BENCHMARK ANALYSIS DID NOT COMPLETE SUCCESSFULLY."
     $ECHO

db/CMakeLists.txt

@@ -1,6 +1,7 @@
 function(G_TARGET in_model folder)
   # Initialize
   set(MODEL_TYPE "UNKNOWN")
+  set(CONV_SUCCESS_CODES 0)
 
   # Regardless of what we decide, let CMake know about the file
   cmakefiles(${CMAKE_CURRENT_SOURCE_DIR}/${in_model})
@@ -25,6 +26,7 @@ function(G_TARGET in_model folder)
   # Find our output file and path
   string(REPLACE "${CMAKE_SOURCE_DIR}/" "" rel_dir "${CMAKE_CURRENT_SOURCE_DIR}")
   set(output_file ${DATA_DIR}/${rel_dir}/${in_model_root}.g)
+  set(CONV_OUTPUT_PATH "${CMAKE_BINARY_DIR}/${output_file}")
   set(log_file ${CMAKE_CURRENT_BINARY_DIR}/${in_model_root}.log)
 
   # Make sure the output db target directory is there
@@ -116,6 +118,10 @@ function(G_TARGET in_model folder)
       return()
     endif(NOT TARGET step-g)
     set(CONV_ARGS "-O \"${CMAKE_BINARY_DIR}/${output_file}\" \"${CMAKE_CURRENT_SOURCE_DIR}/${in_model}\"")
+    # step-g uses status 1 for useful, deliberately published partial output.
+    # Installed sample databases should retain that geometry; statuses 2 and
+    # above, or a missing output file, remain build failures.
+    set(CONV_SUCCESS_CODES "0;1")
     configure_file("${CMAKE_SOURCE_DIR}/db/to_g.cmake.in" "${CMAKE_CURRENT_BINARY_DIR}/${in_model_root}.cmake" @ONLY)
     distclean("${CMAKE_CURRENT_BINARY_DIR}/${in_model_root}.cmake")
     # Custom command to generate the output
@@ -203,6 +209,7 @@ set(
   demo.asc
   die.asc
   earth.asc
+  gaia.asc
   galileo.asc
   goliath.asc
   havoc.asc

db/to_g.cmake.in

@@ -35,10 +35,12 @@ execute_process(
   ERROR_VARIABLE conv_log
 )
 
-if(conv_result)
+set(conv_success_codes "@CONV_SUCCESS_CODES@")
+list(FIND conv_success_codes "${conv_result}" conv_result_index)
+if(conv_result_index EQUAL -1 OR NOT EXISTS "@CONV_OUTPUT_PATH@")
   set(CARGS @CONV_ARGS@)
   message(FATAL_ERROR "[@in_model_root@] Failure: ${conv_result}\n${CONV_EXEC} ${CARGS}\"\n\n${conv_log}")
-endif(conv_result)
+endif()
 
 # Cleanup
 execute_process(

doc/CMakeLists.txt

@@ -13,8 +13,6 @@ set(
   README.MacOSX
   README.Windows
   README.BSD
-  README.Solaris
-  README.VAX
   checklist.txt
   description.txt
   optimization_ideas.adoc
@@ -29,6 +27,7 @@ set(
   notes/editors.txt
   notes/history.txt
   notes/hypot.txt
+  notes/itcl4_migration.txt
   notes/mater.txt
   notes/matrix.txt
   pre_BRL-CAD.bib
@@ -217,6 +216,8 @@ endif(TARGET mged)
 
 cmakefiles(
   CMakeLists.txt
+  README.Solaris
+  README.VAX
   README.adoc
   STARTERS
   STRATEGY

doc/README.Solaris

@@ -1,3 +1,7 @@
+*** ARCHIVED -- legacy platform, no longer supported (retained for
+*** historical reference). This document is not installed and is kept
+*** only to preserve the historical record.
+
 BRL-CAD on Solaris README
 =========================
 There have been a variety of Solaris-style operating systems that appeared

doc/README.VAX

@@ -1,3 +1,7 @@
+*** ARCHIVED -- legacy platform, no longer supported (retained for
+*** historical reference). This document is not installed and is kept
+*** only to preserve the historical record.
+
 BRL-CAD on VAX README
 =====================
 

doc/README.adoc

@@ -33,7 +33,7 @@ toc::[]
 
 === Prerequisites
 To build BRL-CAD from source, you will need:
-* **CMake** (3.14+)
+* **CMake** (3.26+)
 * **C/C++ Compiler** (GCC, Clang, or MSVC)
 * **Build Tools** (Make, Ninja, or Visual Studio)
 
@@ -53,7 +53,7 @@ For detailed installation instructions across different platforms, please refer
 
 == Documentation
 
-We are currently transitioning our extensive documentation (Docbook/XML + MediaWiki + troff + text + ...) to an **Antora-powered ecosystem**.
+We have consolidated our extensive documentation (formerly a mix of DocBook/XML, MediaWiki, troff, plain text, and more) onto **AsciiDoc**, with the authoritative sources under `doc/asciidoc/`.
 
 * **Tutorials:** link:{docs-url}/tutorials[Browse the Manuals]
 * **Developer Guides:** link:{docs-url}/hacking and link:{repo-url}/blob/main/HACKING

doc/asciidoc/CMakeLists.txt

@@ -1,5 +1,6 @@
 include(${BRLCAD_CMAKE_DIR}/AsciiDoc.cmake)
 
+verbose_add_subdirectory(asciidoc toplevel)
 verbose_add_subdirectory(asciidoc system)
 verbose_add_subdirectory(asciidoc articles)
 verbose_add_subdirectory(asciidoc books)

doc/asciidoc/README.adoc

@@ -4,15 +4,14 @@
 
 == Overview
 
-This directory contains BRL-CAD documentation in AsciiDoc format, converted
-from the original DocBook 5 XML sources in `../docbook/`.  The conversion was
-performed once using
-link:../../misc/tools/db2adoc/db2adoc.xsl[db2adoc.xsl] (an XSLT stylesheet)
-applied via `xsltproc`.
+This directory contains BRL-CAD documentation in AsciiDoc format.  The `.adoc`
+files here are the authoritative documentation sources and are committed to
+version control.  The one-time conversion from the original DocBook 5 XML
+sources is complete, and those legacy XML sources have been removed; edit the
+`.adoc` files directly.
 
-The `.adoc` files here are committed to version control as authoritative
-sources.  They are built into HTML and man-page outputs at compile time using
-**asciiquack**, BRL-CAD's self-contained AsciiDoc processor.
+The `.adoc` files are built into HTML and man-page outputs at compile time
+using **asciiquack**, BRL-CAD's self-contained AsciiDoc processor.
 
 == Directory Structure
 
@@ -43,28 +42,17 @@ When `BRLCAD_EXTRADOCS=ON` is set at CMake configuration time:
 
 The build logic is in `brlcad/misc/CMake/AsciiDoc.cmake`.
 
-== Re-running the Conversion
+== Authoritative Sources
 
-If the upstream DocBook sources change and you need to re-generate the AsciiDoc
-files, run the XSLT stylesheet from the repository root:
+The `.adoc` files in this directory are the authoritative documentation
+sources.  The one-time conversion from the retired DocBook 5 XML sources is
+complete, so there is no conversion step to re-run: make all documentation
+changes by editing the `.adoc` files directly.
 
-[source,bash]
-----
-BEXT=/path/to/bext_output
-
-for f in $(find doc/docbook -name "*.xml" -not -path "*/resources/*"); do
-  rel=${f#doc/docbook/}
-  out=doc/asciidoc/${rel%.xml}.adoc
-  mkdir -p "$(dirname "$out")"
-  $BEXT/noinstall/bin/xsltproc -xinclude \
-      misc/tools/db2adoc/db2adoc.xsl "$f" > "$out"
-done
-----
-
-Alternatively, use `db2adoc.py` (requires pandoc ≥ 2.0) for a Python-driven
-approach with better round-trip fidelity for complex markup:
-
-[source,bash]
-----
-python3 misc/tools/db2adoc/db2adoc.py
-----
+[NOTE]
+====
+Documentation is built only when CMake is configured with
+`BRLCAD_EXTRADOCS=ON`.  With the default configuration the documentation
+targets are skipped, so remember to enable this option when working on or
+verifying documentation.
+====

doc/asciidoc/articles/CMakeLists.txt

@@ -227,20 +227,21 @@ set(
   images/renderer_gallery_rthide.png
   images/renderer_gallery_rtdepth.png
   images/renderer_gallery_rtxray.png
-  images/adrt_toyjeep_path.png
-  images/adrt_toyjeep_rt.png
-  images/adrt_toyjeep_rt_ao.png
-  images/adrt_toyjeep_phong.png
-  images/adrt_toyjeep_normal.png
-  images/adrt_toyjeep_depth.png
-  images/adrt_chess_path.png
-  images/adrt_chess_rt.png
-  images/adrt_chess_rt_ao.png
   images/adrt_castle_path.png
   images/adrt_castle_rt.png
   images/adrt_castle_rt_ao.png
+  images/adrt_chess_path.png
+  images/adrt_chess_rt.png
+  images/adrt_chess_rt_ao.png
   images/adrt_cornell_path.png
   images/adrt_cornell_phong.png
+  images/adrt_toyjeep_depth.png
+  images/adrt_toyjeep_normal.png
+  images/adrt_toyjeep_path.png
+  images/adrt_toyjeep_phong.png
+  images/adrt_toyjeep_rt.png
+  images/adrt_toyjeep_rt_ao.png
+  images/adrt_toyjeep_spall.png
   images/objtype_arb8.png
   images/objtype_arb8_variety.png
   images/objtype_arbn.png

doc/asciidoc/articles/TEMPLATE.adoc

@@ -71,11 +71,11 @@ More paragraphs...
 
 [CAUTION]
 ====
-There's a lot more you can do with Docbook/XML. Search the web for references and examples:
+There's a lot more you can do with AsciiDoc. Consult the reference documentation for syntax and examples:
 
 
-* http://www.docbook.org/tdg5/en/html/article.html[http://www.docbook.org/tdg5/en/html/article.html]
-* http://www.openoffice.org/xml/xmerge/docbook/UserGuide.html[http://www.openoffice.org/xml/xmerge/docbook/UserGuide.html]
+* https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc Language Documentation]
+* https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc Syntax Quick Reference]
 
 ====
 

doc/asciidoc/articles/build_pattern.adoc

@@ -43,7 +43,7 @@ part.s22 part.s22-1 part.s23 part.s24 part.s24+1 part.s24-1 part.s25,
       
 ....
 
-one needs to determine the span. Note that the leftmost numbers in these primitives range from 22–25.Thus, as shown in the following expression, the span is four (inclusively). *******NEED FIGURE HERE***** If we use an increment of four, we will get the following set of primitives.
+one needs to determine the span. Note that the leftmost numbers in these primitives range from 22 to 25. The span is the count of distinct leftmost numbers taken inclusively, from the lowest through the highest: 22, 23, 24, and 25 -- four values in all. It is computed as (highest - lowest) + 1, that is, (25 - 22) + 1 = 4. If we use an increment of four, each leftmost number is shifted up by four (22 becomes 26, 23 becomes 27, and so on), and we will get the following set of primitives.
 
 
 ....

doc/asciidoc/articles/build_region.adoc

@@ -55,7 +55,7 @@ u wgn.s2 + wgn.s2+1 - wgn.s2-1
     
 ....
 
-If we wanted to make a second subtraction from wgn.s2--say, for a drain hole in the corner of the wagon--we would name that primitive wgn.s2-2 (see Figure F-3). We can break this name down as follows: *****NEED IMAGE HERE*****
+If we wanted to make a second subtraction from wgn.s2--say, for a drain hole in the corner of the wagon--we would name that primitive wgn.s2-2, as shown in <<build_region9>>. We can break this name down as follows: the root name `wgn` identifies the region; `.s2` is the base solid the operation applies to; and the trailing `-2` marks this as the second subtraction from that solid (the first having been `wgn.s2-1`).
 
 [[build_region9]]
 .The region and the subtraction primitives.

doc/asciidoc/articles/gallery/gallery_manifest.cmake

@@ -49,7 +49,7 @@ set(GALLERY_DEMO_14 [=[masonry_sheetrock|Architecture & structural|exec|masonry|
 set(GALLERY_DEMO_15 [=[masonry_brick|Architecture & structural|exec|masonry|-t brick -u in -w 96,48 -n wall|@GLOB@|r.wall.b||ao|masonry wall generator, brick wall type (prototype brick).]=])
 set(GALLERY_DEMO_16 [=[masonry_bm|Architecture & structural|exec|masonry|-t bm -u in -w 96,48 -m 0.25 -n wall|@GLOB@|r.wall.b||ao|masonry wall generator, mortar-brick wall type: brick with horizontal and vertical mortar joints.]=])
 set(GALLERY_DEMO_17 [=[brickwall|Architecture & structural|tomged|brickwall||@OUT@|g.brick||ao|Builds a brick wall: emits mged commands that create RPP brick solids arranged in rows (with optional mortar slabs between them) to fill a specified wall width and height. Output is a stream of mged commands on stdout, not a .g directly.]=])
-set(GALLERY_DEMO_18 [=[mkbuilding|Architecture & structural|exec|mkbuilding|@OUT@|@OUT@|all||ao|Procedurally builds a small building: a floor slab, four framed walls with openings, and an overhanging roof.]=])
+set(GALLERY_DEMO_18 [=[mkbuilding|Architecture & structural|exec|mkbuilding|@OUT@|@OUT@|house||ao|Generates a physically dimensioned building with material-separated walls, slabs, framed openings, roof, and optional structural members; JSON, OSM, and CityJSON specifications can produce full building catalogs.]=])
 set(GALLERY_DEMO_19 [=[cchannel|Architecture & structural|exec|cchannel|-f @OUT@ -H 0.2|@OUT@|channel.r||ao|Creates a section of fully configurable C-channel (structural metal beam). Default is a 1" diameter by 12" long section of American standard C-channel, here generated with a row of drilled holes.]=])
 set(GALLERY_DEMO_20 [=[ringworld|Architecture & structural|exec|ringworld|-o @OUT@|@OUT@|all.g||ao|Generates a "ringworld" as imagined by Larry Niven: a central sun sphere and a large CSG ring (built from three RCCs) orbiting it, combined into a top-level group all.g.]=])
 

doc/asciidoc/articles/gcv.adoc

@@ -49,7 +49,66 @@ The following code illustrates a basic use of GCV from within an application. No
 .gcv_app.c
 [example]
 ====
-TODO: embedded code
+
+[source,c]
+----
+#include "common.h"
+
+#include "bu/log.h"
+#include "bu/mime.h"
+#include "gcv.h"
+
+/* Convert the file at 'in_path' to the file at 'out_path', selecting the
+ * first registered reader and writer filter that match the file types
+ * inferred from the two path extensions.  Returns 0 on success. */
+int
+convert(const char *in_path, const char *out_path)
+{
+    struct gcv_context context;
+    const struct gcv_filter *in_filter, *out_filter;
+    bu_mime_model_t in_type, out_type;
+
+    /* Infer the model file types from the filename extensions. */
+    in_type = (bu_mime_model_t)bu_file_mime(in_path, BU_MIME_MODEL);
+    out_type = (bu_mime_model_t)bu_file_mime(out_path, BU_MIME_MODEL);
+
+    /* A context holds the conversion state, including an in-memory
+     * database used for the intermediate representation. */
+    gcv_context_init(&context);
+
+    /* Look up a reader for the input type and a writer for the output
+     * type.  find_filter() returns the first matching registered filter,
+     * or NULL if none is available. */
+    in_filter = find_filter(GCV_FILTER_READ, in_type, in_path, &context);
+    out_filter = find_filter(GCV_FILTER_WRITE, out_type, NULL, &context);
+
+    if (!in_filter || !out_filter) {
+	bu_log("No filter available for the requested conversion\n");
+	gcv_context_destroy(&context);
+	return 1;
+    }
+
+    /* Read the input into the context's in-memory database.  Passing NULL
+     * for the options selects the defaults from gcv_opts_default().  The
+     * argc/argv pair would carry any filter-specific option strings.
+     * gcv_execute() returns 1 on success and 0 on failure. */
+    if (!gcv_execute(&context, in_filter, NULL, 0, NULL, in_path)) {
+	bu_log("Read filter '%s' failed for '%s'\n", in_filter->name, in_path);
+	gcv_context_destroy(&context);
+	return 1;
+    }
+
+    /* Write the in-memory database out through the selected writer. */
+    if (!gcv_execute(&context, out_filter, NULL, 0, NULL, out_path)) {
+	bu_log("Write filter '%s' failed for '%s'\n", out_filter->name, out_path);
+	gcv_context_destroy(&context);
+	return 1;
+    }
+
+    gcv_context_destroy(&context);
+    return 0;
+}
+----
 
 ====
 
@@ -165,7 +224,57 @@ LIBGCV_ADD_PLUGIN(foo "foo_read.c" "librt;libbu")
 .foo_read.c
 [example]
 ====
-TODO: embedded code
+
+[source,c]
+----
+#include "common.h"
+
+#include "bu/log.h"
+#include "bu/mime.h"
+#include "gcv/api.h"
+#include "wdb.h"
+
+/* The reader callback.  For a GCV_FILTER_READ filter, 'target' is the
+ * path of the input file, and geometry should be written into the
+ * in-memory database reachable through context->dbip.  Return 1 on
+ * success and 0 on failure. */
+static int
+foo_read(struct gcv_context *context, const struct gcv_opts *gcv_options,
+	 const void *UNUSED(options_data), const char *target)
+{
+    struct rt_wdb *wdbp;
+
+    if (gcv_options->verbosity_level)
+	bu_log("Reading foo file: %s\n", target);
+
+    /* Open the context's in-memory database for writing. */
+    wdbp = wdb_dbopen(context->dbip, RT_WDB_TYPE_DB_INMEM);
+    mk_id_units(wdbp, "Converted from foo format", "mm");
+
+    /* ... parse 'target' and create objects with the wdb (mk_*) API,
+     * e.g. mk_sph(), mk_bot(), mk_lcomb() ... */
+
+    return 1;
+}
+
+/* Describe the filter: a unique name, its type, the model type it
+ * handles, and the callbacks.  This reader defines no filter-specific
+ * options, so the create/free option hooks and data_supported are NULL. */
+static const struct gcv_filter gcv_conv_foo_read = {
+    "FOO Reader", GCV_FILTER_READ, BU_MIME_MODEL_FOO, NULL,
+    NULL, NULL, foo_read
+};
+
+/* A plugin exports a NULL-terminated array of its filters ... */
+static const struct gcv_filter * const filters[] = {&gcv_conv_foo_read, NULL};
+
+/* ... referenced by a struct gcv_plugin ... */
+static const struct gcv_plugin gcv_plugin_info_s = { filters };
+
+/* ... which libgcv discovers by dlsym()-ing this exported entry point. */
+COMPILER_DLLEXPORT const struct gcv_plugin *
+gcv_plugin_info(void) { return &gcv_plugin_info_s; }
+----
 
 ====
 
@@ -192,7 +301,89 @@ The following example implements a filter that tessellates all geometry into BoT
 .tessellation_statistics.c
 [example]
 ====
-TODO: embedded code
+
+[source,c]
+----
+#include "common.h"
+
+#include "bu/log.h"
+#include "bu/mime.h"
+#include "nmg.h"
+#include "rt/geom.h"
+#include "raytrace.h"
+#include "gcv/api.h"
+#include "gcv/util.h"
+
+/* State shared with the region-end callback. */
+struct tess_stats {
+    size_t face_count;
+};
+
+/* Invoked once per region by gcv_region_end() after the region's leaf
+ * meshes have been Boolean-evaluated into a single NMG region 'r'.  Here
+ * we simply tally the outward-facing (OT_SAME) faces.  This routine must
+ * be prepared to run in parallel. */
+static void
+count_region_faces(struct nmgregion *r, const struct db_full_path *UNUSED(pathp),
+		   struct db_tree_state *UNUSED(tsp), void *client_data)
+{
+    struct tess_stats *stats = (struct tess_stats *)client_data;
+    struct shell *s;
+
+    NMG_CK_REGION(r);
+
+    for (BU_LIST_FOR(s, shell, &r->s_hd)) {
+	struct faceuse *fu;
+	for (BU_LIST_FOR(fu, faceuse, &s->fu_hd)) {
+	    if (fu->orientation != OT_SAME)
+		continue;
+	    bu_semaphore_acquire(BU_SEM_GENERAL);
+	    stats->face_count++;
+	    bu_semaphore_release(BU_SEM_GENERAL);
+	}
+    }
+}
+
+/* A GCV_FILTER_FILTER receives a NULL target and operates on the geometry
+ * already present in context->dbip.  Return 1 on success, 0 on failure. */
+static int
+tessellation_statistics(struct gcv_context *context, const struct gcv_opts *gcv_options,
+			const void *UNUSED(options_data), const char *UNUSED(target))
+{
+    struct tess_stats stats = {0};
+    struct gcv_region_end_data end_data;
+    struct db_tree_state tree_state;
+    struct model *the_model = nmg_mm();
+
+    /* Configure the tree-walk state: tolerances come from the conversion
+     * options, and ts_m provides the NMG model used during tessellation. */
+    RT_DBTS_INIT(&tree_state);
+    tree_state.ts_tol = &gcv_options->calculational_tolerance;
+    tree_state.ts_ttol = &gcv_options->tessellation_tolerance;
+    tree_state.ts_m = &the_model;
+
+    /* gcv_region_end() expects its client_data to point at this struct. */
+    end_data.write_region = count_region_faces;
+    end_data.vlfree = &rt_vlfree;
+    end_data.client_data = &stats;
+
+    /* Walk every top-level object.  Leaves are tessellated to BoTs by
+     * rt_booltree_leaf_tess(); gcv_region_end() then Boolean-evaluates
+     * each region and invokes our callback with the result. */
+    (void)db_walk_tree(context->dbip, (int)gcv_options->num_objects,
+		       (const char **)gcv_options->object_names, 1, &tree_state,
+		       NULL, gcv_region_end, rt_booltree_leaf_tess, &end_data);
+
+    bu_log("Total faces after tessellation: %zu\n", stats.face_count);
+
+    return 1;
+}
+
+static const struct gcv_filter gcv_conv_tess_stats = {
+    "Tessellation Statistics", GCV_FILTER_FILTER, BU_MIME_MODEL_AUTO, NULL,
+    NULL, NULL, tessellation_statistics
+};
+----
 
 ====
 
@@ -250,7 +441,51 @@ The following example will leverage the filter in the above plugin example, `tes
 .gcv_embedded.c
 [example]
 ====
-TODO: embedded code
+
+[source,c]
+----
+#include "common.h"
+
+#include "bu/log.h"
+#include "bu/mime.h"
+#include "gcv.h"
+
+/* Defined in tessellation_statistics.c, above. */
+extern const struct gcv_filter gcv_conv_tess_stats;
+
+/* Load the geometry file at 'in_path' into a fresh context, then run the
+ * tessellation-statistics filter over it.  A GCV_FILTER_FILTER operates
+ * on the geometry already in the context, so its target is NULL.
+ * Returns 0 on success. */
+int
+report_tessellation_stats(const char *in_path)
+{
+    struct gcv_context context;
+    const struct gcv_filter *in_filter;
+    bu_mime_model_t in_type;
+
+    gcv_context_init(&context);
+
+    /* Import the input model into the context's in-memory database. */
+    in_type = (bu_mime_model_t)bu_file_mime(in_path, BU_MIME_MODEL);
+    in_filter = find_filter(GCV_FILTER_READ, in_type, in_path, &context);
+    if (!in_filter || !gcv_execute(&context, in_filter, NULL, 0, NULL, in_path)) {
+	bu_log("Failed to read '%s'\n", in_path);
+	gcv_context_destroy(&context);
+	return 1;
+    }
+
+    /* Run the filter; it tallies the faces and reports via bu_log(). */
+    if (!gcv_execute(&context, &gcv_conv_tess_stats, NULL, 0, NULL, NULL)) {
+	bu_log("Tessellation-statistics filter failed\n");
+	gcv_context_destroy(&context);
+	return 1;
+    }
+
+    gcv_context_destroy(&context);
+    return 0;
+}
+----
 
 ====
 
@@ -468,7 +703,7 @@ At this time, the FASTGEN4 writer plugin does not make use of any filter-specifi
 |`--constant-ident`
 |Specify that the starting ident should remain constant.
 |`--material=_code_`
-|Specify the material code that will be assigned to all created regions (the default is `1`).
+|Specify the material code that will be assigned to all created regions (the default is `0`).
 |===
 
 
@@ -579,7 +814,7 @@ The Open Asset Import Library (assimp) is an open source library integrated into
 |`--constant-ident`
 |Specify that the starting ident should remain constant.
 |`--material=_code_`
-|Specify the material code that will be assigned to all created regions (the default is `1`).
+|Specify the material code that will be assigned to all created regions (the default is `0`).
 |`--format=_file_fmt_`
 |Specify the file format for conversion. By default, this is inferred from the file extension.
 |===

doc/asciidoc/articles/mged.adoc

@@ -2452,13 +2452,13 @@ mged> bev -t triangulated_lens sphere1 + sphere2
 
 – Create a triangulated object by intersecting objects _sphere1_ and _sphere2._
 
-*bo*_[-o|-i pattern type] dest source_
+*bo*_[-o|-i pattern [h|n]type] dest source_
 
 The “bo” command is used to create or retrieve binary opaque objects. One of _-i_ or _-o_ must be specified.
 
-The _-o_ option “outputs” or extracts a binary object from the database object _source_ to a file called _dest_.
+The _-o_ option “outputs” or extracts a binary object from the database object _source_ to a host-order file called _dest_.
 
-The _-i_ option “inputs” or imports a file called _source_ into a binary object called _dest_ in the database. There are two additional arguments that must be specified with the _-i_ option: pattern and type. Currently, only uniform binary objects (arrays of values) are supported. As a result, the _pattern_ is always _u_ for “uniform” pattern. The _type_ can be one of the following:
+The _-i_ option “inputs” or imports a file called _source_ into a binary object called _dest_ in the database. There are two additional arguments that must be specified with the _-i_ option: pattern and type. Currently, only uniform binary objects (arrays of values) are supported. As a result, the _pattern_ is always _u_ for “uniform” pattern. Input defaults to host byte order. An `h` or `n` prefix on _type_ explicitly selects host or network byte order. The base _type_ can be one of the following:
 
 _f_-> float
 
@@ -2482,10 +2482,14 @@ _L_-> unsigned long (64 bit)
 
 Examples:
 
-`mged>` *bo -i -u c cmds /usr/brlcad/html/manuals/mged/mged_cmds.html*
+`mged>` *bo -i u c cmds /usr/brlcad/html/manuals/mged/mged_cmds.html*
 
 – Create an opaque uniform binary object of characters with the name _cmds_ that contains the contents of the file __/usr/brlcad/html/manuals/mged/mged_cmds.html.__
 
+`mged>` *bo -i u nS dsp.data terrain.dsp*
+
+– Import a standard network-order DSP data file as an unsigned-short binary object named _dsp.data_.
+
 `mged>` *bo -o /home/jim/cmds.html cmds*
 
 – Copy the contents of the binary object named _cmds_ into the file named _/home/jim/cmds.html._
@@ -6429,12 +6433,18 @@ mged *rset r draw 1* – Draw rubber band.
 
 mged *rset ax*
 
-Axes model_draw=0 model_size=500 model_linewidth=1 model_pos=0,0,0 view_draw=0 view_size=500 view_linewidth=1 view_pos=0,0 edit_draw=0 edit_size1=500 edit_size2=500 edit_linewidth1=1 edit_linewidth2=1.
+Axes model_draw=0 model_size=500 model_linewidth=1 model_pos=0,0,0 model_tick_enable=0 model_tick_interval=100 model_ticks_per_major=10 model_tick_length=4 model_tick_major_length=8 model_tick_threshold=8 view_draw=0 view_size=500 view_linewidth=1 view_pos=0,0 edit_draw=0 edit_size1=500 edit_size2=500 edit_linewidth1=1 edit_linewidth2=1.
 
 –Prints the values of the axes
 
 mged *rset ax model_size* – Get size of model axes 500.
 
+mged *rset ax model_tick_enable* – Enable (1) or disable (0) a ticked scale
+along the model axes. The tick spacing is set with *rset ax
+model_tick_interval* (in mm), with a major tick every *rset ax
+model_ticks_per_major* ticks. This gives a measurable scale in the target
+coordinate system.
+
 **
 
 

doc/asciidoc/articles/object_types.adoc

@@ -767,6 +767,21 @@ image::objtype_brep.png[brep,align=center]
 |===
 |Creation |`brep _oldobj_ brep _newname_` converts an existing primitive to a
 BREP.  BREPs are also produced directly by importers.
+|Structure |A BREP records vertices, 3D edge curves, trimming curves, loops,
+faces, and their topology. Each face references an underlying parametric
+surface and uses one or more trimming loops to define the portion belonging to
+the boundary.
+|Capabilities |BRL-CAD can ray trace BREP objects directly, draw their
+wireframes and shaded surfaces, inspect their topology and NURBS data, and
+convert supported CSG primitives to BREP form. The `brep` command also
+provides validity checks, plotting tools, experimental Boolean evaluation,
+mesh generation, and attempts to recover CSG representations.
+|Limitations |A closed, consistently oriented, topologically valid boundary is
+required for dependable solid ray tracing. Open or invalid models may still be
+useful as surfaces but do not define an unambiguous volume. General
+component-level editing, BREP Boolean evaluation, CSG recovery, and production
+mesh generation remain limited or experimental; difficult imported models may
+need repair in their source CAD system.
 |===
 
 === poly and bspline -- Legacy surface types
@@ -1086,7 +1101,24 @@ two reference paths it connects.
 
 Annotations place text labels in the scene, optionally tied to a point of
 interest by a leader.  They are used to dimension and document a model directly
-in 3D.
+in 3D.  Legacy annotations keep their two-dimensional offsets in screen space.
+Model-space annotations instead store two basis vectors that embed their
+leaders, dimensions, symbols, and text in a plane in the model.
+
+Annotation text is UTF-8.  BRL-CAD loads scalable TrueType fonts at runtime and
+plots their glyph outlines, preserving the annotation plane and text rotation.
+OSIFont is the default because its technical lettering and engineering symbols
+are suited to dimensioning and PMI.  A segment style may select a font by an
+installed filename, by a name whose `.ttf` suffix is implied, or by a path.  If
+that font cannot be used, plotting tries OSIFont and then the built-in stroke
+font.  The font file remains an installed data file; it is not compiled into
+BRL-CAD.
+
+Enhanced annotations may also preserve a semantic role for each segment, such
+as text, leader, extension line, dimension line, arrowhead, or symbol.  Line
+pattern, width, color, font, and symbol metadata can accompany those roles.
+Importers can therefore retain PMI meaning separately from the plotted
+geometry even when a display backend does not implement every style property.
 
 [cols="1,1,4"]
 |===
@@ -1097,6 +1129,9 @@ in 3D.
 |horizontal / vertical |1/2/3 |Text justification (left/center/right, bottom/middle/top).
 |text size |scalar |Height of the text.
 |text angle |scalar |Rotation of the text.
+|placement |screen/model |Screen-space offsets or a model-space annotation plane.
+|segment role |enumeration |Optional text, leader, extension, dimension, arrowhead, symbol, or geometry meaning.
+|font |name/path |Optional runtime TrueType font selection; OSIFont is the default.
 |===
 
 Recipe:
@@ -1207,8 +1242,8 @@ by object name instead of by external file.
 [cols="1,1,4"]
 |===
 |Parameter |Type |Description
-|minor type |char |Element type: `f` d `c` s `i` L (signed) / `C` S `I` L (unsigned).
-|file |name |File to read the array from.
+|minor type |char |Element type: `f` d `c` s `i` l (signed) / `C` S `I` L (unsigned).
+|file |name |Host-order file to read the array from.
 |count |integer |Number of values to read (-1 for the whole file).
 |===
 

doc/asciidoc/articles/procedural_geometry.adoc

@@ -79,7 +79,7 @@ building the `procedural-gallery-snapshot` target.
 |image:images/gallery_brickwall.png[brickwall,512]
 |*brickwall*: Builds a brick wall: emits mged commands that create RPP brick solids arranged in rows (with optional mortar slabs between them) to fill a specified wall width and height. Output is a stream of mged commands on stdout, not a .g directly.
 |image:images/gallery_mkbuilding.png[mkbuilding,512]
-|*mkbuilding*: Procedurally builds a small building: a floor slab, four framed walls with openings, and an overhanging roof.
+|*mkbuilding*: Generates physically dimensioned buildings from presets, a validated native JSON schema, OSM GeoJSON or Overpass data, and CityJSON 2.x. It supports arbitrary footprints, storeys and basements, material-separated envelopes and roofs, doors and windows, structural grids, installations, and nested building parts.
 |image:images/gallery_cchannel.png[cchannel,512]
 |*cchannel*: Creates a section of fully configurable C-channel (structural metal beam). Default is a 1" diameter by 12" long section of American standard C-channel, here generated with a row of drilled holes.
 |image:images/gallery_ringworld.png[ringworld,512]

doc/asciidoc/books/BRL-CAD_Tutorial_Series-VolumeII.adoc

@@ -65,6 +65,7 @@ In this lesson, you will:
 * Create a sphere using the GUI menu.
 * Use the l command to list a shape's attributes or parameters.
 * Use the ls command to list the contents of the database.
+* Use the tops command to identify top-level objects in the database.
 * Eliminate a shape or object from the database using the kill command.
 * Edit a command.
 * Use the q or exit commands to quit the program.
@@ -274,6 +275,17 @@ Use the l command to list both sph1.s and sph2.s before continuing with this les
 
 In addition to viewing a shape's contents, you might also want to list the contents of the database to see what items have been created. To view the database contents, type at the Command Window prompt: *ls[ENTER]*
 
+The *ls* command lists every object, which can be overwhelming in an existing
+database. The *tops* command is usually the best starting point when exploring
+an unfamiliar database: it lists only objects that are not members of another
+combination. These top-level objects are typically the assemblies or models
+you will want to draw or inspect first. At the Command Window prompt, type:
+*tops[ENTER]*
+
+In the simple _sphere.g_ database, the primitive shapes are still top-level
+objects. As you build combinations in later lessons, *tops* will omit their
+member shapes and show the higher-level entry points instead.
+
 
 [[kill_object]]
 === Killing a Shape or Object
@@ -325,6 +337,7 @@ In this lesson, you:
 * Used the GUI to create a primitive shape.
 * Used the l command to view a shape's parameters.
 * Used the ls command to list the contents of the database.
+* Used the tops command to identify top-level database objects.
 * Used the kill command to eliminate a shape from the database.
 * Edited commands in the Command Window.
 * Used the q or Exit commands to quit the program.

doc/asciidoc/books/BRL-CAD_Tutorial_Series-VolumeIII.adoc

@@ -29,7 +29,7 @@ Finally, the authors would especially like to acknowledge Mr. Michael Muuss, the
 
 Since 1979, the U.S. Army Research Laboratory (ARL) has been developing and distributing the U.S. Army Ballistic Research Laboratory - Computer-Aided Design (BRL-CAD) constructive solid geometry (CSG) modeling package for a wide range of military and industrial applications. The package includes a large collection of tools and utilities including an interactive geometry editor, raytracing and generic framebuffer libraries, network-distributed image-processing/signal-processing capabilities, and an embedded scripting language.
 
-As part of this effort, a multivolume tutorial series is under development to assist users with the many features of the BRL-CAD package. Volume I provides an overview of the package contents and installation (Butler and Edwards, 2002). Volume II addresses the basic features and functionality of the package's Multi-Device Geometry Editor (MGED) and offers a comprehensive list of the user commands available (Butler et al., 2001). These documents are available for download at http://ftp.arl.army.mil/brlcad/ (U.S. ARL, 2003).
+As part of this effort, a multivolume tutorial series is under development to assist users with the many features of the BRL-CAD package. Volume I provides an overview of the package contents and installation (Butler and Edwards, 2002). Volume II addresses the basic features and functionality of the package's Multi-Device Geometry Editor (MGED) and offers a comprehensive list of the user commands available (Butler et al., 2001). These documents are available for download at https://ftp.arl.army.mil/brlcad/ (U.S. ARL, 2003).
 
 The purpose of Volume III is to discuss the components of the modeling process and suggest principles for maximizing the effectiveness of BRL-CAD's capabilities. Because of the large diversity in modeling projects, these principles have largely been kept to a general nature so that they have the widest applicability possible. In addition, several appendices have been included to offer detailed discussions on several BRL-CAD tools and features, including the pipe primitive (Appendix A), the projection shader (Appendix B), the extruded bitmap primitive (Appendix C), the .mgedrc file (Appendix D), the Build Pattern tool (Appendix E), and the build_region command (Appendix F).
 
@@ -293,7 +293,7 @@ The following are some general tips regarding the efficient development of geome
 
 [NOTE]
 ====
-For a list of all the primary primitives and their shapes, see Appendix C of BRL-CAD Tutorial Volume II (Butler et al., 2001) or consult http://ftp.arl.army.mil/brlcad/ (U.S. ARL, 2003). For detailed guidance on using the pipe and the extruded bitmap (ebm) primitives, see Appendices A and C of this volume.
+For a list of all the primary primitives and their shapes, see Appendix C of BRL-CAD Tutorial Volume II (Butler et al., 2001) or consult https://ftp.arl.army.mil/brlcad/ (U.S. ARL, 2003). For detailed guidance on using the pipe and the extruded bitmap (ebm) primitives, see Appendices A and C of this volume.
 
 ====
 
@@ -1374,213 +1374,20 @@ image::../articles/images/mgedrc_fig03.png[]
 [appendix]
 == Using the Build Pattern Tool
 
-[[build_pattern_generalinfo]]
-=== General Pattern Information
-
-As mentioned previously, the Build Pattern tool automates the process of making copies of existing geometry in rectangular, spherical, or cylindrical patterns. The user can choose to pattern at any of three depths of duplication: top, regions, and primitives.
-
-The Build Pattern tool is run from the graphical user interface (GUI) (under the Tools menu); it currently has no command-line equivalent. The bottom of the pattern control GUI is a usage dialog box that lists pertinent information about each item on the GUI as the user mouses over the text.
-
-There are many input fields. Some stand alone, and others belong to series that work together to provide the needed information for a specific option. Each series is denoted by a diamond-shaped check box. If the diamond is highlighted red, then all fields in that series are required. All required fields must be filled in for the pattern tool to work properly. It is also important to note that all dimensions must be in millimeters and that no commas should be used in number strings.
-
-The Build Pattern tool is designed to work from a prototype geometry object. That is to say, the object that is patterned is not included in the resultant pattern.
-
-
-[[build_pattern_names]]
-=== Pattern Names
-
-As shown in Figure E-1, the tool appends three numbers to all patterned objects (unless you are using the increment option for primitives, in which case, the numbers for regions and primitives are incremented by the increment amount). For rectangular patterns, the first number is the X axis offset, the second is the Y axis offset, and the third is the Z axis offset. For spherical patterns, the first number references the azimuth, the second references the elevation, and the third references the radii. For cylindrical patterns, the first number references the radii, the second number references the height, and the third number references the azimuth.
-
-
-[[build_pattern_fields]]
-=== Common Fields for all Patterns:
-
-There are several fields in the pattern tool GUI that are common to all types of patterns.
-
-The Group Name field is for the name of the combination to be created (or appended to) by a pattern call.
-
-The Source String and Replacement String fields must be used together. The source string is the set of characters in each element of the patterned object to be changed. The replacement string is the set of characters that will replace the source string.
-
-.Example of pattern-generated assembly names.
-image::../articles/images/build_pattern_fig01.png[]
-
-The Increment field is only for use when duplicating to the primitive level. It is added to the leftmost number field of each primitive. To determine the increment, examine the primitives of the object(s) you wish to pattern and find the largest span. For example, to create a pattern to the primitive level with the following primitives (which may or may not be in regions or assemblies):
-
-
-....
-
-part.s22 part.s22-1 part.s23 part.s24 part.s24+1 part.s24-1 part.s25,
-      
-....
-
-one needs to determine the span. Note that the leftmost numbers in these primitives range from 22–25.Thus, as shown in the following expression, the span is four (inclusively). *******NEED FIGURE HERE***** If we use an increment of four, we will get the following set of primitives.
-
-
-....
-
-part.s26 part.s26-1 part.s27 part.s28 part.s28+1 part.s28-1 part.s29
-      
-....
-
-Although it is acceptable to use a greater increment, gaps in numbers may be troublesome if one is using this capability extensively.
-
-Finally, the Objects field is used for the names of all the items to be patterned.
-
-
-[[build_pattern_stringsub]]
-=== String Substitution
-
-It is also possible to create a pattern in which a string of characters in each element in the object is changed (e.g., "l_" -> "r_"). This is useful for symmetry applications (e.g., left - right) or series (e.g., 1 - n). Each element of the object must have the source string so the user must be thorough and name each primitive, region, and assembly properly. Consider the following example: image:../articles/images/build_pattern_fig07.png[]
-
-Top-level duplications copy the patterned object and reference its entire structure with matrices, as follows:
-
-
-....
-
-/pattern group
-       /COPIED assemblies [MATRICES]
-	    /assemblies
-		  /regions
-			/primitives
-      
-....
-
-Region-level duplications copy all assembly and regions and reference from the region level down with matrices.
-
-
-....
-
-/pattern group
-       /COPIED assemblies
-	    /COPIED regions [MATRICES]
-/primitives
-      
-....
-
-Primitive-level duplications copy the entire tree structure to the primitive level without matrices using an increment on all primitives.
-
-
-....
-
-/pattern group
-       /COPIED assemblies       NO MATRICES
-	    /COPIED regions
-		 /COPIED primitives
-      
-....
-
-
-
-
-[[build_pattern_recpatterns]]
-=== Rectangular Patterns
-
-The rectangular pattern GUI (shown in Figure E-2) is designed to facilitate one-, two-, or three-dimensional rectangular patterns. The default X, Y, and Z directions are positive along each axis. In order to create a rectangle that is not axis aligned, these vectors may be changed with the condition that each must remain precisely perpendicular to the other two. If the Use Directions series is checked, the user specifies the number of copies and the Delta between copies for each axis. If the Use Lists series is checked, the user can specify a list of deltas along each axis.
-
-.The user interface for building rectangular patterns.
-image::../articles/images/build_pattern_fig02.png[]
-
-
-[[build_pattern_spherical]]
-=== Spherical Patterns
-
-The spherical pattern GUI (shown in Figure E-3) facilitates sphere-shaped patterns rotated around a center vertex using user-specified radii with azimuth and elevation angles. As shown in Figure E-4, the patterned objects--in this case, a series of arrows--may be oriented as built around the sphere or rotated by azimuth and/or elevation such that they are oriented toward the pattern center using the Rotate Azimuth and Rotate Elevation check boxes.
-
-As shown in Figure E-4, the Pattern Center field is the coordinate at the center of the pattern. The Object Center field is a user-defined coordinate used to locate the object(s) relative to the pattern center. It acts as the key point for any transformations to the pattern object(s).
-
-The Starting Azimuth and Starting Elevation fields follow the same right-hand-rule Cartesian coordinate conventions as Multi-Device Geometry Editor (MGED) viewing. The Starting Radius is the distance from the Pattern Center to the object center at the user-specified azimuths and elevations.
-
-If the Create Az/El series is checked, the user defines the number of azimuths and elevations and the deltas between each. If the Use Lists series is checked, the user must specify a list of azimuths and/or elevations.
-
-The Create Radii and Use Radii List series define offsets from the Starting Radius, allowing the user to create a pattern of concentric spheres. If Create Radii is checked, the user specifies the Number of Radii and the Radius Delta in order to construct a number of equally offset sphere patterns. If the Use Radii List is checked, the user specifies a list of radius offsets.
-
-.The user interface for building spherical patterns.
-image::../articles/images/build_pattern_fig03.png[]
-
-Without the Rotate Azimuth or Rotate Elevation boxes checked, the patterned objects are oriented as built without any rotations. Notice, for example, that every arrow in Figure E-5 points to the left. Notice also that for each patterned arrow, the Object Center (here specified as the tip of the arrow) is located on the circle outline at a distance of one Starting Radius from the Pattern Center. If we set the Object Center to the coordinate at the base of the arrow, the base would then lie on the circular outline. Wherever the Object Center is set is the point at which MGED works with the Object Center coordinate to place and rotate patterned objects.
-
-.Examples of different spherical pattern orientations.
-image::../articles/images/build_pattern_fig04.png[]
-
-.Implementation of spherical patterns.
-image::../articles/images/build_pattern_fig05.png[]
-
-
-[[build_pattern_cylind]]
-=== Cylindrical Patterns
-
-The cylindrical pattern GUI (shown in Figure E-6) facilitates the creation of cylinder-shaped patterns with user-defined center, direction, height, azimuth, and radii inputs. The Base Center is the vertex of the cylinder shape. The Object Center is a user-defined coordinate used to locate the object(s) relative to the Base Center and Height Direction. It acts as the key point for any transformations to the pattern object(s). The Height Direction is the vector along which the cylinder runs. The Starting Height is the offset from the Base Center along the Height Direction that the pattern will place the Object Center.
-
-.The user interface for building cylindrical patterns.
-image::../articles/images/build_pattern_fig06.png[]
+// The body of this appendix is maintained as the standalone article
+// doc/asciidoc/articles/build_pattern.adoc and included here so there is a
+// single source of truth.  The article's own title, author, and attribute
+// header (its first six lines) are skipped; leveloffset=+1 nests the article's
+// top-level sections beneath this appendix heading.
+include::../articles/build_pattern.adoc[lines=7..,leveloffset=+1]
 
 
 [appendix]
 == Using the build_region Command
 
-Just as the Build Pattern tool can help automate the process of building multiple occurrences of objects, the build_region command can help automate the process of creating regions. The command (which currently has no graphical user interface equivalent) uses meaning assigned by the user in the primitive name based on the intended use of the primitive.
-
-The user includes the Boolean operation and relational information in the name of the primitive using a simple naming convention. The naming convention is designed around the following two assumptions:
-
-
-* The same text "tag" is used for all primitives in a region.
-* A sequential numbering pattern is used.
-
-For example, let's say we want to build the four rounded corners of a "tub" region for a toy metal wagon assembly (see Figure F-1). We could choose something such as "wgn"--an abbreviated form of "wagon"--as the tag. This tag is short, easy to type, and representative of the final assembly name. Our primitives would therefore be of the form wgn.s#.
-
-[[build_region5]]
-.The rounded corners of a toy wagon.
-image::../articles/images/build_region_fig01.png[]
-
-Next, we create an arb8 for one long side of the wagon tub. It is named wgn.s1. After that, we create an rcc for one corner of the tub. It is named wgn.s2. To get a hollow quarter cylinder, we need to subtract a cylinder and intersect a bounding box (see Figure F-2). In order to relate the subtraction and intersecting primitives with wgn.s2, they will each share the same root name, wgn.s2. The subtraction primitive will be named wgn.s2-1, and the intersecting primitive will be named wgn.s2+1.
-
-[[build_region7]]
-.Arb8, cylinder, and two Boolean primitives.
-image::../articles/images/build_region_fig02.png[]
-
-Now we have created the following four primitives:
-
-
-....
-
-wgn.s1 wgn.s2 wgn.s2+1 wgn.s2-1
-    
-....
-
-If we separate the primitives sequentially as follows,
-
-
-....
-
-wgn.s1
-
-wgn.s2 wgn.s2+1 wgn.s2-1,
-    
-....
-
-we can begin to see the Boolean structure falling out of the naming convention
-
-
-....
-
-u wgn.s1
-
-u wgn.s2 + wgn.s2+1 - wgn.s2-1
-    
-....
-
-If we wanted to make a second subtraction from wgn.s2--say, for a drain hole in the corner of the wagon--we would name that primitive wgn.s2-2 (see Figure F-3). We can break this name down as follows: *****NEED IMAGE HERE*****
-
-[[build_region9]]
-.The region and the subtraction primitives.
-image::../articles/images/build_region_fig03.png[]
-
-Note that the root name stays the same so we can maintain the relationship, and the second number (associated with the Boolean operation) is incremented sequentially.
-
-[[build_region11]]
-.Raytraced image with hole.
-image::../articles/images/build_region_fig04.png[]
-
-Obviously, the overall success or failure of the build_region command depends on primitives being named properly. But if they are, the command can organize them in one automated step, creating complex regions in just a few keystrokes.
-
-Another modeling benefit of the build_region tool is that it allows the user to quickly organize primitives. Assume, for example, that we have used the aforementioned naming convention to construct a complicated region. If there was a subsection of the region that we needed to, say, keep out for another assembly, delete from our database, move slightly, or copy, it would be a simple matter to create a new region with just those primitives that we needed.
+// The body of this appendix is maintained as the standalone article
+// doc/asciidoc/articles/build_region.adoc and included here so there is a
+// single source of truth.  The article's own title, author, and attribute
+// header (its first six lines) are skipped; leveloffset=+1 keeps any article
+// sections nested beneath this appendix heading.
+include::../articles/build_region.adoc[lines=7..,leveloffset=+1]

doc/asciidoc/books/BRL-CAD_Tutorial_Series-VolumeIV.adoc

@@ -27,7 +27,7 @@ The authors would like to thank Messrs. Lee Butler, Edwin Davisson, William Land
 
 Since 1979, the U.S. Army Research Laboratoryfootnote:[On 30 September 1992, the U.S. Army Ballistic Research Laboratory (BRL) was deactivated and subsequently became part of the U.S. Army Research Laboratory (ARL) on 1 October 1992.] has been developing and distributing the Ballistic Research Laboratory - Computer-Aided Design (BRL-CAD) three-dimensional (3-D) solid modeling package to support combat vehicle vulnerability studies and various other military and industrial applications. The software, which is now in its third generation, includes a large collection of tools and utilities, including an interactive geometry editor, raytracing and generic framebuffer libraries, network-distributed image-processing/signal-processing capabilities, and an embedded scripting language.
 
-In support of the package, a multivolume tutorial series is being written to assist users with the many features and functionality of BRL-CAD. Three volumes have been published thus far. Volume I provides an overview of the package contents and installation (Butler and Edwards, 2002). Volume II addresses the basic functionality of the package's Multi-Device Geometry Editor (MGED) and offers a comprehensive list of the user commands available (Butler et al., 2001). Volume III discusses the modeling process as well as principles and techniques to help maximize BRL-CAD's effectiveness (Butler et al., 2003). All of these documents are available for download at http://ftp.arl.army.mil/brlcad/[http://ftp.arl.army.mil/brlcad/] (U.S. Army Research Laboratory, 2003).
+In support of the package, a multivolume tutorial series is being written to assist users with the many features and functionality of BRL-CAD. Three volumes have been published thus far. Volume I provides an overview of the package contents and installation (Butler and Edwards, 2002). Volume II addresses the basic functionality of the package's Multi-Device Geometry Editor (MGED) and offers a comprehensive list of the user commands available (Butler et al., 2001). Volume III discusses the modeling process as well as principles and techniques to help maximize BRL-CAD's effectiveness (Butler et al., 2003). All of these documents are available for download at https://ftp.arl.army.mil/brlcad/[https://ftp.arl.army.mil/brlcad/] (U.S. Army Research Laboratory, 2003).
 
 The purpose of Volume IV is to discuss issues of compatibility and conversion between the BRL-CAD geometry file format and the formats of various other computer-aided design (CAD), computer-aided manufacturing (CAM), and computer-aided engineering (CAE) packages. Conversion is increasingly important for BRL-CAD users who must interact with a growing number of Government and commercial organizations involved in the research, development, testing, and evaluation of today's combat systems.
 
@@ -299,7 +299,7 @@ The options for the command are as follows:
 * *-t* - sets tolerance distance (in millimeters) (default is 0.005) (takes an argument).
 * *-v* - verbose; prints out progress information.
 
-For more information on the DXF file format and import possibilities, see the on-line documentation on the Autodesk web site at http://adeskftp.autodesk.com/ prodsupp/downloads/dxf.pdf[http://adeskftp.autodesk.com/ prodsupp/downloads/dxf.pdf] (Autodesk, 2003).
+For more information on the DXF file format and import possibilities, see the on-line documentation on the Autodesk web site at https://adeskftp.autodesk.com/ prodsupp/downloads/dxf.pdf[https://adeskftp.autodesk.com/ prodsupp/downloads/dxf.pdf] (Autodesk, 2003).
 
 
 [[Converting_From_Elysium_Neutral_Facetted_Format]]
@@ -336,7 +336,7 @@ The options for the command are as follows:
 * *-n part_name_mapping* - sets the mapping from input names to output names.
 * *-t tolerance_distance* - sets distance calculation tolerance (in millimeters) (default is 0.005).
 
-For more information on the Elysium file format and import possibilities, see the Elysium web site at http://www.elysiuminc.com[http://www.elysiuminc.com] (Elysium, 2003).
+For more information on the Elysium file format and import possibilities, see the Elysium web site at https://www.elysiuminc.com[https://www.elysiuminc.com] (Elysium, 2003).
 
 
 [[Converting_From_EUCLID_Format]]
@@ -365,7 +365,7 @@ The options for the command are as follows:
 * *-x lvl* - sets librt debug flag (see _raytrace.h_ in the binary distribution for definitions of DEBUG_xxx).
 * *-X lvl* - sets NMG library debug flag (see _nmg.h_ in the binary distribution for definitions of DEBUG_xxx).
 
-For more information about the EUCLID file format and import possibilities, see the MDTVISION web site at http://support.mdtvision.com[http://support.mdtvision.com] (MDTVISION, 2003).
+For more information about the EUCLID file format and import possibilities, see the MDTVISION web site at https://support.mdtvision.com[https://support.mdtvision.com] (MDTVISION, 2003).
 
 .Header file note
 [cols="2*"]
@@ -435,7 +435,7 @@ The options for the command are as follows:
 * *-T tolerance_distance* - sets distance tolerance (in inches).
 * *-A parallel_tolerance* - sets parallel tolerance (sine).
 
-For more information about the FASTGEN file formats and import possibilities, see the SURVIAC web site at http://www.bahdayton.com/surviac/fastgen.htm[http://www.bahdayton.com/surviac/fastgen.htm] (SURVIAC, 2003).
+For more information about the FASTGEN file formats and import possibilities, see the SURVIAC web site at https://www.bahdayton.com/surviac/fastgen.htm[https://www.bahdayton.com/surviac/fastgen.htm] (SURVIAC, 2003).
 
 
 
@@ -464,7 +464,7 @@ The options available for this command are as follows:
 
 The *-n*, *-d*, *-t*, and *-3* options are mutually exclusive. If none of these four options is provided, the default action is to convert only IGES solid model entities (CSG and planar face BREP) to BRL-CAD.
 
-For more information about the IGES file format and import possibilities, see the National Institute of Standards and Technology (NIST) web site at http://www.nist.gov/iges[http://www.nist.gov/iges] (NIST, 2003).
+For more information about the IGES file format and import possibilities, see the National Institute of Standards and Technology (NIST) web site at https://www.nist.gov/iges[https://www.nist.gov/iges] (NIST, 2003).
 
 
 [[Converting_From_Jack]]
@@ -482,7 +482,7 @@ The options for this command are:
 * *-r region_name* - specifies a name for the BRL-CAD region created. If this option is not specified, the input file name will be used to construct a region name.
 * *-g group_name* - specifies the name of a combination to create to hold the BRL-CAD region created. If this option is not specified, the combination will not be created.
 
-For more information on the Jack file format and import possibilities, see the EDS web page at http://www.eds.com/products/plm/efactory/jack/[http://www.eds.com/products/plm/efactory/jack/] (EDS, 2003a).
+For more information on the Jack file format and import possibilities, see the EDS web page at https://www.eds.com/products/plm/efactory/jack/[https://www.eds.com/products/plm/efactory/jack/] (EDS, 2003a).
 
 
 [[Converting_From_NASTRAN_Format]]
@@ -513,7 +513,7 @@ The options for the command are as follows:
 * *-t tolerance_distance* - sets distance calculation tolerance (in millimeters) (default is 0.005).
 * *-m* - sets input units to millimeters (default is inches).
 
-For more on the NASTRAN file format and import possibilities, see the MSC web site at http://www.mscsoftware.com[http://www.mscsoftware.com] (MSC.Software Corporation, 2003) and the EDS web site at http://www.eds.com/products/plm/nastran/[http://www.eds.com/products/plm/nastran/] (EDS, 2003b).
+For more on the NASTRAN file format and import possibilities, see the MSC web site at https://www.mscsoftware.com[https://www.mscsoftware.com] (MSC.Software Corporation, 2003) and the EDS web site at https://www.eds.com/products/plm/nastran/[https://www.eds.com/products/plm/nastran/] (EDS, 2003b).
 
 
 [[Converting_From_Pro_E_Format]]
@@ -559,7 +559,7 @@ The following list provides a description of the use and functionality of the pr
 * *Max Tessellation Error* - This value (expressed in millimeters) is used to control the coarseness of the tessellation. It is the maximum distance between the actual surface and its tessellated approximation. Smaller values here will result in finer tessellations and more triangles. The default value is reasonable for ballistic vulnerability analysis purposes.
 * *Angle Control Value* - This is a number between 0 and 1 that provides additional control over the coarseness of the tessellation. The exact relationship between the tessellation and this value is not specified in the Pro/E documentation, but the default value of 0.5 seems to work well.
 
-For more information about the Pro/E file format and import possibilities, see the Parametric Technology Corporation (PTC) web site at http://www.ptc.com[http://www.ptc.com] (PTC, 2003).
+For more information about the Pro/E file format and import possibilities, see the Parametric Technology Corporation (PTC) web site at https://www.ptc.com[https://www.ptc.com] (PTC, 2003).
 
 
 [[sec_converting_from_stl]]
@@ -594,7 +594,7 @@ The options for this command are as follows:
 * *-t tolerance_distance* - specifies the minimum distance (in millimeters) allowed between distinct vertices. Vertices closer than this minimum will be considered to be the same vertex (the default value is 0.005 mm).
 * *-x librt_debug_flag* - specifies a flag for the raytracing library that will result in additional debug log messages (see `librt/debug.h` in the binary distribution for details).
 
-For more information on the STL file format and import possibilities, see the 3D Systems web site at http://www.3dsystems.com[http://www.3dsystems.com] (3D Systems, 2003).
+For more information on the STL file format and import possibilities, see the 3D Systems web site at https://www.3dsystems.com[https://www.3dsystems.com] (3D Systems, 2003).
 
 
 [[Converting_From_TANKILL_Format]]
@@ -617,7 +617,7 @@ The options for the command are as follows:
 * *-x lvl* - sets librt debug flag (see `raytrace.h` in the binary distribution for definitions of DEBUG_xxx).
 * *-X lvl* - sets NMG library debug flag (see `nmg.h` in the binary distribution for definitions of DEBUG_xxx).
 
-For more information on the TANKILL file format and import possibilities, contact the Advantage Business Group at the Barbician, East Street, Farnham, Surrey, GU9 7TB or visit the web site at http://www.advantage-business.co.uk[http://www.advantage-business.co.uk] (Advantage Business Group, 2003).
+For more information on the TANKILL file format and import possibilities, contact the Advantage Business Group at the Barbician, East Street, Farnham, Surrey, GU9 7TB or visit the web site at https://www.advantage-business.co.uk[https://www.advantage-business.co.uk] (Advantage Business Group, 2003).
 
 
 [[Converting_From_Unigraphics_Format]]
@@ -655,7 +655,7 @@ The available options are as follows:
 * *-c min_chamfer* - specifies that any chamfer with dimensions less than the provided minimum (in millimeters) will be ignored. By default, no features are ignored.
 * *-r min_round* - specifies that any round (or fillet) with a radius less than the specified minimum (in millimeters) will be ignored. By default, no features are ignored.
 
-For more information on the Unigraphics file format and conversion potential, see the EDS web site at http://www.eds.com/products/plm/unigraphics_nx/[http://www.eds.com/products/plm/unigraphics_nx/] (EDS, 2003c).
+For more information on the Unigraphics file format and conversion potential, see the EDS web site at https://www.eds.com/products/plm/unigraphics_nx/[https://www.eds.com/products/plm/unigraphics_nx/] (EDS, 2003c).
 
 
 [[Converting_From_Viewpoint_Datalabs_Format]]
@@ -754,7 +754,7 @@ The options for the g-acad command are as follows:
 * *-a abs_tess_tol* - sets absolute tessellation tolerance to specified value (in millimeters) (overrides *-r* option).
 * *-n norm_tess_tol* - sets surface normal tessellation tolerance (angle in radians) (overrides *-r* option).
 
-For more information on the ACAD file format and conversion potential, contact Lockheed Martin Tactical Aircraft Systems at http://www.lockheedmartin.com[http://www.lockheedmartin.com] (Lockheed Martin, 2003).
+For more information on the ACAD file format and conversion potential, contact Lockheed Martin Tactical Aircraft Systems at https://www.lockheedmartin.com[https://www.lockheedmartin.com] (Lockheed Martin, 2003).
 
 
 [[Converting_to_AutoCAD_DXF_Format]]
@@ -773,7 +773,7 @@ The options for the g-dxf command are as follows:
 
 The command also accepts the *-v*, *-r*, *-a*, *-n*, *-x*, and *-X* options, which have been discussed in the import converters portion of this document (<<sec_convert_to_brlcad>>).
 
-For more information on the DXF file format and export possibilities, see the on-line documentation on the Autodesk web site at http://www.autodesk.com[http://www.autodesk.com] (Autodesk, Inc., 2003).
+For more information on the DXF file format and export possibilities, see the on-line documentation on the Autodesk web site at https://www.autodesk.com[https://www.autodesk.com] (Autodesk, Inc., 2003).
 
 
 [[Converting_to_EUCLID_Format]]
@@ -789,7 +789,7 @@ The options for the *g-euclid* command are as follows:
 * *-u units* - sets the output units (the default is millimeters).
 * *-o _output_file_name_* - sets the output file name (the default is `stdout`).
 
-For more information about the EUCLID file format and export possibilities, see the MDTVISION web site at http://support.mdtvision.com[http://support.mdtvision.com] (MDTVISION, 2003).
+For more information about the EUCLID file format and export possibilities, see the MDTVISION web site at https://support.mdtvision.com[https://support.mdtvision.com] (MDTVISION, 2003).
 
 
 [[Converting_to_IGES_Format]]
@@ -818,7 +818,7 @@ With the *-t* and *-f* options, the converter will employ Boolean evaluation of
 |Note that different CAD packages seem to ``prefer'' certain options for the IGES converter. In particular, Pro/E works well with IGES files that use the *-m* option, and Unigraphics works well with IGES files that use the *-s* option.
 |===
 
-For more information about the IGES file format and export possibilities, see the NIST web site at http://www.nist.gov/iges[http://www.nist.gov/iges] (NIST, 2003).
+For more information about the IGES file format and export possibilities, see the NIST web site at https://www.nist.gov/iges[https://www.nist.gov/iges] (NIST, 2003).
 
 
 [[Converting_to_Jack]]
@@ -834,7 +834,7 @@ The options for the jack-g command are as follows:
 * *-r region_name* - specifies the name of the region to create in the BRL-CAD output (by default, this name is constructed from the input filename).
 * *-g combination_name* - specifies the name of a combination to be created to hold the region produced. If not specified, no combination will be created.
 
-For more information about the Jack file format and export possibilities, see the EDS web page at http://www.eds.com/products/plm/efactory/jack[http://www.eds.com/products/plm/efactory/jack/] (EDS, 2003a).
+For more information about the Jack file format and export possibilities, see the EDS web page at https://www.eds.com/products/plm/efactory/jack[https://www.eds.com/products/plm/efactory/jack/] (EDS, 2003a).
 
 
 [[Converting_to_STL_Format]]
@@ -855,7 +855,7 @@ The options for the *g-stl* command are as follows:
 
 The command also accepts the previously mentioned *-v*, *-r*, *-a*, *-n*, *-x*, and *-X* options.
 
-For more information on the STL file format and export possibilities, see the 3D Systems web site at http://www.3dsystems.com[http://www.3dsystems.com] (3D Systems, 2003).
+For more information on the STL file format and export possibilities, see the 3D Systems web site at https://www.3dsystems.com[https://www.3dsystems.com] (3D Systems, 2003).
 
 
 [[Converting_to_TANKILL_Format]]
@@ -876,7 +876,7 @@ The options for the *g-tankill* command are as follows:
 
 The command also accepts the previously mentioned *-v*, *-r*, *-a*, *-n*, *-x*, and *-X* options.
 
-For more information on the TANKILL file format and export possibilities, contact the Advantage Business Group at the Barbician, East Street, Farnham, Surrey GU9 7TB or visit the web site at http://www.advantage-business.co.uk[http://www.advantage-business.co.uk] (Advantage Business Group, 2003)
+For more information on the TANKILL file format and export possibilities, contact the Advantage Business Group at the Barbician, East Street, Farnham, Surrey GU9 7TB or visit the web site at https://www.advantage-business.co.uk[https://www.advantage-business.co.uk] (Advantage Business Group, 2003)
 
 
 [[Converting_to_VRML_Format]]
@@ -897,7 +897,7 @@ The options for the command are as follows:
 
 The command also accepts the previously mentioned *-v*, *-r*, *-a*, *-n*, *-x*, and *-X* options.
 
-For more information on VRML, see the Web3D Consortium web site at http://www.web3d.org /fs_technicalinfo.htm[http://www.web3d.org /fs_technicalinfo.htm] (Web3D Consortium, 2003b).
+For more information on VRML, see the Web3D Consortium web site at https://www.web3d.org /fs_technicalinfo.htm[https://www.web3d.org /fs_technicalinfo.htm] (Web3D Consortium, 2003b).
 
 .The Web3D Consortium
 [cols="2*"]
@@ -928,7 +928,7 @@ The options for the command are as follows:
 
 The command also accepts the previously mentioned *-v*, *-r*, *-a*, *-n*, *-x*, and *-X* options.
 
-For more information on the Wavefront file format and export possibilities, see the Alias web site at http://www.alias.com/eng/index.shtml[http://www.alias.com/eng/index.shtml] (Alias, 2003).
+For more information on the Wavefront file format and export possibilities, see the Alias web site at https://www.alias.com/eng/index.shtml[https://www.alias.com/eng/index.shtml] (Alias, 2003).
 
 
 [[Converting_to_X3D_Format]]
@@ -949,7 +949,7 @@ The options for the command are as follows:
 
 The command also accepts the previously mentioned *-v*, *-r*, *-a*, *-n*, *-x*, and *-X* options.
 
-For more information on the X3D file format and export possibilities, see the Web3D Consortium web site at http://www.web3d.org/technicalinfo/specifications/ISO_IEC_19775[http://www.web3d.org/technicalinfo/specifications/ISO_IEC_19775] (Web3D Consortium, 2003a).
+For more information on the X3D file format and export possibilities, see the Web3D Consortium web site at https://www.web3d.org/technicalinfo/specifications/ISO_IEC_19775[https://www.web3d.org/technicalinfo/specifications/ISO_IEC_19775] (Web3D Consortium, 2003a).
 
 
 [[sec_build_new_converter]]

doc/asciidoc/books/CMakeLists.txt

@@ -4,6 +4,7 @@ set(
   BRL-CAD_Tutorial_Series-VolumeII.adoc
   BRL-CAD_Tutorial_Series-VolumeIII.adoc
   BRL-CAD_Tutorial_Series-VolumeIV.adoc
+  HACKING_BRL-CAD.adoc
 )
 
 if(BRLCAD_EXTRADOCS)
@@ -65,6 +66,7 @@ set(
 if(TARGET mged OR TARGET qged OR TARGET archer)
   if(BRLCAD_EXTRADOCS)
     add_doc(books_EN_IMAGES html/books/images)
+    add_doc(hacking_brlcad_images html/books/images)
   endif(BRLCAD_EXTRADOCS)
 endif(TARGET mged OR TARGET qged OR TARGET archer)
 
@@ -102,7 +104,6 @@ cmakefiles(
   ${books_ADOC}
   ${books_EN_IMAGES}
   ${hacking_brlcad_images}
-  HACKING_BRL-CAD.adoc
 )
 
 # Local Variables:

doc/asciidoc/books/HACKING_BRL-CAD.adoc

@@ -296,10 +296,10 @@ Example geometry
 Project documentation
 
 
-`doc/docbook`::
-User documentation in XML format
+`doc/asciidoc/`::
+User and developer documentation in AsciiDoc format
 +
-See doc/docbook/README for more details
+See doc/asciidoc/README.adoc for more details
 
 
 `include/`::
@@ -382,11 +382,11 @@ API Unit tests
 
 ==== Code Conventions
 
-BRL-CAD has a STABLE branch in Git that should always compile and run on all supported platforms. The primary development branch trunk, unlike STABLE, is generally expected to compile but may occasionally fail to do so during active development.
+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.
 
 ===== Languages
 
-The majority of BRL-CAD is written in ANSI/POSIX C with the intent of strictly conforming with the C standard. The core libraries are all C API, though several--such as the LIBBU and LIBRT libraries--use C++ for implementation details. Our C libraries can use C++ for implementation detail, but they cannot expose C++ in the public API.
+The majority of BRL-CAD is written in portable C with the intent of strictly conforming with the C11 standard (ISO/IEC 9899:2011). C++ code targets the C++17 standard (ISO/IEC 14882:2017). The core libraries all expose a C API, though several--such as the LIBBU and LIBRT libraries--use C++ for implementation details. Our C libraries can use C++ for implementation detail, but they cannot expose C++ in the public API.
 
 Major components of the system are written in the following languages:
 
@@ -411,7 +411,7 @@ Source code files use the following extensions:
 
 
 
-With release 7.0, BRL-CAD has moved forward and worked toward making all of the software's C code conform strictly with the ANSI/ISO standard for C language compilation (ISO/IEC 9899:1990, or c89). Support for older compilers and older K&R-based system facilities is being migrated to build system declarations or preprocessor defines, or is being removed outright. You can, however, make modifications that assume compiler conformance with the ANSI C standard (c89).
+BRL-CAD requires that all of the software's C code conform strictly with the ISO C11 standard (ISO/IEC 9899:2011), and that all C++ code conform with the ISO C++17 standard (ISO/IEC 14882:2017). Support for older compilers and older K&R-based system facilities has been migrated to build system declarations or preprocessor defines, or removed outright. You may make modifications that assume compiler conformance with the C11 and C++17 standards.
 
 
 ===== Coding Style
@@ -569,11 +569,9 @@ Check out our list of available mini tasks that we call http://brlcad.org/wiki/D
 
 ==== Two-Week Tasks
 
-If you have few hours to spare each day, check our http://brlcad.org/xref/source/TODO[TODO list] (http://brlcad.org/xref/source/TODO). These tasks can help potential developers do modifications and submit patches to gain commit access to 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 our mailing list brlcad-devel@lists.sourceforge.net.
+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 https://brlcad.zulipchat.com[Zulip chat] or in our https://github.com/BRL-CAD/brlcad/discussions[GitHub Discussions].
 
-We also have a http://sourceforge.net/p/brlcad/code/HEAD/tree/brlcad/trunk/BUGS[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 http://sourceforge.net/p/brlcad/bugs/[bug tracker].
-
-Students participating in Google Code-in can view tasks on the http://brlcad.org/wiki/GCI_Tasks[BRL-CAD website] (http://brlcad.org/wiki/GCI_Tasks). Each task is described in a little detail, and students are directed to relevant BRL-CAD source code or websites to help them complete these tasks.
+We also have a https://github.com/BRL-CAD/brlcad/blob/main/BUGS[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 https://github.com/BRL-CAD/brlcad/issues[issue tracker].
 
 
 ==== Two-Month Tasks
@@ -591,7 +589,7 @@ You can get the development code for BRL-CAD from our Git code repository using
 
 *git clone https://github.com/BRL-CAD/brlcad*
 
-The code will be saved in your `/home` directory, and you can compile it by following the instructions `HACKING` file located in top-level code directory. That said, the following are a few useful tips to help get you going.
+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.
 
 ===== Obtaining the Development Tools
 
@@ -644,11 +642,11 @@ That's it! If you have a Release compile, you can submit your benchmark results
 
 ==== Discussing Code
 
-After obtaining the source code, you should to join the BRL-CAD developer mailing list (http://lists.sourceforge.net/lists/listinfo/brlcad-devel) and the #brlcad IRC channel at irc.freenode.net.
+After obtaining the source code, you should join the BRL-CAD community on https://brlcad.zulipchat.com[Zulip chat], our primary discussion venue. For longer-form questions and answers, use https://github.com/BRL-CAD/brlcad/discussions[GitHub Discussions]. A secondary, legacy IRC channel named #brlcad is also available on irc.libera.chat.
 
-Joining both lists helps introduce yourself to the BRL-CAD community and gives you the opportunity to regularly communicate with other experienced contributors. You can also ask questions on the mailing list or the IRC channel.
+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 on the mailing list or on the IRC channel. We also strongly advise you to use interleaved posting when replying on any communication channels. And _never be afraid to ask questions_.
+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:
 
@@ -656,7 +654,7 @@ Finally, when modifying code, it's advisable to regularly consult with experienc
 * Test your code to ensure that the change is correct.
 * Document your changes clearly and succinctly to ensure that others understand the change.
 * Write tests for your change so others can use them when testing subsequent changes.
-* Make a handful of patches and submit them to SourceForge for review.
+* Open a pull request against the https://github.com/BRL-CAD/brlcad[BRL-CAD repository] on GitHub so your changes can be reviewed.
 * Obtain commit access.
 
 
@@ -673,136 +671,123 @@ BRL-CAD provides documentation in the following formats:
 
 Our challenge is to maintain BRL-CAD's documentation in multiple formats. It is difficult enough to keep software documentation up to date without needing to update multiple documents using different formats that contain the same information. As well, it is not possible to supply documentation in a single format that works optimally on all platforms. For example, while UNIX man pages are standard across all UNIX and UNIX-like systems, most Windows systems will not understand that format and will require HTML versions of those documents.
 
-Instead of using a mix of formats and tools, BRL-CAD uses the DocBook documentation format and toolchain to produce documentation in the range of required formats.
+Instead of using a mix of formats and tools, BRL-CAD writes its documentation in AsciiDoc and uses a single toolchain to produce documentation in the range of required formats.
 
-==== What is DocBook?
+==== What is AsciiDoc?
 
-DocBook is a schema (a structured approach to organization of information) that uses the eXtensible Markup Language standard (XML) as its fundamental framework and builds atop that framework a vocabulary for describing the content and structure of technical documentation. BRL-CAD uses the DocBook 5.0 documentation format to describe its documentation. For detailed documentation for DocBook 5.0, see http://www.docbook.org/tdg5/en/html/docbook.html.
+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 https://asciidoc.org[AsciiDoc project site] and the https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc language documentation].
 
 
-==== Tools for Working with DocBook
+==== Tools for Working with AsciiDoc
 
-While you can write documentation in DocBook using WYSIWYG (What You See Is What You Get) editors, we require that a document saved to DocBook from an editing tool should be inspected for human readability and, if necessary, reformatted for simplicity.
+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.
 
-If you are comfortable with working with DocBook XML directly, we recommend that you use the Emacs editor and its nXML module. nXML can automatically recognize and highlight mistakes in the structure of a document while you are editing. The following image illustrates nXML identifying an incorrect closing tag for an informal figure object:
+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.
 
-image::../books/images/hacking_brlcad_emacs-nxml.png[width=100%]
-
-Aside from error checking tools like nXML, the ability to pinpoint errors in a document's formatting is built into the BRL-CAD compilation process. That process uses a tool called xmllint to report incorrect formatting. When, for example, the error illustrated in the image above is encountered during BRL-CAD's build, xmllint produces the following error:
+The AsciiDoc sources live under `doc/asciidoc/`, organized by document type into the following subdirectories:
 
 
-....
+* `articles/` - general articles.
+* `books/` - long-form books (including this guide).
+* `lessons/` - step-by-step tutorial lessons.
+* `devguides/` - developer guides.
+* `presentations/` - presentation slides.
+* `specifications/` - format and protocol specifications.
+* `system/` - manual pages, further divided into `man1/`, `man3/`, `man5/`, and `mann/`.
 
-[40%] Validating DocBook source with xmllint:
-/home/user/brlcad/doc/docbook/articles/en/tire.xml:65: parser error : Opening and ending tag mismatch: informalfigure line 54 and informafigure
-</informafigure>
-^
-CMake Error at tire_validate.cmake:39 (message):
-xmllint failure: 1
-....
-
-In this case, the error is reasonably informative. However, xmllint is not the only tool available for this sort of error checking. You can specify the following validation tools when you configure your environment:
+For more information, see the file `doc/asciidoc/README.adoc` in the BRL-CAD source code archive.
 
 
-* Oracle Multi-Schema XML Validator (https://msv.java.net) - specified as *msv* on the command line.
-* oNVDL (http://sourceforge.net/projects/onvdl) - specified as *nvld* on the command line.
-* Relax NG Validator (rnv) (http://sourceforge.net/projects/rnv) - specified as *rsv* on the command line.
+==== AsciiDoc Syntax Essentials
 
-Note that these alternative validation tools must be installed on the system on which you are working; they are not provided with BRL-CAD. To specify an alternative tool, use the VALIDATE_EXECUTABLE option. For example, run the following command to use the Oracle Multi-Schema XML Validator:
+A few constructs cover the majority of everyday documentation editing:
 
-*cmake -DVALIDATE_EXECUTABLE=msv ...*
 
-While BRL-CAD provides enough DocBook support to guarantee that HTML files and UNIX man pages are generated, you can only generate PDF documents if the http://xmlgraphics.apache.org/fop[Apache Formatting Objects Processor (FOP)] (http://xmlgraphics.apache.org/fop") is installed on your system. When FOP is available, BRL-CAD can automatically produce PDF outputs.
+* *Section headings* use leading equals signs, one per nesting level. A single `=` is the document title; `==`, `===`, and `====` are progressively deeper section levels.
++
+----
+== A Top-Level Section
+=== A Subsection
+----
 
-For more information, including how to use alternative tools for other DocBook processing steps besides validation, see the file `doc/docbook/README` in the BRL-CAD source code archive.
+* *Images* are embedded with the `image::` block macro, optionally with attributes such as a width. Image files are kept alongside the sources (for example, in an `images/` subdirectory) and are listed in the directory's `CMakeLists.txt` so they are copied to the build:
++
+----
+image::images/example.png[width=100%]
+----
+
+* *External links* use the `link:` macro or a bare URL followed by the display text in brackets:
++
+----
+link:https://brlcad.org[the BRL-CAD website]
+https://brlcad.org[the BRL-CAD website]
+----
+
+* *Cross-references* within a document use an anchor and a reference to it. Define an anchor with `[[anchor]]` (or the block form `[#anchor]`) and refer to it with `<<anchor,link text>>`:
++
+----
+[[ray_example]]
+=== Code Example: Shooting Rays
+
+See <<ray_example,the ray-shooting example>> for details.
+----
+
+* *Verbatim/code blocks* are delimited by lines of four or more hyphens (`----`), and admonitions such as notes use the `[NOTE]` block style.
 
 
 ==== Adding a New Document to BRL-CAD
 
-Because creating and editing DocBook documentation is greatly simplified by BRL-CAD's management of the conversion process, it is usually a good idea to add a new document to the build system at the beginning of the document creation and editing process. To do this, copy a template file from the source directories to the file name to be used for the new document.
+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 DocBook article in English about the ellipsoid, use the following command to copy the article template to the filename `ellipsoid.xml` in the English articles directory:
+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/docbook/articles/en/TEMPLATE.xml doc/docbook/articles/en/ellipsoid.xml*
+~/brlcad$ *cp doc/asciidoc/articles/TEMPLATE.adoc doc/asciidoc/articles/ellipsoid.adoc*
 
-Next, open the file `doc/docbook/articles/en/CMakeLists.txt` in a text editor. Then, add the name of the new document to the file to alert the build system of its existence:
-
-image::../books/images/hacking_brlcad_docbook_CMakeLists.png[width=100%]
-
-BRL-CAD now knows about the new file and can generate output for it.
-
-You will generally only want to rebuild a specific output (say, HTML) to confirm that output renders properly. To set up the specific targets for the new file, run the command below to refresh the build targets (in this example, the build output directory is called `build`):
-
-~/brlcad/build$ *cmake ..*
-
-This creates a new build target, ellipsoid_article_html, which will build only the HTML output of the document and its dependencies:
+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:
 
 
-....
+----
+set(
+  articles_EN
+  TEMPLATE.adoc
+  about.adoc
+  ...
+  ellipsoid.adoc
+)
+----
 
-~/brlcad/build $ make ellipsoid_article_html
+Reconfigure and build with documentation enabled (in this example, the build output directory is called `build`):
 
-[  0%] Built target printtimestamp
-[  0%] Built target buildtimestart
+~/brlcad/build$ *cmake .. -DBRLCAD_EXTRADOCS=ON*
 
-Build Time: Tue Oct 15 19:14:42 2013
+~/brlcad/build$ *cmake --build . --target doc*
 
-[  0%] Built target timestamp
-[  0%] Built target zlib
-[100%] Built target xml
-[100%] Built target xslt
-[100%] Built target exslt
-[100%] Built target xmllint
-[100%] Built target xsltproc
-[100%] Built target schema-expand
-[100%] Built target fonts-dejavu-expand
-[100%] Built target fonts-stix-expand
-[100%] Built target offo-2-expand
-[100%] Built target svg-dtd-expand
-[100%] Built target xsl-expand
-[100%] Built target docbook_articles_EN_IMAGES_cp
-Scanning dependencies of target ellipsoid_article_html
-[100%] Validating DocBook source with xmllint:
-/home/user/brlcad/doc/docbook/articles/en/ellipsoid.xml validates
-[100%] Generating ../../../../share/doc/html/articles/en/ellipsoid.html
-[100%] Built target ellipsoid_article_html
-~/brlcad/build $
-....
+The asciiquack processor renders the article to:
 
-This generates a file named `brlcad/build/share/doc/html/articles/en/ellipsoid.html.` Open this document in a web browser to view the HTML output:
+`build/share/doc/html/articles/ellipsoid.html`
 
-image::../books/images/hacking_brlcad_example_docbook_default_output.png[width=100%]
+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:
 
 
-. Modify the DocBook XML sources.
-. Build the HTML output. As long as the DocBook file is the only file being changed, you can use the target ellipsoid_article_html/fast to avoid checking the target's dependencies and to speed up the compilation process.
-. Once you have generated the updated HTML file, refresh the page in your web browser to view the changes.
-
-In the following example, all of the previous elements are combined into a DocBook editing workflow. The title of the article was changed from the default (Article Title) to the article's actual title (A Guide to Modeling with the Ellipsoid Primitive), the build target was remade, and the results are seen in a web browser.
-
-image::../books/images/hacking_brlcad_docbook_working_session.png[width=100%]
+. Modify the AsciiDoc source (`doc/asciidoc/articles/ellipsoid.adoc`).
+. Rebuild the documentation so the corresponding HTML under `share/doc/html/` is regenerated.
+. Refresh the page in your web browser to view the changes.
 
 
-==== Adding a Translated Document to BRL-CAD
+==== Working with Translated Documents
 
-By and large, adding translations of BRL-CAD documents follows the same process as adding English documents. However, you must select the correct subdirectory for the language of the translation.
-
-BRL-CAD uses the http://www-01.sil.org/iso639-3/codes.asp[ISO 639-1 language codes] (http://www-01.sil.org/iso639-3/codes.asp) as language-specific subdirectories within the higher-level categories. These are two-letter codes that represent the names of languages (for example, `pt` for Portuguese). If a language is not listed in ISO 639-1, use that's language's three-letter code from ISO 639-2 or (if necessary) ISO 639-3 instead.
-
-Currently, all translations are manually created and manually maintained. If you are working with translated documents, you are not limited to the ASCII character set; you can use Unicode characters in a document. The following example is the Armenian translation of the BRL-CAD introduction documentation:
-
-image::../books/images/hacking_brlcad_brlcad_intro_hy.png[width=100%]
+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.
 
 
 ==== Selecting Output Formats
 
-Although you can produce HTML, UNIX man pages, and PDF files from the DocBook sources, you don't have to produce all of them. By default, PDF output is not produced because it takes longer to generate than other formats. UNIX man pages are not generated by default for Windows (where they generally are of little use) to avoid wasting configuration and compilation time.
+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 the compilation of various formats on and off:
+You can use the following configuration options to turn documentation compilation on and off:
 
-.BRL-CAD DocBook Configuration Options
+.BRL-CAD Documentation Configuration Options
 [cols="3*"]
 |===
 |Option
@@ -810,64 +795,42 @@ You can use the following configuration options to turn the compilation of vario
 |Setting
 
 |BRLCAD_EXTRADOCS
-|Enable DocBook documentation
-|ON
+|Enable AsciiDoc documentation
+|ON for a full build (OFF for reduced target sets)
 |BRLCAD_EXTRADOCS_HTML
 |Enable HTML output
 |ON
 |BRLCAD_EXTRADOCS_MAN
 |Enable UNIX man page output
 |ON (OFF on Windows)
-|BRLCAD_EXTRADOCS_PDF
-|Enable PDF output (needs FOP)
-|OFF
-|BRLCAD_EXTRADOCS_PDF_MAN
-|Enable PDF man page output
-|Defaults to setting of BRLCAD_EXTRADOCS_PDF
 |===
 
-The option to disable the PDF man page output exists to support situations where someone wants the article and tutorial PDFs, without the overhead of generating hundreds of PDFs for the various manual pages. If you do not specifically want PDF versions of the individual manual pages, set the BRLCAD_EXTRADOCS_PDF_MAN option to 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.
 
 
 ==== Sharing Content Between Documents
 
-Just as different documentation formats are needed to display the same content in different software environments, different documents that serve different needs will often need to share common content. DocBook provides a mechanism, called XInclude, which allows one document to directly reference content from another document.
+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:
 
-For example, volume II of the BRL-CAD Tutorial Series makes extensive use of the XInclude mechanism. The majority of the original content in that tutorial was split up into individual lessons, each which exist as separate documents. To provide those individual documents and at the same time preserve the original Volume II, without duplicating content, the file `BRL-CAD_Tutorial_Series-VolumeII.xml` pulls in the content of the lessons using XInclude:
 
-`<xi:include href="/lessons/en/mged01_creating_primitive_shapes.xml" xpointer="creating_primitive_shapes_overviewlist"/>`
+----
+include::../lessons/mged01_creating_primitive_shapes.adoc[]
+----
 
-For this reference to work, the lesson `mged01_creating_primitive_shapes.xml` must provide matching identifying labels. The matching label for the reference above is:
+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:
 
-`<para xml:id="creating_primitive_shapes_overviewlist">`
+
+----
+include::shared_snippet.adoc[tag=overview]
+----
 
 The drawbacks to this mechanism are that:
 
 
-* You can't read a source document as a single, coherent whole. Most of the time, content pulled into a document using XInclude should be a fairly small subset of that document unless the specific purpose of the document is to aggregate other documents.
-* Content changed in one document introduces changes in other documents the author is not currently editing. Only share content with XInclude when the content is not expected to change based on the context.
+* You can't read the aggregating source document as a single, coherent whole without also consulting the included files. Keep shared fragments small unless the specific purpose of the document is to aggregate other documents.
+* Content changed in one document introduces changes in every document that includes it, even ones the author is not currently editing. Only share content this way when it is not expected to change based on context.
 
-
-==== Customizing DocBook Output
-
-DocBook does not allow you to specify the formatting details of a document. This is a deliberate design decision, since avoiding the encoding of formatting information in the original document offers greater consistency and uniformity across documents.
-
-However, some documents have unique formatting requirements. DocBook's toolchain allows you to do this type of customization, but it is the most complex aspect of working with DocBook. You should only customize the output when there is a compelling need to do so.
-
-One of the best examples of DocBook output customization in BRL-CAD is work done by Tom Browder to format the PDF covers of the BRL-CAD Tutorial Series volumes, as shown below:
-
-image::../books/images/hacking_brlcad_tutorial_1_pdf.png[width=100%]
-
-A number of elements are needed to achieve this result:
-
-
-* A custom XML Stylesheet Language (XSL) file (named `doc/docbook/resources/brlcad/tutorial-template.xsl.in`) that defines the layout of the document.
-* A custom CMake build logic file (named `doc/docbook/books/en/CMakeLists.txt`) that further customizes the template file for each individual book.
-* The Deja-Vu and STIX fonts (located in `doc/docbook/resources/other/fonts`) to ensure uniform, high-quality text rendering.
-
-Although each case of special formatting is likely to be unique, the preceding example can serve as a starting point. Another useful resource for information about customizing DocBook output is the book http://www.sagehill.net/docbookxsl[DocBook XSL: The Complete Guide] (http://www.sagehill.net/docbookxsl).
-
-Now that you have an idea about how to format documentation for the BRL-CAD project, let's take a look at the types of documentation that the project maintains.
+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.
 
 
 === Types of Documentation We Maintain
@@ -890,7 +853,7 @@ image::../books/images/hacking_brlcad_man_page_search.png[width=100%]
 
 ==== API Documentation
 
-Most of the project's documentation is maintained in the BRL-CAD source code repository as DocBook files (see the chapter Working with Our Documentation for more information about DocBook). 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 http://www.doxygen.org/[Doxygen] (http://www.doxygen.org), a tool for generating source code documentation.
+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 http://www.doxygen.org/[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.
 
@@ -972,29 +935,26 @@ The documentation and the toolchain required to generate the documentation is pa
 
 *git clone https://github.com/BRL-CAD/brlcad*
 
-The directory `brlcad` should be within your `/home` directory so that BRL-CAD's build directory commands don't interfere with your system's commands.
+The `brlcad` directory should be kept separate from your build directory so that BRL-CAD's build outputs don't clutter the source tree.
 
-===== Obtaining FOP
-
-While BRL-CAD comes with the tools for generating HTML files and UNIX man pages, you will need additional software to generate PDF files. That software is called Apache FOP, and you can download it from the http://xmlgraphics.apache.org/fop/[FOP project's website] (http://xmlgraphics.apache.org/fop/). The FOP website also has instructions for installing and configuring FOP to run on your system.
+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.
 
 
 ===== Configure
 
-Next, you must set up the build directory and configure the compilation. This will also set up the tools that you need to generate the documentation. Do that by running the following command.
+Next, you must set up the build directory and configure the compilation with documentation enabled. Run the following command from an empty build directory:
 
-*cmake ../brlcad_build -DBRLCAD_BUILD_TYPE=Debug*
+*cmake ../brlcad -DBRLCAD_EXTRADOCS=ON*
 
 
 ===== Generate the Documentation
 
-Once you've configured the compilation, you'll need to run the following build targets to generate the documentation:
+Once you've configured the compilation, you can run the following build targets to generate the documentation:
 
 
-* doc (to generate the HTML version of the documentation and the UNIX man pages)
+* doc (to generate both the HTML documentation and the UNIX man pages)
 * html (to generate the HTML version of the documentation)
 * man (to generate the UNIX man pages)
-* pdf (to generate PDF versions of the documentation. Running this target is optional, and you must have FOP installed on the system on which you're working).
 
 
 
@@ -1007,10 +967,10 @@ You can find the source files for the documentation in the following directories
 Project documentation
 
 
-`doc/docbook`::
-User documentation in XML format
+`doc/asciidoc/`::
+User and developer documentation in AsciiDoc format
 +
-See the file `doc/docbook/README` for more details
+See the file `doc/asciidoc/README.adoc` for more details
 
 
 
@@ -1025,11 +985,11 @@ Remember to:
 
 ==== Discussing the Documentation
 
-Before undertaking a documentation task, you should join the BRL-CAD http://lists.sourceforge.net/lists/listinfo/brlcad-devel[developer mailing list] (http://lists.sourceforge.net/lists/listinfo/brlcad-devel) and the #brlcad IRC channel irc.freenode.net.
+Before undertaking a documentation task, you should join the BRL-CAD community on https://brlcad.zulipchat.com[Zulip chat] and, for longer discussions, our https://github.com/BRL-CAD/brlcad/discussions[GitHub Discussions]. A secondary, legacy IRC channel named #brlcad is also available on irc.libera.chat.
 
-Joining both lists helps introduce you the the BRL-CAD community and gives you the opportunity to regularly communicate with other experienced contributors. You can also ask questions on the mailing list or the IRC channel.
+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 on the mailing list or on the IRC channel. We also strongly advise you to use interleaved posting when replying on any communication channels. And once again, _don't be afraid to ask questions_.
+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_.
 
 
 == Other Contributors
@@ -1052,9 +1012,9 @@ Let's take a look at a few other ways that you can contribute to the BRL-CAD pro
 
 ==== Bug Reporting and Feature Requests
 
-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 https://github.com/BRL-CAD/brlcad/issues[issue tracking page] on SourceForge (http://sourceforge.net/p/brlcad/bugs/). Please remember to provide enough detail so that we can reproduce the problem. You can also post to our developer mailing list at brlcad-devel@lists.sourceforge.net.
+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 https://github.com/BRL-CAD/brlcad/issues[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 https://brlcad.zulipchat.com[Zulip chat] or in our https://github.com/BRL-CAD/brlcad/discussions[GitHub Discussions].
 
-In addition, if you have a suggestion for new feature, feel free to submit a request on BRL-CAD's official http://sourceforge.net/p/brlcad/feature-requests/[feature request page] (http://sourceforge.net/p/brlcad/feature-requests/) on SourceForge. You can also post to our developer mailing list at brlcad-devel@lists.sourceforge.net.
+In addition, if you have a suggestion for a new feature, feel free to submit a request on the same https://github.com/BRL-CAD/brlcad/issues[issue tracker] (https://github.com/BRL-CAD/brlcad/issues). You can also share the idea on https://brlcad.zulipchat.com[Zulip chat] or in our https://github.com/BRL-CAD/brlcad/discussions[GitHub Discussions].
 
 
 ==== Outreach and Artwork
@@ -1127,91 +1087,56 @@ In addition to the resources provided previously in this book, the following res
 [appendix]
 === Doc Template: New MGED Command
 
-The following DocBook XML template illustrates the general structure that is used when defining a man page for MGED commands, along with examples of how elements such as paragraphs, lists, and examples are included. If you haven't worked with DocBook before, refer to the section What is DocBook? in the chapter Working with our Documentation.
+The following AsciiDoc template illustrates the general structure that is used when defining a man page for MGED commands, along with examples of how elements such as paragraphs, lists, and examples are included. Save the source as `commandname.adoc` in `doc/asciidoc/system/mann/` and register it in that directory's `CMakeLists.txt`. When rendered by asciiquack, the `:doctype: manpage` attribute produces a section-n manual page in addition to HTML. If you haven't worked with AsciiDoc before, refer to the section What is AsciiDoc? in the chapter Working with our Documentation.
 
 
+....
+= COMMANDNAME(nged)
+:doctype: manpage
+:mansource: BRL-CAD
+:manmanual: BRL-CAD MGED Commands
+
+== NAME
+commandname - A one-line summary of what the command does.
+
+== SYNOPSIS
+
+[source]
+----
+commandname [options] arguments
 ----
 
-<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="">
+[[description]]
+== DESCRIPTION
 
-<refmeta>
-  <refentrytitle> <refentrytitle/>
-  <manvolnum>nged</manvolnum>
-  <refmiscinfo class="source">BRL-CAD</refmiscinfo>
-  <refmiscinfo class="manual">BRL-CAD User Commands</refmiscinfo>
-</refmeta>
+A full description of the command goes here, in one or more paragraphs.
 
-<refnamediv xml:id="name">
-  <refname><refname/>
-  <refpurpose>
+The following options are supported:
 
-  </refpurpose>
-</refnamediv>
+* *-a* - Description of the -a option.
+* *-b* - Description of the -b option.
 
-<!-- body begins here -->
-<refsynopsisdiv xml:id="synopsis">
-  <cmdsynopsis sepchar=" ">
-    <command/>
-    <arg choice="opt" rep="norepeat"/>
-  </cmdsynopsis>
-</refsynopsisdiv>
+[[examples]]
+== EXAMPLES
 
-<refsection xml:id="description"><info><title>DESCRIPTION</title></info>
-  <para>
+.A short caption describing the first example.
+[example]
+====
+mged>**commandname arg**
 
-  </para>
-</refsection>
+An explanation of what this invocation does and what output to expect.
+====
 
-<refsection xml:id="examples"><info><title>EXAMPLES</title></info>
+== AUTHOR
 
-  <para>
+BRL-CAD Team
 
-  </para>
-  <example><info><title/></info>
+== BUG REPORTS
 
-    <variablelist>
-      <varlistentry>
-           <term><prompt/> <userinput/></term>
-           <listitem>
-             <para>
-
-             </para>
-           </listitem>
-      </varlistentry>
-      <varlistentry>
-           <term><prompt/> <userinput/></term>
-           <listitem>
-             <para>
-
-             </para>
-           </listitem>
-      </varlistentry>
-    </variablelist>
-  </example>
-
-  <example><info><title/></info>
-
-    <para>
-      <prompt/><userinput/>
-    </para>
-    <para>
-
-    </para>
-  </example>
-
-</refsection>
-
-<info><corpauthor>BRL-CAD Team</corpauthor></info>
-
-<refsection xml:id="bug_reports"><info><title>BUG REPORTS</title></info>
-
-  <para>
-    Reports of bugs or problems should be submitted via electronic
-    mail to <email>devs@brlcad.org</email>
-  </para>
-</refsection>
-</refentry>
-----
+Reports of bugs or problems should be submitted via the issue tracker at
+https://github.com/BRL-CAD/brlcad/issues, or raised on Zulip chat at
+https://brlcad.zulipchat.com.
+....
 
 [appendix]
 === Code Example: Shooting Rays

doc/asciidoc/devguides/CMakeLists.txt

@@ -1,8 +1,12 @@
 set(
   devguides_EN
   adding_new_primitive_superellipsoid.adoc
+  api_reference.adoc
   bool_eval_development.adoc
+  getting_started_as_contributor.adoc
   iterate_geometry.adoc
+  libged_command_authoring.adoc
+  raytracing_pipeline.adoc
 )
 
 set(

doc/asciidoc/devguides/adding_new_primitive_superellipsoid.adoc

@@ -854,10 +854,51 @@ and the fact that `n` and `e` are unchanged by `rt_superell_mat`.
 |MGED primitive-edit menu behavior for `Set A`, `Set B`, `Set C`, and mouse
 scaling.
 
+|`regress/mged/csg_edit.mged`
+|The MGED-to-librt integration boundary: edit lifecycle and persistence across
+the practical CSG types, menu dispatch, numeric and mouse input, knob rotation,
+selection-driven edits, file-backed primitives, and accept/reject behavior.
+
 |`src/librt/tests/prim_tess.c`
 |Documents that `rt_superell_tess` is a stub returning `-1`.
 |===
 
+The MGED regression is intentionally complementary to the librt edit tests.
+It verifies that MGED reaches the requested librt state, persists the result,
+and produces a known geometric outcome where MGED has a stable observable:
+rigid translations preserve and offset bounds, parameter edits produce the
+requested value or endpoint, and rotations produce the requested vector.  The
+lifecycle runner requires an operation-specific result validator, preventing a
+new test from checking only that serialization changed.  The librt tests remain
+responsible for exhaustive numerical validation of the editing algorithms.
+Mouse input is meaningful for translate, scale, and pick states; interactive
+rotation is delivered through the knob path.
+Selection-heavy editors such as ARS, BoT, metaball, NMG, pipe, and sketch
+receive representative end-to-end workflows in MGED and detailed topology
+coverage in librt.  ARB4 through ARB8 are the exception to representative menu
+sampling: every point, edge, move-face, and rotate-face entry is exercised and
+checked against its selected point, line, face plane, or fixed rotation vertex
+because their menus have type-specific operation mappings.
+
+The same regression also exercises the GUI command boundary without requiring
+a window system.  It runs the command sequence issued by the Tk matrix picker,
+invokes all eight matrix-edit menu callbacks, and sends the unconstrained and
+X/Y/Z-constrained translate, rotate, and scale drags installed by the default
+Tk bindings.  Each case checks the exact stored combination matrix and confirms
+that the view center, size, and orientation did not change.  A graphical
+primitive pick similarly verifies the resulting primitive bounds and unchanged
+view.  This catches event-routing failures and stale MGED-to-librt edit state in
+ordinary headless regression runs.
+
+Headless testing cannot verify rendered classic-faceplate hit regions, Tk
+widget construction and bindings, or the separate Tk Primitive Editor form.
+Those require a display-backed test (normally Xvfb) which generates events on
+the real widgets.  Such a test should verify the selected matrix path, invoke
+each faceplate operation, and exercise Primitive Editor Apply, Reset, create,
+and type-change actions with exact database assertions.  Keep those widget
+tests separate from `csg_edit.mged`: the latter remains the portable behavioral
+test for the commands the widgets dispatch.
+
 At minimum, a new primitive should have tests for database round trip, `make`
 or `in` creation, ray hits and misses, normals, bounding boxes, text
 description, transforms, and every edit mode it advertises.  If a hook is a

doc/asciidoc/devguides/api_reference.adoc

@@ -0,0 +1,123 @@
+= The BRL-CAD API Reference
+:doctype: article
+:toc: left
+:toclevels: 3
+:sectlinks:
+:sectanchors:
+
+BRL-CAD ships a comprehensive C/C++ API reference generated directly from the
+documentation comments in its public headers and sources.  The reference is
+produced with https://www.doxygen.nl[Doxygen], and this page explains what it
+covers and how to build it.
+
+The narrative developer guides on this site (for example,
+link:raytracing_pipeline.html[The librt Ray Tracing Pipeline] and
+link:libged_command_authoring.html[Authoring a New libged Command]) describe
+architecture and intent.  The Doxygen reference complements them by documenting
+the exact functions, structures, and macros at the level of individual symbols.
+
+You can find an online version of the Doxygen generated pages at the
+https://brl-cad.github.io/doxygen[BRL-CAD Doxygen] github.io website. Usually
+this page is automatically regenerated on a nightly basis.
+
+== What the API reference covers
+
+The reference documents BRL-CAD's public programming interfaces at the symbol
+level: functions and their parameters, data structures and their fields,
+typedefs, enumerations, and macros, together with the relationships between
+them (call graphs, include graphs, and module groupings) that Doxygen derives
+from the source.
+
+It is organized around BRL-CAD's core libraries.  The Doxygen configuration
+groups the libraries as modules, including the portability layer `libbu`, the
+numerics libraries `libbn`, `libbg`, and `libbv`, the geometry and modeling
+libraries `libnmg`, `libbrep`, `librt`, `libwdb`, and `libgcv`, the analysis
+library `libanalyze`, the optical/shading library `liboptical`, the geometry
+editing library `libged`, the display and networking libraries `libdm` and
+`libpkg`, and shared foundational headers such as `common.h` and `vmath.h`.
+The library APIs are also summarized in the
+link:../man3_index.html[Library APIs] index.
+
+Because the content is generated from in-source comments, it always reflects
+the state of the tree you build from, which makes it the authoritative source
+for exact signatures and structure layouts.
+
+== Prerequisites
+
+To build the API reference you need a working Doxygen installation.  BRL-CAD's
+build detects Doxygen with CMake's `find_package(Doxygen)`; when Doxygen is
+found, the documentation build targets described below are defined
+automatically.  If Doxygen is not installed, those targets are simply not
+created, and configuring will still succeed for the rest of the build.
+
+The Doxygen setup itself lives in `misc/doxygen/`: the template configuration
+`misc/doxygen/Doxyfile.in` is expanded by CMake (via the logic in
+`misc/CMake/Doxygen.cmake` and `misc/doxygen/CMakeLists.txt`) into the
+per-library and whole-tree Doxygen configuration files that drive the run.
+
+== Building the reference
+
+Configure the project as usual, then build one of the Doxygen targets from your
+build directory.  Two granularities are available.
+
+To build the complete API reference across all documented libraries, build the
+`doxygen` target (equivalently, the `dox` target):
+
+[source,sh]
+----
+cmake -S . -B build
+cmake --build build --target doxygen
+----
+
+To build the reference for a single library, build its `dox-<library>` target.
+For example, to document only `librt`:
+
+[source,sh]
+----
+cmake --build build --target dox-librt
+----
+
+Per-library targets are defined for each library in the Doxygen module list,
+which is convenient when you are iterating on the comments in one library and do
+not want to regenerate everything.
+
+== Where the output is written
+
+The generated HTML is written under your build directory's `doc/` tree.  The
+whole-tree build populates `doc/doxygen_output/html/`, and each per-library
+build populates `doc/doxygen_<library>/html/` (for instance,
+`doc/doxygen_librt/html/`).  Open the `index.html` in the corresponding
+directory to browse the result.
+
+== Optional configuration
+
+A couple of optional CMake variables adjust the Doxygen run:
+
+* `BRLCAD_DOXYGEN_ADD_SRCS` — when defined, adds the libraries' `src/`
+  directories to the Doxygen inputs so that implementation files, not just
+  public headers, are documented.
+* `BRLCAD_DOXYGEN_ONLY` — when set, configures the project purely to produce
+  Doxygen output, skipping the rest of the normal configure-and-build process.
+  This is useful for documentation-only builds.
+
+These are optional; the default build produces the header-level reference
+without them.
+
+== Writing documentation that appears in the reference
+
+Because the reference is generated from source comments, the way to improve it
+is to improve the Doxygen comments in the headers and sources.  When you add or
+change a public function, structure, or macro, document it with a Doxygen
+comment block so it is captured in the generated output.  Building the relevant
+`dox-<library>` target and reviewing the result is a good final check when
+contributing API changes.
+
+== Relationship to the AsciiDoc documentation
+
+The Doxygen API reference and this AsciiDoc documentation set are produced by
+separate mechanisms.  The AsciiDoc guides and man pages are built when CMake is
+configured with `BRLCAD_EXTRADOCS=ON`, whereas the Doxygen reference is built
+through the `doxygen`/`dox-<library>` targets described above whenever Doxygen
+is available.  Use the AsciiDoc guides for tutorials, walkthroughs, and
+architectural overviews, and use the Doxygen reference for precise, symbol-level
+API detail.

doc/asciidoc/devguides/bool_eval_development.adoc

@@ -647,7 +647,7 @@ In order to inspect the surfaces and indices for a particular stage of the overa
 
 The *dplot* command is used to visualize the results of different stages of the NURBS Boolean evaluation algorithm. This makes it easier to isolate the source of a problem in an evaluation.
 
-Unlike the *brep* command, the *dplot* command is purely a development tool. Its implementation does not honor library boundaries and does not conform to the typical conventions for editor commands, and for this reason is only available as an Archer command in the NURBS Boolean evaluation development branch (https://sourceforge.net/p/brlcad/code/HEAD/tree/brlcad/branches/brep-debug/).
+Unlike the *brep* command, the *dplot* command is purely a development tool. Its implementation does not honor library boundaries and does not conform to the typical conventions for editor commands, and for this reason is only available as an Archer command in the historical NURBS Boolean evaluation development branch of the source repository.
 
 In the development branch, the NURBS Boolean evaluation source code contains additional calls to `DebugPlot` functions (implemented in `debug_plot.cpp`) that create wireframe visualizations of data produced during the evaluations.
 
@@ -883,7 +883,7 @@ For a multi-part evaluation, you'll need to first skip to the correct invocation
 
 What follows is a step-by-step debugging of a real issue affecting the `X` combination from the BRL-CAD sample database `axis.g`.
 
-This issue was fixed in revision 65179 in the NURBS Boolean evaluation development branch of the source repository (https://sourceforge.net/p/brlcad/code/HEAD/tree/brlcad/branches/brep-debug/).
+This issue was fixed in the historical NURBS Boolean evaluation development branch of the source repository.
 
 If you want to follow along, you can reinstate the error in a checkout of the development branch:
 

doc/asciidoc/devguides/getting_started_as_contributor.adoc

@@ -0,0 +1,198 @@
+= Getting Started as a BRL-CAD Contributor
+:doctype: article
+:toc: left
+:toclevels: 3
+:sectlinks:
+:sectanchors:
+
+This guide is a practical, end-to-end walkthrough for making your first
+contribution to BRL-CAD.  It covers acquiring the source, configuring and
+building it, running the test suite, finding an appropriate first task, and
+submitting your work for review.
+
+BRL-CAD is a large, cross-platform, open-source solid modeling system with a
+long history.  You do not need to understand all of it to contribute
+effectively.  Most first contributions touch a single tool, library function,
+document, or test, and this guide is written with that scope in mind.
+
+For a deeper treatment of coding standards, project conventions, and internal
+architecture, consult the canonical contributor reference,
+link:../books/HACKING_BRL-CAD.html[HACKING BRL-CAD].
+
+== Prerequisites
+
+Before you begin, make sure you have the following available on your system:
+
+* *Git* for cloning the repository and managing your changes.
+* *CMake* version 3.22 or newer, which drives the entire build.
+* A *C11* and *C++17* capable toolchain (for example, GCC, Clang, or the
+  Microsoft Visual C++ compiler).
+* Enough free disk space for the source tree, its external dependencies, and a
+  full build.  A complete build is sizable; budget several gigabytes.
+
+BRL-CAD manages most of its third-party dependencies through a bundled external
+dependency system, so you generally do not need to install libraries by hand.
+Platform-specific requirements and any optional prerequisites are documented in
+the top-level `INSTALL` file, which is the authoritative source for build
+requirements.
+
+== Getting the source
+
+Clone the official repository from GitHub:
+
+[source,sh]
+----
+git clone https://github.com/BRL-CAD/brlcad
+cd brlcad
+----
+
+The default branch is `main`, which is where active development takes place.
+When you start work on a change, create a topic branch off `main` so your work
+stays isolated and easy to review:
+
+[source,sh]
+----
+git switch -c my-first-change
+----
+
+== Configuring and building
+
+BRL-CAD uses an out-of-source CMake build.  Create a separate build directory
+so generated files never mix with the source tree:
+
+[source,sh]
+----
+cmake -S . -B build
+cmake --build build
+----
+
+The first configure step will also stage and build the bundled external
+dependencies, so the initial run takes noticeably longer than subsequent
+builds.
+
+The top-level `INSTALL` file describes the supported generators, useful
+configuration options, and platform-specific notes.  Read it before your first
+build; it is the definitive reference for how to configure BRL-CAD on your
+platform.
+
+=== Building the documentation
+
+The documentation, including this guide, is only generated when the build is
+configured with the `BRLCAD_EXTRADOCS` option enabled:
+
+[source,sh]
+----
+cmake -S . -B build -DBRLCAD_EXTRADOCS=ON
+cmake --build build
+----
+
+If you are contributing documentation, enable this option so you can build and
+review your changes locally before submitting them.  For the C/C++ API
+reference generated from source comments, see
+link:api_reference.html[The BRL-CAD API Reference].
+
+== Running the test suite
+
+BRL-CAD's automated tests are driven by CTest.  After building, run the suite
+from your build directory:
+
+[source,sh]
+----
+ctest --test-dir build
+----
+
+Useful options while iterating:
+
+* `ctest --test-dir build -N` lists the available tests without running them.
+* `ctest --test-dir build -R <pattern>` runs only tests whose names match a
+  regular expression, which is handy when you are working on one area.
+* `ctest --test-dir build --output-on-failure` prints the output of any test
+  that fails, which is essential for diagnosing problems.
+
+Run the relevant tests before and after your change so you can confirm you have
+not introduced a regression.  If your contribution adds or fixes behavior,
+consider adding a test that exercises it.
+
+== Finding a good first issue
+
+Open tasks are tracked as GitHub issues:
+
+* Issue tracker (bugs and feature requests):
+  https://github.com/BRL-CAD/brlcad/issues
+
+Browse the open issues for something small and self-contained.  Documentation
+fixes, small tool improvements, and well-described bugs make excellent first
+contributions because their scope is clear.  If an issue is unclear, ask a
+question on the issue itself before investing significant effort.
+
+If you would like to discuss ideas or ask for guidance before picking a task,
+use the project's communication channels described below.
+
+== Submitting a pull request
+
+BRL-CAD accepts contributions as pull requests against the `main` branch of the
+GitHub repository.  A typical workflow is:
+
+. Fork the repository on GitHub and add your fork as a remote, or push your
+  topic branch to a branch you have permission to push.
+. Commit your work in logical, self-contained commits with clear messages that
+  explain *why* the change is being made, not only *what* changed.
+. Push your topic branch and open a pull request against
+  https://github.com/BRL-CAD/brlcad targeting `main`.
+. In the pull request description, summarize the change, reference any related
+  issue, and note how you verified it (for example, which tests you ran).
+
+Keep each pull request focused on a single logical change.  Smaller, focused
+pull requests are reviewed faster and merged more easily than large ones that
+mix unrelated changes.
+
+== The review process
+
+Once your pull request is open, maintainers and other contributors will review
+it.  Reviews are a normal, collaborative part of the process, and it is common
+for even experienced contributors to be asked for revisions.
+
+During review you can expect:
+
+* Feedback on correctness, style, and adherence to project conventions.  The
+  conventions are documented in
+  link:../books/HACKING_BRL-CAD.html[HACKING BRL-CAD].
+* Requests to add or adjust tests, or to split a change into smaller pieces.
+* Automated checks that build the project and run tests against your change.
+
+Respond to review comments by updating your topic branch and pushing new
+commits; the pull request updates automatically.  Be patient and courteous;
+maintainers are volunteers and reviewers, and clear, responsive communication
+helps your contribution land.
+
+== Communicating with the community
+
+The BRL-CAD community uses the following channels:
+
+* *Chat (Zulip):* https://brlcad.zulipchat.com — the primary place for
+  real-time discussion, questions, and coordination.
+* *Q&A and longer discussions (GitHub Discussions):*
+  https://github.com/BRL-CAD/brlcad/discussions — for questions and topics that
+  benefit from a durable, searchable thread.
+* *Bugs and feature requests (GitHub Issues):*
+  https://github.com/BRL-CAD/brlcad/issues
+
+A secondary, legacy IRC channel also exists at `#brlcad` on
+`irc.libera.chat`, but Zulip and GitHub Discussions are the recommended
+channels for new contributors.
+
+== Next steps
+
+Once you are comfortable with the build-and-test loop, the following resources
+will help you go deeper:
+
+* link:../books/HACKING_BRL-CAD.html[HACKING BRL-CAD] — coding standards,
+  conventions, and internals.
+* link:raytracing_pipeline.html[The librt Ray Tracing Pipeline] — how the core
+  ray tracing library works end to end.
+* link:libged_command_authoring.html[Authoring a New libged Command] — how to
+  add a new geometry-editing command.
+* link:api_reference.html[The BRL-CAD API Reference] — the Doxygen-generated
+  C/C++ API documentation.
+
+Welcome to BRL-CAD.  We look forward to your contributions.

doc/asciidoc/devguides/libged_command_authoring.adoc

@@ -0,0 +1,203 @@
+= Authoring a New libged Command
+:doctype: article
+:toc: left
+:toclevels: 3
+:sectlinks:
+:sectanchors:
+
+`libged` is BRL-CAD's geometry-editing library.  It provides the `ged_*`
+commands that front-end applications such as MGED, Archer, and `qged` dispatch
+when a user types a command.  This guide describes, at an architectural level,
+how to add a new `libged` command: how commands are structured, how they are
+registered and dispatched, and the argument and result conventions they follow.
+
+This page does not reproduce full function prototypes.  For exact signatures
+and structure fields, consult `include/ged.h`, the headers under
+`include/ged/`, and the sources under `src/libged/`, along with the
+Doxygen-generated link:api_reference.html[API Reference].
+
+== The shape of a command
+
+Every `libged` command is a C function with a uniform signature: it takes a
+`struct ged *`, an argument count, and an argument vector, and returns an `int`
+status code.  Conceptually:
+
+[source,c]
+----
+int ged_example_core(struct ged *gedp, int argc, const char *argv[]);
+----
+
+* `gedp` carries the editing context: the open database, view state, and, among
+  other things, the result string `gedp->ged_result_str`.
+* `argc`/`argv` follow the usual command-line convention, with `argv[0]` being
+  the command name itself.
+* The return value is `BRLCAD_OK` on success or `BRLCAD_ERROR` on failure
+  (defined alongside the other status codes in `include/ged/defines.h`).
+
+By convention the implementation function is named `ged_<name>_core`.  Existing
+commands under `src/libged/` are the best templates; the `echo` command in
+`src/libged/echo/echo.c` is a minimal, self-contained example.
+
+== Where a command lives
+
+Each command (or closely related group of commands) lives in its own
+subdirectory under `src/libged/`, for example `src/libged/echo/`.  A directory
+typically contains:
+
+* one or more `.c`/`.cpp` source files implementing the command, and
+* a `CMakeLists.txt` that builds the command as a `libged` plugin.
+
+The new subdirectory must be registered in `src/libged/CMakeLists.txt` with an
+`add_subdirectory(<name>)` entry so it is included in the build.
+
+== Argument and result conventions
+
+`libged` commands communicate results through the context, not through return
+values or `stdout`:
+
+* *Clear the result first.*  Truncate `gedp->ged_result_str` at the start so
+  stale output from a previous command does not leak into yours.
+* *Write output to `ged_result_str`.*  Use `bu_vls_printf()` (and related
+  `bu_vls` functions) to build the textual result the caller will read.  Do not
+  print directly to `stdout`/`stderr` for normal results.
+* *Return a status code.*  Return `BRLCAD_OK` or `BRLCAD_ERROR`; on error,
+  place a human-readable message in `ged_result_str`.
+
+`libged` provides guard macros in `include/ged/defines.h` to enforce common
+preconditions cleanly.  For example, `GED_CHECK_ARGC_GT_0()` verifies that a
+command name was actually supplied, emitting a diagnostic into
+`ged_result_str` and returning early if not.  Other `GED_CHECK_*` macros guard
+conditions such as an open database or a writable (non-read-only) database.
+Use them at the top of your implementation to keep error handling uniform with
+the rest of the library.
+
+== Registration
+
+`libged` supports two deployment models from the same source: commands can be
+compiled into the library as a static core, or loaded as plugins.  A small set
+of macros, declared in `src/libged/include/plugin.h`, generates the correct
+registration code for both models so that individual commands do not have to
+care which one is in effect.
+
+A command file registers itself with two steps at file scope, after the
+implementation:
+
+. Define a *command-set list macro* that enumerates the commands the file
+  provides, mapping each command name to its implementation function and a set
+  of option flags.
+. Invoke `GED_DECLARE_COMMAND_SET()` and `GED_DECLARE_PLUGIN_MANIFEST()` on
+  that list.
+
+Using the `echo` command as a concrete example:
+
+[source,c]
+----
+#include "../include/plugin.h"
+
+#define GED_ECHO_COMMANDS(X, XID) \
+    X(echo, ged_echo_core, GED_CMD_DEFAULT)
+
+GED_DECLARE_COMMAND_SET(GED_ECHO_COMMANDS)
+GED_DECLARE_PLUGIN_MANIFEST("libged_echo", 1, GED_ECHO_COMMANDS)
+----
+
+Each list entry has the form `X(token, fn, opts)`:
+
+* `token` is the command name as a C identifier (it becomes the command
+  string).
+* `fn` is the implementation function (for example, `ged_echo_core`).
+* `opts` is a bitmask of `GED_CMD_*` option flags from
+  `src/libged/include/plugin.h`.  `GED_CMD_DEFAULT` requests no special
+  behavior; other flags mark a command as interactive, or as updating the scene
+  or view, and so on.
+
+When a command name cannot be written as a plain C identifier (for example the
+`?` command), use the `XID(symbol, "cmdname", fn, opts)` form instead, which
+lets you supply an explicit symbol name and an arbitrary command string.  A
+single list may contain multiple entries, which is also how aliases (several
+names bound to the same implementation) are expressed.
+
+`GED_DECLARE_COMMAND_SET()` emits the command metadata (and, in static-core
+builds, the registration anchors that let the library find the command).
+`GED_DECLARE_PLUGIN_MANIFEST()` emits the plugin export manifest when the file
+is compiled as a plugin.  Because both are driven by the same list macro, you
+describe your commands in exactly one place.
+
+== Building the command
+
+The command's `CMakeLists.txt` builds it as a plugin with the
+`ged_plugin_library()` helper defined in `src/libged/CMakeLists.txt`.  Following
+the `echo` example (`src/libged/echo/CMakeLists.txt`):
+
+[source,cmake]
+----
+set(PLUGIN_LIBS libged libbu)
+
+ged_plugin_library(ged-echo
+  echo.c
+  LIBS ${PLUGIN_LIBS}
+)
+
+cmakefiles(
+  CMakeLists.txt
+)
+----
+
+Adjust the plugin target name, source files, and `LIBS` to match your command's
+needs, then add the corresponding `add_subdirectory()` line in
+`src/libged/CMakeLists.txt`.
+
+== Dispatch: how the command is invoked
+
+Front-end applications do not call your `ged_<name>_core` function directly.
+Instead they call `ged_exec()` (declared in `include/ged/commands.h`) with the
+command name and arguments.  `ged_exec()` looks the name up in the command
+registry, runs any registered pre-command callbacks, invokes your
+implementation, and runs any post-command callbacks.  This indirection is what
+makes registration necessary: `ged_exec()` is the single entry point through
+which every command is reached, and it is also where scene/view update
+callbacks associated with your `GED_CMD_*` flags are honored.
+
+Because dispatch always flows through `ged_exec()`, command implementations
+should not invoke that machinery themselves; they simply do their work and
+return a status code.
+
+== Checklist for a new command
+
+. Create `src/libged/<name>/` with your source file(s).
+. Implement `ged_<name>_core(struct ged *gedp, int argc, const char *argv[])`.
+. Clear `gedp->ged_result_str`, validate inputs with the `GED_CHECK_*` macros,
+  do the work, write results to `ged_result_str`, and return
+  `BRLCAD_OK`/`BRLCAD_ERROR`.
+. Register the command with a list macro plus `GED_DECLARE_COMMAND_SET()` and
+  `GED_DECLARE_PLUGIN_MANIFEST()`.
+. Add a `CMakeLists.txt` using `ged_plugin_library()`.
+. Add `add_subdirectory(<name>)` to `src/libged/CMakeLists.txt`.
+. Build and exercise the command through a front end (for example, MGED) so it
+  runs via `ged_exec()`.
+
+== Where to look next
+
+[cols="1,2",options="header"]
+|===
+| Location
+| Contents
+
+| `include/ged.h`
+| Public `libged` entry points.
+
+| `include/ged/defines.h`
+| `struct ged`, status codes, and the `GED_CHECK_*` guard macros.
+
+| `include/ged/commands.h`
+| `ged_exec()` and command dispatch.
+
+| `src/libged/include/plugin.h`
+| The registration macros, option flags, and `struct ged_cmd_impl`.
+
+| `src/libged/echo/`
+| A minimal, complete command to use as a template.
+|===
+
+For generated API documentation covering these headers, build and consult the
+link:api_reference.html[API Reference].

doc/asciidoc/devguides/raytracing_pipeline.adoc

@@ -0,0 +1,233 @@
+= The librt Ray Tracing Pipeline
+:doctype: article
+:toc: left
+:toclevels: 3
+:sectlinks:
+:sectanchors:
+
+This guide explains, at an architectural level, how ray tracing works in
+`librt`, BRL-CAD's solid ray tracing library.  It follows a single ray from
+application setup through geometry preparation, ray shooting, and the callbacks
+that deliver results back to your code.
+
+This page intentionally does not reproduce full function prototypes.  For exact
+signatures, argument details, and structure fields, consult the headers under
+`include/rt/` and the Doxygen-generated
+link:api_reference.html[API Reference].  The most relevant headers are called
+out throughout.
+
+== What librt does
+
+`librt` computes ray/geometry intersections against BRL-CAD's constructive
+solid geometry (CSG) models.  Unlike a surface-only renderer, it reports
+*in/out pairs* of hits so that closed volumes can be characterized correctly,
+and it evaluates the Boolean combination trees (union, intersection,
+subtraction) that define regions.  The result of shooting a ray is a set of
+*partitions*, each describing a span of the ray that lies inside one region.
+
+== The overall flow
+
+A typical ray tracing session follows four phases:
+
+. *Open the database* and build its directory with `rt_dirbuild()`.
+. *Load geometry* into the ray tracing instance with `rt_gettree()` (or a
+  related variant).
+. *Prepare* the acceleration structures with `rt_prep()` /
+  `rt_prep_parallel()`.
+. *Shoot rays* with `rt_shootray()`, receiving results in your `a_hit()` and
+  `a_miss()` callbacks.
+
+The following sections walk through each phase.  The central data structures
+are `struct rt_i` (the ray tracing instance, declared in
+`include/rt/rt_instance.h`) and `struct application` (the per-ray request,
+declared in `include/rt/application.h`).
+
+== Phase 1: Building the directory (rt_dirbuild)
+
+`rt_dirbuild()` (declared in `include/rt/db_io.h`) opens a `.g` geometry
+database and reads its object directory, returning a pointer to a newly
+allocated `struct rt_i`.  This `rt_i` instance is the handle you pass to the
+rest of the pipeline; the pointer it returns becomes the `a_rt_i` field of your
+application structure.
+
+If the database cannot be opened, `rt_dirbuild()` returns `RTI_NULL`.  A
+companion entry point, `rt_dirbuild_inmem()`, builds an instance from an
+in-memory database image rather than a file.
+
+== Phase 2: Loading geometry (rt_gettree)
+
+Opening the database makes its objects available but does not yet load any
+geometry for ray tracing.  To select which objects participate, call
+`rt_gettree()` (declared in `include/rt/rt_instance.h`) once per top-level
+object you want to trace against.  It walks the named object's combination
+tree, imports the referenced primitives, and associates them with the `rt_i`
+instance.
+
+Related entry points give you more control:
+
+* `rt_gettrees()` loads several named objects in a single call.
+* `rt_gettrees_and_attrs()` additionally captures a specified list of object
+  attributes, which is how per-region attribute data is made available during
+  shooting.
+
+These functions determine the set of *solids* (primitives) and *regions* that
+subsequent rays will intersect.
+
+== Phase 3: Preparation (rt_prep)
+
+Before any ray can be shot, the loaded geometry must be *prepped*.  Preparation
+computes each primitive's bounding information and builds the spatial
+acceleration structure (the space partitioning used to quickly reject geometry
+a ray cannot possibly hit).
+
+* `rt_prep()` prepares the instance for single-threaded use.
+* `rt_prep_parallel()` prepares the instance for use by a specified number of
+  parallel CPUs.
+
+The `rt_i` instance tracks whether preparation is required via its `needprep`
+field.  In practice, `rt_shootray()` will trigger preparation automatically if
+it has not yet been done, but calling `rt_prep()` (or `rt_prep_parallel()`)
+explicitly lets you control when this potentially expensive step happens, and
+is required when tracing in parallel so that the acceleration structures are
+ready before multiple threads begin shooting.
+
+== The application structure
+
+`struct application` is the single parameter to `rt_shootray()`.  It carries
+the ray to shoot, the callbacks to invoke, the instance to trace against, and a
+number of application-specific fields.  Always initialize it with the
+`RT_APPLICATION_INIT()` macro before setting fields, so that reserved sanity
+fields are zeroed.
+
+The mandatory fields are:
+
+[cols="1,3",options="header"]
+|===
+| Field
+| Meaning
+
+| `a_ray.r_pt`
+| Starting point of the ray.
+
+| `a_ray.r_dir`
+| Ray direction, given as a unit vector of direction cosines.
+
+| `a_hit`
+| Callback invoked when the ray intersects geometry.
+
+| `a_miss`
+| Callback invoked when the ray intersects nothing.
+
+| `a_rt_i`
+| The `struct rt_i *` returned by `rt_dirbuild()`.
+|===
+
+Other commonly used fields include `a_resource` (per-CPU resources, required
+for multithreaded tracing), `a_onehit` (stop after the first hit), `a_level`
+and `a_x`/`a_y` (bookkeeping used in logging), and the application-specific
+`a_uptr`, `a_color`, and `a_user` fields, which the library never touches and
+which you can use to carry your own state into the callbacks.  See
+`include/rt/application.h` for the complete, authoritative field list.
+
+== Phase 4: Shooting a ray (rt_shootray)
+
+`rt_shootray()` (declared in `include/rt/shoot.h`) takes a fully populated
+`struct application *` and intersects `a_ray` against the prepped geometry.
+Internally it traverses the space partitioning acceleration structure,
+intersects candidate primitives to produce *segments* (`struct seg`, in
+`include/rt/seg.h`), and evaluates the region Boolean trees to produce
+*partitions* (`struct partition`, in `include/rt/ray_partition.h`).
+
+`rt_shootray()` then dispatches to exactly one of your callbacks and returns
+the value that callback placed in `a_return`.
+
+The library also provides related shooting entry points, including
+`rt_shootrays()` for ray bundles (see `struct application_bundle`) and
+`rt_shootray_simple()`, but `rt_shootray()` is the fundamental operation.
+
+=== The hit callback
+
+Your `a_hit()` function is called when the ray produces at least one partition.
+It receives the application pointer, the head of the partition list, and the
+segment list.  Each `struct partition` describes one in/out span of the ray
+inside a single region and references:
+
+* `pt_inhit` and `pt_outhit` — the entry and exit `struct hit` records (from
+  `include/rt/hit.h`), whose `hit_dist` gives the signed distance along the ray
+  from `a_ray.r_pt`.
+* `pt_regionp` — the `struct region` the span belongs to.
+
+The intersection point is reconstructed from the ray origin, direction, and
+`hit_dist` (conventionally with `VJOIN1`).  Surface normals are obtained with
+the `RT_HIT_NORMAL()` macro rather than by reading raw fields directly.  Walk
+the partition list to examine every region span the ray passed through.
+
+=== The miss callback
+
+Your `a_miss()` function is called when the ray intersects no geometry.  It
+receives only the application pointer.  This is where a renderer would, for
+example, assign a background color.
+
+=== Return values
+
+The `int` you return from `a_hit()` or `a_miss()` is stored in `a_return` and
+becomes the return value of `rt_shootray()`.  By convention, applications use
+this to signal a hit versus a miss (for example, returning 1 from `a_hit()` and
+0 from `a_miss()`), but the exact meaning is defined by your application.
+
+== Overlaps
+
+When two regions claim the same span of a ray, the geometry *overlaps*.
+`librt` resolves overlaps through the `a_multioverlap` callback and reports them
+through `a_logoverlap`; a default implementation is provided if you do not
+supply your own.  Overlaps usually indicate a modeling error, and the reporting
+hooks let tools surface them to the user.
+
+== Parallel ray tracing and resources
+
+For multithreaded tracing, each CPU needs its own `struct resource` (declared
+in `include/rt/resource.h`), assigned to `a_resource`, so that per-ray scratch
+memory is not shared across threads.  Prepare the instance with
+`rt_prep_parallel()` before launching worker threads, give each thread its own
+application structure and resource, and let each call `rt_shootray()`
+independently.
+
+== Cleanup
+
+When you are finished, release the resources associated with the instance.
+`rt_clean()` returns an `rt_i` to a pre-`gettree` state so it can be reused,
+and the resource-cleanup entry points (for example,
+`rt_clean_resource_basic()`) release per-CPU resources.  See
+`include/rt/rt_instance.h` for the current, non-deprecated cleanup functions.
+
+== Where to look next
+
+[cols="1,2",options="header"]
+|===
+| Header
+| Contents
+
+| `include/rt/rt_instance.h`
+| `struct rt_i`, `rt_gettree()`, `rt_prep()`, cleanup functions.
+
+| `include/rt/application.h`
+| `struct application`, `RT_APPLICATION_INIT()`.
+
+| `include/rt/shoot.h`
+| `rt_shootray()` and related shooting entry points.
+
+| `include/rt/ray_partition.h`
+| `struct partition` and the partition list.
+
+| `include/rt/seg.h`
+| `struct seg` (ray/primitive segments).
+
+| `include/rt/hit.h`
+| `struct hit` and `RT_HIT_NORMAL()`.
+
+| `include/rt/db_io.h`
+| `rt_dirbuild()` and database I/O.
+|===
+
+For generated API documentation covering these headers, build and consult the
+link:api_reference.html[API Reference].

doc/asciidoc/lessons/es/CMakeLists.txt

@@ -25,8 +25,8 @@ set(
   images/mged01_terminal.png
   images/mged02_coordsys.png
   images/mged02_defaultradio.png
-  images/mged02_flower_zooomin.png
-  images/mged02_flower_zooomout.png
+  images/mged02_flower_zoomin.png
+  images/mged02_flower_zoomout.png
   images/mged02_multipane.png
   images/mged02_radio_35_25.png
   images/mged02_radio_front.png
@@ -43,6 +43,10 @@ set(
   images/mged02_truck_left.png
   images/mged02_truck_rear.png
   images/mged02_truck_right.png
+  images/mged03_shapes_in_command.png
+  images/mged03_shapes_make_command.png
+  images/mged03_wireframe_sph.png
+  images/mged03_wireframe_sph_rcc.png
   images/mged04_commandwindow.png
   images/mged04_fb_overlay_mode.png
   images/mged04_raytracedshapes.png
@@ -55,7 +59,7 @@ set(
   images/mged05_subtractionspheres.png
   images/mged05_twoprimitivespheres.png
   images/mged05_unionspheres.png
-  images/mged06_base_substracted_vol.png
+  images/mged06_base_subtracted_vol.png
   images/mged06_goblet1stsphere.png
   images/mged06_gobletbase.png
   images/mged06_gobletbasestembasin.png

doc/asciidoc/lessons/es/mged01_crear_figuras_primitivas.adoc

@@ -22,6 +22,7 @@ Este tutorial le ayudará a:
 * Crear una esfera usando el menú gráfico.
 * Usar el comando "l" para listar los parámetros o atributos de la figura.
 * Usar el comando "ls" para listar el contenido de la base de datos.
+* Usar el comando "tops" para identificar los objetos de nivel superior de la base de datos.
 * Eliminar una figura u objeto desde la base de datos usando el comando "kill" + comando.
 * Editar un comando.
 * Presionar "q" o usar el comando "exit" para salir del programa.
@@ -231,6 +232,18 @@ Use el comando l para listar sph1.s y sph2.s antes de continuar los ejemplos
 
 Además de ver los parámetros de una figura, también puede ser que desee ver la lista de los contenidos de la base de datos para ver qué artículos han sido creados. Para esto, escriba en la ventana de línea de comandos: *ls [ENTER].*
 
+El comando *ls* muestra todos los objetos, lo cual puede resultar abrumador
+en una base de datos existente. El comando *tops* suele ser el mejor punto de
+partida para explorar una base de datos desconocida: muestra únicamente los
+objetos que no son miembros de otra combinación. Estos objetos de nivel
+superior suelen ser los ensamblajes o modelos que conviene dibujar o examinar
+primero. En la ventana de línea de comandos, escriba: *tops [ENTER].*
+
+En la base de datos sencilla _sphere.g_, las figuras primitivas todavía son
+objetos de nivel superior. Cuando cree combinaciones en tutoriales posteriores,
+*tops* omitirá las figuras que sean miembros y mostrará los puntos de entrada
+de nivel superior.
+
 
 [[kill_object]]
 == Eliminar un objeto de la base de datos
@@ -282,6 +295,7 @@ En este tutorial usted:
 * Utilizó el entorno gráfico para crear una figura primitiva.
 * Utilizó el comando l para visualizar una lista de parámetros de la figura.
 * Utilizó el comando ls para listar los contenidos de una base de datos.
+* Utilizó el comando tops para identificar objetos de nivel superior.
 * Utilizó el comando kill para eliminar una figura de la base de datos.
 * Editó comandos en la ventana de comandos.
 * Utilizó los comandos q o exit para salir del programa.

doc/asciidoc/lessons/es/mged02_opciones_vistas.adoc

@@ -119,8 +119,8 @@ El tamaño de la vista es la cantidad de espacio modelo que se muestra en la ven
 [cols="2*"]
 [%noheader]
 |===
-|image:../../lessons/es/images/mged02_flower_zoomin.jpg[]
-|image:../../lessons/es/images/mged02_flower_zoomout.jpg[]
+|image:../../lessons/es/images/mged02_flower_zoomin.png[]
+|image:../../lessons/es/images/mged02_flower_zoomout.png[]
 |Zoom de acercamiento para ver detalles (vista a pequeña escala)
 |Zoom distante para ver el objeto en relación con su entorno (vista a gran escala)
 |===

doc/asciidoc/lessons/es/mged03_utilizar_comando_in.adoc

@@ -45,7 +45,7 @@ Como pudo apreciar en el tutorial #1, este comando le dice a _MGED_ que:
 
 
 
-image::../../lessons/mged/using_insert_command_images/wireframesphere.png[]
+image::../../lessons/es/images/mged03_wireframe_sph.png[]
 
 
 
@@ -55,7 +55,7 @@ Para crear el rcc desde la ventana de comandos tipee en el prompt: *make rcc1.s
 
 Su ventana gráfica deberá mostrar un rcc grande, con la vista por defecto de az35, el25, viéndose como si entersectara con la esfera previamente creada.
 
-image::../../lessons/es/images/mged03_wireframespherecylinder.png[]
+image::../../lessons/es/images/mged03_wireframe_sph_rcc.png[]
 
 
 

doc/asciidoc/lessons/es/mged06_crear_una_copa.adoc

@@ -193,7 +193,7 @@ Para graficar la copa usando las propiedades del material por defecto de plásti
 
 Cuando haya finalizado de ver la copa desde la vista frontal, seleccione del menú View (Vista) un acimut de 35 y una elevación de 25 de la forma: az35. el25 y luego grafica. Si quieres ver la copa sin la estructura de alambres, seleccione la opción Framebuffer del panel de control de Raytrace y cliquee en Overlay (Cubrir). La copa lucirá similar a la de la siguiente ilustración:
 
-image::../../lessons/es/images/mged06_rtgobletaz_35el_25.png[]
+image::../../lessons/es/images/mged06_rtgobletaz_35_el_25.png[]
 
 
 

doc/asciidoc/lessons/es/mged15_crear_camion_de_juguete.adoc

@@ -22,7 +22,7 @@ En este tutorial usted aprenderá a:
 
 En los tutoriales anteriores, ha creado y editado figuras para producir objetos simples. Este tutorial se centra en la creación de un objeto algo más complejo, un camión de juguete, utilizando la ventana de comandos. Su camión terminado deberá ser similar al siguiente:
 
-image::../../lessons/es/images/mged15_truck_design.pNG[]
+image::../../lessons/es/images/mged15_truck_design.png[]
 
 
 
@@ -54,7 +54,7 @@ Para hacer la cabina del camión, cree un prisma recto paralelo (en inglés: rig
 
 Puede también utilizar el comando con formato de una sola línea: *in cab1.s rpp 0 1 0 1 0 1[Enter]* Una figura cúbica debería aparecer en la ventana gráfica, como muestra la siguiente imagen:
 
-image::../../lessons/es/images/mged15_truck_cab1s.pNG[]
+image::../../lessons/es/images/mged15_truck_cab1s.png[]
 
 
 
@@ -97,7 +97,7 @@ Nota: Tenga en cuenta que en las versiones de _BRL-CAD_ 6.0 en adelante las cara
 
 Cuando está en modo Multipane, el diseño debería verse como la siguiente ilustración:
 
-image::../../lessons/es/images/mged15_truck_cab_cutoff.pNG[]
+image::../../lessons/es/images/mged15_truck_cab_cutoff.png[]
 
 
 
@@ -107,7 +107,7 @@ image::../../lessons/es/images/mged15_truck_cab_cutoff.pNG[]
 
 Crear un cilindro (rcc) a utilizar para cortar un espacio para la primera rueda de la cabina. En la ventana de comandos del sistema, escriba: *make well1.s rcc [Enter]* En el menú Edit (Edición), diríjase a Primitive Selection (Selección de primitivos) y luego seleccione well1.s. Aplique la vista izquierda, vuelva a Edit (Editar) y seleccione Scale (Escala). Reduzca el tamaño del rcc, hasta que su diámetro sea el indicado para la rueda. Regrese a Edit (Edición) y seleccione Rotate (Rotación). Como se ha dicho, un método sencillo para rotar el CCR es mediante el uso de la tecla CTRL y el botón izquierdo del mouse. Sin embargo, como sabemos que queremos voltear el objeto exactamente 90'0 a lo largo del eje x, una mejor opción es usar la línea de comandos. Tipee entonces: *p 90 0 0 [Enter]* Después de esto, todavía puede tener que utilizar Set H (Ajuste h - de altura) además de las opciones de escala para redimensionar y la tecla SHIFT + botón izquierdo del mouse para posicionar su rueda. Cuando haya finalizado, seleccione Aceptar. Su diseño debe ser similar al siguiente en el modo Multipane:
 
-image::../../lessons/es/images/mged15_truck_multipane_1stwheel.pNG[]
+image::../../lessons/es/images/mged15_truck_multipane_1stwheel.png[]
 
 
 
@@ -129,13 +129,13 @@ El botón Reset (Restablecer) le dice a _MGED_ que regrese los valores que han s
 
 Para realizar una copia de la cavidad de la rueda, vaya al menú Edit (Edición) y seleccione Primitive Editor (Editor de primitivos), que contendrá la información de la última forma editada (o dirá myPrimitive si nada ha sido editado). Borre el nombre de la figura anterior en el cuadro de entrada Nombre. Escriba well1.s y oprima Reset (Restablecer) (o pulse Enter mientras el cursor se encuentra todavía en el cuadro de entrada Nombre). Los valores de los parámetros de la forma antigua se sustituirán por las de la nueva forma. El editor va a cambiar y se verá similar al siguiente ejemplo:
 
-image::../../lessons/es/images/mged15_prim_ed_wheel_well.pNG[]
+image::../../lessons/es/images/mged15_prim_ed_wheel_well.png[]
 
 
 
 Vuelva al cuadro de texto Nombre y cambie el 1 por un 2 y haga clic en OK. Cambie la vista al frente en el menú View (Vista). Diríjase a Edit/Primitive Selection (Edición/Selección de primitivos) y cliquee en well2.s. Utilice el SHIFT y botón izquierdo del mouse para arrastrar la nueva cavidad de la rueda a su posición, como se muestra en la ilustración siguiente. Verifique su alineación en el modo Multipane y presione Accept (Aceptar) cuando haya terminado.
 
-image::../../lessons/es/images/mged15_truck_2nd_wheel_wheel_place.pNG[]
+image::../../lessons/es/images/mged15_truck_2nd_wheel_wheel_place.png[]
 
 
 
@@ -201,7 +201,7 @@ Para hacer el cuerpo del camión, tipee en el prompt de la línea de comandos: *
 
 Edite el cuerpo de la camioneta para que su cara frontal se superponga ligeramente con la cara posterior de la cabina. Compruebe desde diferentes puntos de vista que el cuerpo esté correctamente alineado con la cabina. Acepte los cambios cuando haya terminado y, a continuación utilice el comando blast para dibujar su diseño. Su camión ahora debería tener el siguiente aspecto:
 
-image::../../lessons/es/images/mged15_truck_cab_body.pNG[]
+image::../../lessons/es/images/mged15_truck_cab_body.png[]
 
 
 
@@ -211,7 +211,7 @@ image::../../lessons/es/images/mged15_truck_cab_body.pNG[]
 
 Para hacer los dos huecos de las ruedas traseras en el cuerpo de la camioneta, repita los pasos utilizados en la creación de la segunda cavidad. Nombre a las nuevas figuras well3.s y well4.s. Utilice múltiples puntos de vista, y mueva las nuevas formas en la posición indicada hasta que su camión tenga una apariencia similar al siguiente:
 
-image::../../lessons/es/images/mged15_truck_wheel_wells_wireframe.pNG[]
+image::../../lessons/es/images/mged15_truck_wheel_wells_wireframe.png[]
 
 
 
@@ -275,7 +275,7 @@ Cambie a la vista izquierda y luego edite la posición de la rueda. Para una cor
 
 Utilice el Primitive Editor (Editor de Primitivos) de la misma forma con el resto de las ruedas. Mueva cada una de las ruedas a su posición hasta que su camioneta sea similar a la siguiente:
 
-image::../../lessons/es/images/mged15_truck_wheels.pNG[]
+image::../../lessons/es/images/mged15_truck_wheels.png[]
 
 
 
@@ -310,7 +310,7 @@ Su camión se compone de dos regiones: truck1.r y wheel1.r. Utilice el Combinaci
 
 En el Combination Editor (Editor de combinaciones), el sombreado de camuflaje (camo shader) crea un patrón tricolor pseudo-aleatorio de camuflaje en el objeto utilizando un patrón de ruido fractal. El sombreado ofrece gran cantidad de atributos entre los que elegir. Por ahora, seleccione un color de fondo de negro (0 0 0) y complete el Color #1 con verde (0 134 0), y el Color #2 con marrón pardo (164 96 38). Para hacer el patrón proporcional al diseño de la camioneta, seleccione un tamaño de .25 de ruido y, a continuación acepte las selecciones. La ventana del editor de sombreado debería tener este aspecto:
 
-image::../../lessons/es/images/mged15_cameo_shader.pNG[]
+image::../../lessons/es/images/mged15_cameo_shader.png[]
 
 
 

doc/asciidoc/lessons/mged01_creating_primitive_shapes.adoc

@@ -22,6 +22,7 @@ In this lesson, you will:
 * Create a sphere using the GUI menu.
 * Use the l command to list a shape's attributes or parameters.
 * Use the ls command to list the contents of the database.
+* Use the tops command to identify top-level objects in the database.
 * Eliminate a shape or object from the database using the kill command.
 * Edit a command.
 * Use the q or exit commands to quit the program.
@@ -84,7 +85,7 @@ One advantage to using the GUI, if you aren't familiar with UNIX file management
 [[assign_title]]
 == Assigning a Title to Your Database
 
-You can title your new database to provide an audit trail for you or others who might use your database. After the prompt, in the Command Window, type title followed by a space and a name that reflects the database you are going to make. When you are done, press the ENTER key. For example: mged>title MySphere[ENTER] Note that in _BRL-CAD_ versions prior to release 6.0, the title is limited to 72 characters.
+You can title your new database to provide an audit trail for you or others who might use your database. After the prompt, in the Command Window, type title followed by a space and a name that reflects the database you are going to make. When you are done, press the ENTER key. For example: mged>title MySphere[ENTER]
 
 
 [[set_units]]
@@ -231,6 +232,17 @@ Use the l command to list both sph1.s and sph2.s before continuing with this les
 
 In addition to viewing a shape's contents, you might also want to list the contents of the database to see what items have been created. To view the database contents, type at the Command Window prompt: *ls[ENTER]*
 
+The *ls* command lists every object, which can be overwhelming in an existing
+database. The *tops* command is usually the best starting point when exploring
+an unfamiliar database: it lists only objects that are not members of another
+combination. These top-level objects are typically the assemblies or models
+you will want to draw or inspect first. At the Command Window prompt, type:
+*tops[ENTER]*
+
+In the simple _sphere.g_ database, the primitive shapes are still top-level
+objects. As you build combinations in later lessons, *tops* will omit their
+member shapes and show the higher-level entry points instead.
+
 
 [[kill_object]]
 == Killing a Shape or Object
@@ -282,6 +294,7 @@ In this lesson, you:
 * Used the GUI to create a primitive shape.
 * Used the l command to view a shape's parameters.
 * Used the ls command to list the contents of the database.
+* Used the tops command to identify top-level database objects.
 * Used the kill command to eliminate a shape from the database.
 * Edited commands in the Command Window.
 * Used the q or Exit commands to quit the program.

doc/asciidoc/lessons/mged08_goblet_material_properties2.adoc

@@ -26,7 +26,7 @@ image::../lessons/images/mged08_goblet_combeditor.png[]
 
 [NOTE]
 ====
-Note that in _BRL-CAD_ versions prior to 5.2, the default values are used, but they are not displayed in the shader attribute boxes.
+Historical note: in _BRL-CAD_ releases prior to 5.2, the default values were applied but were not shown in the shader attribute boxes. Current releases display the default values.
 
 ====
 

doc/asciidoc/lessons/mged15_creating_a_toy_truck.adoc

@@ -64,7 +64,7 @@ image::../lessons/images/mged15_truck_cab1s.png[]
 
 To make the hood of the cab, you will need to make another rpp shape, this time using the inside command. This special command was originally created to hollow out objects such as gas tanks and boxes; however, it can be used to create any new shape that has some relationship to a pre-existing shape. In this lesson, it is used to cut away material above the hood and in front of the cab.
 
-If you are using _BRL-CAD_ version 6.0 or later, at the Command Window prompt, type: *inside cab1.s caboff1.s -.1 .7 -.1 -.1 .5 -.1[Enter]* The inside command tells _MGED_ to:
+At the Command Window prompt, type: *inside cab1.s caboff1.s -.1 .7 -.1 -.1 .5 -.1[Enter]* The inside command tells _MGED_ to:
 
 [cols="9*"]
 [%noheader]
@@ -378,13 +378,6 @@ To use the stacker option, open the Combination Editor and select truck1.r. Clic
 At this point, your Combination Editor window may have gone off the bottom of the screen. If this happens, reduce the size of the window as much as you can and then drag it up to the top of the screen. The buttons at the bottom of the box should now appear, and you can Apply your selections.
 
 
-[CAUTION]
-====
-When using the stacker option, you need to keep track of the number of characters and spaces in the shader text box. _MGED_ versions prior to release 6.0 will only recognize 64 characters/spaces, so be careful stacking shaders with complex attributes.
-
-====
-
-
 [[truck_combine_regions]]
 == Making a Combination of the Truck Regions
 

doc/asciidoc/presentations/Introduction-brlcad-app-devel.adoc

@@ -1,12 +1,10 @@
-= Untitled
+= Application Development with BRL-CAD (Overview)
 :doctype: article
 :toc:
 :toclevels: 3
 
 == Application Development with BRL-CAD
 
-../presentations/en/brlcad-app-devel_2.html
-
 A suite of utilities capable of interactively displaying, editing, and interrogating geometric models is known as BRL-CAD. BRL-CAD has become a powerful constructive solid geometry (CSG) modeling package. The package includes a large collection of tools and utilities including an interactive geometry editor, ray tracing and generic framebuffer libraries, a network-distributed image-processing and signal-processing capability, and an embedded scripting language.
 
 A particular strength of the package lies in its ability to build and analyze realistic models of complex objects using a relatively small set of "primitive shapes." Another strength of the package is the speed of its ray tracer, which is one of the fastest in existence. Finally, BRL-CAD users can accurately model objects on scales ranging from the subatomic through the galactic and get "all the details, all the time." BRL-CAD has been used for a wide variety of engineering and graphics applications. BRL-CAD is basically a collection of libraries, tools, and utilities that work together to create, raytrace, and interrogate geometry and manipulate files and data. In BRL-CAD library, Each library fits into one of three categories:

doc/asciidoc/presentations/Introduction-to-tcltk.adoc

@@ -1,12 +1,10 @@
-= Untitled
+= Tcl/Tk Overview
 :doctype: article
 :toc:
 :toclevels: 3
 
 == What is Tcl/Tk?
 
-../presentations/to-tcltk_2.html
-
 Tcl (Tool Command Language) is an interpreted language that is embeddable and highly extensible. Tk (ToolKit) is a toolkit for developing user interfaces for desktop applications not only for Tcl, but for many other languages that run across various operating systems including Windows, Mac OS X, Linux etc. Hence when combined, both create a programming framework that can be used for development and use of GUI applications.
 
 The most important benefit of using Tcl/Tk is Rapid Development of applications. Applications can be implemented 5-10 times faster with Tcl than any other languages. Application created with Tcl can be evolved rapidly to meet the changing requirements. Some of the other benefits that make it loved by people are portability, user convenience.

doc/asciidoc/specifications/BRL_CAD_g_format_V5.adoc

@@ -55,7 +55,7 @@ The Object Header consists of:
 * An 8-bit Magic1 element that holds a specific magic number value used for database integrity checking.
 * A 16-bit Flags element consisting of three 8-bit fields: HFlags, AFlags, and BFlags, described later.
 * A 16-bit Object_Type element organized into two 8-bit-wide fields: the Major_Type and the Minor_Type.
-* An Object_Length element that indicates the total number of bytes required for this object, including the magic numbers.
+* An Object_Length element that stores the total size of the object, including the magic numbers, as a count of 8-byte chunks.
 * An Object_Name element that is a string holding a name unique to that object and drawn from a name space that is global to the database. Like other strings, it consists of two fields, Length and Data. In the case of the Object_Name element, these are referred to as Name_Length and Name_Data, respectively. Note: The Object_Name element is mandatory for all allocated storage in the database. Database free-space management objects are the only objects for which the Object_Name element is optional.
 
 
@@ -81,41 +81,39 @@ Note that an object can now have (1) either an attribute or a body, (2) both an
 The on-disk version of each object consists of three distinct parts: Object Header, Object Interior, and Object Footer. This is called the external format of the object.
 
 .On-Disk BRL-CAD Object Structure
-[cols="3*"]
+[cols="1,2,2"]
 |===
 |Part
 |Element
 |Comments
 
-.5+|Object Header: (not compressible) 
+.5+|Object Header (not compressible)
 |Magic1
-.3+|Required
+|Required
+
 |HFlags, AFlags, BFlags
-|Object_Type (Major_Type, Minor_Type) 
+|Required
+
+|Object_Type (Major_Type, Minor_Type)
+|Required
+
 |Object_Length
 |Required
-|Object Name:, Name_Length, Name_Data , Name_Length, Name_Data 
-|Conditional on flag bit N Required for Application Data 
-|Object Name:
-|Name_Length, Name_Data 
-|Name_Length
-|Name_Data
-.2+|Object Interior: (individually compressible) 
-|Object Attributes:, Attribute_Length, Attribute_Data , Attribute_Length, Attribute_Data 
-|Conditional on flag bit A (ZZZ compression) 
-|Object Attributes:
-|Attribute_Length, Attribute_Data 
-|Attribute_Length
-|Attribute_Data
-|Object Body:, Body_Length, Body_Data , Body_Length, Body_Data 
-|Conditional on flag bit B (ZZZ compression) 
-|Object Body:
-|Body_Length, Body_Data 
-|Body_Length
-|Body_Data
-.2+|Object Footer: (not compressible) 
+
+|Object_Name (Name_Length, Name_Data)
+|Present when NP = 1
+
+.2+|Object Interior (individually compressible)
+|Object_Attributes (Attribute_Length, Attribute_Data)
+|Present when AP = 1
+
+|Object_Body (Body_Length, Body_Data)
+|Present when BP = 1
+
+.2+|Object Footer (not compressible)
 |Padding
-|As required to maintain 8-byte object boundaries 
+|As required to maintain 8-byte object boundaries
+
 |Magic2
 |Required
 |===
@@ -623,7 +621,7 @@ A Minor_Type of 2 indicates that this is a database header.
 [[Object_Length]]
 === Object Length
 
-The Object Length specifies the number of 8-byte chunks used to store an object. This includes all bytes from Magic1 through Magic2, inclusive.
+The Object_Length field stores the number of 8-byte chunks used to store the complete object, including all bytes from Magic1 through Magic2, inclusive. The total object size in bytes is `Object_Length * 8`.
 
 
 [[Object_Name]]
@@ -700,7 +698,7 @@ HFlags = 000xxxxx (1 byte)
 AFlags = 0000xx00 (1 byte)
 BFlags = 0000xx00 (1 byte)
 ObjType = Free (2 bytes)
-ObjLen = 8 (1 byte)
+ObjLen = 1 (1 byte; one 8-byte chunk)
 Magic2 (1 byte)
 ....
 
@@ -715,7 +713,7 @@ HFlags = 00000x10 (1 byte), OWid=00, NP=0, NWid=00, DLI=10
 AFlags = 000xx000 (1 byte), AWid=00, AP=0, AZ=000
 BFlags = 000xx000 (1 byte), BWid=00, BP=0, BZ=000
 Object_Type = RESERVED (2 bytes)
-Object_Length = 8 (1 byte)
+Object_Length = 1 (1 byte; one 8-byte chunk)
 Magic2 (1 byte)
 ....
 

doc/asciidoc/specifications/CMakeLists.txt

@@ -1,6 +1,7 @@
 set(
   specifications_EN
   BRL_CAD_g_format_V6.adoc
+  BRL_CAD_g_format_V5.adoc
 )
 
 if(TARGET librt)
@@ -11,7 +12,6 @@ endif(TARGET librt)
 
 cmakefiles(
   ${specifications_EN}
-  BRL_CAD_g_format_V5.adoc
   CMakeLists.txt
 )
 

doc/asciidoc/system/man1/CMakeLists.txt

@@ -2,24 +2,24 @@ set(
   man1_EN
   3dm-g.adoc
   a-d.adoc
+  adrt.adoc
   adrt_master.adoc
   adrt_slave.adoc
   alias-pix.adoc
   ap-pix.adoc
-  ap203e2-g.adoc
-  ap214-g.adoc
-  ap242-g.adoc
   archer.adoc
   art.adoc
   asc-nmg.adoc
   asc-plot3.adoc
   asc2dsp.adoc
   asc2g.adoc
+  beset.adoc
   bolt.adoc
   bombardier.adoc
   bot_dump.adoc
   brep_simple.adoc
   brledit.adoc
+  brlcad-launcher.adoc
   brlman.adoc
   btclsh.adoc
   bw-a.adoc
@@ -47,6 +47,7 @@ set(
   coil.adoc
   comgeom-g.adoc
   conv-vg2g.adoc
+  csg-g.adoc
   cv.adoc
   d-a.adoc
   d-bw.adoc
@@ -97,9 +98,6 @@ set(
   fbzoom.adoc
   fence.adoc
   g-acad.adoc
-  g-ap203e2.adoc
-  g-ap214.adoc
-  g-ap242.adoc
   g-dot.adoc
   g-dxf.adoc
   g-egg.adoc
@@ -110,6 +108,7 @@ set(
   g-off.adoc
   g-ply.adoc
   g-raw.adoc
+  g-scad.adoc
   g-shell-rect.adoc
   g-step.adoc
   g-stl.adoc
@@ -119,6 +118,9 @@ set(
   g-vrml.adoc
   g-x3d.adoc
   g2asc.adoc
+  g4-g5.adoc
+  g5-g4.adoc
+  ganalyze.adoc
   gastank.adoc
   gchecker.adoc
   gcv.adoc
@@ -132,6 +134,7 @@ set(
   gltf-g.adoc
   gqa.adoc
   gsh.adoc
+  gtransfer.adoc
   halftone.adoc
   handle.adoc
   human.adoc
@@ -152,6 +155,7 @@ set(
   lowp.adoc
   mac-pix.adoc
   mged.adoc
+  mkbuilding.adoc
   naca456.adoc
   nastran-g.adoc
   nirt.adoc
@@ -260,6 +264,7 @@ set(
   umod.adoc
   ustats.adoc
   vdeck.adoc
+  walk_example.adoc
   wavelet.adoc
   wdb_example.adoc
   window.adoc

doc/asciidoc/system/man1/a-d.adoc

@@ -35,6 +35,16 @@ to ASCII, is performed by *d-a*(1).
 This command is *deprecated* and is scheduled for removal; it prints a
 deprecation warning on startup.
 
+[[deprecation]]
+== DEPRECATION
+
+*a-d* is one of the legacy signal-analysis conversion filters that are
+being folded into the general-purpose data-conversion tool *cv*(1). New
+work should use *cv*(1), which performs the same ASCII-to-binary numeric
+conversions (and many others) through a single interface. *a-d* is
+retained for backward compatibility with existing scripts and still
+prints a deprecation warning when run.
+
 [[examples]]
 == EXAMPLES
 

doc/asciidoc/system/man1/adrt.adoc

@@ -0,0 +1,136 @@
+= ADRT(1)
+:doctype: manpage
+:mansource: BRL-CAD
+:manmanual: BRL-CAD
+
+== NAME
+
+adrt - render BRL-CAD geometry with the ADRT triangle ray tracer
+
+== SYNOPSIS
+
+[source]
+----
+adrt [options] model.g object [object ...]
+----
+
+
+[[description]]
+== DESCRIPTION
+
+The *adrt* command is a standalone front end to BRL-CAD's ADRT renderer. It
+loads the named _objects_ from _model.g_, converts their evaluated geometry to
+triangles, frames the model, and writes a rendered image. It provides a compact
+command-line interface for ADRT's path, shaded, diagnostic, spall-cone, and cut
+visualization modes without requiring the distributed ADRT master/slave tools.
+
+The default view uses azimuth 35 degrees, elevation 25 degrees, and a
+perspective camera. Explicit eye and look-at points may be supplied instead.
+The output format is selected from the extension of the file named by *-o*.
+
+
+[[options]]
+== OPTIONS
+
+*-o* _file_::
+  Write the rendered image to _file_. Default is _adrt.png_.
+
+*-s* _N_::
+  Set both image dimensions to _N_ pixels. Default is 512.
+
+*-w* _N_::
+  Set the image width, overriding the width selected by *-s*.
+
+*-n* _N_::
+  Set the image height, overriding the height selected by *-s*.
+
+*-m* _mode_::
+  Select *path*, *phong*, *normal*, *depth*, *flat*, *spall*, or *cut*.
+  Default is *path*.
+
+*-H* _N_::
+  Use _N_ samples per pixel in path mode. Default is 32.
+
+*-b* _buffer_::
+  Pass a raw initialization string to a mode that accepts one, such as
+  *cut* or *spall*. This is an advanced renderer-specific option.
+
+*-A* _angle_::
+  Set the full spall-cone angle in degrees. Default is 30.
+
+*-a* _azimuth_::
+  Set the view azimuth in degrees. Default is 35.
+
+*-e* _elevation_::
+  Set the view elevation in degrees. Default is 25.
+
+*-E* _x,y,z_::
+  Set an explicit eye point in model units, overriding *-a* and *-e*.
+
+*-L* _x,y,z_::
+  Set an explicit look-at point in model units. Default is the model center.
+
+*-p* _angle_::
+  Set the perspective half-angle in degrees. Default is 25.
+
+*-C* _r/g/b_::
+  Set the environment/sky color with 0-255 components. Default is
+  230/237/255.
+
+*-P* _N_::
+  Use _N_ render threads. By default all available processors are used.
+
+
+[[examples]]
+== EXAMPLES
+
+.Render with the path tracer
+====
+[source,bash]
+----
+adrt -s 1024 -H 64 -o model.png model.g all.g
+----
+Renders _all.g_ into a 1024x1024 PNG with 64 samples per pixel.
+====
+
+.Inspect surface normals
+====
+[source,bash]
+----
+adrt -m normal -a 45 -e 30 -o normals.png model.g part.r
+----
+Renders a diagnostic normal image of _part.r_ from the specified view.
+====
+
+.Visualize a spall cone
+====
+[source,bash]
+----
+adrt -m spall -A 40 -o spall.png model.g target.r
+----
+Uses the spall visualization mode with a 40-degree full cone angle.
+====
+
+
+[[see_also]]
+== SEE ALSO
+
+*adrt_master*(1), *adrt_slave*(1), *art*(1), *rt*(1)
+
+
+[[author]]
+== AUTHOR
+
+BRL-CAD Team
+
+
+[[copyright]]
+== COPYRIGHT
+
+This software is Copyright (c) 1989-2026 by the United States Government as represented by U.S. Army Research Laboratory.
+
+
+[[bug_reports]]
+== BUG REPORTS
+
+Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org

doc/asciidoc/system/man1/ap203e2-g.adoc

@@ -1,97 +0,0 @@
-= AP203E2-G(1)
-:doctype: manpage
-:mansource: BRL-CAD
-:manmanual: BRL-CAD
-
-== NAME
-ap203e2-g - convert a STEP AP203 edition 2 file to a BRL-CAD geometry database
-
-== SYNOPSIS
-
-[source]
-----
-ap203e2-g [-v] [-D] [-S _summary_file_] [-o _outfile.g_ | -O _outfile.g_] _infile.stp_
-----
-
-
-[[description]]
-== DESCRIPTION
-
-*ap203e2-g* reads an ISO 10303-203 edition 2 (AP203e2) STEP (Standard for the
-Exchange of Product model data) file and translates its boundary representation
-(B-rep) geometry and assembly structure into a BRL-CAD `.g` database.
-
-The converter maps STEP manifold solids and bounded surfaces into BRL-CAD
-Boundary Representation (*brep*) objects, and preserves the assembly/part
-hierarchy using BRL-CAD combinations. It shares its implementation with
-*step-g*(1) but is built against the AP203 edition 2 schema. If _infile.stp_ is
-given as `-`, the STEP data is read from standard input.
-
-Progress, load timing, and convert timing are reported on standard error.
-
-[[options]]
-== OPTIONS
-
-*-o* _outfile.g_::
-  Name the BRL-CAD geometry database to create. If the file already exists,
-  *ap203e2-g* refuses to overwrite it and exits with an error.
-
-*-O* _outfile.g_::
-  Name the BRL-CAD geometry database to create, forcibly overwriting it if it
-  already exists.
-
-*-S* _summary_file_::
-  Write a summary log of the STEP translation to the named file.
-
-*-v*::
-  Enable verbose diagnostic output during parsing and conversion.
-
-*-D*::
-  Perform a dry run: load and parse the STEP file and simulate conversion, but
-  do not write the output `.g` file. Useful for validating a STEP file or
-  timing the parsing phase.
-
-[[examples]]
-== EXAMPLES
-
-.Convert and inspect an AP203e2 part
-====
-[source,bash]
-----
-ap203e2-g -o widget.g widget.stp
-mged widget.g 'tops'
-----
-Translates the AP203 edition 2 file _widget.stp_ into _widget.g_, then lists the
-top-level objects of the resulting database with *mged*(1) so the imported
-geometry can be examined or rendered.
-====
-
-.Validate a STEP file without writing output
-====
-[source,bash]
-----
-ap203e2-g -v -D -O /dev/null model.stp
-----
-Loads and parses _model.stp_ with verbose diagnostics enabled to confirm the
-file converts cleanly, without producing a geometry database.
-====
-
-[[see_also]]
-== SEE ALSO
-
-*brlcad*(1), *step-g*(1), *g-step*(1), *mged*(1)
-
-[[author]]
-== AUTHOR
-
-BRL-CAD Team
-
-[[copyright]]
-== COPYRIGHT
-
-This software is Copyright (c) 1989-2026 by the United States Government as represented by U.S. Army Research Laboratory.
-
-[[bug_reports]]
-== BUG REPORTS
-
-Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org

doc/asciidoc/system/man1/ap214-g.adoc

@@ -1,86 +0,0 @@
-= AP214-G(1)
-:doctype: manpage
-:mansource: BRL-CAD
-:manmanual: BRL-CAD
-
-== NAME
-ap214-g - convert a STEP AP214 file to a BRL-CAD geometry database
-
-== SYNOPSIS
-
-[source]
-----
-ap214-g [-v] [-D] [-S _summary_file_] {-o _outfile.g_ | -O _outfile.g_} _infile.stp_
-----
-
-
-[[description]]
-== DESCRIPTION
-
-*ap214-g* reads an ISO 10303 STEP (Standard for the Exchange of Product model data) file in the AP214 (Core data for automotive mechanical design processes, third edition) application protocol and translates its boundary representation (B-rep) geometry and assembly structure into a BRL-CAD *.g* geometry database.
-
-STEP manifold solids and bounded surfaces are converted to BRL-CAD Boundary Representation (BREP) objects, and the assembly/part hierarchy is preserved using BRL-CAD combinations. The input file may be named *-* to read the STEP data from standard input.
-
-Elapsed load and convert times along with translation progress are written to standard error.
-
-For the closely related AP203/AP214 translator see *step-g*(1); for the reverse BRL-CAD to STEP direction see *g-step*(1).
-
-[[options]]
-== OPTIONS
-
-*-o* _outfile.g_::
-  Write the BRL-CAD geometry database to _outfile.g_. If the file already exists, *ap214-g* refuses to overwrite it and exits with an error.
-
-*-O* _outfile.g_::
-  Write the BRL-CAD geometry database to _outfile.g_, forcibly overwriting it if it already exists.
-
-*-S* _summary_file_::
-  Write a detailed summary log of the translation (parsed entities, skipped unsupported types, and conversion statistics) to _summary_file_.
-
-*-v*::
-  Enable verbose output, printing detailed diagnostics to standard error during parsing and conversion.
-
-*-D*::
-  Perform a dry run: load and parse the STEP file and simulate the conversion, but do not write any output database. Useful for validating a STEP file or timing the parse phase.
-
-[[examples]]
-== EXAMPLES
-
-.Convert an AP214 part and inspect it
-====
-[source,bash]
-----
-ap214-g -o bracket.g bracket.stp
-mged bracket.g 'tops'
-----
-Converts the AP214 STEP file _bracket.stp_ into _bracket.g_ (refusing to clobber an existing _bracket.g_), then lists the top-level objects of the resulting database with *mged*(1) so the imported B-rep solids and assembly combinations can be examined or raytraced.
-====
-
-.Validate a STEP file without writing output
-====
-[source,bash]
-----
-ap214-g -v -D -O /dev/null model.stp
-----
-Loads and parses _model.stp_ with verbose diagnostics enabled to check for unsupported or malformed entities, reporting load and convert timing while producing no geometry database.
-====
-
-[[see_also]]
-== SEE ALSO
-
-*brlcad*(1), *step-g*(1), *g-step*(1), *mged*(1)
-
-[[author]]
-== AUTHOR
-
-BRL-CAD Team
-
-[[copyright]]
-== COPYRIGHT
-
-This software is Copyright (c) 1989-2026 by the United States Government as represented by U.S. Army Research Laboratory.
-
-[[bug_reports]]
-== BUG REPORTS
-
-Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org

doc/asciidoc/system/man1/ap242-g.adoc

@@ -1,102 +0,0 @@
-= AP242-G(1)
-:doctype: manpage
-:mansource: BRL-CAD
-:manmanual: BRL-CAD
-
-== NAME
-ap242-g - convert a STEP AP242 format file to a BRL-CAD geometry database
-
-== SYNOPSIS
-
-[source]
-----
-ap242-g [-v] [-D] [-S _summary_file_] (-o _outfile.g_ | -O _outfile.g_) _infile.stp_
-----
-
-
-[[description]]
-== DESCRIPTION
-
-*ap242-g* reads an ISO 10303-242 STEP (Standard for the Exchange of Product
-model data) AP242 `.stp` or `.step` file and translates its boundary
-representation (B-rep) geometry and assembly structure into a BRL-CAD `.g`
-database. AP242 (Managed Model Based 3D Engineering) supersedes and merges the
-older AP203 and AP214 protocols handled by *step-g*(1).
-
-The translation maps STEP manifolds and bounded surface geometry into BRL-CAD
-Boundary Representation (BREP) objects, and preserves the assembly and part
-hierarchy using BRL-CAD combinations. Progress, along with elapsed load and
-conversion times, is reported to standard error.
-
-The input STEP file may be given as a path, or as *-* to read from standard
-input. By default *ap242-g* refuses to overwrite an existing output file.
-
-[[options]]
-== OPTIONS
-
-*-o* _outfile.g_::
-  Name of the BRL-CAD geometry database to create. If the file already exists,
-  *ap242-g* refuses to overwrite it and exits with an error.
-
-*-O* _outfile.g_::
-  Name of the BRL-CAD geometry database to create, forcibly overwriting it if it
-  already exists.
-
-*-S* _summary_file_::
-  Write a detailed summary log of the translation, including parsed entities,
-  skipped unsupported types, and overall conversion statistics, to the named file.
-
-*-v*::
-  Enable verbose output, printing detailed diagnostic messages to standard error
-  during parsing and conversion.
-
-*-D*::
-  Perform a dry run. The STEP file is loaded and parsed and the conversion is
-  simulated, but no `.g` file is written. Useful for validating a STEP file or
-  timing the parse phase.
-
-[[examples]]
-== EXAMPLES
-
-.Convert an AP242 part and inspect it
-====
-[source,bash]
-----
-ap242-g -o bracket.g bracket.stp
-mged bracket.g 'tops'
-----
-Converts the AP242 file _bracket.stp_ into _bracket.g_ (refusing to clobber an
-existing _bracket.g_), then lists the resulting top-level objects with
-*mged*(1) so the imported assembly can be examined and raytraced.
-====
-
-.Validate a file with a logged dry run
-====
-[source,bash]
-----
-ap242-g -v -D -S report.txt -o /dev/null model.step
-----
-Loads and parses _model.step_ with verbose diagnostics, writes a full
-translation summary to _report.txt_, and skips writing geometry. This checks
-that an AP242 file converts cleanly before committing to a full run.
-====
-
-[[see_also]]
-== SEE ALSO
-
-*brlcad*(1), *step-g*(1), *g-step*(1), *mged*(1)
-
-[[author]]
-== AUTHOR
-
-BRL-CAD Team
-
-[[copyright]]
-== COPYRIGHT
-
-This software is Copyright (c) 1989-2026 by the United States Government as represented by U.S. Army Research Laboratory.
-
-[[bug_reports]]
-== BUG REPORTS
-
-Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org

doc/asciidoc/system/man1/art.adoc

@@ -23,27 +23,26 @@ based rendering engine, producing a photorealistic image of the indicated
 _objects_ in the input _model.g_ database.
 
 *art* shoots rays into the database with *librt*(3) to derive each region's
-geometry and material, then builds an equivalent Appleseed scene. Each
-region becomes an Appleseed object with a corresponding OSL shader: a
-region's RGB color is honored, and if a region references a *material*
-object carrying an "OSL" optical property that named shader is used,
-otherwise a default plastic-like shader is applied. A single point light
-plus a constant-color sky environment illuminate the scene.
+geometry, then builds an equivalent Appleseed scene. Each region becomes an
+Appleseed procedural object with a native plastic-like surface. Region RGB
+colors, including colors inherited from parent combinations, are honored.
+Regions using BRL-CAD's *light* shader become colored point lights located at
+their model-space centroids; their *bright* and *fract* values scale the light
+intensity. If the database has no light regions, *art* supplies a default point
+light. A constant-color sky environment also illuminates the scene.
 
 The view is autosized about the model centroid; the orientation is set with
 the *-a* and *-e* options. A perspective camera is used by default
 (*-p* _85_); setting the perspective angle to 0 selects an orthographic
 camera. Unless image dimensions are given, a 512x512 image is rendered.
 
-The result is written to the file named by *-o* (default _art.png_) inside
-an _output/_ subdirectory of the current directory, and the generated
-Appleseed scene is also saved as _output/objects.appleseed_. The output
-format is inferred from the file extension (e.g. _.png_ or *pix*(5)).
+The result is written to the exact path named by *-o* (default _art.png_).
+The output format is inferred from the file extension.
 
-*art* is built only when BRL-CAD is configured with Appleseed and a
-compatible Boost; otherwise it is not installed. It shares its command-line
-parser and rt-script command set with *rt*(1), but only the options below
-are honored by the Appleseed back end.
+*art* is built only when BRL-CAD is configured with Appleseed enabled;
+otherwise it is not installed.  Art shares its command-line parser and
+rt-script command set with *rt*(1), but only the options below are
+currently supported.
 
 
 [[options]]
@@ -51,7 +50,7 @@ are honored by the Appleseed back end.
 
 *-o* _filename_::
   Render to the named image file (e.g. _image.png_ or _image.pix_).
-  Default is _art.png_. The file is written under _output/_.
+  Default is _art.png_.
 
 *-F* _framebuffer_::
   Also display the render in the named framebuffer (see FB_FILE in
@@ -130,7 +129,7 @@ are honored by the Appleseed back end.
 art -o havoc.png -s 1024 -a 35 -e 25 havoc.g havoc
 ----
 Renders the _havoc_ object from _havoc.g_ at azimuth 35 and elevation 25
-into a 1024x1024 image named _havoc.png_ (placed in _output/havoc.png_).
+into a 1024x1024 image named _havoc.png_ in the current directory.
 ====
 
 .Increase sample count and use an orthographic camera

doc/asciidoc/system/man1/asc2g.adoc

@@ -24,6 +24,21 @@ Both _input.asc_ and _output.g_ are required, and they must name different files
 Historically, the binary representation of a geometry database was architecture-dependent. *asc2g* and *g2asc*(1) were used to export databases to a portable ASCII form for transfer between systems. While this is no longer necessary for the architecture-independent "v5" binary format, the tools remain useful for migrating legacy "v4" databases, inspecting database contents in a human-readable form, or procedurally generating models via scripts.
 
 
+[[deprecation]]
+== DEPRECATION
+
+*asc2g* is *not* deprecated and remains a supported part of BRL-CAD.
+However, its original purpose -- producing an architecture-independent
+form of a geometry database for transfer between machines -- has been
+obsoleted by the machine-independent "v5" binary ".g" format, which can
+be moved between systems directly. For that reason, *asc2g* is no longer
+needed for portability. It is still applicable for importing databases
+saved with *g2asc*(1), for building databases from hand-written or
+generated ASCII scripts, and for round-tripping geometry through a text
+editor or revision-control system. For upgrading an older database to
+the current binary version, use *dbupgrade*(1) instead.
+
+
 [[options]]
 == OPTIONS
 

doc/asciidoc/system/man1/benchmark.adoc

@@ -42,7 +42,12 @@ There are several environment variables (passed as `OPTION=value`) that modify h
 *DB*:: The directory containing the reference geometry (e.g., `../db`).
 *PIX*:: The directory containing the reference images (e.g., `../pix`).
 *LOG*:: The directory containing the reference logs (e.g., `../pix`).
-*CMP*:: The name of a pixel comparison tool (e.g., `./pixcmp` or `cmp`).
+*CMP*:: The name of a pixel comparison tool (e.g., `./pixcmp` or `cmp`). The
+benchmark interprets status 0 as an exact match, 1 as an acceptable difference,
+and 2 as an unacceptable difference. Other statuses indicate a comparison
+failure. A generic *cmp*(1) reports every content difference as status 1, so it
+cannot distinguish acceptable pixel variation from an incorrect image; when
+used as _CMP_, the benchmark consequently accepts any content difference.
 *ELP*:: The name of an elapsed time tool (e.g., `../sh/elapsed.sh`).
 *TIMEFRAME*:: Minimum number of seconds each ray-trace frame should take.
 *MAXTIME*:: Maximum number of seconds to spend on any test.

doc/asciidoc/system/man1/beset.adoc

@@ -0,0 +1,85 @@
+= BESET(1)
+:doctype: manpage
+:mansource: BRL-CAD
+:manmanual: BRL-CAD
+
+== NAME
+beset - evolve a BRL-CAD shape to match a source object
+
+== SYNOPSIS
+
+[source]
+----
+beset [options] db.g object
+----
+
+
+[[description]]
+== DESCRIPTION
+
+*beset* ("Ben's Evolutionary Shape Tool") is an experimental,
+evolutionary-algorithm tool that attempts to evolve a population of
+candidate shapes toward a target _object_ contained in the geometry
+database _db.g_. A source model is ray sampled at the requested
+resolution, an initial population of individuals is spawned, and each
+successive generation is scored against the source using a fitness
+measure. The most-fit individuals of each generation are retained and
+combined using genetic operations (reproduction, mutation, and
+crossover) to produce the next generation. Progress and the most-fit
+individual of each generation are reported on standard output.
+
+Both a database file _db.g_ and a target _object_ within it are required.
+
+
+[[options]]
+== OPTIONS
+
+*-p #*::
+  Population size (number of individuals per generation).
+
+*-g #*::
+  Number of generations to evolve.
+
+*-r #*::
+  Ray-sampling resolution used when comparing candidates against the
+  source object.
+
+*-u #*::
+  Upper percentage of individuals to keep unchanged from one generation
+  to the next.
+
+*-l #*::
+  Lower percentage of individuals to kill (discard) each generation.
+
+*-m #*::
+  Mutation rate.
+
+*-c #*::
+  Crossover rate.
+
+*-x #*::
+  Set the *librt*(3) debug flags to the given hexadecimal value.
+
+
+[[see_also]]
+== SEE ALSO
+
+*brlcad*(1), *mged*(1), *rt*(1)
+
+
+[[author]]
+== AUTHOR
+
+BRL-CAD Team
+
+
+[[copyright]]
+== COPYRIGHT
+
+This software is Copyright (c) 2007-2026 United States Government as represented by the U.S. Army Research Laboratory.
+
+
+[[bug_reports]]
+== BUG REPORTS
+
+Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org

doc/asciidoc/system/man1/brlcad-launcher.adoc

@@ -0,0 +1,99 @@
+= BRLCAD-LAUNCHER(1)
+:doctype: manpage
+:mansource: BRL-CAD
+:manmanual: BRL-CAD
+
+== NAME
+
+brlcad-launcher - discover and start BRL-CAD applications
+
+== SYNOPSIS
+
+[source]
+----
+brlcad-launcher [options]
+----
+
+
+[[description]]
+== DESCRIPTION
+
+The *brlcad-launcher* command presents the installed BRL-CAD applications in a
+small graphical or text menu. It is intended as a portable front door to tools
+such as *mged*(1), Archer, and RtWizard, particularly on systems where users
+expect a single application entry point.
+
+Menu entries are discovered at run time from installed launcher manifests.
+The launcher reports unavailable applications, starts a selected application
+as an independent process, and remains available for additional selections.
+It also provides an entry for a command shell configured to use the installed
+BRL-CAD tools.
+
+The graphical interface uses BRL-CAD's framebuffer library and does not depend
+on Qt or Tcl/Tk. If no graphical framebuffer is available, the launcher falls
+back to the console menu. The text interface is also suitable for headless
+sessions.
+
+
+[[options]]
+== OPTIONS
+
+*-t*, *--text*::
+  Force the console menu.
+
+*-g*, *--gui*::
+  Request the graphical menu. If it cannot be opened, report the problem and
+  use the console menu.
+
+*-l*, *--list*::
+  List discovered applications and their availability, then exit.
+
+*-h*, *--help*::
+  Print command usage and exit.
+
+
+[[examples]]
+== EXAMPLES
+
+.List the discovered applications
+====
+[source,bash]
+----
+brlcad-launcher --list
+----
+Prints the manifest entries, executable names, descriptions, and whether each
+application is installed.
+====
+
+.Use the text menu
+====
+[source,bash]
+----
+brlcad-launcher --text
+----
+Starts the console interface even when a graphical framebuffer is available.
+====
+
+
+[[see_also]]
+== SEE ALSO
+
+*archer*(1), *mged*(1), *rtwizard*(1)
+
+
+[[author]]
+== AUTHOR
+
+BRL-CAD Team
+
+
+[[copyright]]
+== COPYRIGHT
+
+This software is Copyright (c) 1989-2026 by the United States Government as represented by U.S. Army Research Laboratory.
+
+
+[[bug_reports]]
+== BUG REPORTS
+
+Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org

doc/asciidoc/system/man1/brlcad.adoc

@@ -6,6 +6,19 @@
 == NAME
 brlcad - BRL-CAD programs for solid modeling, raytracing, graphics, and image processing
 
+== SYNOPSIS
+
+[source]
+----
+brlcad
+----
+
+*brlcad* is not a single program but the name of the overall software
+suite; it is a collection of many individual tools. Refer to the man
+page for a specific command (for example *mged*(1) or *rt*(1)) for that
+command's own synopsis and options.
+
+
 [[description]]
 == DESCRIPTION
 
@@ -33,7 +46,7 @@ A "message-passing" interface layered on top of TCP network links, to ease const
 
 
 *libfb*::
-A generic frame-buffer library which includes support for a number of display devices, as well as file, network, and debugging interfaces. Most programs which use this library have the letters "fb" in their names. To override your system default frame-buffer, the environment variable `FB_FILE` can be set. In addition, some commands also support a *-F* _framebuffer_ option. Note that the disk file format of _libfb_ is that of *pix*(5), allowing "framebuffer" files to be later processed by any of the "pix" family of programs. See *libfb*(3), *pix-fb*(3), *pix*(5), etc.
+A generic frame-buffer library which includes support for a number of display devices, as well as file, network, and debugging interfaces. Most programs which use this library have the letters "fb" in their names. To override your system default frame-buffer, the environment variable `FB_FILE` can be set. In addition, some commands also support a *-F* _framebuffer_ option. Note that the disk file format of _libfb_ is that of *pix*(5), allowing "framebuffer" files to be later processed by any of the "pix" family of programs. See *pix-fb*(1), *pix*(5), etc.
 
 
 *fbserv*::
@@ -41,11 +54,11 @@ TCP-based network server which implements remote frame-buffer services.
 
 
 *libplot3*::
-A public-domain version of the UNIX-Plot library which differs from that of the standard *libplot*(3), by the addition of 3-D primitives, color, floating point coordinate routines, and the use of a file pointer parameter. See *libplot3*(3), *plot3*(5).
+A public-domain version of the UNIX-Plot library which differs from that of the standard *libplot*(3), by the addition of 3-D primitives, color, floating point coordinate routines, and the use of a file pointer parameter. See *plot3*(5).
 
 
 *librle*::
-A Run-Length-Encoding (RLE) library, providing functions originally from the University of Utah in a library package. Note that the current version of this library reads Edition-3 RLE files. See *rle-fb*(1), *fb-rle*(1), *rle-pix*(1), *pix-rle*(1), *librle*(3).
+A Run-Length-Encoding (RLE) library, providing functions originally from the University of Utah in a library package. Note that the current version of this library reads Edition-3 RLE files. See *rle-fb*(1), *fb-rle*(1), *rle-pix*(1), *pix-rle*(1).
 
 
 *util*::
@@ -65,7 +78,7 @@ Whenever a framebuffer is needed, and the *-F* option has not been specified, th
 
 If `FB_FILE` is not set, the default for your system will be used.
 
-The use of `/dev/` before the __device_name__ is simply to distinguish them from filenames. See the end of the *libfb*(3) manual page for a list of the device names and the meanings of any _num_ parameters they may take, and for a more detailed discussion.
+The use of `/dev/` before the __device_name__ is simply to distinguish them from filenames.
 
 
 [[options]]

doc/asciidoc/system/man1/bwcrop.adoc

@@ -29,6 +29,9 @@ If only the input and output files are provided, *bwcrop* will prompt the user i
 
 Alternatively, all parameters can be provided on the command line for use in scripts. The coordinate names refer to the input file, in clockwise order starting from the upper-left corner. The nearest input pixel is selected for each output pixel; no interpolation is performed.
 
+If an output dimension is one pixel, *bwcrop* samples the midpoint of the
+quadrilateral along that axis.
+
 [[arguments]]
 == ARGUMENTS
 

doc/asciidoc/system/man1/bwhist.adoc

@@ -17,7 +17,7 @@ bwhist [-v] [file.bw]
 [[description]]
 == DESCRIPTION
 
-*bwhist* calculates and displays a histogram of the pixel values in a *bw*(5) format file. If a file is not specified, standard input is read. The histogram is displayed on the framebuffer selected via the `FB_FILE` environment variable (see *libfb*(3)) opened at 512x512.
+*bwhist* calculates and displays a histogram of the pixel values in a *bw*(5) format file. If a file is not specified, standard input is read. The histogram is displayed on the framebuffer selected via the `FB_FILE` environment variable (see *brlcad*(1)) opened at 512x512.
 
 The relative frequency of each pixel value is drawn as a horizontal bar of white pixels along the x-axis, scaled so that the most frequent value spans the full width of the screen. The 256 pixel values map to the y-axis, with 0 (black) at the bottom and 255 (white) at the top. The pixel count corresponding to a full-width bar is always reported to standard output as a "Full screen = N pixels" line.
 

doc/asciidoc/system/man1/csg-g.adoc

@@ -0,0 +1,61 @@
+= CSG-G(1)
+:doctype: manpage
+:mansource: BRL-CAD
+:manmanual: User Commands
+
+== NAME
+csg-g - OpenSCAD CSG Translator (CSG to BRL-CAD)
+
+== SYNOPSIS
+
+[source]
+----
+csg-g [-d] file.csg file.g
+----
+
+
+[[description]]
+== DESCRIPTION
+
+*csg-g* converts an OpenSCAD evaluated CSG file (_file.csg_) to a BRL-CAD _file.g_ file. The CSG format is produced by running `openscad -o file.csg input.scad` and contains the fully evaluated CSG tree with all variables, modules, and loops resolved.
+
+The converter preserves CSG structure, mapping OpenSCAD primitives and boolean operations directly to BRL-CAD equivalents rather than tessellating to mesh. Supported primitives include cube (RPP), sphere (SPH), cylinder (TGC), polyhedron (ARB or BOT), torus via rotate_extrude of circle (TOR), and extrusions of square, circle, and polygon profiles (RPP, TGC, or sketch+extrusion). Boolean operations (difference, union, intersection, group) and transformation matrices (multmatrix) are preserved. Colors are stored as object attributes. The `import()` node reads and inlines referenced STL files as BOT primitives.
+
+Polyhedra are matched against ARB4, ARB5, and ARB8 when the vertex and face counts match and the shape is convex. Non-convex polyhedra and unmatched shapes fall back to BOT (bag of triangles).
+
+The *-d* option prints debugging information during conversion.
+
+
+[[example]]
+== EXAMPLE
+
+
+----
+
+$ openscad -o model.csg model.scad
+$ csg-g model.csg model.g
+----
+
+
+[[see_also]]
+== SEE ALSO
+
+*g-scad*(1), *stl-g*(1), *openscad*(1)
+
+
+[[author]]
+== AUTHOR
+
+BRL-CAD Team
+
+
+[[copyright]]
+== COPYRIGHT
+
+This software is Copyright (c) 2025 by the United States Government as represented by U.S. Army Research Laboratory.
+
+
+[[bug_reports]]
+== BUG REPORTS
+
+Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org

doc/asciidoc/system/man1/cv.adoc

@@ -28,7 +28,8 @@ embedded blanks) drawn from the choices `[h|n][s|u][c|s|i|l|d|8|16|32|64]`:
   two's complement; network doubles are 64-bit IEEE 754 in big-endian
   order. When omitted, network format is assumed.
 * *s* or *u*: Signed (*s*) or unsigned (*u*) integer. This flag has no
-  effect on the double-precision format.
+  effect on the double-precision format. When omitted, signed format is
+  assumed.
 * *c*, *s*, *i*, *l*, *d*: C language types `char`, `short`, `int`,
   `long`, and `double`, sized as on the host processor.
 * *8*, *16*, *32*, *64*: Explicit bit sizes, typically paired with *n*

doc/asciidoc/system/man1/d-a.adoc

@@ -30,6 +30,16 @@ binary doubles, is performed by *a-d*(1).
 This command is *deprecated* and is scheduled for removal; it prints a
 deprecation warning on startup.
 
+[[deprecation]]
+== DEPRECATION
+
+*d-a* is one of the legacy signal-analysis conversion filters that are
+being folded into the general-purpose data-conversion tool *cv*(1). New
+work should use *cv*(1), which performs the same binary-to-ASCII numeric
+conversions (and many others) through a single interface. *d-a* is
+retained for backward compatibility with existing scripts and still
+prints a deprecation warning when run.
+
 [[options]]
 == OPTIONS
 

doc/asciidoc/system/man1/dpix-pix.adoc

@@ -16,12 +16,13 @@ dpix-pix file.dpix > file.pix
 [[description]]
 == DESCRIPTION
 
-*dpix-pix* converts a double-precision image (dpix) file to a *pix*(5)
-format file.  It scans the entire input file once to find the minimum
-and maximum sample values, then reads the file a second time and
-linearly maps each value from that [min, max] range onto the 8-bit
-range of 0 to 255, writing the resulting bytes to standard output.  The
-discovered minimum and maximum are reported on standard error.
+*dpix-pix* converts a double-precision *dpix*(5) image file to a *pix*(5)
+format file.  DPIX samples are stored as big-endian IEEE-754 doubles.
+The program scans the entire input file once to find the minimum and
+maximum sample values, then reads the file a second time and linearly
+maps each value from that [min, max] range onto the 8-bit range of 0 to
+255, writing the resulting bytes to standard output.  The discovered
+minimum and maximum are reported on standard error.
 
 Because the input must be read twice, the data is taken from a named
 file rather than from standard input.  The output is binary and is
@@ -46,7 +47,7 @@ error indicate the exposure range used for the conversion.
 [[see_also]]
 == SEE ALSO
 
-*brlcad*(1), *pix-fb*(1), *cv*(1), *pix*(5)
+*brlcad*(1), *pix-fb*(1), *cv*(1), *dpix*(5), *pix*(5)
 
 [[author]]
 == AUTHOR

doc/asciidoc/system/man1/fast4-g.adoc

@@ -45,7 +45,7 @@ For FASTGEN2 or FASTGEN3 files, convert them using *rpatch*(1) and then
   Quiet mode; suppress progress output, emitting only error messages.
 
 *-o* _plot_file_::
-  Write all processed CTRI and CQUAD elements to _plot_file_ in libplot3
+  Write all processed CTRI and CQUAD elements to _plot_file_ in *plot3*(5)
   format. The result can be viewed in *mged*(1) with the _overlay_ command.
 
 *-m* _muves_file_::

doc/asciidoc/system/man1/fbcbars.adoc

@@ -80,7 +80,7 @@ device.
 [[see_also]]
 == SEE ALSO
 
-*brlcad*(1), *fbclear*(1), *fbgrid*(1), *fbframe*(1), *pix-fb*(1), *pixbackgnd*(1), *libfb*(3)
+*brlcad*(1), *fbclear*(1), *fbgrid*(1), *fbframe*(1), *pix-fb*(1), *pixbackgnd*(1)
 
 
 [[inspirations]]

doc/asciidoc/system/man1/fblabel.adoc

@@ -116,7 +116,7 @@ here in the oldenglish.14 font.
 [[see_also]]
 == SEE ALSO
 
-*brlcad*(1), *fbpoint*(1), *fbline*(1), *fbclear*(1), *pix-fb*(1), *libfb*(3)
+*brlcad*(1), *fbpoint*(1), *fbline*(1), *fbclear*(1), *pix-fb*(1)
 
 
 [[author]]

doc/asciidoc/system/man1/fbline.adoc

@@ -86,7 +86,7 @@ successive invocations accumulate on the same framebuffer.
 [[see_also]]
 == SEE ALSO
 
-*brlcad*(1), *fblabel*(1), *fbpoint*(1), *pix-fb*(1), *plot3-fb*(1), *libfb*(3), *pix*(5)
+*brlcad*(1), *fblabel*(1), *fbpoint*(1), *pix-fb*(1), *plot3-fb*(1), *pix*(5)
 
 
 [[author]]

doc/asciidoc/system/man1/g-ap203e2.adoc

@@ -1,87 +0,0 @@
-= G-AP203E2(1)
-:doctype: manpage
-:mansource: BRL-CAD
-:manmanual: BRL-CAD
-
-== NAME
-g-ap203e2 - convert a BRL-CAD geometry database to a STEP AP203 edition 2 file
-
-== SYNOPSIS
-
-[source]
-----
-g-ap203e2 -o _outfile.stp_ _infile.g_ [_object_ ...]
-----
-
-
-[[description]]
-== DESCRIPTION
-
-*g-ap203e2* reads a BRL-CAD geometry database _infile.g_ and exports the named
-objects to an ISO 10303-203 edition 2 (AP203e2) STEP (Standard for the Exchange
-of Product model data) file _outfile.stp_.
-
-Geometry is written as STEP NURBS Boundary Representation (B-rep), so BRL-CAD CSG
-solids are first evaluated into their boundary representation. The STEP file is
-emitted against the
-`AP203_CONFIGURATION_CONTROLLED_3D_DESIGN_OF_MECHANICAL_PARTS_AND_ASSEMBLIES_MIM_LF`
-schema. Boolean operations are not representable in AP203, so combinations are
-exported as assembly/part structure rather than as live CSG.
-
-If no _object_ names are given, *g-ap203e2* converts the top-level (tops) objects
-of the database. *g-ap203e2* shares its exporter implementation with *g-step*(1)
-but targets the AP203 edition 2 schema. As a safety measure it refuses to run if
-_outfile.stp_ already exists.
-
-[[options]]
-== OPTIONS
-
-*-o* _outfile.stp_::
-  Name the STEP output file to create. This option is required. *g-ap203e2*
-  refuses to overwrite an existing file and exits with an error if _outfile.stp_
-  is already present.
-
-[[examples]]
-== EXAMPLES
-
-.Export an entire database to AP203 edition 2 STEP
-====
-[source,bash]
-----
-g-ap203e2 -o m35.stp m35.g
-----
-Converts every top-level object of _m35.g_ into the STEP file _m35.stp_, suitable
-for import into a mechanical CAD package that reads AP203 edition 2.
-====
-
-.Export selected parts and round-trip back into BRL-CAD
-====
-[source,bash]
-----
-g-ap203e2 -o parts.stp truck.g cab suspension
-step-g -o parts.g parts.stp
-----
-Exports only the _cab_ and _suspension_ assemblies from _truck.g_, then reads the
-resulting STEP file back into a new BRL-CAD database with *step-g*(1) to verify
-that the geometry survives the round trip.
-====
-
-[[see_also]]
-== SEE ALSO
-
-*brlcad*(1), *g-step*(1), *step-g*(1), *ap203e2-g*(1), *mged*(1)
-
-[[author]]
-== AUTHOR
-
-BRL-CAD Team
-
-[[copyright]]
-== COPYRIGHT
-
-This software is Copyright (c) 1989-2026 by the United States Government as represented by U.S. Army Research Laboratory.
-
-[[bug_reports]]
-== BUG REPORTS
-
-Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org

doc/asciidoc/system/man1/g-ap214.adoc

@@ -1,87 +0,0 @@
-= G-AP214(1)
-:doctype: manpage
-:mansource: BRL-CAD
-:manmanual: BRL-CAD
-
-== NAME
-
-g-ap214 - convert a BRL-CAD database to a STEP AP214 file
-
-== SYNOPSIS
-
-[source]
-----
-g-ap214 -o output.stp database.g [object(s)]
-----
-
-
-[[description]]
-== DESCRIPTION
-
-*g-ap214* converts geometry from a BRL-CAD _database.g_ to a STEP
-AP214 (ISO 10303-214, "Core Data for Automotive Mechanical Design
-Process") exchange file. BRL-CAD CSG and B-rep solids are written out
-as NURBS boundary representations.
-
-If one or more _object_ names are supplied, only those objects are
-converted; otherwise all top-level (tops) objects in the database are
-converted. The input database may be read from standard input by
-giving *-* in place of _database.g_.
-
-To avoid clobbering data, *g-ap214* refuses to run if the named output
-file already exists; remove or rename it first.
-
-This program is part of BRL-CAD's experimental STEP support and is
-built only when STEP experimental features are enabled. For AP203
-output see *g-step*(1).
-
-[[options]]
-== OPTIONS
-
-*-o* _output.stp_::
-  Write the STEP AP214 result to _output.stp_. This option is
-  required, and the file must not already exist.
-
-[[examples]]
-== EXAMPLES
-
-.Export the entire model
-====
-[source,bash]
-----
-g-ap214 -o widget.stp widget.g
-----
-With no object names given, every top-level object in widget.g is
-converted to AP214 geometry in widget.stp.
-====
-
-.Export selected components for CAD interchange
-====
-[source,bash]
-----
-g-ap214 -o cab.stp m35.g cab hood
-----
-Converts only the cab and hood assemblies from the m35.g database,
-producing an AP214 file that can be opened by automotive mechanical
-CAD packages.
-====
-
-[[see_also]]
-== SEE ALSO
-
-*brlcad*(1), *g-step*(1), *step-g*(1), *mged*(1)
-
-[[author]]
-== AUTHOR
-
-BRL-CAD Team
-
-[[copyright]]
-== COPYRIGHT
-
-This software is Copyright (c) 1989-2026 by the United States Government as represented by U.S. Army Research Laboratory.
-
-[[bug_reports]]
-== BUG REPORTS
-
-Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org

doc/asciidoc/system/man1/g-ap242.adoc

@@ -1,83 +0,0 @@
-= G-AP242(1)
-:doctype: manpage
-:mansource: BRL-CAD
-:manmanual: BRL-CAD
-
-== NAME
-
-g-ap242 - convert a BRL-CAD database to a STEP AP242 file
-
-== SYNOPSIS
-
-[source]
-----
-g-ap242 -o output.stp database.g object
-----
-
-
-[[description]]
-== DESCRIPTION
-
-*g-ap242* converts geometry from a BRL-CAD _database.g_ to a STEP
-AP242 (ISO 10303-242, "Managed Model Based 3D Engineering") exchange
-file. A single _object_ from the database must be named; it is written
-to the output file with an AP242 "Managed Model Based 3D Engineering"
-schema header. The input database may be read from standard input by
-giving *-* in place of _database.g_.
-
-To avoid clobbering data, *g-ap242* refuses to run if the named output
-file already exists; remove or rename it first.
-
-This program is part of BRL-CAD's experimental STEP support and is
-built only when STEP experimental features are enabled. For AP203 and
-AP214 output see *g-step*(1) and *g-ap214*(1).
-
-[[options]]
-== OPTIONS
-
-*-o* _output.stp_::
-  Write the STEP AP242 result to _output.stp_. This option is
-  required, and the file must not already exist.
-
-[[examples]]
-== EXAMPLES
-
-.Export a single component
-====
-[source,bash]
-----
-g-ap242 -o cab.stp m35.g cab
-----
-Converts the cab assembly from the m35.g database, producing an AP242
-file suitable for model-based engineering interchange.
-====
-
-.Pipe a database from another tool
-====
-[source,bash]
-----
-asc2g < model.asc | g-ap242 -o part.stp - part
-----
-Reads the database from standard input (the *-* argument) instead of a
-file on disk, converting the named part to AP242 in a single pipeline.
-====
-
-[[see_also]]
-== SEE ALSO
-
-*brlcad*(1), *g-ap214*(1), *g-step*(1), *step-g*(1), *mged*(1)
-
-[[author]]
-== AUTHOR
-
-BRL-CAD Team
-
-[[copyright]]
-== COPYRIGHT
-
-This software is Copyright (c) 1989-2026 by the United States Government as represented by U.S. Army Research Laboratory.
-
-[[bug_reports]]
-== BUG REPORTS
-
-Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org

doc/asciidoc/system/man1/g-iges.adoc

@@ -11,26 +11,54 @@ g-iges - convert a BRL-CAD database to an IGES file
 
 [source]
 ----
-g-iges [-f|-t|-m] [-s] [-v] [-a _abs_tol_] [-r _rel_tol_] [-n _norm_tol_] [-d _dist_tol_] [-P _ncpu_] [-x _rt_debug_] [-X _nmg_debug_] [-o _output_file_] _database.g_ _object_ [_object_ ...]
+g-iges [-f|-t|-m] [--flatten-brep] [-s] [-v] [-a _abs_tol_] [-r _rel_tol_] [-n _norm_tol_] [-d _dist_tol_] [-P _ncpu_] [-x _rt_debug_] [-X _nmg_debug_] [-o _output_file_] _database.g_ [_output.igs_] [_object_ ...]
 ----
 
 [[description]]
 == DESCRIPTION
 
 *g-iges* converts the specified _object_(s) from a BRL-CAD _database.g_ database
-into an IGES version 5.1 file.
+into an IGES version 5.3 file.
 
 By default a CSG IGES file is produced: every region is written as a Boolean
 tree, with each solid represented by its IGES CSG equivalent. Any solid that has
-no IGES CSG equivalent is tessellated (using the tessellation tolerances) and
-written as a boundary-representation (B-Rep) object. The *-f*, *-t*, and *-m*
-options select alternative output modes; they are mutually exclusive, and the
-last one given wins.
+no IGES CSG equivalent uses a primitive B-Rep conversion where available,
+including general truncated cones, oblique cylinders, pipes, extrusions,
+clines, and legacy B-splines. Already-faceted geometry keeps its polygonal
+representation. Tessellation is a fallback for other supported geometry when
+no usable primitive B-Rep conversion is available; it is controlled by the
+tessellation tolerances. Native OpenNURBS B-Reps
+are written with IGES manifold topology (type 186), preserving shared vertices,
+edges, loops, faces, shells, and NURBS geometry. The *-f*, *-t*, and *-m*
+options select alternative output modes and are mutually exclusive.
 
-If no output file is given with *-o*, the IGES file is written to standard
-output. The inverse translation, from IGES to BRL-CAD, is performed by
+CLINE plate-mode geometry is exported with fixed wall thickness. Its native
+ray-dependent line-of-sight thickness cannot be represented exactly in IGES;
+the exporter reports this limitation.
+
+Temporary B-Reps produced by native primitive callbacks receive the same
+conservative closed-shell orientation check used by *iges-g*. Clearly inverted
+isolated shells are corrected before export, with a diagnostic. This does not
+change the source database or reorient authored B-Rep inputs; open, nested,
+overlapping, and uncertain shells are left unchanged.
+
+An output filename ending in *.igs* or *.iges* (case-insensitive) may follow
+the input database, as in *g-iges input.g output.igs*. Remaining arguments
+select objects; when a destination is given without objects, all top-level
+objects are exported. The *-o* option overrides a positional destination and
+supports output filenames without an IGES extension. In multi-file mode,
+an existing output directory may take the place of the positional filename.
+If the candidate destination also names an object in the database, *-o* is
+required to disambiguate; that positional argument then selects the object.
+
+If neither form specifies a destination, the IGES file for the named objects
+is written to standard output. The inverse translation, from IGES to BRL-CAD, is performed by
 *iges-g*(1).
 
+Long conversions report their current operation, elapsed time, and completed
+top-level selections about every five seconds. Counts describe source items,
+not an estimate of remaining time.
+
 [[options]]
 == OPTIONS
 
@@ -45,12 +73,23 @@ output. The inverse translation, from IGES to BRL-CAD, is performed by
   region.
 
 *-m*::
-  Multi-file output: write a separate IGES file for each converted region.
-  Implies *-t*, and the *-o* argument must name an existing directory in which
-  the per-region files are created.
+  Multi-file output: write a separate IGES file for each converted region occurrence.
+  Implies *-t*, and the output destination must name an existing directory in which
+  the per-region files are created. Repeated regions retain their individual
+  assembly placements. Names are sanitized and numbered to avoid overwriting
+  another occurrence or an existing file.
 
 *-s*::
-  Write the faces of B-Rep objects as planar NURBS surfaces.
+  Write NMG facets using NURBS surfaces and boundary curves instead of analytic
+  planes and lines. This does not tessellate native OpenNURBS B-Reps.
+
+*--flatten-brep*::
+  Write native OpenNURBS B-Reps as independent type 144 trimmed surfaces
+  instead of type 186 manifold topology. This compatibility mode is intended
+  for older readers that do not implement IGES 5.3 B-Rep entities. Exact
+  surfaces and trimming curves are retained, but shared topology is not
+  represented explicitly in the file. The faces remain grouped so instances
+  reference the entire original object.
 
 *-a* _abs_tol_::
   Absolute tessellation tolerance, in millimeters. Default 0.0 (disabled).
@@ -65,10 +104,12 @@ output. The inverse translation, from IGES to BRL-CAD, is performed by
   Minimum distance between distinct points, in millimeters. Default 0.0005.
 
 *-P* _ncpu_::
-  Number of processors to use during tessellation. Default 1.
+  Requested maximum worker count. Default 1. IGES conversion currently runs
+  serially to protect record ordering and NMG error recovery; larger positive
+  values are accepted with a diagnostic.
 
 *-v*::
-  Verbose output; repeat for more detail.
+  Include entity-type counts in the export summary.
 
 *-x* _rt_debug_::
   Set the *librt* raytrace debug flag (hexadecimal). See raytrace.h for values.
@@ -77,8 +118,12 @@ output. The inverse translation, from IGES to BRL-CAD, is performed by
   Set the NMG debug flag (hexadecimal). See nmg.h for values.
 
 *-o* _output_file_::
-  Write the IGES output to _output_file_ instead of standard output. With *-m*,
-  this argument must be a directory.
+  Write the IGES output to _output_file_, overriding a positional destination.
+  With *-m*,
+  this argument must be a directory. File output is staged beside its destination.
+  Input/output aliases are rejected before writing, and an I/O failure does not
+  replace an existing destination. A diagnosed partial conversion may publish
+  its usable geometry while returning a nonzero status.
 
 [[examples]]
 == EXAMPLES
@@ -87,11 +132,11 @@ output. The inverse translation, from IGES to BRL-CAD, is performed by
 ====
 [source,bash]
 ----
-g-iges -o assembly.iges assembly.g hull turret
+g-iges assembly.g assembly.iges hull turret
 ----
 Writes the hull and turret regions of assembly.g as a CSG IGES file, preserving
-the Boolean tree where IGES primitive equivalents exist and tessellating the
-rest.
+the Boolean tree where IGES primitive equivalents exist and using B-Rep
+representations for other supported geometry.
 ====
 
 .Produce a faceted B-Rep IGES file with tight tolerances
@@ -118,6 +163,13 @@ parts directory, which is convenient for importing assemblies part-by-part.
 ====
 
 [[see_also]]
+== EXIT STATUS
+
+Zero indicates successful conversion.  A nonzero status indicates an error,
+including missing requested objects or omitted solids or combinations.
+A partial IGES file may still
+contain usable geometry; consult the diagnostics before using it.
+
 == SEE ALSO
 
 *brlcad*(1), *iges-g*(1), *g-step*(1), *mged*(1)

doc/asciidoc/system/man1/g-scad.adoc

@@ -0,0 +1,59 @@
+= G-SCAD(1)
+:doctype: manpage
+:mansource: BRL-CAD
+:manmanual: User Commands
+
+== NAME
+g-scad - BRL-CAD to OpenSCAD Translator (BRL-CAD to SCAD)
+
+== SYNOPSIS
+
+[source]
+----
+g-scad [-d] [-o output.scad] file.g object(s)
+----
+
+
+[[description]]
+== DESCRIPTION
+
+*g-scad* converts the specified BRL-CAD objects from _file.g_ to OpenSCAD format. The output preserves CSG structure, mapping BRL-CAD boolean operations and primitives directly to OpenSCAD equivalents rather than tessellating everything to polyhedron.
+
+Direct primitive mappings: SPH and ELL to sphere(), TGC and REC to cylinder(), ARB to polyhedron(), BOT to polyhedron(), TOR to rotate_extrude(circle()), PARTICLE to hull() of two spheres, PIPE to union of cylinders and spheres, EXTRUDE to linear_extrude(polygon()), REVOLVE to rotate_extrude(polygon()), and HALF to a large translated cube. Combination colors are emitted as color() wrappers. Primitives without direct mappings are tessellated via their ft_tessellate method and emitted as polyhedron().
+
+The *-d* option prints debugging information. The *-o* option specifies the output file (default is stdout).
+
+
+[[example]]
+== EXAMPLE
+
+
+----
+
+$ g-scad -o model.scad model.g all.g
+$ openscad model.scad
+----
+
+
+[[see_also]]
+== SEE ALSO
+
+*csg-g*(1), *g-stl*(1), *openscad*(1)
+
+
+[[author]]
+== AUTHOR
+
+BRL-CAD Team
+
+
+[[copyright]]
+== COPYRIGHT
+
+This software is Copyright (c) 2025 by the United States Government as represented by U.S. Army Research Laboratory.
+
+
+[[bug_reports]]
+== BUG REPORTS
+
+Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org

doc/asciidoc/system/man1/g-step.adoc

@@ -5,67 +5,267 @@
 
 == NAME
 
-g-step - convert a BRL-CAD database to a STEP AP203 file
+g-step - export a BRL-CAD database as an ISO 10303 STEP file
 
 == SYNOPSIS
 
 [source]
 ----
-g-step -o output.stp database.g [object(s)]
+g-step [--schema AP] [--native-csg] [--output-units UNIT]
+       [--angle-units degree|radian] [--uncertainty VALUE]
+       [--strict] [--report FILE] -o output.step input.g [object ...]
+g-step --list-schemas
 ----
 
-
 [[description]]
 == DESCRIPTION
 
-*g-step* exports geometry from a BRL-CAD database _database.g_ to a STEP
-AP203 (Configuration Controlled 3D Designs of Mechanical Parts and
-Assemblies) exchange file _output.stp_.
+*g-step* writes selected BRL-CAD objects to an ISO 10303-21 exchange file.
+It supports AP203, AP203 edition 2, AP214 edition 3, and AP242 editions 1
+through 4 when their schema plugins are installed. AP203 is the default;
+*--schema ap242* selects AP242 edition 4.
 
-One or more named _object_ arguments may be supplied to limit the export
-to those objects; if none are given, every top-level object in the
-database is converted. BRL-CAD CSG primitives are tessellated into the
-STEP NURBS boundary representation, since AP203 has no notion of Boolean
-operations. The input database name may be given as *-* to read the
-database from standard input.
+Named _object_ arguments limit the export. Without them, every top-level
+object in _input.g_ is selected. The input may be *-* for standard input. The
+required *-o* option names the output, which is replaced if it already exists.
 
-To avoid clobbering data, *g-step* refuses to run when the named output
-file already exists.
+The default path writes B-reps and mechanical product structure for maximum
+interoperability. Union-only combinations become assemblies with repeated
+rigid occurrences preserved. Native CSG export is optional for AP203e2,
+AP214, and AP242. Unsupported content is reported rather than silently
+approximated; permissive mode may publish useful partial output with status 1,
+while *--strict* makes any omission transactional.
+
+The exporter also re-authors supported product identity, presentation,
+material, property, unit, occurrence, and configuration data retained by
+*step-g*. See *STEP*(5) for detailed representation and metadata coverage.
 
 [[options]]
 == OPTIONS
 
-*-o* _output.stp_::
-  Write the STEP AP203 output to _output.stp_. This option is required.
+=== Output and schema
+
+*-h*, *--help*::
+  Print usage and option information.
+
+*-o*, *--output* _output.step_::
+  Name the STEP Part 21 file to create. This option is required.
+
+*--schema* _AP_::
+  Select *ap203*, *ap203e2*, *ap214*, *ap242*, *ap242e1*, *ap242e2*,
+  *ap242e3*, *ap242e4*, or *auto*. *auto* currently selects AP203, and
+  *ap242* aliases *ap242e4*. Availability depends on the installed plugins.
+
+*--list-schemas*::
+  Print the installed STEP schema plugins and exit.
+
+=== Representation policy
+
+*--native-csg*::
+  Preserve supported Boolean CSG expressions and implicit primitives in
+  AP203e2, AP214, or AP242 instead of using only the normal B-rep-oriented
+  path. This is disabled by default.
+
+*--strict*::
+  Do not publish a STEP file if any selected or reachable object, Boolean
+  semantic, occurrence transform, or requested metadata value is omitted.
+  Without this option, usable partial output is published with status 1 and
+  every omission is diagnosed.
+
+=== Units and accuracy
+
+*--output-units* _UNIT_::
+  Select the STEP length unit. Any recognized BRL-CAD length unit is accepted;
+  common choices include *mm*, *cm*, *m*, *in*, and *ft*. The default is
+  *mm*. Geometry dimensions and placement translations use the same policy.
+
+*--angle-units* _degree|radian_::
+  Select the STEP plane-angle unit. *deg* and *rad* are also accepted. The
+  default is *degree*.
+
+*--uncertainty* _VALUE_::
+  Declare a positive finite global geometric uncertainty in the selected
+  output length unit. The default is the selected-unit equivalent of 0.05 mm.
+
+=== Reports
+
+*--report* _FILE_::
+  Write a `brlcad-step-export-report-v1` JSON report. It classifies every
+  selected and reachable object, records omissions and metadata dispositions,
+  and reports the effective schema, units, uncertainty, and aggregate
+  *complete*, *partial*, *empty*, or *failed* outcome.
+
+[[policy]]
+== EXPORT POLICY
+
+The ordinary path uses an existing B-rep or a primitive's B-rep conversion.
+It does not run the STEP importer's topology-repair pipeline on an existing
+BRL-CAD B-rep. A primitive for which neither the requested native mapping nor
+a B-rep fallback is available is omitted explicitly; an empty placeholder is
+never written.
+
+Until evaluated B-rep export is available, a non-union Boolean combination
+cannot be flattened on the ordinary path. It is reported as partial rather
+than misrepresented as an assembly union. Use *--native-csg* when its tree and
+leaves have exact mappings in the selected schema. Operations which cannot be
+represented without changing their meaning remain failures rather than being
+approximated.
+
+Permissive output is useful when supported objects should still be exchanged
+despite explicit omissions. Use *--report* to audit coverage, or *--strict*
+when the file must represent every selected and reachable object and requested
+metadata value.
+
+[[schemas]]
+== SCHEMAS AND GEOMETRY
+
+[cols="1,3"]
+|===
+|Schema |Export behavior
+
+|*ap203*
+|Default B-rep and mechanical product export; no native CSG or presentation authoring
+
+|*ap203e2*
+|B-reps, exact supported sweeps, presentation and metadata, and optional native CSG
+
+|*ap214*
+|B-reps, exact supported sweeps, presentation and metadata, and optional native CSG
+
+|*ap242e1* through *ap242e4*
+|Edition-specific output with shared mechanical, presentation, metadata, sweep, and optional native CSG support
+|===
+
+With *--native-csg*, union, intersection, and difference map directly and XOR
+is lowered to an equivalent expression. AP203e2 and AP214 share mappings for
+common STEP primitives; AP242 adds exact mappings such as ellipsoid,
+rectangular pyramid, tetrahedron, and convex hexahedron. Finite unsupported
+leaves may use an exact B-rep inside an otherwise preserved tree. BRL-CAD NOT
+and guard/no-op nodes have no lossless finite STEP encoding. See *STEP*(5) for
+the complete mapping policy.
+
+[[assemblies]]
+== ASSEMBLIES
+
+Union-only combinations become nested product assemblies. Repeated children
+remain repeated occurrences, and rigid member transforms become occurrence
+placements. Scaling cannot be expressed by this product-structure mapping and
+is reported as an omission.
+
+When a database came from *step-g*, retained role and source provenance lets
+the exporter distinguish a product's representation items from its assembly
+occurrences. Secondary placed geometry is restored with a transforming
+representation relationship instead of manufacturing another product usage.
+With native CSG, non-region union structure remains an assembly while a region
+or non-union Boolean shape receives its own CSG representation. Embedded CSG
+operands are not also emitted as unrelated products.
+
+Occurrence identity is retained on the parent combination with guarded
+`step:occurrence:N:...` attributes. The exporter applies those values only
+while the recorded child still matches the current tree member, preventing
+stale imported metadata from moving to another occurrence after edits.
+
+[[metadata]]
+== METADATA ROUND TRIP
+
+Product names, identifiers, descriptions, revisions, and definition fields
+are restored from `step:` object attributes when present; otherwise the
+BRL-CAD object name supplies a product name and identifier. Part 21 strings
+preserve apostrophes and Unicode.
+
+AP203e2, AP214, and AP242 can re-author retained colour, transparency, layers,
+materials, and typed product or material properties. Native BRL-CAD colour
+takes precedence over retained STEP colour. Supported numeric properties keep
+their measure type, dimensional exponents, and structured SI,
+conversion-based, context-dependent, or derived unit graph. Unsupported or
+malformed metadata is reported rather than emitted with guessed semantics.
+
+Reference-linked approvals, people, organizations, dates, documents,
+classifications, categories, effectivities, and related records retained by
+*step-g* are validated against the target schema before re-authoring. Every
+source reference is remapped to a newly emitted entity. AP203's narrower
+vocabularies, assignments, and mandatory management closure are enforced;
+records that cannot be translated legally remain explicit omissions. The
+export report gives each retained configuration node an *emitted*,
+*unsupported*, or *malformed* disposition.
+
+The exporter does not treat unrelated opaque `STEP::...` attributes as
+entities, and source IDs are never reused as output Part 21 instance numbers.
+AP242 PMI retained by the importer is not yet re-authored.
+
+[[units]]
+== UNITS AND UNCERTAINTY
+
+BRL-CAD geometry is stored internally in millimetres. *g-step* therefore
+defaults to millimetres, degrees, and a physical uncertainty of 0.05 mm.
+Changing *--output-units* rescales coordinates, B-rep control geometry,
+analytic dimensions, assembly translations, and the default uncertainty
+together. Recognized SI lengths use *SI_UNIT*; other recognized lengths use
+exact *CONVERSION_BASED_UNIT* values.
+
+An explicit *--uncertainty* value is interpreted in the selected output unit.
+A `.g` database has no authoritative model-wide construction tolerance, so
+display units and primitive-local tolerances are not silently promoted to a
+STEP uncertainty. Imported `step:source_context:N:...` attributes remain
+provenance rather than automatic export instructions; select the output
+policy explicitly when source settings should be restored.
+
+[[diagnostics]]
+== REPORTING
+
+The JSON report covers every selected and reachable object as *handled*,
+*deliberately skipped*, *unsupported*, or *failed*, with its BRL-CAD name and
+reason. Separate counters summarize products, occurrences, presentation,
+materials, properties, and retained configuration records. Records recognized
+but not supported for authoring are explicit omissions, not silent losses.
+
+[[exit_status]]
+== EXIT STATUS
+
+Status 0 means complete output. Status 1 means permissive partial output was
+published. Other nonzero statuses mean no STEP output was published; the JSON
+report, when requested, distinguishes empty input coverage from conversion,
+input, and output failures.
 
 [[examples]]
 == EXAMPLES
 
-.Export an entire database to STEP
+.Export all top-level objects as AP203
 ====
 [source,bash]
 ----
-g-step -o m35.stp m35.g
+g-step -o assembly.step assembly.g
 ----
-Converts every top-level object in _m35.g_ to STEP AP203 and writes the
-result to _m35.stp_, suitable for import into a mechanical CAD package.
 ====
 
-.Export selected assemblies for a downstream CAD tool
+.Export selected objects as AP214 with a report
 ====
 [source,bash]
 ----
-g-step -o cab.stp m35.g cab suspension
+g-step --schema ap214 --report cab.json -o cab.step vehicle.g cab suspension
+----
+====
+
+.Preserve a representable AP242 CSG tree
+====
+[source,bash]
+----
+g-step --schema ap242 --native-csg -o region.step model.g region
+----
+====
+
+.Require complete inch-based output
+====
+[source,bash]
+----
+g-step --strict --output-units in -o exact.step model.g
 ----
-Exports only the _cab_ and _suspension_ assemblies, producing a smaller
-STEP file containing just the components of interest rather than the
-whole vehicle.
 ====
 
 [[see_also]]
 == SEE ALSO
 
-*brlcad*(1), *step-g*(1), *mged*(1), *g-iges*(1)
+*step-g*(1), *STEP*(5), *brlcad*(1), *mged*(1), *g-iges*(1)
 
 [[author]]
 == AUTHOR

doc/asciidoc/system/man1/g2asc.adoc

@@ -37,6 +37,18 @@ single dash (*-*) to use standard input or standard output, but a dash is
 rejected for "v5" databases: those must be named regular files. The input and
 output may not refer to the same file.
 
+[[deprecation]]
+== DEPRECATION
+
+*g2asc* is *not* deprecated and remains a supported part of BRL-CAD.
+However, its original purpose -- producing an architecture-independent
+ASCII form of a geometry database for transfer between machines -- has
+been obsoleted by the machine-independent "v5" binary ".g" format, which
+can be moved between systems directly. For that reason, *g2asc* is no
+longer needed for portability. It is still applicable for inspecting,
+editing, or diff'ing geometry as text, after which *asc2g*(1) can convert
+the result back to binary form.
+
 [[options]]
 == OPTIONS
 

doc/asciidoc/system/man1/g4-g5.adoc

@@ -0,0 +1,74 @@
+= G4-G5(1)
+:doctype: manpage
+:mansource: BRL-CAD
+:manmanual: BRL-CAD
+
+== NAME
+g4-g5 - convert a BRL-CAD version 4 geometry database to version 5
+
+== SYNOPSIS
+
+[source]
+----
+g4-g5 v4.g v5.g
+----
+
+
+[[description]]
+== DESCRIPTION
+
+*g4-g5* reads the objects stored in a version 4 ("v4") BRL-CAD geometry
+database and writes out the equivalent objects in the current version 5
+("v5") ".g" format. Every object in the input database is read into its
+in-memory representation and re-exported to the output database.
+
+During conversion a few object types are updated to their modern
+equivalents:
+
+* the *plastic* shader name found in combination shader strings is
+  rewritten as *phong*;
+* height-field (HF) solids are converted to displacement-map (DSP)
+  solids;
+* polysolids (POLY) are converted to bags of triangles (BOT).
+
+Both _v4.g_ (the input) and _v5.g_ (the output) file names are required
+and must name different files. The input must be a version 4 database;
+*g4-g5* aborts if it is given a database of any other version. Objects
+that cannot be read or written are skipped, and the number of objects
+that failed to convert is reported on standard error when the run
+completes.
+
+The related program *dbupgrade*(1) provides a more general database
+upgrade path and is the recommended tool for routine version upgrades.
+
+
+[[see_also]]
+== SEE ALSO
+
+*brlcad*(1), *g5-g4*(1), *dbupgrade*(1), *mged*(1)
+
+
+[[diagnostics]]
+== DIAGNOSTICS
+
+Descriptive messages are printed on standard error. The name of each
+object is echoed as it is processed, and objects that fail to convert are
+reported individually before a final count of failures is printed.
+
+
+[[author]]
+== AUTHOR
+
+BRL-CAD Team
+
+
+[[copyright]]
+== COPYRIGHT
+
+This software is Copyright (c) 2004-2026 United States Government as represented by the U.S. Army Research Laboratory.
+
+
+[[bug_reports]]
+== BUG REPORTS
+
+Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org