support assemblies

get converter working again with native prt files
unified part writer
2026-09-01 13:22:02 -04:00 · 2026-09-01 13:22:02 -04:00 · 2026-09-01 13:22:02 -04:00 · 2026-09-01 13:22:02 -04:00 · 2026-09-01 13:22:02 -04:00 · 2026-09-01 13:22:01 -04:00
948 changed files with 47797 additions and 79966 deletions
@@ -1,260 +0,0 @@
-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."
@@ -69,12 +69,12 @@ jobs:

      - name: Configure
        run: |
-          export PATH=$GITHUB_WORKSPACE:$PATH
+          export PATH=$ENV{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=$GITHUB_WORKSPACE:$PATH
+          export PATH=$ENV{GITHUB_WORKSPACE}:$PATH
          cmake --build build_linux --config Release --target check

      - name: Debugging - tmate session
@@ -23,7 +23,7 @@ jobs:

  linux:
    name: Ubuntu GCC
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-latest
    strategy:
      fail-fast: true
    env:
@@ -33,6 +33,14 @@ jobs:
      - name: Setup - CMake
        uses: lukka/get-cmake@latest

+      # Cache apt package downloads (not installed pkgs)
+      - name: Cache apt packages
+        uses: actions/cache@v6
+        with:
+          path: |
+            /var/cache/apt/archives
+          key: ${{ runner.os }}-apt-${{ hashFiles('.github/workflows/push.yml') }}
+
      # Install system dependencies
      - name: Install apt dependencies
        run: |
@@ -50,20 +58,44 @@ 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@v6
+        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
@@ -73,7 +105,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=${{ runner.temp }}/bext_output -DBRLCAD_ENABLE_QT=ON
+          cmake -S brlcad -B build_linux -G Ninja -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_DIR=${{ github.workspace }}/bext_output -DBRLCAD_ENABLE_QT=ON

      - name: Build
        id: build_parallel
@@ -94,7 +126,7 @@ jobs:
  # repository integrity check and make sure we can build source archives.
  archives:
    name: Source Archives
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-latest
    needs: [linux]
    strategy:
      fail-fast: true
@@ -105,6 +137,13 @@ jobs:
      - name: Setup - CMake
        uses: lukka/get-cmake@latest

+      - name: Cache apt packages
+        uses: actions/cache@v6
+        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.
@@ -126,24 +165,47 @@ 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@v6
+        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 -j2
+          rm -rf bext
+          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: 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=${{ runner.temp }}/bext_output
+          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

  # A full bext build every time we push is too much, but we can exercise the
@@ -163,6 +225,13 @@ jobs:
      - name: Setup - CMake
        uses: lukka/get-cmake@latest

+      - name: Cache apt packages
+        uses: actions/cache@v6
+        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.
@@ -197,12 +266,13 @@ jobs:

      - name: Build
        run: |
+          cmake -E make_directory build_components_
          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-2025
+    runs-on: windows-latest
    strategy:
      fail-fast: true
    if: github.event_name == 'push'
@@ -220,27 +290,66 @@ 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@v6
+        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=${{ runner.temp }}\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=${{ github.workspace }}\bext_output -DCMAKE_BUILD_TYPE=Release -DBRLCAD_ENABLE_QT=ON

      - name: Build
        id: build_parallel
@@ -272,7 +381,7 @@ jobs:
  windows_std_tools:
    name: MSVC - Standard Tools
    needs: [windows]
-    runs-on: windows-2025
+    runs-on: windows-latest
    strategy:
      fail-fast: true
    if: github.event_name == 'push'
@@ -286,20 +395,66 @@ jobs:
      - 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@v6
+        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
@@ -320,7 +475,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=%RUNNER_TEMP%\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=%GITHUB_WORKSPACE%\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()
@@ -395,20 +550,51 @@ 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: |
+          set -euo pipefail
+          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"
+          cache_hash="$(printf '%s' "$info" | shasum -a 1 | awk '{print $1}')"
+          [[ "$cache_hash" =~ ^[[:xdigit:]]{40}$ ]]
+          echo "hash=$cache_hash" >> "$GITHUB_OUTPUT"
+
+      - name: Cache bext build outputs
+        id: cache-bext
+        uses: actions/cache@v6
+        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
@@ -420,7 +606,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=${{ runner.temp }}/bext_output -DBRLCAD_ENABLE_QT=ON
+          cmake -S brlcad -B build_osx -DCMAKE_BUILD_TYPE=Release -DBRLCAD_EXT_DIR=${{ github.workspace }}/bext_output -DBRLCAD_ENABLE_QT=ON

      - name: Build
        id: build_parallel
@@ -25,10 +25,19 @@ 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@v6
+        with:
+          path: |
+            /var/cache/apt/archives
+          key: ${{ runner.os }}-apt-${{ hashFiles('.github/workflows/scheduled.yml') }}
+
      # Install system dependencies
      - name: Install apt dependencies
        run: |
@@ -74,7 +83,7 @@ jobs:
    runs-on: windows-latest
    strategy:
      fail-fast: true
-    if: ${{ !cancelled() }}
+    if: github.event_name == 'schedule'
    steps:
      - name: Setup - CMake
        uses: lukka/get-cmake@latest
@@ -126,7 +135,7 @@ jobs:
    runs-on: windows-latest
    strategy:
      fail-fast: true
-    if: ${{ !cancelled() }}
+    if: github.event_name == 'schedule'
    steps:
      - name: Setup - CMake
        uses: lukka/get-cmake@latest
@@ -157,7 +166,7 @@ jobs:
          where ninja
          where cl.exe
          where msbuild
-          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
+          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

      - name: Build
        shell: cmd
@@ -180,7 +189,7 @@ jobs:
    runs-on: macos-14
    strategy:
      fail-fast: true
-    if: ${{ !cancelled() }}
+    if: github.event_name == 'schedule'
    steps:
      - name: Setup - CMake
        uses: lukka/get-cmake@latest
@@ -225,16 +234,23 @@ jobs:
  linux_static:
    name: Clang Static Analyser
    needs: [linux_bext]
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-latest
    strategy:
      fail-fast: true
    env:
      DEBIAN_FRONTEND: noninteractive
-    if: ${{ !cancelled() && github.ref == 'refs/heads/main' }}
+    if: github.event_name == 'schedule' && github.ref == 'refs/heads/main'
    steps:
      - name: Setup - CMake
        uses: lukka/get-cmake@latest

+      - name: Cache apt packages
+        uses: actions/cache@v6
+        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: |
@@ -253,20 +269,43 @@ 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@v6
+        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
@@ -275,8 +314,6 @@ 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 .
@@ -295,21 +332,28 @@ jobs:
  linux_cov:
    name: LCOV Coverage testing
    needs: [linux_bext]
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-latest
    strategy:
      fail-fast: true
    env:
      DEBIAN_FRONTEND: noninteractive
-    if: ${{ !cancelled() && github.ref == 'refs/heads/main' }}
+    if: github.event_name == 'schedule' && github.ref == 'refs/heads/main'
    steps:
      - name: Setup - CMake
        uses: lukka/get-cmake@latest

+      - name: Cache apt packages
+        uses: actions/cache@v6
+        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 gdb
+          sudo apt-get install lcov
          # 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
@@ -323,20 +367,43 @@ 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@v6
+        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
@@ -346,46 +413,24 @@ 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=${{ runner.temp }}/bext_output -DBRLCAD_ENABLE_QT=ON
+          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

      - 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 Tests
-        id: coverage_tests
+      - name: Run Coverage Test
        run: |
          find . -name '*.gcda' -exec rm {} \;
-          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: |
+          make check
          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
@@ -3,7 +3,7 @@
 /.build*
 /*_build*
 /*-build*
-/out
+out/

 # Temporary files
 *~
@@ -27,9 +27,9 @@
 # CMakeSettings.json for Visual Studio going forward)
 # https://learn.microsoft.com/en-us/cpp/build/cmake-presets-vs
 # https://learn.microsoft.com/en-us/cpp/build/customize-cmake-settings
-/.vs
+.vs/
 .vscode
-/CMakeSettings.json
+CMakeSettings.json

 #Qt Creator
 CMakeLists.txt.user
@@ -7,26 +7,14 @@ Write code as a senior engineer would for long-term maintenance. These are non-n
 - **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.
+- **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.
+- **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.
+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.
@@ -393,11 +393,6 @@ Sieu, Jeff
 2017 December
 Open Source (GCI)

-Baker, Josh
-nicknames joshbaker22
-2023 August
-U.S. Army Research Laboratory
-

 CODE CONTRIBUTIONS
 ------------------
@@ -1090,15 +1085,6 @@ 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
 --------------
@@ -21,9 +21,21 @@ 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.
+
 * 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.
@@ -52,12 +64,20 @@ 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
@@ -112,6 +132,12 @@ 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.

@@ -127,6 +153,9 @@ 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.
@@ -144,6 +173,15 @@ 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
@@ -200,6 +238,11 @@ 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.
@@ -247,6 +290,9 @@ 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
+
 * encountered a crash during rtarea on a (default) facetized version
  of the hyp from the proc-db csgbrep tool.

@@ -261,6 +307,9 @@ 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.
@@ -288,6 +337,10 @@ 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.

@@ -412,6 +465,11 @@ 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:

@@ -471,6 +529,9 @@ 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
@@ -565,6 +626,11 @@ 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
@@ -606,6 +672,9 @@ 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


@@ -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(12115e6c5922e2db27a9b88e00dd714af5315f69)
+brlcad_bext_init(2db06652996a5f37875de3ef9fcdadb57f89c8b3)

 #---------------------------------------------------------------------
 # Define various utilities.
@@ -1806,22 +1806,17 @@ 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 provider ${BRLCAD_X11_PROVIDER_RESOLVED} detected and enabled")
-  if(BRLCAD_X11_PROVIDER_RESOLVED STREQUAL "XMIN")
+  message("X11 detected and enabled")
+  if(X11_Xlib_INCLUDE_PATH)
    set(HAVE_X11_XLIB_H 1)
    brlcad_deferred_define("HAVE_X11_XLIB_H 1")
-  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()
+    # 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(BRLCAD_ENABLE_X11)

 # math library
@@ -2876,23 +2871,6 @@ 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")
@@ -3291,7 +3269,6 @@ 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
-  .github/actions/prepare-bext/action.yml
  .github/workflows/distcheck.yml
  .github/workflows/linux_interactive.yml
  .github/workflows/push.yml
@@ -39,7 +39,7 @@ including instructions for building on Windows.

 Required tools:
  - Git must be 2.17 or later
-  - CMake must be 3.26 or later
+  - CMake must be 3.20 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.  Released files and their checksums are
-available from the GitHub releases page (https://github.com/BRL-CAD/brlcad/releases).  If you
+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
 re-distribute BRL-CAD, checksums should be retained with the files so others
 can validate origination.

@@ -350,35 +350,6 @@ 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
@@ -467,10 +438,13 @@ Aliases:  ENABLE_ALL_CXX
 --- BRLCAD_EXTRADOCS ---

 The core option that enables and disables building of BRL-CAD's
-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.
+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).

-Aliases:  ENABLE_DOCS, ENABLE_EXTRA_DOCS
+Aliases:  ENABLE_DOCS, ENABLE_EXTRA_DOCS, ENABLE_DOCBOOK

@@ -13,166 +13,44 @@ 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
+* 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 pixborder utilitiy 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


 ----------------------------------------------------------------------
@@ -18,20 +18,8 @@ tasks as they are completed.
 THESE TASKS SHOULD HAPPEN BEFORE THE NEXT RELEASE
 -------------------------------------------------

-* 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
+* need extensive testing of MGED CSG editing with the shift
+  to librt based editing logic.

 THESE TASKS SHOULD HAPPEN WITHIN TWO RELEASE ITERATIONS
 -------------------------------------------------------
@@ -343,6 +331,11 @@ 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.
+
 * ability to visualize metaball centerpoints and with/without
  translucency.

@@ -364,6 +357,9 @@ 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
@@ -488,6 +484,8 @@ lookup check to ensure none are missing.

 * add unit tests for primitive callback routines (e.g., bbox).

+* 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
@@ -588,6 +586,10 @@ 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
@@ -636,6 +638,8 @@ 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
@@ -1070,6 +1074,12 @@ 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)

@@ -2540,6 +2550,8 @@ 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
@@ -1,246 +0,0 @@
-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.
@@ -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 ? setval : "", var);
+    echo("Using [%s] for %s\n", setval, var);
 }


@@ -589,7 +589,6 @@ 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);
@@ -605,7 +604,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", logfile ? logfile : "disabled");
+	echo("Logging output to %s\n", getenv("LOGFILE"));
 	echo("%s\n\n", bu_vls_addr(&v));
    }

@@ -654,7 +653,6 @@ 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 "
@@ -663,7 +661,7 @@ main(int ac, char *av[])
 		  "%s/../../pix "
 		  "%s/../../../pix "
 		  "./pix",
-		  pix_env ? pix_env : "", pix, thisp, thisp, thisp, thisp);
+		  getenv("PIX"), 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);
@@ -13,6 +13,8 @@ set(
  README.MacOSX
  README.Windows
  README.BSD
+  README.Solaris
+  README.VAX
  checklist.txt
  description.txt
  optimization_ideas.adoc
@@ -27,7 +29,6 @@ set(
  notes/editors.txt
  notes/history.txt
  notes/hypot.txt
-  notes/itcl4_migration.txt
  notes/mater.txt
  notes/matrix.txt
  pre_BRL-CAD.bib
@@ -216,8 +217,6 @@ endif(TARGET mged)

 cmakefiles(
  CMakeLists.txt
-  README.Solaris
-  README.VAX
  README.adoc
  STARTERS
  STRATEGY
@@ -1,7 +1,3 @@
-*** 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
@@ -1,7 +1,3 @@
-*** 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
 =====================

@@ -33,7 +33,7 @@ toc::[]

 === Prerequisites
 To build BRL-CAD from source, you will need:
-* **CMake** (3.26+)
+* **CMake** (3.14+)
 * **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 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/`.
+We are currently transitioning our extensive documentation (Docbook/XML + MediaWiki + troff + text + ...) to an **Antora-powered ecosystem**.

 * **Tutorials:** link:{docs-url}/tutorials[Browse the Manuals]
 * **Developer Guides:** link:{docs-url}/hacking and link:{repo-url}/blob/main/HACKING
@@ -1,6 +1,5 @@
 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)
@@ -4,14 +4,15 @@

 == Overview

-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.
+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`.

-The `.adoc` files are built into HTML and man-page outputs at compile time
-using **asciiquack**, BRL-CAD's self-contained AsciiDoc processor.
+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.

 == Directory Structure

@@ -42,17 +43,28 @@ When `BRLCAD_EXTRADOCS=ON` is set at CMake configuration time:

 The build logic is in `brlcad/misc/CMake/AsciiDoc.cmake`.

-== Authoritative Sources
+== Re-running the Conversion

-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.
+If the upstream DocBook sources change and you need to re-generate the AsciiDoc
+files, run the XSLT stylesheet from the repository root:

-[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.
-====
+[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
+----
@@ -227,21 +227,20 @@ set(
  images/renderer_gallery_rthide.png
  images/renderer_gallery_rtdepth.png
  images/renderer_gallery_rtxray.png
-  images/adrt_castle_path.png
-  images/adrt_castle_rt.png
-  images/adrt_castle_rt_ao.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_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
@@ -71,11 +71,11 @@ More paragraphs...

 [CAUTION]
 ====
-There's a lot more you can do with AsciiDoc. Consult the reference documentation for syntax and examples:
+There's a lot more you can do with Docbook/XML. Search the web for references and examples:


-* https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc Language Documentation]
-* https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc Syntax Quick Reference]
+* 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]

 ====

@@ -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 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.
+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.


 ....
@@ -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, 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`).
+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.
@@ -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@|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_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_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.]=])

@@ -49,66 +49,7 @@ The following code illustrates a basic use of GCV from within an application. No
 .gcv_app.c
 [example]
 ====
-
-[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;
-}
----
+TODO: embedded code

 ====

@@ -224,57 +165,7 @@ LIBGCV_ADD_PLUGIN(foo "foo_read.c" "librt;libbu")
 .foo_read.c
 [example]
 ====
-
-[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; }
----
+TODO: embedded code

 ====

@@ -301,89 +192,7 @@ The following example implements a filter that tessellates all geometry into BoT
 .tessellation_statistics.c
 [example]
 ====
-
-[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
-};
----
+TODO: embedded code

 ====

@@ -441,51 +250,7 @@ The following example will leverage the filter in the above plugin example, `tes
 .gcv_embedded.c
 [example]
 ====
-
-[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;
-}
----
+TODO: embedded code

 ====

@@ -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 [h|n]type] dest source_
+*bo*_[-o|-i pattern 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 host-order file called _dest_.
+The _-o_ option “outputs” or extracts a binary object from the database object _source_ to a 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. 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:
+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:

 _f_-> float

@@ -2482,14 +2482,10 @@ _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._
@@ -1242,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 |Host-order 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 |File to read the array from.
 |count |integer |Number of values to read (-1 for the whole file).
 |===

@@ -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*: 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.
+|*mkbuilding*: Procedurally builds a small building: a floor slab, four framed walls with openings, and an overhanging roof.
 |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]
@@ -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 https://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 http://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 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.
+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.

 ====

@@ -1374,20 +1374,213 @@ image::../articles/images/mgedrc_fig03.png[]
 [appendix]
 == Using the Build Pattern Tool

-// 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]
+[[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[]


 [appendix]
 == Using the build_region Command

-// 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]
+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.
@@ -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 https://ftp.arl.army.mil/brlcad/[https://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 http://ftp.arl.army.mil/brlcad/[http://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 https://adeskftp.autodesk.com/ prodsupp/downloads/dxf.pdf[https://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 http://adeskftp.autodesk.com/ prodsupp/downloads/dxf.pdf[http://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 https://www.elysiuminc.com[https://www.elysiuminc.com] (Elysium, 2003).
+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).


 [[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 https://support.mdtvision.com[https://support.mdtvision.com] (MDTVISION, 2003).
+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).

 .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 https://www.bahdayton.com/surviac/fastgen.htm[https://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 http://www.bahdayton.com/surviac/fastgen.htm[http://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 https://www.nist.gov/iges[https://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 http://www.nist.gov/iges[http://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 https://www.eds.com/products/plm/efactory/jack/[https://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 http://www.eds.com/products/plm/efactory/jack/[http://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 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).
+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).


 [[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 https://www.ptc.com[https://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 http://www.ptc.com[http://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 https://www.3dsystems.com[https://www.3dsystems.com] (3D Systems, 2003).
+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).


 [[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 https://www.advantage-business.co.uk[https://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 http://www.advantage-business.co.uk[http://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 https://www.eds.com/products/plm/unigraphics_nx/[https://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 http://www.eds.com/products/plm/unigraphics_nx/[http://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 https://www.lockheedmartin.com[https://www.lockheedmartin.com] (Lockheed Martin, 2003).
+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).


 [[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 https://www.autodesk.com[https://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 http://www.autodesk.com[http://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 https://support.mdtvision.com[https://support.mdtvision.com] (MDTVISION, 2003).
+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).


 [[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 https://www.nist.gov/iges[https://www.nist.gov/iges] (NIST, 2003).
+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).


 [[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 https://www.eds.com/products/plm/efactory/jack[https://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 http://www.eds.com/products/plm/efactory/jack[http://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 https://www.3dsystems.com[https://www.3dsystems.com] (3D Systems, 2003).
+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).


 [[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 https://www.advantage-business.co.uk[https://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 http://www.advantage-business.co.uk[http://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 https://www.web3d.org /fs_technicalinfo.htm[https://www.web3d.org /fs_technicalinfo.htm] (Web3D Consortium, 2003b).
+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).

 .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 https://www.alias.com/eng/index.shtml[https://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 http://www.alias.com/eng/index.shtml[http://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 https://www.web3d.org/technicalinfo/specifications/ISO_IEC_19775[https://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 http://www.web3d.org/technicalinfo/specifications/ISO_IEC_19775[http://www.web3d.org/technicalinfo/specifications/ISO_IEC_19775] (Web3D Consortium, 2003a).


 [[sec_build_new_converter]]
@@ -4,7 +4,6 @@ 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)
@@ -66,7 +65,6 @@ 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)

@@ -104,6 +102,7 @@ cmakefiles(
  ${books_ADOC}
  ${books_EN_IMAGES}
  ${hacking_brlcad_images}
+  HACKING_BRL-CAD.adoc
 )

 # Local Variables:
@@ -296,10 +296,10 @@ Example geometry
 Project documentation


-`doc/asciidoc/`::
-User and developer documentation in AsciiDoc format
+`doc/docbook`::
+User documentation in XML format
 +
-See doc/asciidoc/README.adoc for more details
+See doc/docbook/README 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, main, 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 trunk, 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 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.
+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.

 Major components of the system are written in the following languages:

@@ -411,7 +411,7 @@ Source code files use the following extensions:



-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.
+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).


 ===== Coding Style
@@ -569,9 +569,11 @@ 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 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].
+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.

-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].
+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.


 ==== Two-Month Tasks
@@ -589,7 +591,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 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.
+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.

 ===== Obtaining the Development Tools

@@ -642,11 +644,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 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.
+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.

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

-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_.
+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_.

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

@@ -654,7 +656,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.
-* Open a pull request against the https://github.com/BRL-CAD/brlcad[BRL-CAD repository] on GitHub so your changes can be reviewed.
+* Make a handful of patches and submit them to SourceForge for review.
 * Obtain commit access.


@@ -671,123 +673,136 @@ 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 writes its documentation in AsciiDoc and uses a single toolchain to produce documentation in the range of required formats.
+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.

-==== What is AsciiDoc?
+==== What is DocBook?

-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].
+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.


-==== Tools for Working with AsciiDoc
+==== Tools for Working with DocBook

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

-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.
+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 AsciiDoc sources live under `doc/asciidoc/`, organized by document type into the following subdirectories:
+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:


-* `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/`.
+....

-For more information, see the file `doc/asciidoc/README.adoc` in the BRL-CAD source code archive.
+[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:


-==== AsciiDoc Syntax Essentials
+* 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.

-A few constructs cover the majority of everyday documentation editing:
+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:

+*cmake -DVALIDATE_EXECUTABLE=msv ...*

-* *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
----
+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.

-* *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.
+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.


 ==== Adding a New Document to BRL-CAD

-Adding a new document is straightforward: create the AsciiDoc source, then register it with the build system so BRL-CAD renders it.
+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.

-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:
+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:

-~/brlcad$ *cp doc/asciidoc/articles/TEMPLATE.adoc doc/asciidoc/articles/ellipsoid.adoc*
+~/brlcad$ *cp doc/docbook/articles/en/TEMPLATE.xml doc/docbook/articles/en/ellipsoid.xml*

-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:
+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:


----
-set(
-  articles_EN
-  TEMPLATE.adoc
-  about.adoc
-  ...
-  ellipsoid.adoc
-)
----
+....

-Reconfigure and build with documentation enabled (in this example, the build output directory is called `build`):
+~/brlcad/build $ make ellipsoid_article_html

-~/brlcad/build$ *cmake .. -DBRLCAD_EXTRADOCS=ON*
+[  0%] Built target printtimestamp
+[  0%] Built target buildtimestart

-~/brlcad/build$ *cmake --build . --target doc*
+Build Time: Tue Oct 15 19:14:42 2013

-The asciiquack processor renders the article to:
+[  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 $
+....

-`build/share/doc/html/articles/ellipsoid.html`
+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:

-Open this file in a web browser to view the HTML output.
+image::../books/images/hacking_brlcad_example_docbook_default_output.png[width=100%]

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


-. 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.
+. 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%]


-==== Working with Translated Documents
+==== Adding a Translated Document to BRL-CAD

-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.
+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%]


 ==== Selecting Output Formats

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

-You can use the following configuration options to turn documentation compilation on and off:
+You can use the following configuration options to turn the compilation of various formats on and off:

-.BRL-CAD Documentation Configuration Options
+.BRL-CAD DocBook Configuration Options
 [cols="3*"]
 |===
 |Option
@@ -795,42 +810,64 @@ You can use the following configuration options to turn documentation compilatio
 |Setting

 |BRLCAD_EXTRADOCS
-|Enable AsciiDoc documentation
-|ON for a full build (OFF for reduced target sets)
+|Enable DocBook documentation
+|ON
 |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 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.
+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.


 ==== Sharing Content Between Documents

-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:
+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.

+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:

----
-include::../lessons/mged01_creating_primitive_shapes.adoc[]
----
+`<xi:include href="/lessons/en/mged01_creating_primitive_shapes.xml" xpointer="creating_primitive_shapes_overviewlist"/>`

-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:
+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:

-
----
-include::shared_snippet.adoc[tag=overview]
----
+`<para xml:id="creating_primitive_shapes_overviewlist">`

 The drawbacks to this mechanism are that:


-* 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.
+* 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.

-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.
+
+==== 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.


 === Types of Documentation We Maintain
@@ -853,7 +890,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 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.
+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.

 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.

@@ -935,26 +972,29 @@ The documentation and the toolchain required to generate the documentation is pa

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

-The `brlcad` directory should be kept separate from your build directory so that BRL-CAD's build outputs don't clutter the source tree.
+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.

-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.
+===== 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.


 ===== Configure

-Next, you must set up the build directory and configure the compilation with documentation enabled. Run the following command from an empty build directory:
+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.

-*cmake ../brlcad -DBRLCAD_EXTRADOCS=ON*
+*cmake ../brlcad_build -DBRLCAD_BUILD_TYPE=Debug*


 ===== Generate the Documentation

-Once you've configured the compilation, you can run the following build targets to generate the documentation:
+Once you've configured the compilation, you'll need to run the following build targets to generate the documentation:


-* doc (to generate both the HTML documentation and the UNIX man pages)
+* doc (to generate the HTML version of the 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).



@@ -967,10 +1007,10 @@ You can find the source files for the documentation in the following directories
 Project documentation


-`doc/asciidoc/`::
-User and developer documentation in AsciiDoc format
+`doc/docbook`::
+User documentation in XML format
 +
-See the file `doc/asciidoc/README.adoc` for more details
+See the file `doc/docbook/README` for more details



@@ -985,11 +1025,11 @@ Remember to:

 ==== Discussing the Documentation

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

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

-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_.
+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_.


 == Other Contributors
@@ -1012,9 +1052,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 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].
+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.

-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].
+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.


 ==== Outreach and Artwork
@@ -1087,56 +1127,91 @@ In addition to the resources provided previously in this book, the following res
 [appendix]
 === Doc Template: New MGED Command

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


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

-[[description]]
-== DESCRIPTION
+<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="">

-A full description of the command goes here, in one or more paragraphs.
+<refmeta>
+  <refentrytitle> <refentrytitle/>
+  <manvolnum>nged</manvolnum>
+  <refmiscinfo class="source">BRL-CAD</refmiscinfo>
+  <refmiscinfo class="manual">BRL-CAD User Commands</refmiscinfo>
+</refmeta>

-The following options are supported:
+<refnamediv xml:id="name">
+  <refname><refname/>
+  <refpurpose>

-* *-a* - Description of the -a option.
-* *-b* - Description of the -b option.
+  </refpurpose>
+</refnamediv>

-[[examples]]
-== EXAMPLES
+<!-- body begins here -->
+<refsynopsisdiv xml:id="synopsis">
+  <cmdsynopsis sepchar=" ">
+    <command/>
+    <arg choice="opt" rep="norepeat"/>
+  </cmdsynopsis>
+</refsynopsisdiv>

-.A short caption describing the first example.
-[example]
-====
-mged>**commandname arg**
+<refsection xml:id="description"><info><title>DESCRIPTION</title></info>
+  <para>

-An explanation of what this invocation does and what output to expect.
-====
+  </para>
+</refsection>

-== AUTHOR
+<refsection xml:id="examples"><info><title>EXAMPLES</title></info>

-BRL-CAD Team
+  <para>

-== BUG REPORTS
+  </para>
+  <example><info><title/></info>

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

 [appendix]
 === Code Example: Shooting Rays
@@ -1,12 +1,8 @@
 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(
@@ -1,123 +0,0 @@
-= 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.
@@ -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 historical NURBS Boolean evaluation development branch of the source repository.
+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/).

 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 the historical NURBS Boolean evaluation development branch of the source repository.
+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/).

 If you want to follow along, you can reinstate the error in a checkout of the development branch:

@@ -1,198 +0,0 @@
-= 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.
@@ -1,203 +0,0 @@
-= 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].
@@ -1,233 +0,0 @@
-= 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].
@@ -25,8 +25,8 @@ set(
  images/mged01_terminal.png
  images/mged02_coordsys.png
  images/mged02_defaultradio.png
-  images/mged02_flower_zoomin.png
-  images/mged02_flower_zoomout.png
+  images/mged02_flower_zooomin.png
+  images/mged02_flower_zooomout.png
  images/mged02_multipane.png
  images/mged02_radio_35_25.png
  images/mged02_radio_front.png
@@ -43,10 +43,6 @@ 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
@@ -59,7 +55,7 @@ set(
  images/mged05_subtractionspheres.png
  images/mged05_twoprimitivespheres.png
  images/mged05_unionspheres.png
-  images/mged06_base_subtracted_vol.png
+  images/mged06_base_substracted_vol.png
  images/mged06_goblet1stsphere.png
  images/mged06_gobletbase.png
  images/mged06_gobletbasestembasin.png
@@ -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.png[]
-|image:../../lessons/es/images/mged02_flower_zoomout.png[]
+|image:../../lessons/es/images/mged02_flower_zoomin.jpg[]
+|image:../../lessons/es/images/mged02_flower_zoomout.jpg[]
 |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)
 |===
@@ -45,7 +45,7 @@ Como pudo apreciar en el tutorial #1, este comando le dice a _MGED_ que:



-image::../../lessons/es/images/mged03_wireframe_sph.png[]
+image::../../lessons/mged/using_insert_command_images/wireframesphere.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_wireframe_sph_rcc.png[]
+image::../../lessons/es/images/mged03_wireframespherecylinder.png[]



@@ -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_35_el_25.png[]
+image::../../lessons/es/images/mged06_rtgobletaz_35el_25.png[]



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



@@ -85,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]
+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.


 [[set_units]]
@@ -26,7 +26,7 @@ image::../lessons/images/mged08_goblet_combeditor.png[]

 [NOTE]
 ====
-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.
+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.

 ====

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

-At the Command Window prompt, type: *inside cab1.s caboff1.s -.1 .7 -.1 -.1 .5 -.1[Enter]* The inside command tells _MGED_ to:
+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:

 [cols="9*"]
 [%noheader]
@@ -378,6 +378,13 @@ 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

@@ -1,10 +1,12 @@
-= Application Development with BRL-CAD (Overview)
+= Untitled
 :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:
@@ -1,10 +1,12 @@
-= Tcl/Tk Overview
+= Untitled
 :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.
@@ -1,7 +1,6 @@
 set(
  specifications_EN
  BRL_CAD_g_format_V6.adoc
-  BRL_CAD_g_format_V5.adoc
 )

 if(TARGET librt)
@@ -12,6 +11,7 @@ endif(TARGET librt)

 cmakefiles(
  ${specifications_EN}
+  BRL_CAD_g_format_V5.adoc
  CMakeLists.txt
 )

@@ -2,7 +2,6 @@ set(
  man1_EN
  3dm-g.adoc
  a-d.adoc
-  adrt.adoc
  adrt_master.adoc
  adrt_slave.adoc
  alias-pix.adoc
@@ -13,13 +12,11 @@ set(
  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
@@ -118,9 +115,6 @@ set(
  g-vrml.adoc
  g-x3d.adoc
  g2asc.adoc
-  g4-g5.adoc
-  g5-g4.adoc
-  ganalyze.adoc
  gastank.adoc
  gchecker.adoc
  gcv.adoc
@@ -134,7 +128,6 @@ set(
  gltf-g.adoc
  gqa.adoc
  gsh.adoc
-  gtransfer.adoc
  halftone.adoc
  handle.adoc
  human.adoc
@@ -155,7 +148,6 @@ set(
  lowp.adoc
  mac-pix.adoc
  mged.adoc
-  mkbuilding.adoc
  naca456.adoc
  nastran-g.adoc
  nirt.adoc
@@ -264,7 +256,6 @@ set(
  umod.adoc
  ustats.adoc
  vdeck.adoc
-  walk_example.adoc
  wavelet.adoc
  wdb_example.adoc
  window.adoc
@@ -35,16 +35,6 @@ 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

@@ -1,136 +0,0 @@
-= 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
@@ -23,26 +23,27 @@ 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, 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.
+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.

 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 exact path named by *-o* (default _art.png_).
-The output format is inferred from the file extension.
+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)).

-*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.
+*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.


 [[options]]
@@ -50,7 +51,7 @@ currently supported.

 *-o* _filename_::
  Render to the named image file (e.g. _image.png_ or _image.pix_).
-  Default is _art.png_.
+  Default is _art.png_. The file is written under _output/_.

 *-F* _framebuffer_::
  Also display the render in the named framebuffer (see FB_FILE in
@@ -129,7 +130,7 @@ currently supported.
 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_ in the current directory.
+into a 1024x1024 image named _havoc.png_ (placed in _output/havoc.png_).
 ====

 .Increase sample count and use an orthographic camera
@@ -24,21 +24,6 @@ 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

@@ -1,85 +0,0 @@
-= 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
@@ -1,99 +0,0 @@
-= 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
@@ -6,19 +6,6 @@
 == 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

@@ -46,7 +33,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 *pix-fb*(1), *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 *libfb*(3), *pix-fb*(3), *pix*(5), etc.


 *fbserv*::
@@ -54,11 +41,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 *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 *libplot3*(3), *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).
+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).


 *util*::
@@ -78,7 +65,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.
+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.


 [[options]]
@@ -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 *brlcad*(1)) 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 *libfb*(3)) 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.

@@ -28,8 +28,7 @@ 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. When omitted, signed format is
-  assumed.
+  effect on the double-precision format.
 * *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*
@@ -30,16 +30,6 @@ 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

@@ -16,13 +16,12 @@ dpix-pix file.dpix > file.pix
 [[description]]
 == DESCRIPTION

-*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.
+*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.

 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
@@ -47,7 +46,7 @@ error indicate the exposure range used for the conversion.
 [[see_also]]
 == SEE ALSO

-*brlcad*(1), *pix-fb*(1), *cv*(1), *dpix*(5), *pix*(5)
+*brlcad*(1), *pix-fb*(1), *cv*(1), *pix*(5)

 [[author]]
 == AUTHOR
@@ -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 *plot3*(5)
+  Write all processed CTRI and CQUAD elements to _plot_file_ in libplot3
  format. The result can be viewed in *mged*(1) with the _overlay_ command.

 *-m* _muves_file_::
@@ -80,7 +80,7 @@ device.
 [[see_also]]
 == SEE ALSO

-*brlcad*(1), *fbclear*(1), *fbgrid*(1), *fbframe*(1), *pix-fb*(1), *pixbackgnd*(1)
+*brlcad*(1), *fbclear*(1), *fbgrid*(1), *fbframe*(1), *pix-fb*(1), *pixbackgnd*(1), *libfb*(3)


 [[inspirations]]
@@ -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)
+*brlcad*(1), *fbpoint*(1), *fbline*(1), *fbclear*(1), *pix-fb*(1), *libfb*(3)


 [[author]]
@@ -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), *pix*(5)
+*brlcad*(1), *fblabel*(1), *fbpoint*(1), *pix-fb*(1), *plot3-fb*(1), *libfb*(3), *pix*(5)


 [[author]]
@@ -11,54 +11,26 @@ g-iges - convert a BRL-CAD database to an IGES file

 [source]
 ----
-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_ ...]
+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_ ...]
 ----

 [[description]]
 == DESCRIPTION

 *g-iges* converts the specified _object_(s) from a BRL-CAD _database.g_ database
-into an IGES version 5.3 file.
+into an IGES version 5.1 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 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.
+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.

-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
+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
 *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

@@ -73,23 +45,12 @@ not an estimate of remaining time.
  region.

 *-m*::
-  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.
+  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.

 *-s*::
-  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.
+  Write the faces of B-Rep objects as planar NURBS surfaces.

 *-a* _abs_tol_::
  Absolute tessellation tolerance, in millimeters. Default 0.0 (disabled).
@@ -104,12 +65,10 @@ not an estimate of remaining time.
  Minimum distance between distinct points, in millimeters. Default 0.0005.

 *-P* _ncpu_::
-  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.
+  Number of processors to use during tessellation. Default 1.

 *-v*::
-  Include entity-type counts in the export summary.
+  Verbose output; repeat for more detail.

 *-x* _rt_debug_::
  Set the *librt* raytrace debug flag (hexadecimal). See raytrace.h for values.
@@ -118,12 +77,8 @@ not an estimate of remaining time.
  Set the NMG debug flag (hexadecimal). See nmg.h for values.

 *-o* _output_file_::
-  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.
+  Write the IGES output to _output_file_ instead of standard output. With *-m*,
+  this argument must be a directory.

 [[examples]]
 == EXAMPLES
@@ -132,11 +87,11 @@ not an estimate of remaining time.
 ====
 [source,bash]
 ----
-g-iges assembly.g assembly.iges hull turret
+g-iges -o assembly.iges assembly.g 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 using B-Rep
-representations for other supported geometry.
+the Boolean tree where IGES primitive equivalents exist and tessellating the
+rest.
 ====

 .Produce a faceted B-Rep IGES file with tight tolerances
@@ -163,13 +118,6 @@ 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)
@@ -37,18 +37,6 @@ 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

@@ -1,74 +0,0 @@
-= 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
@@ -1,74 +0,0 @@
-= G5-G4(1)
-:doctype: manpage
-:mansource: BRL-CAD
-:manmanual: BRL-CAD
-
-== NAME
-g5-g4 - convert a BRL-CAD version 5 geometry database to version 4
-
-== SYNOPSIS
-
-[source]
----
-g5-g4 v5.g v4.g
----
-
-
-[[description]]
-== DESCRIPTION
-
-*g5-g4* reads the objects stored in a current version 5 ("v5") BRL-CAD
-geometry database and writes out the equivalent objects in the legacy
-version 4 ("v4") ".g" format. It is the inverse of *g4-g5*(1) and is
-provided chiefly for interoperability with older tools that only
-understand the v4 format.
-
-Not every v5 object can be represented in a v4 database. Objects whose
-major type is not native BRL-CAD geometry are not supported in v4
-databases and are skipped rather than converted. For the objects that
-are converted, a few types are adjusted as they are written:
-
-* 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 _v5.g_ (the input) and _v4.g_ (the output) file names are required.
-The input must be a version 5 database; *g5-g4* aborts if it is given a
-database of any other version. When the run completes, the number of
-v5-specific objects that were skipped and the number of attempted objects
-that failed to convert are reported on standard error.
-
-
-[[see_also]]
-== SEE ALSO
-
-*brlcad*(1), *g4-g5*(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. Objects that cannot be stored in a
-v4 database are reported as unsupported, and objects that fail to convert
-are reported individually before final counts are 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
@@ -1,66 +0,0 @@
-= GANALYZE(1)
-:doctype: manpage
-:mansource: BRL-CAD
-:manmanual: BRL-CAD
-
-== NAME
-ganalyze - command-line interface to BRL-CAD geometry analysis capabilities
-
-== SYNOPSIS
-
-[source]
----
-ganalyze
----
-
-
-[[description]]
-== DESCRIPTION
-
-*ganalyze* is a command-line front end to the analysis routines provided
-by BRL-CAD's *libanalyze* library. It presents a command-driven prompt
-from which geometry analysis operations can be requested.
-
-*ganalyze* runs in one of two modes, selected automatically according to
-how it is invoked:
-
-Interactive mode::
-  When standard input is a terminal, *ganalyze* presents an interactive
-  *ganalyze:* prompt with line editing and command history. The special
-  input *clear screen* clears the terminal, and *q* or *quit* exits the
-  program.
-
-Batch mode::
-  When standard input is not a terminal, *ganalyze* reads commands from
-  standard input one line at a time, which allows it to be driven from a
-  script or a pipeline.
-
-The command interpreter is under active development; at present it
-recognizes only a small set of commands (for example a *draw* command
-that names an object, and *q* / *quit* to exit). Unrecognized commands
-and commands given the wrong number of arguments are reported without
-terminating the session.
-
-
-[[see_also]]
-== SEE ALSO
-
-*brlcad*(1), *gqa*(1), *mged*(1)
-
-
-[[author]]
-== AUTHOR
-
-BRL-CAD Team
-
-
-[[copyright]]
-== COPYRIGHT
-
-This software is Copyright (c) 2019-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
@@ -78,35 +78,6 @@ filter, or both, allowing format-specific behavior to be tuned without
  Pass _opts_ to both the input and output filters. Consumes arguments until
  the next top-level *gcv* option is encountered.

-[[iges_options]]
-== IGES FILTER OPTIONS
-
-The IGES reader and writer share their conversion implementation with
-*iges-g*(1) and *g-iges*(1). Native CSG, exact B-Reps, and NMG conversion
-remain available without changing BRL-CAD's library interfaces.
-
-The reader accepts *--breps-only* (solid and surface geometry, including
-native CSG), *--drawings-only*, *--3d-drawings*, *--exact*, *--strict*,
-*--repair* _none|safe|best-effort_, *--relative-tolerance* _fraction_, and
-*--max-repair-tolerance* _mm_ through *-I*. By default it attempts both model
-geometry and drawings; a drawing-only file retains its model-space planes.
-The relative boundary repair target defaults to 0.0001 of the local bounding
-box diagonal. Strict mode rejects repaired or partial imports.
-Safe and best-effort imports also correct clearly inward or inconsistently
-oriented isolated closed BRep shells, using the same low-memory signed-volume
-check as *iges-g*. Open, nested, overlapping, and uncertain shells are left
-unchanged. Orientation corrections are diagnosed and recorded on the objects.
-
-The writer preserves native CSG where representable and uses exact B-Reps
-for supported non-CSG primitives. Its *-O* options are *--faceted*,
-*--trimmed-surfaces*, *--nurbs*, and *--flatten-brep*, corresponding to the
-same export modes in *g-iges*. Tessellation is explicit for regions; existing
-polyhedral geometry retains the NMG export path. Output replaces the
-destination only after a complete IGES file has been written. A partial
-export reports failure even when a readable subset has been written.
-The filters honor IGES file units; a non-unit libgcv scale override is
-rejected rather than silently ignored.
-
 [[examples]]
 == EXAMPLES

@@ -1,97 +0,0 @@
-= GTRANSFER(1)
-:doctype: manpage
-:mansource: BRL-CAD
-:manmanual: BRL-CAD
-
-== NAME
-gtransfer - example client/server transfer of BRL-CAD geometry over a network
-
-== SYNOPSIS
-
-[source]
----
-gtransfer [-t] [-p#] host gfile [geometry ...]
----
-
-[source]
----
-gtransfer -r [-p#]
----
-
-
-[[description]]
-== DESCRIPTION
-
-*gtransfer* is a sample application that demonstrates how to open a
-geometry database, extract a serialized ("external") representation of
-selected objects, transfer those objects to a remote host over a network
-connection, and operate on the received geometry entirely in memory using
-standard *librt*(3) routines. The network transport is built on
-BRL-CAD's *libpkg* message-passing library, using a simple protocol
-patterned after *ttcp*(1): a connection begins with a greeting, carries a
-variable number of geometry and argument messages, and ends with a
-farewell.
-
-*gtransfer* operates as either a client (the sender, the default) or a
-server (the receiver, selected with *-r*).
-
-As a client, it connects to _host_, reads the database _gfile_, and sends
-geometry to the server. If one or more _geometry_ object names are given,
-only those objects and the combinations and primitives beneath them are
-sent; otherwise the entire contents of the database are sent.
-
-As a server, it listens for a single client connection, receives the
-transmitted geometry into an in-memory database, and (when the client
-requested particular objects) fires a demonstration ray at each named
-object to show that the received geometry can be ray traced.
-
-*gtransfer* is provided as a worked example of the *libpkg* and *librt*
-interfaces rather than as a general-purpose production utility.
-
-
-[[options]]
-== OPTIONS
-
-*-t*::
-  Run as a client (sender). This is the default behavior.
-
-*-r*::
-  Run as a server (receiver), listening for a single client connection.
-
-*-p #*::
-  Port number to send to (client) or listen on (server). The default is
-  2000.
-
-*host*::
-  Hostname or IP address of the receiving server (client mode).
-
-*gfile*::
-  BRL-CAD ".g" geometry database file to read from (client mode).
-
-*geometry*::
-  Optional name or names of geometry objects to send. When omitted, the
-  entire database is sent.
-
-
-[[see_also]]
-== SEE ALSO
-
-*brlcad*(1), *fbserv*(1), *rt*(1), *librt*(3)
-
-
-[[author]]
-== AUTHOR
-
-BRL-CAD Team
-
-
-[[copyright]]
-== COPYRIGHT
-
-This software is Copyright (c) 2006-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
@@ -11,8 +11,7 @@ iges-g - convert an IGES file to a BRL-CAD database

 [source]
 ----
-iges-g [--exact|--strict] [--repair _none|safe|best-effort_] [--relative-tolerance _fraction_] [--max-repair-tolerance _mm_] [--default-plate-thickness _mm_] [--report _file.json_] [-3] [-d] [-n] [-t] [-m|-p] [-N _solid_name_] [-x _rt_debug_flag_] [-X _nmg_debug_flag_] [-o _database.g_] _file.iges_ [_database.g_]
-iges-g --check-orientation _database.g_ [--report _file.json_]
+iges-g [-3] [-d] [-n] [-t] [-p] [-N _solid_name_] [-x _rt_debug_flag_] [-X _nmg_debug_flag_] -o _database.g_ _file.iges_
 ----


@@ -21,240 +20,52 @@ iges-g --check-orientation _database.g_ [--report _file.json_]

 *iges-g* reads an IGES (Initial Graphics Exchange Specification) file and
 writes the converted geometry to a BRL-CAD _database.g_ file. The input is
-expected to conform to IGES version 5.3 or an earlier version.
+expected to conform to IGES version 5.1.

 With none of the *-3*, *-d*, *-n*, or *-t* options, the default action is to
-convert IGES solid model entities to their BRL-CAD equivalents. Type 186
-manifold topology is constructed directly in OpenNURBS, including type 192
-analytic cylindrical faces. Parameterized planes and cylinders retain their
-reference directions and authored parameter units (degrees for cylinder
-angles). Type 143 bounded and
-Type 144 trimmed surfaces are constructed as independent OpenNURBS faces and
-conservatively stitched into shared manifold topology when their boundary
-curves agree within the file tolerance. Trimmed surfaces may use the finite
-natural outer boundary of their base surface. Legacy type 108 bounded planes
-and their type 402 single-parent hole associations are also supported.
-Native CSG uses BRL-CAD primitives where representable. Supported general
-revolution and extrusion profiles use exact NURBS and primitive BRep callbacks;
-linear revolutions and circular extrusions retain native CSG when possible.
-All geometry and hierarchy are read from the same validated document.
-BREP objects are written as
-native BRL-CAD BRep objects by default; *-m* and *-p* select polygonal
-output by tessellating the validated OpenNURBS representation.
+convert only IGES solid model entities (CSG primitives and planar-face BREP
+objects) to their BRL-CAD equivalents. Most CSG conversions are exact; solids
+of revolution are approximated by a series of BRL-CAD cones and solids of
+linear extrusion are approximated by polysolids. Planar-faced BREP objects are
+written as BOT solids by default (or as NMG solids with *-p*).

-If a default import contains no bounded surface or solid entities, the converter imports
-its supported drawings and datums in model space without projecting them to XY.
-Unbounded construction planes do not prevent this drawing-mode selection.
-Non-planar curves and supported composite, conic, and parametric spline curves
-can be retained as adaptively sampled NMG wire geometry.
-
-Surfaces of revolution retain their angular parameterization so their trims
-remain in the authored parameter space. Boundaries at surface poles may have
-parameter-space segments without corresponding model-space edges. Safe repair
-recognizes rounded poles, completes missing parameter-space sides at poles,
-and can match differently segmented boundaries using
-bounded geometric comparison while retaining the original model curves.
-Closed manifold edges retain their authored use orientation. Missing optional
-manifold parameter curves can be reconstructed from model-space boundaries in
-safe repair mode, starting at the source accuracy to preserve small features.
-Bounded parameter-loop endpoint repairs also apply to manifold faces.
-The initial repair allowance and the allowance for boundary recovery
-are the larger of 100 times the source resolution and 0.0001 times the local
-model-space boundary bounding-box diagonal. If no resolution is declared,
-0.000001 mm supplies the source-resolution fallback. The bound uses the
-geometry being repaired, not the entire assembly, its distance from the
-origin, or the size of an untrimmed supporting surface. Initial pullback
-fitting still starts at source accuracy, and repairs exceeding the
-source-based allowance are flagged in the output and report.
-The default best-effort mode retries otherwise omitted bounded or trimmed
-faces individually. It first reconstructs parameter boundaries from the
-authored model curves, then tries adaptive parameter endpoint corrections
-if reconstruction fails. The adaptive pass can exceed the initial relative
-allowance while retaining the original model curves and supporting surface.
-It does not enlarge the tolerance used to stitch neighboring faces.
-Recovered faces must still pass OpenNURBS validity checks and periodic-domain
-checks. Their database objects carry *iges.import_status=needs_review* and
-*iges.recovery* attributes; adaptive repairs also record their tolerance.
-Warnings and the JSON report identify the source faces and recovery methods.
-Validity does not certify agreement between inconsistent source descriptions
-or make an open sheet a closed solid.
-Recovered periodic trims are placed inside closed NURBS surface domains;
-boundaries requiring unsupported seam splits are rejected.
-
-After face recovery, retained bounded and trimmed faces are reassembled within
-their original source ownership groups, at the unchanged stitching tolerance.
-Closed connected components are oriented and recognized independently of
-unrelated open sheets. Closed shells with overlapping bounding boxes remain
-together, preserving possible cavity relationships and their relative
-orientation; the importer does not infer containment or force every shell
-outward. Disconnected open sheets are written as individual B-Reps beneath
-an uncolored, non-region combination retaining the aggregate's name and source
-hierarchy references. Connected faces stay together rather than each becoming
-a separate B-Rep. Children have stable source-based names, and a uniformly colored
-sheet receives its own display color. Different colors within a connected
-sheet remain in per-face metadata; color boundaries do not split geometry.
-Plate thickness applies only to non-solid output. If reassembly or sheet
-extraction fails validation, the previously validated geometry is retained.
-Explicit manifold solids, including incomplete solids retained as invalid
-B-Reps, and void-shell relationships are not split into sheet combinations.
-Per-face metadata retains source IDs and recovery methods after regrouping.
-An object containing different recovery methods or tolerance bases records
-*mixed* in the corresponding object-level attribute.
-
-Safe and best-effort import normalize trimmed-face parameter loops before
-assembly: outer loops run counterclockwise and inner loops clockwise in
-OpenNURBS parameter space. The surface geometry and its natural normal are
-unchanged. Normalizations are diagnosed and counted in the report. This avoids
-propagating incorrect face senses from otherwise valid clockwise outer loops.
-
-These modes also check closed-shell orientation using bounded
-numerical integration directly over the trimmed surfaces. Isolated, closed,
-orientable shells are made outward-facing when the signed-volume estimate is
-well separated from zero and the oriented surface area cancels. This can
-reverse an entire inward shell or correct inconsistent face senses. Corrections
-are reported and recorded in *iges.orientation_faces_reversed*, without changing
-surface geometry or face provenance. *--exact* and *--repair none* leave the
-original face senses unchanged; *--strict* rejects a required correction.
-
-Open, invalid, non-orientable, nearly zero-volume, and numerically inconclusive
-shells are left unchanged. Shells with overlapping boxes are also left unchanged:
-an inward shell inside another may be a legitimate cavity. Box containment is
-reported only as *possible_cavity*, not proof of containment. This diagnostic
-does not certify absence of self-intersections or validate Boolean assemblies.
-It does not depend on the cached OpenNURBS solid-orientation flag, tessellation,
-or ray-tracing acceleration structures.
-
-For legacy bounded planes, safe repair can resolve an opposite plane-constant
-sign when all sampled boundary points support that interpretation within the
-nominal tolerance; the repair is reported without moving the boundary curves.
-
-Default imports may be partial. The conversion summary counts omitted source
-geometry entities, and *--report* identifies their failures. Use *--strict*
-when omissions or repairs must cause the import to fail.
-
-Long conversions print a progress message about every five seconds, including
-elapsed time, the current stage and operation, and the source entity where
-available. Geometry counts include processed source items, both retained and
-omitted; retries do not advance the count again. These counts are not an
-estimate of elapsed work or remaining time. Reporting continues during lengthy
-individual geometry operations. Short conversions do not incur a reporting
-delay.
-
-An explicit type 186 manifold solid that cannot be reconstructed is retained
-by default as one invalid-solid BRep, containing its independently validated
-faces. An empty BRep preserves the identity when no faces can be rebuilt.
-The *iges.shell_metadata* attribute records outer and void shells, source
-face IDs, orientations, and which faces were retained. Such objects carry
-*iges.import_status=invalid_solid* and *_brep_invalid_solid=1*. They are not
-treated as plate-mode sheets, and validity checking and ray-tracing preparation
-reject them. Repair the intended solid topology before clearing the marker.
-Strict, exact, and polygonal output modes reject these incomplete solids.
-
-The *-3*/*-d* drawing options and the *-n*/*-t* compatibility surface options
-are mutually exclusive. Both surface options use the direct B-Rep importer
-and retain native CSG members and their hierarchy. The output database may
-follow the input filename, as in *iges-g input.igs output.g*. The *-o* option
-overrides a positional output filename. Diagnostics identify unsupported or omitted geometry. To export
-geometry in the other direction, see *g-iges*(1).
+The *-3*/*-d*, *-n*, and *-t* options are mutually exclusive and select
+alternate conversion modes (drawings, B-spline surfaces, or trimmed surfaces,
+respectively). The *-o* output option is required. When the chosen mode cannot
+represent something present in the file, *iges-g* prints suggestions for the
+options that would convert the remaining entities. To export geometry in the
+other direction, see *g-iges*(1).

 [[options]]
 == OPTIONS

 *-3*::
-  Preserve drawing model-space planes instead of projecting them to XY.
+  Convert IGES drawings to BRL-CAD NMG objects without the final projection
+  into 2D, preserving 3D drawings produced from a 3D model. Solid model
+  entities are ignored.

 *-d*::
-  Convert IGES drawings to native BRL-CAD sketch and annotation objects,
-  preserving text, leaders, grouping, and style metadata when possible.
-
-*--legacy-drawings*::
-  Request NMG wire geometry for supported drawing curves. This compatibility
-  option uses the C++ document reader; it does not select a separate parser.
-  Use with *-d* or *-3* to select drawing import explicitly.
+  Convert IGES drawings to BRL-CAD NMG objects (projected to 2D). Solid model
+  entities are ignored.

 *-n*::
-  Import supported surfaces directly as OpenNURBS BReps, as in the default
-  mode. Native CSG members and their assembly placements are also retained.
+  Combine all rational B-spline surfaces in the IGES file into a single
+  BRL-CAD spline solid.

 *-t*::
-  Import supported trimmed surfaces directly as OpenNURBS BReps, as in the
-  default mode, retaining native CSG members and assembly placements. Shared
-  topology is assembled without using NMG.
+  Convert all trimmed surfaces in the IGES file into a single BRL-CAD NMG
+  trimmed-NURBS solid.

 *-p*::
-  Write BREP objects as polygonal NMG solids instead of native BRep objects.
-
-*-m*::
-  Write BREP objects as triangulated BOT solids instead of native BRep objects.
-
-*--exact*::
-  Disallow source-data repairs during direct geometry or annotation import.
-
-*--strict*::
-  Reject repaired or partial direct imports.
-
-*--repair* _none|safe|best-effort_::
-  Select no repairs, bounded structural repairs, or bounded repairs followed
-  by isolated face recovery. The default is _best-effort_. Use _safe_ to
-  disable the last-resort boundary reconstruction and adaptive endpoint pass.
-
-*--relative-tolerance* _fraction_::
-  Set the dimensionless local boundary repair allowance. The default 0.0001
-  is 0.01% of the boundary bounding-box diagonal: for example, 0.1 mm for a
-  1,000 mm diagonal. Zero disables the relative part of the initial allowance;
-  combine it with *--repair safe* for source-resolution-based bounded repairs.
-  In best-effort mode this is a repair target, not a final omission cutoff.
-  This does not change initial fitting accuracy or enable repairs under
-  *--exact*, *--strict*, or *--repair none*. It does not set the drawing-wire
-  sampling tolerance.
-
-*--max-repair-tolerance* _mm_::
-  Permit model-space boundary reconstruction and parameter-space trim-loop
-  endpoint repairs up to the given tolerance in millimeters. Relaxed faces
-  remain subject to OpenNURBS validity checks and are
-  flagged with their actual repair tolerance in the output database and JSON
-  report. This is not a guarantee that existing source boundary-to-surface
-  discrepancies are below that value. This option requires safe OpenNURBS
-  BRep output. A positive value overrides the object-relative allowance and
-  disables best-effort fallback; the existing source-based endpoint closure
-  allowance is retained.
-
-*--default-plate-thickness* _mm_::
-  Assign the given thickness to imported open BReps in plate mode. The default
-  zero thickness retains the authored sheet geometry.
-
-*--report* _file.json_::
-  Write structured parser and import diagnostics to a JSON file, including
-  valid and invalid solid counts, unreconstructed faces, unresolved hierarchy
-  members, native-solid and wire conversion counts, and post-recovery reassembly
-  counts, plus per-object shell orientation estimates and corrections.
-  An import producing no supported geometry fails in every mode.
-
-*--check-orientation* _database.g_::
-  Check an existing BRL-CAD database without importing or modifying geometry.
-  Only *--report* and debug options may accompany this mode. Each stored BRep
-  primitive is loaded once, in object coordinates; instance transformations,
-  Boolean operations, and non-BRep primitives are not evaluated. Memory use is
-  proportional to the largest BRep, not to a prepared scene. Progress is reported
-  approximately every five seconds, including the current object and face.
-  The optional JSON report lists shell orientation, possible cavity relationships,
-  repairable face counts and indices, signed-volume estimates in cubic millimeters, numerical
-  uncertainty, and evaluation counts. For inconsistent face senses, the volume
-  estimate refers to a provisionally consistent shell. A zero exit status means
-  the scan completed without read errors, not that all shells were outward or
-  valid. This mode never applies the proposed corrections.
+  Write BREP objects as NMG solids instead of the default BOT solids.

 *-o* _database.g_::
-  Specify the output BRL-CAD database file, overriding any positional output.
-  Required only when no output filename follows the input filename.
-  Conversion is staged beside the destination; a failed conversion leaves
-  an existing database untouched. The input, output, and report must identify
-  distinct files, including through symbolic links or hard links.
+  Specify the output BRL-CAD database file. This option is required.

 *-N* _solid_name_::
-  Name the output root combination. The default is *iges_geometry* for solid
-  and surface imports or *iges_drawing* for drawings, with a unique suffix if
-  needed. This option applies to all import modes.
+  Name the single solid created by the *-n* or *-t* option. If not given, the
+  default name "all" (or a unique variant) is used. Ignored for all other
+  modes.

 *-x* _rt_debug_flag_::
  Set the librt debug flag, given as a hexadecimal value. See _raytrace.h_ for
@@ -271,23 +82,22 @@ geometry in the other direction, see *g-iges*(1).
 ====
 [source,bash]
 ----
-iges-g widget.iges widget.g
+iges-g -o widget.g widget.iges
 mged widget.g 'tops'
 ----
-Convert the CSG and BREP entities of _widget.iges_ into
+Convert the CSG and planar-face BREP entities of _widget.iges_ into
 _widget.g_, then list the resulting top-level objects with *mged*(1) to verify
 the conversion.
 ====

-.Assemble trimmed surfaces into a BRep
+.Convert trimmed surfaces into a single named solid
 ====
 [source,bash]
 ----
-iges-g --strict --report boat-import.json -o boat.g boat.iges
+iges-g -t -N hull -o boat.g boat.iges
 ----
-Build the supported trimmed surfaces in _boat.iges_ directly as OpenNURBS
-faces, stitch coincident naked edges conservatively, and write diagnostics to
-_boat-import.json_.
+Collapse all trimmed surfaces in _boat.iges_ into one BRL-CAD NMG solid named
+"hull" inside _boat.g_, useful for surface models that have no CSG geometry.
 ====

 [[see_also]]
@@ -295,7 +105,7 @@ _boat-import.json_.

 *brlcad*(1), *g-iges*(1), *mged*(1)

-_The Initial Graphics Exchange Specification (IGES) Version 5.3_, US PRO/IPO, September 1996.
+_The Initial Graphics Exchange Specification (IGES) Version 5.1_, IGES/PDES Organization, September 1991.

 [[author]]
 == AUTHOR
@@ -1,177 +0,0 @@
-= MKBUILDING(1)
-:doctype: manpage
-:mansource: BRL-CAD
-:manmanual: BRL-CAD
-
-== NAME
-
-mkbuilding - generate parametric buildings and building parts
-
-== SYNOPSIS
-
-[source]
----
-mkbuilding [options] [output.g]
----
-
-== DESCRIPTION
-
-*mkbuilding* creates physically dimensioned BRL-CAD building geometry from
-archetype presets, a native JSON specification, OpenStreetMap (OSM) data, or
-OGC CityJSON 2.x data. Lengths are interpreted as metres unless the input
-schema declares another unit.
-
-The generated model separates walls, slabs and foundations, roofs, opening
-frames and panels, structural columns and beams, and installations into
-material-bearing regions. Exterior walls use Boolean subtraction for doors,
-windows, and unfilled openings. Floor slabs, closed roof solids, and
-structural members use the requested physical thicknesses and cross sections.
-Building parts are generated recursively.
-
-The native schema is JSON Schema draft 2020-12. It covers identity and
-classification; arbitrary or rectangular footprints; above- and below-ground
-storeys; skipped lower storeys; envelope dimensions and materials; roofs;
-doors, windows, and openings; column and beam grids; installations; nested
-building parts; OSM tags; CityGML attributes; and extension metadata. Print
-the schema with *--schema*. Example files are installed with the source under
-_src/shapes/building/examples_.
-
-OSM GeoJSON Feature and FeatureCollection inputs accept Polygon geometry and
-either direct OSM properties or a nested _tags_ object. Overpass JSON ways
-with inline _geometry_ are also accepted. All tags are retained as
-_osm::key_ database attributes. The Simple 3D Buildings tags for height,
-minimum height, storeys, minimum storey, material, colour, roof geometry, and
-building parts are interpreted. Documented _building=_ taxonomy values select
-an appropriate physical archetype; unknown values are retained and use a
-conservative house-like realization.
-
-CityJSON 2.x Building and BuildingPart objects are accepted. Classification,
-function, usage, roof type, measured height, storey counts and heights,
-children, transforms, extents, and referenced geometry bounds are mapped into
-the generator. Source attributes remain available as _cityjson::key_
-database attributes. CityJSON input is currently converted to a procedural
-building envelope derived from its bounds; its original boundary surfaces are
-not copied verbatim.
-
-== OPTIONS
-
-*-o* _file.g_, *--output* _file.g_::
-  Write the output database to _file.g_. The default is _mkbuilding.g_. A
-  single positional output filename is accepted for compatibility.
-
-*-s* _file.json_, *--spec* _file.json_::
-  Read a native JSON, OSM GeoJSON, Overpass JSON, or CityJSON specification.
-
-*-p* _name_, *--preset* _name_::
-  Start from _house_, _apartments_, _office_, _warehouse_, _church_, _barn_,
-  _garage_, _parking_, _greenhouse_, _sports_hall_, _silo_, _tower_, _civic_,
-  _carport_, _shed_, or _service_. An OSM _building=_ value may also be used.
-
-*-t* _value_, *--type* _value_::
-  Set the OSM-compatible building type stored on the generated object.
-
-*-n* _name_, *--name* _name_::
-  Set the top-level object name.
-
-*-L* _count_, *--levels* _count_::
-  Set the number of above-ground storeys.
-
-*-W* _metres_, *--width* _metres_::
-  Set the rectangular footprint width. Must be used with *--depth*.
-
-*-D* _metres_, *--depth* _metres_::
-  Set the rectangular footprint depth. Must be used with *--width*.
-
-*-H* _metres_, *--floor-height* _metres_::
-  Set a uniform floor-to-floor height.
-
-*-R* _shape_, *--roof-shape* _shape_::
-  Set an OSM-compatible _roof:shape_. Use *--list-roofs* to show the
-  implemented values.
-
-*--roof-height* _metres_::
-  Set roof height above the facade.
-
-*--wall-thickness* _metres_::
-  Set exterior wall thickness.
-
-*--structure* _system_::
-  Enable a structural column-and-beam grid and record its system name.
-
-*--no-auto-openings*::
-  Suppress automatically placed exterior doors and windows.
-
-*-f*, *--force*::
-  Replace an existing output database.
-
-*-j*, *--append*::
-  Append generated objects to an existing database.
-
-*--validate-only*::
-  Parse, normalize, and validate the input without writing geometry.
-
-*--effective-spec* _file.json_::
-  Write the fully resolved native specification after imports and command-line
-  overrides.
-
-*--demo-file* _file.g_::
-  Generate a catalog containing at least 50 distinct building types and a
-  nested building-part example. Generation fails if two catalog entries differ
-  only in classification or appearance but have identical shape and structure.
-
-*--schema*::
-  Print the native JSON Schema and exit.
-
-*--list-types*::
-  List the covered OSM building taxonomy and exit.
-
-*--list-roofs*::
-  List supported OSM roof shapes and exit.
-
-*-h*, *-?*, *--help*::
-  Print usage information and exit.
-
-== EXAMPLES
-
-.Generate a three-storey framed house
-====
-[source,bash]
----
-mkbuilding --preset house --levels 3 --structure wood_frame -o house.g
----
-====
-
-.Validate and generate an OSM GeoJSON building
-====
-[source,bash]
----
-mkbuilding --validate-only --spec building.geojson
-mkbuilding --spec building.geojson -o building.g
----
-====
-
-.Generate a broad taxonomy catalog
-====
-[source,bash]
----
-mkbuilding --demo-file buildings.g
----
-====
-
-== SEE ALSO
-
-*art*(1), *mged*(1), *rt*(1), *gqa*(1)
-
-== AUTHOR
-
-BRL-CAD Team
-
-== COPYRIGHT
-
-This software is Copyright (c) 2026 by the United States Government as
-represented by U.S. Army Research Laboratory.
-
-== BUG REPORTS
-
-Reports of bugs or problems should be submitted via electronic mail to
-devs@brlcad.org
@@ -132,10 +132,6 @@ Command to set the backout flag. With no option, prints the current value. When
 Sets the _useair_ member of the __rt_i__ structure to the integer _n_. If _n_ is 0, then *nirt* ignores any air in the geometry. If this command is invoked with no arguments, *nirt* prints the current value of _useair_. Default is 0.


-*useannot [* _n_*]*::
-Enables (_n_=1) or disables (_n_=0) diagnostic annotation intersections. When enabled, *nirt* evaluates all model-space annotations below the active database paths and invokes the *a* output action for each crossing. Screen-space annotations are not evaluated because an individual NIRT ray does not supply a pixel size or model-to-view transform. If this command is invoked with no arguments, *nirt* prints the current value. Default is 0.
-
-
 *overlap_claims [* _n_*]*::
 Specifies how to handle multiple regions' claims to segments of a ray. If _n_ is 0 or "resolve", then all overlaps are resolved in favor of a single region and any other claimants are ignored. If _n_ is 2 or "rebuild_all", then all overlaps are rebuilt, so any overlapping regions along the ray create individual (geometrically intersecting) partitions. If _n_ is 3 or "retain", then all overlaps are retained. In this case, the resulting partitions are always geometrically disjoint, each one is owned by a single region according to the current overlap resolution strategy, but every claimant is recorded. If _n_ is 1 or "rebuild_fastgen", then *nirt* takes on _FASTGEN_ behavior, so overlaps of plate-mode primitives are rebuilt, but other overlaps are retained. This command is useful with the __claimant_count__, __claimant_list__, and __claimant_listn__ output items. Default is "resolve".

@@ -201,11 +197,7 @@ Quits *nirt*.
 [[output_statements]]
 == OUTPUT STATEMENTS

-*nirt* allows the user a high degree of control, via the _fmt_ command, over what information gets printed out for each ray and in what format. There are eight types of output statements, each of which is executed under appropriate circumstances. The types and their use are:
-
-
-*a*::
-Annotation. Executed once for each model-space annotation crossing when *useannot* is enabled. Crossings are reported in ray-distance order after the ordinary solid shotline output. The default format is empty.
+*nirt* allows the user a high degree of control, via the _fmt_ command, over what information gets printed out for each ray and in what format. There are six types of output statements, each of which is executed under appropriate circumstances. The types and their use are:


 *r*::
@@ -286,41 +278,6 @@ azimuth of view (i.e., of ray direction).
 elevation of view (i.e., of ray direction).


-Annotation Information
-
-
-*annot_path*::
-full database path of the annotation primitive.
-
-
-*annot_segment*::
-zero-based annotation segment index.
-
-
-*annot_role*::
-semantic role of the annotation segment, such as `text`, `leader`, `dimension`, or `arrowhead`.
-
-
-*annot_x*::
-_x_ coordinate of the annotation hit point.
-
-
-*annot_y*::
-_y_ coordinate of the annotation hit point.
-
-
-*annot_z*::
-_z_ coordinate of the annotation hit point.
-
-
-*annot_d*::
-_d_ grid-plane coordinate of the annotation hit point.
-
-
-*annot_visible*::
-1 if no non-air solid surface is closer to the ray origin, otherwise 0. Occluded annotation crossings are still reported so they can be inspected during debugging.
-
-

 Partition Information

@@ -564,15 +521,6 @@ nirt -A material_id -A los_density model.g all
 Each region the ray passes through is reported together with its _material_id_ and _los_density_ attribute values via the *attributes* output item, which is useful for vulnerability and mass-properties analyses.
 ====

-.Reporting annotation crossings for debugging
-====
-[source,bash]
----
-nirt -s -e 'useannot 1;fmt a "%s %d (%g %g %g) visible=%d\n" annot_path annot_segment annot_x annot_y annot_z annot_visible;s' model.g component dimensions
----
-This opt-in format reports every model-space annotation crossing and whether it is in front of the first solid surface. Ordinary NIRT output is unchanged unless *useannot* is enabled and an *a* format is supplied.
-====
-

 [[hints]]
 == HINTS
@@ -36,7 +36,7 @@ To go the other direction (save a framebuffer image to a *pix*(5) file), use *fb
  Clear the framebuffer before displaying. By default the new image overwrites whatever is already on screen without clearing.

 *-z*::
-  Zoom and center the image to fill the display, using integer zoom factors via the framebuffer library's fb_view() routine.
+  Zoom and center the image to fill the display, using integer zoom factors via the libfb fb_view() routine.

 *-1*::
  Force one scanline per write using *fb_write*(3). This is the default and overrides *-m*.
@@ -105,7 +105,7 @@ Displays a 512x512 image and keeps the framebuffer open for 5 seconds before clo
 [[see_also]]
 == SEE ALSO

-*brlcad*(1), *fb-pix*(1), *png-fb*(1), *rt*(1), *pix*(5)
+*brlcad*(1), *fb-pix*(1), *png-fb*(1), *rt*(1), *libfb*(3), *pix*(5)

 [[author]]
 == AUTHOR
@@ -29,7 +29,7 @@ The image is selected either by name with *-f* or by byte count with
 *-l*; exactly one of the two must be given (specifying both is an
 error). The number of bytes per sample (pixel) defaults to 3, which is
 correct for *pix*(5) files; use *-b* `1` for *bw*(5) files and
-*-b* `24` for *dpix*(5) files (three channels of 8-byte double samples).
+*-b* `24` for dpix files (three channels of 8-byte double samples).

 If no standard size matches, a diagnostic is printed to standard error,
 `WIDTH=0; HEIGHT=0` is printed to standard output, and a non-zero exit
@@ -82,7 +82,7 @@ with `pixautosize -b 3 -l 7500`.
 [[see_also]]
 == SEE ALSO

-*brlcad*(1), *pix-fb*(1), *bw*(5), *dpix*(5), *pix*(5), *sh*(1)
+*brlcad*(1), *pix-fb*(1), *bw*(5), *pix*(5), *sh*(1)

 [[author]]
 == AUTHOR
@@ -122,7 +122,7 @@ them as shell variables for further processing.
 [[see_also]]
 == SEE ALSO

-*brlcad*(1), *fb-png*(1), *rt*(1), *pix-fb*(1), *pix*(5)
+*brlcad*(1), *fb-png*(1), *rt*(1), *pix-fb*(1), *libfb*(3), *pix*(5)


 [[author]]
@@ -109,7 +109,7 @@ are:
  _file.N_. With no *-o* and no *-F*, frames go to temporary files.

 *-F* _framebuffer_::
-  Send pixels to the named framebuffer.
+  Send pixels to the named framebuffer (see *libfb*(3)).

 *-M*::
  Read a model2view matrix and animation script from standard input,
@@ -202,7 +202,7 @@ the distributed-computation machinery.
 == SEE ALSO

 *brlcad*(1), *rt*(1), *rtsrv*(1), *mged*(1), *fbserv*(1),
-*fb-png*(1), *ssh*(1), *libpkg*(3), *librt*(3), *pix*(5)
+*fb-png*(1), *ssh*(1), *libfb*(3), *libpkg*(3), *librt*(3), *pix*(5)

 M. Muuss, "Workstations, Networking, Distributed Graphics, and Parallel
 Processing", in "Computer Graphics Techniques: Theory and Practice", ed:
@@ -56,12 +56,8 @@ The following options are recognized:
 selects auto-sizing, and gives the view azimuth in degrees. Used with *-e* and conflicts with *-M* .


-*-b #*, *-b "# #"*, *--single-pixel #*, *--single-pixel "# #"*::
-is sometimes useful for debugging. A single ray is fired at the specified
-linear pixel index or X and Y pixel coordinates. This is best when
-accompanied by debugging options. Because *getopt*(3) only allows one option
-parameter, coordinate pairs must be enclosed in double quotes. This option
-must follow any viewing parameters.
+*-b "# #"*, *--single-pixel # #*::
+is sometimes useful for debugging. A single ray is fired at the pixel coordinates specified. This is best when accompanied by debugging options. Note that the standard *getopt*(3) routine only allows options to have one parameter, so the X and Y pixel coordinates need to be combined into one string parameter by enclosing them in double quotes. This option must follow any viewing parameters.


 *-c "script_command"*, *--command "script_command"*::
@@ -193,7 +189,7 @@ sets the distance from the eye point to the center of the model RPP; default is


 *-F framebuffer*, *--framebuffer*::
-indicates that the output should be sent to the indicated framebuffer. For remote framebuffer access, this may be a TCP-style specification (for example, _host:port_ or _port_) or an IPC address using the form *ipc:*_addr_. See *brlcad*(1) for more details on framebuffer naming.
+indicates that the output should be sent to the indicated framebuffer. For remote framebuffer access, this may be a TCP-style specification (for example, _host:port_ or _port_) or an IPC address using the form *ipc:*_addr_. See *libfb*(3) for more details on framebuffer naming.

 When using *fbserv* authentication, set *FBSERV_TOKEN* in the *rt* environment to the same token value used by the server. To request TLS for remote framebuffer connections (OpenSSL builds), set *FBSERV_TLS* to a non-empty value.

@@ -223,7 +219,7 @@ sets the NMG_debug flags to the given hexadecimalbit vector. See h/nmg.h for the


 *-O output.dpix*, *--output-double output.dpix*::
-specifies the name of a file in which to store a double-precision floating-point version of the image in *dpix*(5) format. *dpix-pix*(1) can be used to later convert the file to *pix*(5) format output.
+specifies the name of a file in which to store a double-precision floating-point version of the image. *dpix-pix*(1) can be used to later convert the file to *pix*(5) format output.


 *-P #*, *--cpus #*::
@@ -348,7 +344,7 @@ Renders with 8 hypersamples each averaging 512 ambient-occlusion samples (a brut
 [[see_also]]
 == SEE ALSO

-*brlcad*(1), *mged*(1), *pix-fb*(1), *png-fb*(1), *librt*(3), *dpix*(5), *pix*(5)
+*brlcad*(1), *mged*(1), *pix-fb*(1), *png-fb*(1), *librt*(3), *pix*(5)


 [[diagnostics]]
@@ -61,7 +61,7 @@ sets (see ADDITIONAL OPTIONS and OCCLUSION CHECKING).

 *-F* _framebuffer_::
  Send output to the named framebuffer. Required (instead of *-o*) for overlay
-  and occlusion renderings.
+  and occlusion renderings. See *libfb*(3).

 *-s* _#_::
  Square grid size: fire _#_ rays in X and Y (default 512, i.e. 512x512).
@@ -175,11 +175,10 @@ sets (see ADDITIONAL OPTIONS and OCCLUSION CHECKING).
 *-K* _#_::
  Ending (kill-after) frame number for animation scripts; pair with *-D*.

-*-b* _index|"x y"_::
-  Fire a single debug ray at a linear pixel index or at pixel (x, y), and
-  force serial execution. Coordinate pairs must be combined into one quoted
-  argument. Best used with debugging options, and must follow any viewing
-  parameters.
+*-b* _"x y"_::
+  Fire a single debug ray at pixel (x, y) and force serial execution. The X
+  and Y coordinates must be combined into one quoted argument. Best used with
+  debugging options, and must follow any viewing parameters.

 *-Q* _x,y_::
  Compute the full image but enable debug flags only for the pixel (x, y).
@@ -381,7 +380,7 @@ required for overlay and occlusion modes.
 == SEE ALSO

 *brlcad*(1), *rt*(1), *mged*(1), *pix-fb*(1), *dpix-pix*(1), *fbserv*(1),
-*pix*(5), *librt*(3)
+*pix*(5), *librt*(3), *libfb*(3)

 [[author]]
 == AUTHOR
@@ -1,70 +0,0 @@
-= WALK_EXAMPLE(1)
-:doctype: manpage
-:mansource: BRL-CAD
-:manmanual: BRL-CAD
-
-== NAME
-walk_example - example of traversing a BRL-CAD database hierarchy
-
-== SYNOPSIS
-
-[source]
----
-walk_example [-h] [-d hexflags] input.g object ...
----
-
-
-[[description]]
-== DESCRIPTION
-
-*walk_example* is a sample application that demonstrates how to traverse a
-portion of a BRL-CAD geometry database using the *librt*(3) function
-`db_walk_tree()`. It builds a directory index for the database _input.g_
-and then walks the directed acyclic graph rooted at each named _object_
-(tree top), invoking callback routines as regions, the ends of regions,
-and leaf primitives are encountered.
-
-The program itself performs no useful work beyond illustrating the
-traversal mechanism; the leaf callback contains stub cases showing where
-per-primitive processing (for example of BOT and ARB8 primitives) would
-be added. It is intended as a starting point for writing custom database
-parsers and analysis tools.
-
-At least one _object_ name must be supplied in addition to the database
-file.
-
-
-[[options]]
-== OPTIONS
-
-*-h*::
-  Print a usage message and exit.
-
-*-d hexflags*::
-  Set the internal debug flags to the given hexadecimal value. When the
-  name-printing bit is set, the name of each region and leaf is echoed as
-  it is visited during the traversal.
-
-
-[[see_also]]
-== SEE ALSO
-
-*brlcad*(1), *mged*(1), *librt*(3)
-
-
-[[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
@@ -1,54 +1,36 @@
 set(
  man3_EN
-  libanalyze.adoc
-  libbg.adoc
-  libbn.adoc
-  libbrep.adoc
-  libbu.adoc
  libbv.adoc
-  libdm.adoc
-  libfft.adoc
-  libgcv.adoc
-  libged.adoc
  libicv.adoc
-  libnmg.adoc
-  liboptical.adoc
-  libpc.adoc
  libpkg.adoc
-  libqtcad.adoc
  librt.adoc
-  libtclcad.adoc
-  libtermio.adoc
  libwdb.adoc
 )

-# Libraries that ship as headers/sources without a standalone linkable
-# target but still have reference man pages we want to publish.
-set(man3_NOTARGET libpc libtermio)
-
 foreach(mp ${man3_EN})
  get_filename_component(tname ${mp} NAME_WE)

  # BRLCAD_ADDLIB doesn't take care of the man pages currently - most of our
  # libs don't have one at the moment - so do it here if we have the associated
-  # target (or if the library is documented but intentionally has no target).
-  list(FIND man3_NOTARGET "${tname}" tname_notarget)
-  if((TARGET ${tname} OR NOT tname_notarget EQUAL -1) AND BRLCAD_EXTRADOCS)
+  # target.
+  if(TARGET ${tname} AND BRLCAD_EXTRADOCS)
    add_asciidoc("MAN3" ${mp} man3 "")
-  endif()
+  endif(TARGET ${tname} AND BRLCAD_EXTRADOCS)

  # Warn if we've got a man page but no target, unless we're doing a partial
  # build (if the build is partial it's expected that some of the man pages
-  # will be disabled) or the library intentionally has no target.
+  # will be disabled)
  if(NOT BRLCAD_COMPONENTS)
-    if(NOT TARGET ${tname} AND tname_notarget EQUAL -1)
+    if(NOT TARGET ${tname})
      message("Warning: man3 man page ${tname} has no associated build target")
-    endif()
+    endif(NOT TARGET ${tname})
  endif(NOT BRLCAD_COMPONENTS)
 endforeach(mp ${man3_EN})

 cmakefiles(
  ${man3_EN}
+  libbu.adoc
+  libdm.adoc
  TODO
  CMakeLists.txt
 )
@@ -1,10 +1,5 @@
-The libbu and libdm man pages were originally DocBook conversions of
-files from elsewhere in the documentation.  They have since been
-rewritten as proper man3 overview pages and are now built alongside the
-other man3 pages.
-
-libpc and libtermio have man3 overview pages here but are not currently
-built as standalone libraries with their own CMake targets (libtermio is
-header-only; libpc has no addlib target unless GECODE support is
-enabled).  Their pages are therefore tracked but only built once an
-associated library target exists.
+The libbu and libdm files here are docbook conversions of files
+from elsewhere in the documentation.  They aren't yet proper
+man pages, and they need to be reviewed to see if the information
+they contain is still accurate.  Until then, they are present
+but not built.
@@ -1,63 +0,0 @@
-= LIBANALYZE(3)
-:doctype: manpage
-:mansource: BRL-CAD
-:manmanual: BRL-CAD
-
-== NAME
-libanalyze - geometry analysis library for BRL-CAD
-
-== SYNOPSIS
-
-[source,c]
----
-#include <analyze.h>
----
-
-Link with *-lanalyze*.
-
-The public interface is organized across the headers included by
-_analyze.h_, including _analyze/diff.h_, _analyze/density.h_,
-_analyze/grid.h_, _analyze/heal.h_, _analyze/info.h_, _analyze/pnts.h_,
-_analyze/polygonize.h_, _analyze/nirt.h_, _analyze/voxelize.h_, and
-_analyze/worker.h_.
-
-== DESCRIPTION
-
-LIBANALYZE provides higher-level geometry analysis routines for BRL-CAD
-models. Unlike the lower-level geometry library (libbg), the algorithms
-in this library operate on the BRL-CAD constructive solid geometry (CSG)
-boolean hierarchy and generally rely on solid ray tracing through librt
-to gather the information they need.
-
-Facilities provided by the library include model differencing, material
-density and mass property analysis, ray-based gridding and sampling,
-geometry healing, model information queries, point-cloud generation and
-processing, polygonization and voxelization of geometry, and the
-interactive ray-tracing engine used by the *nirt*(1) command. A parallel
-worker interface supports distributing analysis work across multiple
-threads.
-
-Because these routines build on librt, applications using LIBANALYZE must
-first prepare a ray-tracing instance (see *librt*(3)). The complete API,
-including data structures and function signatures, is documented in the
-headers noted above and in the Doxygen-generated reference for the
-LIBANALYZE module.
-
-== SEE ALSO
-
-*brlcad*(1), *nirt*(1), *librt*(3), *libbg*(3), *libbn*(3), *libbu*(3)
-
-The BRL-CAD Doxygen API reference provides the authoritative,
-up-to-date description of all public LIBANALYZE routines.
-
-== AUTHOR
-
-BRL-CAD Team
-
-== COPYRIGHT
-
-This software is Copyright (c) 2008-2026 United States Government as represented by the U.S. Army Research Laboratory.
-
-== BUG REPORTS
-
-Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org
@@ -1,61 +0,0 @@
-= LIBBG(3)
-:doctype: manpage
-:mansource: BRL-CAD
-:manmanual: BRL-CAD
-
-== NAME
-libbg - geometry algorithms library for BRL-CAD
-
-== SYNOPSIS
-
-[source,c]
----
-#include <bg.h>
----
-
-Link with *-lbg*.
-
-The public interface is organized across the headers included by
-_bg.h_, including _bg/chull.h_, _bg/clip.h_, _bg/lseg.h_, _bg/obr.h_,
-_bg/plane.h_, _bg/polygon.h_, _bg/sat.h_, _bg/spsr.h_, _bg/tri_pt.h_,
-_bg/tri_ray.h_, _bg/tri_tri.h_, and _bg/trimesh.h_.
-
-== DESCRIPTION
-
-LIBBG is BRL-CAD's geometry library, intended for generic computational
-geometry algorithms. Typical operations include point-in-polygon testing,
-line/sphere and triangle intersection tests, convex hull computation,
-oriented bounding box fitting, polygon triangulation (for example, ear
-clipping), surface reconstruction, and triangle mesh processing.
-
-The library occupies a deliberate layer in the BRL-CAD stack. Algorithms
-in LIBBG do not require solid ray tracing of the BRL-CAD constructive
-solid geometry (CSG) boolean hierarchy; routines that need those
-high-level constructs belong in libanalyze instead, which uses librt to
-perform the necessary ray tracing. LIBBG is lower level and depends only
-on the numerics library (libbn) and the utility library (libbu). Strictly
-numerical algorithms that do not involve three-dimensional geometry
-concepts belong in libbn rather than here.
-
-The complete API, including data structures and function signatures, is
-documented in the headers noted above and in the Doxygen-generated
-reference for the LIBBG module.
-
-== SEE ALSO
-
-*brlcad*(1), *libbn*(3), *libbu*(3), *libanalyze*(3), *librt*(3)
-
-The BRL-CAD Doxygen API reference provides the authoritative,
-up-to-date description of all public LIBBG routines.
-
-== AUTHOR
-
-BRL-CAD Team
-
-== COPYRIGHT
-
-This software is Copyright (c) 2015-2026 United States Government as represented by the U.S. Army Research Laboratory.
-
-== BUG REPORTS
-
-Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org
@@ -1,62 +0,0 @@
-= LIBBN(3)
-:doctype: manpage
-:mansource: BRL-CAD
-:manmanual: BRL-CAD
-
-== NAME
-libbn - numerical computation library for BRL-CAD
-
-== SYNOPSIS
-
-[source,c]
----
-#include <bn.h>
----
-
-Link with *-lbn*.
-
-The public interface is organized across the headers included by
-_bn.h_, including _bn/tol.h_, _bn/anim.h_, _bn/complex.h_, _bn/mat.h_,
-_bn/msr.h_, _bn/noise.h_, _bn/poly.h_, _bn/multipoly.h_, _bn/qmath.h_,
-_bn/rand.h_, _bn/randmt.h_, _bn/wavelet.h_, _bn/sobol.h_, _bn/str.h_,
-_bn/ulp.h_, and _bn/tabdata.h_.
-
-== DESCRIPTION
-
-LIBBN is BRL-CAD's numerical computation library. It provides a broad
-assortment of numerical algorithms and computational routines, including
-pseudorandom number generation, vector and matrix math, quaternion math,
-complex arithmetic, polynomial synthetic division and root finding,
-noise generation, wavelet transforms, quasi-random (Sobol) sequences,
-tabulated data handling, and floating-point tolerance and unit-in-the-last
-place utilities.
-
-LIBBN sits above the utility library (libbu) and supplies the numerical
-foundation used throughout the rest of the BRL-CAD libraries. Strictly
-numerical algorithms that do not involve three-dimensional geometry
-concepts belong here, whereas generic geometry algorithms belong in
-libbg. Many core vector and matrix macros used by LIBBN are declared in
-_vmath.h_.
-
-The complete API, including data structures and function signatures, is
-documented in the headers noted above and in the Doxygen-generated
-reference for the LIBBN module.
-
-== SEE ALSO
-
-*brlcad*(1), *libbu*(3), *libbg*(3), *librt*(3)
-
-The BRL-CAD Doxygen API reference provides the authoritative,
-up-to-date description of all public LIBBN routines.
-
-== AUTHOR
-
-BRL-CAD Team
-
-== COPYRIGHT
-
-This software is Copyright (c) 2004-2026 United States Government as represented by the U.S. Army Research Laboratory.
-
-== BUG REPORTS
-
-Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org
@@ -1,61 +0,0 @@
-= LIBBREP(3)
-:doctype: manpage
-:mansource: BRL-CAD
-:manmanual: BRL-CAD
-
-== NAME
-libbrep - boundary representation (NURBS) library for BRL-CAD
-
-== SYNOPSIS
-
-[source,c]
----
-#include <brep.h>
----
-
-Link with *-lbrep*.
-
-The public interface is organized across the headers included by
-_brep.h_, including _brep/defines.h_, _brep/util.h_, _brep/ray.h_,
-_brep/curvetree.h_, _brep/surfacetree.h_, _brep/edit.h_,
-_brep/pullback.h_, _brep/quality.h_, _brep/intersect.h_,
-_brep/boolean.h_, _brep/cdt.h_, and _brep/csg.h_.
-
-== DESCRIPTION
-
-LIBBREP provides BRL-CAD's boundary representation (B-rep) support,
-defining surface and curve structures for Non-Uniform Rational B-Spline
-(NURBS) curves and surfaces. The library builds upon the openNURBS
-library for its underlying geometric representation.
-
-Facilities provided by the library include acceleration structures for
-curves and surfaces (curve trees, surface trees, and bounding-box
-nodes), ray/B-rep intersection, curve/surface intersection, pullback of
-three-dimensional points into surface parameter space, boolean
-evaluation of B-rep solids, constrained Delaunay triangulation (CDT) for
-tessellation, B-rep quality assessment, editing operations, and
-conversion between B-rep and constructive solid geometry (CSG)
-representations.
-
-The complete API, including data structures and function signatures, is
-documented in the headers noted above and in the Doxygen-generated
-reference for the LIBBREP module.
-
-== SEE ALSO
-
-*brlcad*(1), *librt*(3), *libnmg*(3), *libbn*(3), *libbu*(3)
-
-The BRL-CAD Doxygen API reference provides the authoritative,
-up-to-date description of all public LIBBREP routines.
-
-== AUTHOR
-
-BRL-CAD Team
-
-== COPYRIGHT
-
-This software is Copyright (c) 2007-2026 United States Government as represented by the U.S. Army Research Laboratory.
-
-== BUG REPORTS
-
-Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org
@@ -1,70 +1,84 @@
-= LIBBU(3)
-:doctype: manpage
-:mansource: BRL-CAD
-:manmanual: BRL-CAD
+= Command History Object Documentation
+Mark L. Ulferts <mulferts@austin.dsccc.com>; Glenn Durfee
+:doctype: book
+:toc:
+:toclevels: 3
+
+== 
+
+=== Name
+
+ch_open - create and manipulate a command history object.
+
+
+=== SYNOPSIS
+
+__ch_open__[_chName_]
+
+
+=== DESCRIPTION
+
+The *ch_open* command creates a new command history object (given by the _chName_ argument). The *ch_open* command returns its _chName_ argument. At the time this command is invoked, there must not exist a command history object named _chName_.
+
+
+=== METHODS
+
+The *ch_open* command creates a new Tcl command whose name is _chName_. This command may be used to invoke various operations on the command history object. It has the following general form:
+
+_chName option ?arg arg ...?_
+
+_Option_ and the _args_ determine the exact behavior of the command. The following commands are possible for command history objects:
+
+_chName_ *add command_string _chName_ *addM* command_string*
+
+Add a command to the history and reset the current command pointer.
+
+_chName_ *curr*
+
+Return the current command in the history.
+
+_chName_ *history*
+
+Return the entire history.
+
+_chName_ *next*
+
+Return the next command in the history making that the current command.
+
+_chName_ *prev*
+
+Return the previous command in the history making that the current command.
+
+
+=== EXAMPLE
+
+The following sequence creates a command history object, adds commands and traverses the history.
+

-== NAME
-libbu - BRL-CAD utility library

-== SYNOPSIS

-[source,c]
----
-#include <bu.h>
 ----

-Link with *-lbu*.
-
-The public interface is organized across the headers included by
-_bu.h_, including _bu/app.h_, _bu/avs.h_, _bu/bitv.h_, _bu/cmd.h_,
-_bu/color.h_, _bu/list.h_, _bu/log.h_, _bu/malloc.h_, _bu/opt.h_,
-_bu/parallel.h_, _bu/ptbl.h_, _bu/str.h_, and _bu/vls.h_, among others.
-
-== DESCRIPTION
-
-LIBBU is BRL-CAD's utility library; the two letters "BU" stand for
-"BRL-CAD" and "Utility". It provides several layers of low-level utility
-routines that make cross-platform coding easier, serving as a general
-extension to the data types offered by the C language and to the basic C
-runtime provided by the system C library.
-
-Facilities provided by the library include parallel-processing support
-(threads, semaphores, and parallel-safe memory allocation), consolidated
-logging and error handling (_bu_log()_, _bu_exit()_, and _bu_bomb()_),
-dynamic memory management (_bu_malloc()_ and related routines),
-variable-length strings (_struct bu_vls_), linked lists, pointer and
-bit vectors, attribute/value sets, command dispatch, option parsing, and
-numerous string and path helpers. All routines in LIBBU are designed to
-be parallel-safe (thread-safe) to ease development for multiprocessor
-systems.
-
-By design, none of the routines in this library depend on data types
-defined in other BRL-CAD headers such as _vmath.h_; numerical routines
-that build on those types are found in libbn. All truly fatal errors
-detected by the library use _bu_bomb()_ to exit with a status of 12, and
-the LIBBU variants of system calls (for example _bu_malloc()_) do not
-return to the caller unless they succeed, sparing the programmer from
-constant NULL checks.
-
-The complete API, including data structures and function signatures, is
-documented in the headers noted above and in the Doxygen-generated
-reference for the LIBBU module.
-
-== SEE ALSO
-
-*brlcad*(1), *libbn*(3), *libbg*(3), *librt*(3)
-
-The BRL-CAD Doxygen API reference provides the authoritative,
-up-to-date description of all public LIBBU routines.
-
-== AUTHOR
-
-BRL-CAD Team
-
-== COPYRIGHT
-
-This software is Copyright (c) 2004-2026 United States Government as represented by the U.S. Army Research Laboratory.
-
-== BUG REPORTS
-
-Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org
+cwish> ch_open ch
+ch
+cwish> ch add "cmd1"
+cwish> ch add "cmd2"
+cwish> ch prev
+cmd2
+cwish> ch prev
+cmd1
+cwish> ch curr
+cmd1
+cwish> ch add "cmd3"
+cwish> ch prev
+cmd3
+cwish> ch prev
+cmd2
+cwish> ch next
+cmd3
+cwish> ch next
+cwish> ch history
+cmd1
+cmd2
+cmd3
+----
@@ -1,61 +1,914 @@
-= LIBDM(3)
-:doctype: manpage
-:mansource: BRL-CAD
-:manmanual: BRL-CAD
+= LIBDM
+Robert G. Parker <mulferts@austin.dsccc.com>
+:doctype: book
+:toc:
+:toclevels: 3

-== NAME
-libdm - display manager library for BRL-CAD
+== Preface
+
+LIBDM provides the <<api,API>> for accessing BrlCad's display managers. Display managers can be thought of as configurable drawing machines that grind away on generic drawing commands called vlists resulting in display manager specific drawing actions. Vlists are capable of specifying points, lines and polygons in 3D. Display managers are also capable of drawing 2D points, lines, and strings.
+
+The following DM (display manager) types are supported:
+
+
+
+.Key Frame
+[cols="2*"]
+|===
+|DM Type
+|Canvas Type
+
+|X
+|X window
+|ogl
+|mixed X/OpenGL window
+|ps
+|postscript file
+|plot
+|unix plot file
+|===
+
+
+
+
+== Application Programming Interface
+
+[[api]]
+=== LIBDM's Application Programming Interface
+
+_struct dm *_ *DM_OPEN* _( int dtype, int argc, char *argv[] )_
+
+__DM_OPEN__ creates a display manager of type _dtype_ and returns a pointer to its _dm_ structure. _argc_ and _argv_ are passed to <<dm_p,dm_processOptions>> for interpretation. __DM_NULL__ is returned if unable to acquire a display manager.
+
+
+
+
+----
+
+    int dtype;
+    int argc;
+    char *argv[];
+    struct dm *dmp;
+
+    /*
+     * Open a 512x512 X display manager window on the local
+     * display using my_default_bindings to set default key
+     * and mouse button bindings.
+     */
+    dtype = DM_TYPE_X;
+    argv[0] = "X_open";
+    argv[1] = "-i";
+    argv[2] = "my_default_bindings";
+    argv[3] = "-S";
+    argv[4] = "512";
+    argv[5] = "-d";
+    argv[6] = ":0";
+    argv[7] = (char *)NULL;
+    dmp = DM_OPEN(dtype, argc, argv);
+     
+----
+
+
+
+_int_ *DM_CLOSE* _( struct dm *dmp )_
+
+__DM_CLOSE__ closes the display manager indicated by _dmp_.
+
+
+
+
+----
+
+            /* open a display manager */
+    dmp = DM_OPEN(dtype, argc, argv);
+
+              .  .  .
+
+    /* close the display manager */
+    DM_CLOSE(dmp);
+  
+----
+
+
+
+_int_ *DM_DRAW_BEGIN*_( struct dm *dmp )_
+
+__DM_DRAW_BEGIN__ prepares the display manager indicated by _dmp_ for a round of drawing.
+
+
+
+
+----
+
+            /* begin another drawing sequence */
+    (void)DM_DRAW_BEGIN(dmp);
+  
+----
+
+
+
+_int_ *DM_DRAW_END* _( struct dm *dmp )_
+
+__DM_DRAW_END__ ends the drawing sequence for the display manager indicated by _dmp_. This should be called before the next call to __<<dm_draw_begin,DM_DRAW_BEGIN>>__ in order to see the results of the current drawing sequence.
+
+
+
+
+----
+
+          /* end the current drawing sequence */
+    (void)DM_DRAW_END(dmp);
+      
+----
+
+
+
+_int_ *DM_NORMAL* _( struct dm *dmp )_
+
+__DM_NORMAL__ restores the display manager indicated by _dmp_ to a normal mode of operation (i.e. not scaled, rotated, displaced, etc.).
+
+
+
+
+----
+
+            /* restore to normal mode */
+    (void)DM_NORMAL(dmp);
+        
+----
+
+
+
+_int_*DM_LOADMATRIX* __( struct dm *dmp, mat_t mat, int which_eye )__
+
+__DM_LOADMATRIX__ loads the display manager indicated by _dmp_ with a new transformation matrix. _mat_ indicates the matrix to be loaded. __which_eye__ denotes the eye the matrix applies to and can have a value of 0 to indicate non-stereo, a value of 1 to indicate the right eye, or a value of 2 to indicate the left eye.
+
+
+
+
+----
+
+              /* load the display manager with mat --- not using stereo */
+    (void)DM_LOADMATRIX(dmp, mat, 0);
+----
+
+
+
+_int_ *DM_DRAW_STRING_2D* __( struct dm *dmp, char *str, int x, int y, int size, int use_aspect )__
+
+__DM_DRAW_STRING_2D__ draws a string in the display manager window indicated by _dmp_. _str_ is a pointer to the string to be drawn. x and y indicate where to begin drawing the string and are expected to be in the range [-2048,2047]. The _size_ argument indicates the font size to use (currently used only by dm-ps). The expected values for _size_ are 0 for small, 1 for medium, 2 for large, and 3 for huge. __use_aspect__ indicates whether to use the aspect ratio to modify the starting point where the string will be drawn.
+
+
+
+
+----
+
+          /*
+     * - draw the string starting at the lower left corner
+     * - use the small font
+     * - don't use aspect ratio to modify string placement
+     */
+    (void)DM_DRAW_STRING_2D(dmp, "starting string at lower left", -2040, -2040, 0, 0)
+      
+----
+
+
+
+_int_ *DM_DRAW_LINE_2D* _( struct dm *dmp, int x1, int y1, int x2, int y2 )_
+
+__DM_DRAW_LINE_2D__ is used to draw two-dimensional lines in the display manager window indicated by _dmp. x1, y1, x2,_ and _y2_ indicate the coordinates for the line to be drawn.
+
+
+
+
+----
+
+          /* draw a line from the lower left corner of the window to the upper right corner */
+    (void)DM_DRAW_LINE_2D(dmp, -2048, -2048, 2047, 2047);
+  
+----
+
+
+
+_int_ *DM_DRAW_POINT_2D* _( struct dm *dmp, int x, int y )_
+
+__DM_DRAW_POINT_2D__ draws a point in the display manager window indicated by _dmp_. _x_ and _y_ indicate the coordinates for the point to be drawn.
+
+
+
+
+----
+
+          /* draw a yellow dot in the center of the window */
+    (void)DM_SET_FGCOLOR(dmp, 230, 230, 0, 1);
+    (void)DM_DRAW_POINT_2D(dmp, 0, 0);
+  
+----
+
+
+
+_int_ *DM_DRAW_VLIST* __( struct dm *dmp, struct rt_vlist *vp )__
+
+__DM_DRAW_VLIST__ takes the vlist pointer _vp_ and interprets it for drawing into the display manager window indicated by _dmp_ .
+
+
+
+
+----
+
+          /* draw the vlists pointed to by view_list_ptr */
+    (void)DM_DRAW_VLIST(dmp, view_list_ptr);
+    
+----
+
+
+
+_int_ *DM_SET_FGCOLOR* _( struct dm *dmp, short r, short g, short b, int strict )_
+
+__DM_SET_FGCOLOR__ sets the color for drawing in the display manager indicated by _dmp_. _r, g,_ and _b_ denote the color and have values in the range [0,255]. _Strict_ specifies to really use this color (i.e. don't allow ogl to do fancy things with the color when depth cueing).
+
+
+
+
+----
+
+          /* set the drawing color to red */
+    (void)DM_SET_FGCOLOR(dmp, 220, 0, 0, 1);
+    
+----
+
+
+
+_int_ *DM_SET_BGCOLOR* _( struct dm *dmp, short r, short g, short b )_
+
+__DM_SET_BGCOLOR__ sets the background color for the display manager indicated by _dmp. r, g,_ and _b_ denote the color and have values in the range [0,255].
+
+
+
+
+----
+
+          /* set the background color to red */
+    (void)DM_SET_BGCOLOR(dmp, 220, 0, 0);
+      
+----
+
+
+
+_int_ *DM_GET_BGCOLOR* __( struct dm *dmp, Tcl_Interp *interp )__
+
+__DM_SET_BGCOLOR__ gets the background color for the display manager indicated by _dmp_ and places the result in interp.
+
+
+
+
+----
+
+          /* get the background color */
+    return DM_GET_BGCOLOR(dmp, interp);
+  
+----
+
+
+
+_int_ *DM_SET_LINE_ATTR* _( struct dm *dmp, int width, int style )_
+
+__DM_SET_LINE_ATTR__ sets the display managers (i.e. dmp) line width to width and sets its line style to _style_ . Currently, there are only 2 valid values for _style: 0_ for solid lines and 1 for dashed lines.
+
+
+
+
+----
+
+          /* set the display manager up to draw fat dashed lines */
+    (void)DM_SET_LINE_ATTR(dmp, 10, 1);
+
+    
+----
+
+
+
+_int_ *DM_SET_WIN_BOUNDS* _( struct dm *dmp, int clip[6] )_
+
+__DM_SET_WIN_BOUNDS__ sets the view clipping planes for the display manager indicated by _dmp. clip_ is interpreted as follows: {XMIN, XMAX, YMIN, YMAX, ZMIN, ZMAX}
+
+
+
+
+----
+
+          int clip[6] = { -2048, 2047, -2048, 2047, -2048, 2047 };
+
+    /* set the display managers clipping planes */
+    (void)DM_SET_WIN_BOUNDS(dmp, clip);
+  
+----
+
+
+
+_int_ *DM_ENDDLIST* _( struct dm *dmp )_
+
+__DM_ENDDLIST__ ends the definition of the display list currently being defined for the display manager indicated by _dmp_.
+
+
+
+
+----
+
+          /* define display list 1 to draw objects */
+    (void)DM_BEGINDLIST(dmp, 1);
+
+    /* Put code to draw objects here */
+
+    (void)DM_ENDDLIST(dmp);
+    
+----
+
+
+
+_int_ *DM_DRAWDLIST* _( struct dm *dmp, unsigned int list )_
+
+__DM_DRAWDLIST__ draws the previously defined display list list in the display manager indicated by _dmp_.
+
+
+
+
+----
+
+          unsigned int i;
+
+    /* draw display lists 1 through 9 */
+    for (i = 1; i < 10; ++i)
+       (void)DM_DRAWDLIST(dmp, i);
+----
+
+
+
+_int_ *DM_FREEDLISTS* _( struct dm *dmp, unsigned int list, int range )_
+
+__DM_FREEDLISTS__ frees the display lists indicated by _list and range. list_ indicates the display list to start with and range indicates the number of display lists to be freed.
+
+
+
+
+----
+
+       /* free display lists 10 through 29 */
+    (void)DM_FREEDLISTS(dmp, 10, 20);
+      
+----
+
+
+
+
+=== LIBDM's Other Support Routines
+
+_int_ *dm_share_list* _( struct dm *dmp1, struct dm *dmp2 )_
+
+__dm_share_dlist__ provides a way to (un)share display lists. If dmp1 and dmp2 are not NULL, dmp1 will share its display lists with dmp2. If dmp2 is NULL, dmp1 will no longer share its display lists.
+
+_void_ *dm_fogHint* _( struct dm *dmp, int fastfog )_
+
+__dm_fogHint__ is used to give a hint to the display manager about whether to use an efficient fog calculation method or the most accurate. Note - this is currently only implemented by the ogl display manager.
+
+
+
+
+----
+
+              /* use the most efficient method for calculating fog */
+    dm_fogHint(dmp, 1);
+
+    /* use the most accurate method for calculating fog */
+    dm_fogHint(dmp, 0);
+
+        
+----
+
+
+
+_int_ *dm_limit* _( val )_
+
+__dm_limit__ takes an integer argument and returns zero if (NOISE <= val < = NOISE) where NOISE is the size of the dead spot around zero. If ( val < -NOISE ), the return value is _( val + NOISE )_. If _( NOISE < val ),_ the return value is _( val - NOISE )._
+
+
+
+
+----
+
+              /* The examples below assume that NOISE is 16 */
+
+    /* i = 0 */
+    i = dm_limit(16);
+
+    /* i = 1 */
+    i = dm_limit(17);
+
+    /* i = 0 */
+    i = dm_limit(-16);
+
+    /* i = -1 */
+    i = dm_limit(-17);
+  
+----
+
+
+
+_int_ *dm_unlimit* _( val )_
+
+__dm_unlimit__ takes an integer value and returns zero if _( val == 0 )._ If _( 0 < val ),_ the return value is _( NOISE + val ). If ( val < 0 ),_ the return value is _( -NOISE + val )._ In short, dm_unlimit puts NOISE back into val.
+
+
+
+
+----
+
+            /* i = 0 */
+    i = dm_unlimit(0);
+
+    /* i = 17 */
+    i = dm_unlimit(1);
+
+    /* i = -17 */
+    i = dm_unlimit(-1);
+      
+----
+
+
+
+__fastf_t__ *dm_wrap* _( val )_
+
+__dm_wrap__ wraps _val_ into the range [-1.0, 1.0].
+
+
+
+
+----
+
+              /* f = 0.9 */
+    f = dm_wrap(0.9);
+
+    /* f = -0.5 */
+    f = dm_wrap(1.5);
+
+    /* f = 0.0 */
+    f = dm_wrap(6.0);
+
+    /* f = 1.0 */
+    f = dm_wrap(7.0);
+
+    /* f = 0.5 */
+    f = dm_wrap(-1.5);
+
+    /* f = -1.0 */
+    f = dm_wrap(-5.0);
+
+        
+----
+
+
+
+_int_ *dm_processOptions*__(struct dm *dmp, struct bu_vls *vls, int argc, char *argv[])__
+
+__dm_processOptions__ is used primarily by LIBDM's display manager open routines to process options. The table below lists the available options. Note - the application would not typically call processOptions. The application would instead build the desired options into the argv list that is supplied to the call to DM_OPEN.
+
+
+
+.Key Frame
+[cols="2*"]
+|===
+|Options
+|Description
+
+|-d string
+|This option specifies where to draw the display manager. string is expected to be in the same form as the X DISPLAY environment variable.
+|-i init_script
+|This option specifies a Tcl script to use to initialize the display manager.
+|-N height
+|This option specifies the number of scanlines or height to make the display manager window.
+|-n name
+|This option specifies a name to use for the display manager.
+|-S size
+|This option specifies the display manager windows square size.
+|-s
+|This option turns on stereo mode and is currently only available with the ogl display manager.
+|-t 0|1
+|This option specifies whether the display manager window will be a top level window or an embedded window. A non-zero value indicates a top level window, while zero indicates an embedded window.
+|-W width
+|This option specifies the width in pixels of the display manager window.
+|===
+
+
+
+_void_ *dm_configureWindowShape* _( dmp )_
+
+__dm_configureWindowShape__ is used to update the internal state of a display manager after its window has been newly created or resized. This routine is typically called by an event handler.
+
+_void_ *dm_zbuffer* __( struct dm *dmp, zbuffer_on )__
+
+__dm_zbuffer__ is used to turn Z-buffering on/off. Note - zbuffering is only supported by the _ogl_ display manager.
+
+
+
+
+----
+
+              /* turn zbuffering on */
+    dm_zbuffer(dmp, 1);
+  
+----
+
+
+
+_void_ __dm_lighting__ __( struct dm *dmp, int lighting_on )__
+
+__dm_lighting__ is used to turn lighting on/off. Note - lighting is only supported by the ogl display manager.
+
+
+
+
+----
+
+              /* turn lighting on */
+    dm_lighting(dmp, 1);
+        
+----
+
+
+
+__fastf_t__ *dm_Xx2Normal* _( struct dm *dmp, int x )_
+
+__dm_Xx2Normal__ takes x in X screen coordinates and returns a value in the range [-1.0, 1.0]. dmp indicates the display manager of interest.
+
+__fastf_t__ *dm_Xy2Normal* __( struct dm *dmp, int y, int use_aspect )__
+
+__dm_Xy2Normal__ takes y in X screen coordinates and returns a value in the range [-1.0, 1.0]. _dmp_ indicates the display manager of interest. __use_aspect specifies__ whether to use the window's aspect ratio in the calculation.
+
+_int_ *dm_Normal2Xx* __( struct dm *dmp, fastf_t x )__
+
+__dm_Normal2Xx__ takes x in normalized coordinates and returns a value in X screen coordinates. _dmp_ indicates the display manager of interest
+
+_int_ *dm_Normal2Xy* __( struct dm *dmp, fastf_t y )__
+
+__dm_Normal2Xy__ takes y in normalized coordinates and returns a value in X screen coordinates. _dmp_ indicates the display manager of interest.
+
+_int_ *Dm_Init* __( Tcl_Interp *interp )__
+
+__Dm_Init initializes__ LIBDM's tcl commands. _interp_ indicates the Tcl interpreter.
+
+
+=== LIBDM's Tcl Interface
+
+*dm_bestXType* _display_
+
+__dm_bestXType__ returns the best available display manager type that can be used on the X server indicated by _display_. _Display_ is specified the same and has the same meaning as the X DISPLAY environment variable.
+
+*dm_validXType* _display dtype_
+
+__dm_validXType__ returns 1 if dtype is a valid display manager type for the X server indicated by _display_. Otherwise, 0 is returned. _Display_ is specified the same and has the same meaning as the X DISPLAY environment variable.
+
+
+== Display Manager Objects
+
+=== NAME
+
+dm_open - create and manipulate a display manager object.
+
+
+=== SYNOPSIS
+
+*dm_open* [ _pathName_ type [options]]
+
+
+=== COMMAND LINE OPTIONS
+
+Option:
+
+*-N* _height_
+
+Specifies the window's height (i.e. number of raster lines).
+
+Option:
+
+*-W* _width_
+
+Specifies the window's width.
+
+Option:
+
+*-S* _size_
+
+Specifies the window's square size (i.e. width and height).
+
+Option:
+
+*-i* _initproc_
+
+Specifies the initialization proc. This proc is called with the pathName as an argument.
+
+Option:
+
+*-t* _0|1>_
+
+Specifies the toplevel flag. 0 indicates the display manager object is an internal window, while 1 indicates a toplevel window.
+
+Option:
+
+*-d* _dpy_
+
+Specifies the display string in a format understood by X windows.
+
+
+=== DESCRIPTION
+
+The dm_open command creates a new window (given by the pathName argument) and makes it into a display manager object for displaying geometry. Additional options, described above, may be specified on the command line to configure aspects of the display manager object. The dm_open command returns its pathName argument. At the time this command is invoked, there must not exist a window named pathName, but pathName's parent must exist.
+
+
+=== METHODS
+
+The *dm_open* command creates a new Tcl command whose name is pathName. This command may be used to invoke various operations on the display manager object. It has the following general form:
+
+_pathName option ?arg arg ...?_
+
+Option and the args determine the exact behavior of the command. The following commands are possible for display manager objects:
+
+_pathName_ *bg ["r g b"]*
+
+Set/get the background color. The rgb components are expected to be integers between 0 and 255. pathName bounds [xmin xmax ymin ymax zmin zmax]
+
+Set/get the window bounds. Some display managers use this to calculate clipping planes (i.e. X).
+
+_pathName_ *clear*
+
+Clear the drawing area using the background color.
+
+_pathName_ *close*
+
+Close the display manager object.
+
+_pathName_ *configure*
+
+Called to handle Configure events.
+
+_pathName_ *debug [0|1]*
+
+Set/get debug mode. 0 indicates debugging is off while 1 indicates debugging is on.
+
+_pathName_ *drawBegin*
+
+Begin the drawing sequence.
+
+_pathName_ *drawEnd*
+
+End the drawing sequence. This will cause the graphics pipe to be flushed.
+
+_pathName drawGeom_ *geo_obj(s)*
+
+Draw one or more drawable geometry objects.
+
+_pathName_ *drawLine x1 y1 x2 y2*
+
+Draw the 2D line indicated by endpoints (x1, y1) and (x2, y2). The given coordinates are expected to be in the range [-1, 1].
+
+_pathName_ *drawPoint x y*
+
+Draw the 2D point at position (x, y).
+
+_pathName_ *drawSList slp*
+
+Draw the solid list specified by the solid list pointer (i.e.slp).
+
+_pathName_ *drawString str x y size use_aspect*
+
+Draw the 2D string starting at position (x, y). The x and y coordinates are expected to be in the range [-1, 1]. The size is currently ignored. The use_aspect flag indicates whether or not to use the aspect ratio to modify the starting position.
+
+_pathName_ *drawVList vlp*
+
+Draw the vector list specified by the vector list pointer (i.e.vlp).
+
+_pathName_ *fg ["r g b"]*
+
+Set/get the foreground color. The rgb components are expected to be integers between 0 and 255.
+
+_pathName_ *flush*
+
+Flushes the X server's request buffer.
+
+_pathName_ *get_aspect*
+
+Get the window's aspect ratio (i.e. width / height).
+
+_pathName_ *light [0|1]*
+
+Set/get light mode. 0 indicates light is off while 1 indicates light is on.
+
+_pathName_ *linestyle [0|1]*
+
+Set/get linestyle. 0 indicates solid lines while 1 indicates dashed lines.
+
+_pathName_ *linewidth [width]*
+
+Set/get linewidth. This setting determines how fat to draw the wireframe lines.
+
+_pathName_ *listen [port]*
+
+Set/get the port used to listen for framebuffer clients. Port values less than zero turn off listening.
+
+_pathName_ *loadmat mat*
+
+Load the matrix, mat, into the display manager. This is typically a model2view matrix.
+
+_pathName_ *normal*
+
+Restore display manager to a normal mode of operation (i.e. not scaled, rotated, displaced, etc.).
+
+_pathName_ *observer [subcommand]*
+
+This command is used to maintain a list of observers. Observers are objects who have registered an interest in when this display manager object receives pixels in its role as a framebuffer server. Whenever pixel data is received the observers on the list are notified.
+
+_pathName_ *observer attach obs [command]*
+
+Add the specified observer, obs, to the list of observers. If command is specified then it is executed each time pixel data is received. Otherwise, the observer is expected to have an update method which is called with the name of this display manager object as an argument.
+
+_pathName observer detach obs_
+
+Remove the specified observer, obs, from the list of observers.
+
+_pathName_ *observer show*
+
+Return the list of observers for this display manager object.
+
+_pathName_ *perspective [0|1]*
+
+Set/get perspective mode. 0 indicates perspective is off, while 1 indicates perspective is on.
+
+_pathName_ *refreshfb*
+
+Draws/displays the pixels stored in the widget's framebuffer.
+
+_pathName_ *size [width height]*
+
+Set/get the window size.
+
+_pathName_ *sync*
+
+Flushes the X server's request buffer and waits until all events have been processed.
+
+_pathName_ *zbuffer [0|1]*
+
+Set/get zbuffer mode. 0 indicates that zbuffer is off, while 1 indicates zbuffer is on.
+
+_pathName_ *zclip [0|1]*
+
+Set/get zclipping mode. 0 indicates zclipping is off, while 1 indicates zclipping is on.
+
+
+
+
+----
+
+The following sequence creates a display manager object and draws two yellow lines that connect the opposite corners of the window.
+cwish> dm_open .d X -t 0 -s 400
+.d
+cwish> pack .d -expand yes -fill both
+cwish> .d drawBegin
+cwish> .d fg "255 255 0"
+cwish> .d drawLine -1 1 1 -1
+cwish> .d drawLine -1 -1 1 1
+cwish> .d drawEnd
+----
+
+
+
+
+[[libfbgeneric]]
+== Generic frame buffer routines

-== SYNOPSIS

 [source,c]
 ----
-#include <dm.h>
+fb *fb_open(* fbfile, int fb_close ( fbp ) fb * fbp, int fb_read ( fbp , x , y , addr , count ) fb * fbp, RGBpixel *addr;, long count;);
+int fb_write(* fbp, RGBpixel * addr, long count, int fb_rmap ( fbp , cmap ) fb * fbp, ColorMap * cmap);
+int fb_wmap(* fbp, ColorMap * cmap);
+int fb_clear(* fbp, RGBpixel * colorp);
+char *fb_gettype(* fbp);
+int fb_getwidth(* fbp);
+int fb_getheight(* fbp);
+
 ----

-Link with *-ldm*.

-The public interface is organized across the headers included by
-_dm.h_, namely _dm/defines.h_, _dm/fbserv.h_, _dm/util.h_, and
-_dm/view.h_.
+[[libfbhardware]]
+== Hardware specific frame buffer routines

+
+[source,c]
+----
+int fb_cursor(* fbp, int fb_scursor ( fbp , mode , x , y ) fb * fbp, int fb_setcursor ( fbp , bits , xbits , ybits , xorig , yorig ) fb * fbp, unsigned char bits[], int xbits, ybits;, int xorig, yorig;);
+int fb_window(* fbp, int fb_zoom ( fbp , x , y ) fb * fbp, / *Buffered frame buffer I/O: */ int fb_ioinit ( fbp ) fb * fbp);
+int fb_seek(* fbp, void fb_tell ( fbp , xp , yp ) fb * fbp, int *xp , * yp);
+int fb_rpixel(* fbp, RGBpixel * pixelp);
+int fb_wpixel(* fbp, RGBpixel * pixelp);
+int fb_flush(* fbp);
+void fb_log(format [ , arg ] ... );
+
+----
+
+
+[[description]]
 == DESCRIPTION

-LIBDM provides BRL-CAD's display manager API. A display manager can be
-thought of as a configurable drawing machine: it consumes generic,
-device-independent drawing commands -- primarily vector lists (vlists)
-that describe points, lines, and polygons in three dimensions, along
-with two-dimensional points, lines, and text -- and translates them into
-the drawing operations of a specific output device or window system.
+These routines are designed to provide a device-independent method of using frame buffers or files containing frame buffer images. The coordinate system used is first-quadrant (0..width-1, 0..height-1), with integer addressing. Translation to hardware coordinate systems is handled by the library.

-The library abstracts the underlying rendering target behind a common
-_struct dm_ interface, so that applications can draw the same geometry to
-any supported backend without change. Backends provided with BRL-CAD
-include X11, OpenGL (via GLX on X11 and WGL on Windows), a Qt/OpenGL
-target, a software rasterizer, PostScript output, UNIX plot output, a
-text backend, and a null device. LIBDM also integrates with the BRL-CAD
-framebuffer facilities, including the framebuffer server support in
-_dm/fbserv.h_.
+This version of the library assumes that red, green, and blue intensities are described by unsigned 8-bit bytes in the range (0..255). The library interface uses arrays of *RGBpixel* s, which is a typedef for an array of three unsigned chars (this was done to avoid structure padding). Note that a pointer to an *RGBpixel* is thus the name of the *RGBpixel* itself, i.e. no ampersand is needed.

-The complete API, including data structures and function signatures, is
-documented in the headers noted above and in the Doxygen-generated
-reference for the LIBDM module.
+The exact interpretation of color maps tends to be somewhat device specific. The three ColorMap arrays each have 256 entries of unsigned 16-bit values. In order to accommodate color maps with differing amounts of output resolution, the color map entries are fixed-point fractions in the range (0.0..1.0). In integer notation, the range is (0..65525). For devices with less than 16 bits of output from their color maps, the left-most portion of each entry is used.

-== SEE ALSO
+__Fb_open__ is used to open a frame buffer file _fbfile_. The file may be either the name of a supported frame buffer interface, referenced as "/dev/interface", or the name of a UNIX file. The routine will try to determine if the file opened was a real frame buffer by examining the name, and if so will perform whatever initialization actions are necessary. If the value of _fbfile_ is NULL and the environment variable `FB_FILE` is set, then the value of `FB_FILE` is used; otherwise the default frame buffer device for the system is used. See below for more details. The _width_ and _height_ parameters specify the initial size of display desired. If these are zero the default sizes for that device will be used. On a successful open, the frame buffer I/O (fb) structure pointer is returned. This structure contains size you were actually given, as well as the maximum possible size for the selected device. A return of FB_NULL indicates failure.

-*brlcad*(1), *mged*(1), *archer*(1), *libbv*(3), *libged*(3), *libicv*(3)
+__Fb_close__ simply closes the frame buffer.

-The BRL-CAD Doxygen API reference provides the authoritative,
-up-to-date description of all public LIBDM routines.
+__Fb_read__ reads _count_ pixels from the frame buffer starting at the location specified by _x_ and _y_, and places them at program memory address specified by _addr_. __Fb_read__ returns the number of pixels actually read, or -1 on error.

-== AUTHOR
+__Fb_write__ writes _count_ pixels from program address _addr_ into the frame buffer starting at the location specified by _x_ and _y_. __Fb_write__ returns the number of pixels actually written, or -1 on error.

-BRL-CAD Team
+__Fb_rmap__ reads in the color map from the frame buffer and leaves at the location pointed to by _cmap_.

-== COPYRIGHT
+__Fb_wmap__ writes the color map pointed to by _cmap_ into the frame buffer. If the value of _cmap_ is NULL then a linear color map is used as the default.

-This software is Copyright (c) 1993-2026 United States Government as represented by the U.S. Army Research Laboratory.
+__Fb_clear__ erases the frame buffer by setting all pixels to the given color. If the color pointer is NULL, black will be used. On a UNIX file, this entails writing the entire file, which is an expensive operation, whereas on most frame buffer displays this can be done in less than a second by a special command.

-== BUG REPORTS
+__Fb_gettype__ returns a pointer to a string describing the frame buffer specified by the fb pointer.

-Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org
+__Fb_getwidth__ and __Fb_getheight__ returns the current size of the fb frame buffer.
+
+The following routines work in conjunction with those described above to provide functions which only apply if the frame buffer file is actually a hardware frame buffer display.
+
+__Fb_cursor__ places the cursor at the image space coordinates given by _x_ and _y_. If the mode is non-zero, the cursor is made visible, and if mode is zero, the cursor is turned off.
+
+__Fb_scursor__ is the same as __fb_cursor__ except that it places the cursor at the *screen* space coordinates given by _x_ and _y_.
+
+__Fb_setcursor__ allows the user to set the bitmap used to represent the cursor, thereby changing the cursor shape. This is not necessarily supported by all hardware. The argument _bits_ is a pointer to an array of unsigned chars containing the bits of the cursor. The arguments _xbits_ and _ybits_ specify the size of the cursor bitmap. The number of bytes in the `bits` array will be the width rounded up to a multiple of eight (so that the cursor "scanlines" are byte aligned) times the height. `bits`[0] is the lower left corner, `bits`[1] is to the right of it, etc. The next line of the `bits` array goes above the current one. Within a byte the most significant bit is the leftmost. The values _xorig_ and _yorig_ specify which bit in the bitmap actually gets placed at the location specified in the cursor move routines. Again, a first quadrant coordinate system is used.
+
+__Fb_window__ sets the frame buffer window center position to the image space coordinates given by _x_ and _y_. This command is usually used in conjunction with the __fb_zoom__ routine.
+
+__Fb_zoom__ sets the zoom factor for the X coordinate to _x_ and the zoom factor for the Y coordinate to _y_. Zooming is generally done by pixel replication in hardware.
+
+The following routines work in conjunction with those described above to provide buffered reading and writing of frame buffer images either to a real frame buffer or a UNIX file. The routines use a simple paging strategy to hold “bands” of the image in core. Since horizontal bands are buffered, the ideal motion is to scan left to right, then bottom to top.
+
+__Fb_ioinit__ should be called before using any of the other buffered I/O routines and repeated whenever the frame buffer is reopened.
+
+__Fb_seek__ is used to position the current read/write pointer to the location to the next position to be read or written. It is not necessary to do a __fb_seek__ after every read or write since both __fb_rpixel__ and __fb_wpixel__ imply an automatic move to the next pixel. If you read or write the last pixel on a scan line, the pointer will automatically move to the beginning of the following scan line.
+
+__Fb_tell__ returns the current location of the read write pointer in terms of (X,Y) coordinates on the frame buffer. The X and Y values are returned into the integers pointed to by _xp_ and _yp_.
+
+__Fb_rpixel__ reads the pixel at the current frame buffer location and returns it into the location specified by _pixelp_.
+
+__Fb_wpixel__ writes the pixel pointed to by _pixelp_ at the current frame buffer location.
+
+__Fb_flush__ caused any current buffered frame buffer pages to be written out. Unnecessary writes are avoided by the use of page reference bits.
+
+The following is a printing routine which this library uses to indicate errors.
+
+__Fb_log__ will convert, format and print its _args_ under control of _format_ to the standard error output. For more detailed information on the specification of the control string, see *printf*(3S). This function may be supplied by the application if different behavior is desired.
+
+
+[[fb_file_devices]]
+== FB_FILE DEVICES
+
+The following devices are supported by the library; not all may be available on any given system. New device support can be incorporated by the addition of a single module to the library.
+
+
+`/dev/debug` _[num]_::
+The "/dev/debug" interface prints one line to logs each call to the frame buffer library._num_ is a bitvector indicating the levels of verbosity of the output. See *fb.h* for the bit definitions.
+
+
+_filename_::
+Disk file interface
+
+
+*hostname:* _[devicename]_::
+TCP-based network links to a remote framebuffer, where _devicename_ is any from this list, for example, fictitious.brlcad.org:/dev/ik0 or fictitious.brlcad.org:/dev/sgi. A *hostname* with a null _devicename_ will select the default display device on that host. If explicitly specifying a remote device, be careful not to omit the colon between the host and device name, or you will be specifying a local disk file as the result. Note that for security reasons, it is not permitted to access a disk file via the remote interface.
+
+
+
+
+[[examples]]
+== EXAMPLES
+
+_Libfb_ can be loaded with any C program:
+
+
+----
+
+			$  /bin/cc  program.c  -lfb -l\<system-library...\>
+		
+----
+
+where _<system-library>_ denotes specific libraries necessary on a particular machine. All machines with networking will require the "-lpkg" option. Machines which support the X Windows(tm) system will require the "-lX11" option.
+
+
+[[return_values]]
+== RETURN VALUES
+
+__fb_close__, __fb_write__, __fb_read__, __fb_wmap__, __fb_rmap__, __fb_clear__, __fb_cursor__, __fb_scursor__, __fb_setcursor__, __fb_window__, __fb_zoom__, __fb_ioinit__, __fb_seek__, __fb_wpixel__, __fb_rpixel__ and __fb_flush__ return -1 to indicate failure. __Fb_open__ returns FB_NULL to indicate failure, and a non-null fb structure pointer upon success. __fb_read__, and __fb_write__ return the number of pixels actually read or written. __fb_gettype__ returns a pointer to a NULL terminated description string.
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
f4alt	45bd03651e	support assemblies	2026-09-01 13:22:02 -04:00
f4alt	76949e1814	get converter working again with native prt files	2026-09-01 13:22:02 -04:00
f4alt	78afc4908f	unified part writer	2026-09-01 13:22:02 -04:00
f4alt	ab63f800e3	Revert "snapshot writer for frontend" This reverts commit e75ddc22963ab5ffb769c2520458126ba5abfb82.	2026-09-01 13:22:02 -04:00
f4alt	e6a2c23110	snapshot writer for frontend	2026-09-01 13:22:02 -04:00
f4alt	9c8029f34b	experiment with a conversion contract use a snapshot as a lightweight intermediary from the conversion core to the creo frontend	2026-09-01 13:22:01 -04:00
f4alt	2c1366d99e	first major shift: profile loading since profile loading is coming from a .g, separate it from the creo standup	2026-09-01 13:22:01 -04:00
f4alt	4ed030bb2d	ignore vs files anywhere in the project	2026-09-01 13:22:01 -04:00
f4alt	149da288f0	add a spawned exe debug fallback This method _works_ but requires a spawned console to run the converter - ugly, fragile, and not what we want long term. Adding it here behind a define for shortterm debugging	2026-09-01 13:22:01 -04:00
f4alt	786b911538	use translation files method	2026-09-01 13:22:01 -04:00
f4alt	b46732c0e8	wip	2026-09-01 13:22:01 -04:00
f4alt	633023ab4b	Creo expects text/	2026-09-01 13:22:01 -04:00
f4alt	2b5f76fe69	begin shift from requiring copying files to Creo install Old mechanism required copying output files into "Program Files/Creo" - it works, but is not preferred (for both users and Creo development documentation). The better pattern is to have our tool live outside the Creo system install and pointed to. However, this requires the BRL-CAD dll's to be runtime loaded (either by quirk or design of Creo). To stage this we first need to separate the brlcad 'real' work from the Creo standup. This will allow us to register the frontend with Creo's tools and runtime-load the brl backend.	2026-09-01 13:22:01 -04:00
f4alt	fad1606492	wip: cleanup hardcoded paths	2026-09-01 13:22:00 -04:00
f4alt	1df5693b4f	update API calls	2026-09-01 13:22:00 -04:00
f4alt	563a555664	pull in Bill's last wip changes	2026-09-01 13:22:00 -04:00