usdGeospatial: shrinkwrap the C++ Hydra plugin into build_usd.py (--usdGeospatial), cross-platform

Make the usdGeospatialSceneIndex example an opt-in, cross-platform build like
hdParticleField -- one build_usd.py flag builds PROJ and the plugin, replacing
the Linux-only shell scripts. Validated on Linux and Windows (MSVC).

Build:
- build_usd.py: --usdGeospatial builds PROJ (+ its SQLite3 dependency) as opt-in
  third-party deps, then passes -DPXR_ENABLE_GEOSPATIAL_SUPPORT to the USD build.
- cmake/defaults: PXR_ENABLE_GEOSPATIAL_SUPPORT option + find_package(PROJ).
- Register the example under extras/usd/examples (gated on the flag + imaging);
  fix its CMakeLists: add the missing geospatialAPISchemaAdapter/geospatialSchema
  sources, define USDGEOSPATIAL_SI_EXPORTS, DISABLE_PRECOMPILED_HEADERS, link
  PROJ::proj.

Parity as a ctest:
- run_parity.py + pxr_register_test(testUsdGeospatialParity): CRS engine 9/9,
  stage resolver 30/30, Hydra scene index 30/30, stage-free auto-insert 30/30 --
  all 0.0 mm. dumpHydraXforms built for the runtime_parity figure.
- dump_oracle.py auto-converts the committed railway asset so the oracle is the
  full 30-row set.

Cross-platform figure/doc tooling:
- fig_runtime_parity.py / render_figures.py: portable dumper + tsv paths
  (GEO_HYDRA_TSV / GEO_HYDRA_DUMPER, system temp, os.pathsep) -- no /tmp or
  /usr/share/proj hardcodes.
- docs/build_deck.py: read the README as UTF-8 (Windows).
- probe_autoinsert.py: drop dead Hd/HdGp imports.

Docs (README is the base artifact; deck derives from it):
- README build sections -> the cross-platform build + ctest; add a
  reproducibility slide; regenerate the deck PDF.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: asluk

build_scripts/build_usd.py

@@ -789,7 +789,75 @@ def InstallZlib(context, force, buildArgs):
         RunCMake(context, force, extraArgs + buildArgs)
 
 ZLIB = Dependency("zlib", InstallZlib, "include/zlib.h")
-        
+
+############################################################
+# SQLite3 (required by PROJ to build/read its CRS database proj.db)
+
+# SQLite ships as an "amalgamation" (a single sqlite3.c plus headers and the
+# shell.c command-line driver) with no build system, so we drop in a minimal
+# CMakeLists that produces both a static library AND the sqlite3 command-line
+# tool -- PROJ needs the CLI to generate proj.db at build time.
+SQLITE3_URL = "https://www.sqlite.org/2024/sqlite-amalgamation-3460100.zip"
+
+SQLITE3_CMAKELISTS = """\
+cmake_minimum_required(VERSION 3.15)
+project(SQLite3 C)
+add_library(sqlite3 STATIC sqlite3.c)
+set_property(TARGET sqlite3 PROPERTY POSITION_INDEPENDENT_CODE ON)
+add_executable(sqlite3_cli shell.c sqlite3.c)
+set_target_properties(sqlite3_cli PROPERTIES OUTPUT_NAME sqlite3)
+if(NOT WIN32)
+  find_package(Threads REQUIRED)
+  target_link_libraries(sqlite3 PUBLIC Threads::Threads ${CMAKE_DL_LIBS})
+  target_link_libraries(sqlite3_cli PRIVATE Threads::Threads ${CMAKE_DL_LIBS})
+endif()
+install(TARGETS sqlite3 ARCHIVE DESTINATION lib LIBRARY DESTINATION lib)
+install(TARGETS sqlite3_cli RUNTIME DESTINATION bin)
+install(FILES sqlite3.h sqlite3ext.h DESTINATION include)
+"""
+
+def InstallSQLite3(context, force, buildArgs):
+    with CurrentWorkingDirectory(DownloadURL(SQLITE3_URL, context, force)):
+        with open("CMakeLists.txt", "w") as f:
+            f.write(SQLITE3_CMAKELISTS)
+        RunCMake(context, force, buildArgs)
+
+SQLITE3 = Dependency("SQLite3", InstallSQLite3, "include/sqlite3.h")
+
+############################################################
+# PROJ (coordinate transforms / CRS engine; used by the
+# usdGeospatialSceneIndex example when PXR_ENABLE_GEOSPATIAL_SUPPORT is on).
+# Depends on SQLite3 (built above) for proj.db.
+
+PROJ_URL = "https://github.com/OSGeo/PROJ/archive/refs/tags/9.4.1.zip"
+
+def InstallPROJ(context, force, buildArgs):
+    with CurrentWorkingDirectory(DownloadURL(PROJ_URL, context, force)):
+        sqlite3Exe = os.path.join(context.instDir, "bin",
+                                  "sqlite3.exe" if Windows() else "sqlite3")
+        sqlite3Lib = os.path.join(context.instDir, "lib",
+                                  "sqlite3.lib" if Windows() else "libsqlite3.a")
+        extraArgs = [
+            '-DENABLE_TIFF=OFF',
+            '-DENABLE_CURL=OFF',
+            '-DBUILD_TESTING=OFF',
+            '-DBUILD_APPS=OFF',
+            '-DBUILD_SHARED_LIBS=ON',
+            '-DEXE_SQLITE3="{exe}"'.format(exe=sqlite3Exe),
+            '-DSQLITE3_INCLUDE_DIR="{inc}"'.format(
+                inc=os.path.join(context.instDir, "include")),
+            '-DSQLITE3_LIBRARY="{lib}"'.format(lib=sqlite3Lib),
+            # For compatibility with CMake 4+
+            '-DCMAKE_POLICY_VERSION_MINIMUM=3.5',
+        ]
+
+        # Add on any user-specified extra arguments.
+        extraArgs += buildArgs
+
+        RunCMake(context, force, extraArgs)
+
+PROJ = Dependency("PROJ", InstallPROJ, "include/proj.h")
+
 ############################################################
 # boost
 
@@ -1873,7 +1941,12 @@ def InstallUSD(context, force, buildArgs):
             extraArgs.append('-DPXR_BUILD_USD_VALIDATION=ON')
         else:
             extraArgs.append('-DPXR_BUILD_USD_VALIDATION=OFF')
-            
+
+        if context.enableGeospatial:
+            extraArgs.append('-DPXR_ENABLE_GEOSPATIAL_SUPPORT=ON')
+        else:
+            extraArgs.append('-DPXR_ENABLE_GEOSPATIAL_SUPPORT=OFF')
+
         if context.buildImaging:
             extraArgs.append('-DPXR_BUILD_IMAGING=ON')
             if context.enablePtex:
@@ -2298,10 +2371,18 @@ def InstallUSD(context, force, buildArgs):
 subgroup.add_argument("--openvdb", dest="enable_openvdb", action="store_true", 
                       default=False, 
                       help="Enable OpenVDB support in imaging")
-subgroup.add_argument("--no-openvdb", dest="enable_openvdb", 
+subgroup.add_argument("--no-openvdb", dest="enable_openvdb",
                       action="store_false",
                       help="Disable OpenVDB support in imaging (default)")
 subgroup = group.add_mutually_exclusive_group()
+subgroup.add_argument("--usdGeospatial", dest="enable_geospatial",
+                      action="store_true", default=False,
+                      help="Enable geospatial (PROJ) support and build the "
+                           "usdGeospatialSceneIndex example")
+subgroup.add_argument("--no-usdGeospatial", dest="enable_geospatial",
+                      action="store_false",
+                      help="Disable geospatial support (default)")
+subgroup = group.add_mutually_exclusive_group()
 subgroup.add_argument("--usdview", dest="build_usdview",
                       action="store_true", default=True,
                       help="Build usdview (default)")
@@ -2540,6 +2621,11 @@ def __init__(self, args):
                               and args.enable_vulkan
                               and not embedded)
 
+        # - Geospatial (PROJ). Independent of imaging at the flag level, though
+        #   the usdGeospatialSceneIndex plugin itself links usdImaging, so its
+        #   CMake registration is additionally gated on PXR_BUILD_USD_IMAGING.
+        self.enableGeospatial = (args.enable_geospatial and not embedded)
+
         # - USD Imaging
         self.buildUsdImaging = (args.build_imaging == USD_IMAGING and 
                                 not self.targetWasm)
@@ -2629,6 +2715,10 @@ def ForceBuildDependency(self, dep):
 if context.buildMaterialX:
     requiredDependencies += [MATERIALX]
 
+# PROJ needs SQLite3 built first (for proj.db), so list SQLITE3 before PROJ.
+if context.enableGeospatial:
+    requiredDependencies += [SQLITE3, PROJ]
+
 if context.buildImaging:
     if context.enablePtex:
         requiredDependencies += [ZLIB, PTEX]

cmake/defaults/Options.cmake

@@ -35,6 +35,7 @@ option(PXR_ENABLE_HDF5_SUPPORT "Enable HDF5 backend in the Alembic plugin for US
 option(PXR_ENABLE_OSL_SUPPORT "Enable OSL (OpenShadingLanguage) based components" OFF)
 option(PXR_ENABLE_PTEX_SUPPORT "Enable Ptex support" OFF)
 option(PXR_ENABLE_OPENVDB_SUPPORT "Enable OpenVDB support" OFF)
+option(PXR_ENABLE_GEOSPATIAL_SUPPORT "Enable geospatial (PROJ) support, used by the usdGeospatialSceneIndex example" OFF)
 option(PXR_ENABLE_NAMESPACES "Enable C++ namespaces." ON)
 option(PXR_PREFER_SAFETY_OVER_SPEED
        "Enable certain checks designed to avoid crashes or out-of-bounds memory reads with malformed input files.  These checks may negatively impact performance."

cmake/defaults/Packages.cmake

@@ -319,6 +319,14 @@ if (PXR_ENABLE_MATERIALX_SUPPORT)
     add_definitions(-DPXR_MATERIALX_SUPPORT_ENABLED)
 endif()
 
+if (PXR_ENABLE_GEOSPATIAL_SUPPORT)
+    # PROJ ships its own config-mode package (proj-config.cmake) providing the
+    # PROJ::proj imported target; it is found on CMAKE_PREFIX_PATH (the shared
+    # install prefix that build_usd.py populates).
+    find_package(PROJ REQUIRED)
+    add_definitions(-DPXR_GEOSPATIAL_SUPPORT_ENABLED)
+endif()
+
 if(PXR_ENABLE_OSL_SUPPORT)
     find_package(OSL REQUIRED)
     set(REQUIRES_Imath TRUE)

extras/usd/examples/CMakeLists.txt

@@ -10,4 +10,10 @@ else()
 	add_subdirectory(usdResolverExample)
 	add_subdirectory(usdSchemaExamples)
 	add_subdirectory(usdMakeFileVariantModelAsset)
+
+	# The geospatial scene-index example is opt-in (needs PROJ) and links
+	# usdImaging/hd, so it additionally requires USD imaging to be built.
+	if (PXR_ENABLE_GEOSPATIAL_SUPPORT AND PXR_BUILD_USD_IMAGING)
+		add_subdirectory(usdGeospatialSceneIndex)
+	endif()
 endif()

extras/usd/examples/usdGeospatial/README.md

@@ -426,6 +426,14 @@ The takeaway is the schema claim itself: **the schema is the contract; the behav
 third runtime (OpenExec, a GPU / cuProj engine, an Omniverse runtime) plugs into the same seam and
 is held to the same oracle.
 
+<!-- slide:text eyebrow="Reproducible · cross-platform" title="The second runtime builds like any USD example" body="`build_usd.py --usdGeospatial` fetches and builds PROJ, then the C++ Hydra plugin, behind one opt-in flag — the `hdParticleField` pattern, no bespoke setup. | Parity is a `ctest` (`testUsdGeospatialParity`): CRS engine + stage resolver + Hydra scene index + stage-free auto-insert, all 0.0 mm. | Validated on Linux **and** Windows — the contract builds twice, the same way, on two platforms." -->
+
+And it builds like any other OpenUSD example: `build_usd.py --usdGeospatial --examples` fetches and
+builds PROJ and the C++ Hydra plugin behind one opt-in flag — the same shape as `hdParticleField`,
+on Linux and Windows alike — and `ctest -R testUsdGeospatialParity` runs the whole parity proof
+(CRS engine, stage resolver, Hydra scene index, and the stage-free auto-insert path). The second
+runtime isn't a Linux-only lab artifact; it's a normal, opt-in part of the build.
+
 ### Where the Python reference runtime sits (no exact precedent — by design)
 
 <!-- slide:text eyebrow="No exact precedent — by design" title="Where the Python reference runtime sits" body="It's the codeless schema's **conformance oracle** — 'given this stage, where does each prim end up?' — pinned to closed-form geodesy, that compliant implementations should match. | NOT the specification: the normative behavior belongs in **prose** (proposed into the Esri proposal); the Python is the oracle that expresses it, not the source of truth. | NOT proposed for USD core, NOT a runtime dependency, NOT Python-in-the-render-loop, NOT the prescribed consumer. | Precedent: AOUSD's core-spec-supplemental — Python sample impls + a compliance framework, spec normative and impl illustrative — is exactly this shape." -->
@@ -474,17 +482,18 @@ Every test is openable and runnable; each has a real negative control or an inde
   neutral scene has zero xformOps).
 - `render_figures.py` — the coherence figure self-asserts sub-mm co-registration; `fig_runtime_parity`
   fails the build if Python-vs-Hydra disagreement exceeds 1 mm.
-- `../usdGeospatialSceneIndex/run_parity.sh` — the compiled C++ scene index: CRS engine 9/9, stage
-  resolver 30/30, Hydra SI via `HdXformSchema` 30/30 — all 0.0 mm; negative control: stock Hydra
-  puts georef prims at the origin. `testHydraAutoParity` adds the stage-free auto-insert path (30/30).
+- `ctest -R testUsdGeospatialParity` (cross-platform; also `run_parity.sh`) — the compiled C++ scene
+  index: CRS engine 9/9, stage resolver 30/30, Hydra SI via `HdXformSchema` 30/30 — all 0.0 mm;
+  negative control: stock Hydra puts georef prims at the origin. `testHydraAutoParity` adds the
+  stage-free auto-insert path (30/30).
 - `pxr/usd/usdGeospatial/regen-schema.sh --check` — schema resources are in sync.
 
 ### Running — two paths
 
-**The codeless Python path (no external renderer):**
+**The codeless Python path (no external renderer)** — any Python with `pxr` (a usd-core wheel or a
+USD build) plus `pyproj`, `numpy`, `matplotlib`:
 
 ```bash
-source <repo>/.venv/bin/activate        # usd-core 26.5, pyproj 3.7.1 (PROJ 9.5.1)
 cd extras/usd/examples/usdGeospatial
 python3 src/reencode_georef.py --stride 40 --out out/earth2_georef.usda
 python3 src/verify.py out/earth2_georef.usda
@@ -496,17 +505,21 @@ python3 src/render_figures.py           # regenerate the Python-reference figure
 ```
 
 `render_figures.py` regenerates the nine Python-reference figures; it also produces
-`multi_runtime.png` / `runtime_parity.png` **if** the compiled C++ Hydra binary is already built,
-otherwise it skips those two with a clear note.
+`multi_runtime.png` / `runtime_parity.png` if the compiled C++ Hydra binary is available (built as
+below), otherwise it skips those two with a clear note.
 
-**The full two-runtime parity proof (needs a prebuilt USD):**
+**The full two-runtime parity proof — an opt-in, cross-platform build.** The C++ Hydra scene index
+builds like any other OpenUSD example: one flag makes `build_usd.py` fetch and build PROJ, then the
+plugin and its parity tests. Validated on Linux and Windows.
 
 ```bash
-USD_INST=/path/to/usd/inst ../usdGeospatialSceneIndex/run_parity.sh
+python build_scripts/build_usd.py --usdGeospatial --examples --tests <inst>   # builds PROJ + plugin + tests
+ctest --test-dir <build> -R testUsdGeospatialParity                            # engine + resolver + Hydra SI + auto-insert, 0.0 mm
 ```
 
-See `../usdGeospatialSceneIndex/README.md` for the full build environment, and the same directory's
-notes for reproducing the auto-insert usdview / usdrecord render.
+The plugin installs discoverable via `PXR_PLUGINPATH_NAME`; opening the georef scene in `usdview` /
+`usdrecord` then auto-resolves it. `run_parity.py` (invoked by that ctest) is also runnable
+standalone. See `../usdGeospatialSceneIndex/README.md` for details and the auto-insert render notes.
 
 ## Status, scope, and open questions
 

extras/usd/examples/usdGeospatial/docs/build_deck.py

@@ -102,7 +102,7 @@ def caption_after(lines, start):
 
 
 def build_slides():
-    lines = open(README).read().splitlines()
+    lines = open(README, encoding="utf-8").read().splitlines()
     marks = [(i, m.group(1), parse_attrs(m.group(2)))
              for i, ln in enumerate(lines) for m in [MARKER.search(ln)] if m]
     slides = []
@@ -240,7 +240,7 @@ def main():
     slides = build_slides()
     doc = (f"<!doctype html><html><head><meta charset='utf-8'><style>{CSS}</style></head>"
            f"<body>{render(slides)}</body></html>")
-    with open(OUT, "w") as f:
+    with open(OUT, "w", encoding="utf-8") as f:
         f.write(doc)
     print(f"wrote {OUT} ({len(slides)} slides, {len(doc)//1024}KB)")
     print("order:", " ".join(s[0].lower() for s in slides))

extras/usd/examples/usdGeospatial/docs/usdGeospatial.pdf

@@ -18,7 +18,7 @@
 
 Output: docs/runtime_parity.png
 """
-import os, sys, numpy as np, matplotlib.pyplot as plt
+import os, sys, tempfile, numpy as np, matplotlib.pyplot as plt
 from PIL import Image
 
 HERE = os.path.dirname(os.path.abspath(__file__))
@@ -30,7 +30,10 @@
 ECEF = CRS.from_epsg(4978)
 
 STAGE = os.path.join(HERE, "out", "railway_georef.usda")
-HYDRA_TSV = "/tmp/hydra_railway_xforms.tsv"
+# Portable: honor GEO_HYDRA_TSV (set by render_figures.py), else the system temp
+# dir -- not a hardcoded /tmp (so this works on Windows/macOS too).
+HYDRA_TSV = os.environ.get(
+    "GEO_HYDRA_TSV", os.path.join(tempfile.gettempdir(), "hydra_railway_xforms.tsv"))
 OUT = os.path.join(HERE, "docs", "runtime_parity.png")
 TEXDIR = os.path.join(HERE, "data", "thirdparty")
 

extras/usd/examples/usdGeospatial/fig_runtime_parity.py

@@ -666,17 +666,25 @@ def fig_runtime_parity(out, stage_path="out/railway_georef.usda"):
     plugin lives in ../usdGeospatialSceneIndex/)."""
     here = os.path.dirname(os.path.abspath(__file__))
     repo_dir = os.path.abspath(os.path.join(here, ".."))
-    tsv = "/tmp/hydra_railway_xforms.tsv"
-    dumper = "/tmp/dumpHydraXforms"
+    import tempfile, shutil
+    # Portable locations (no hardcoded /tmp): GEO_HYDRA_TSV / GEO_HYDRA_DUMPER
+    # override; otherwise the system temp dir + PATH lookup. dumpHydraXforms is
+    # built with the example (installed under <inst>/tests).
+    tsv = os.environ.get("GEO_HYDRA_TSV",
+                         os.path.join(tempfile.gettempdir(), "hydra_railway_xforms.tsv"))
+    os.environ["GEO_HYDRA_TSV"] = tsv  # fig_runtime_parity.py reads the same file
+    _exe = "dumpHydraXforms" + (".exe" if os.name == "nt" else "")
+    dumper = (os.environ.get("GEO_HYDRA_DUMPER") or shutil.which("dumpHydraXforms")
+              or os.path.join(tempfile.gettempdir(), _exe))
     needs = (not os.path.exists(tsv)) or \
             (os.path.getmtime(tsv) < os.path.getmtime(os.path.join(repo_dir, stage_path)))
     if needs and os.path.exists(dumper):
-        print("[B] re-running Hydra xform dumper -> /tmp/hydra_railway_xforms.tsv")
+        print(f"[B] re-running Hydra xform dumper -> {tsv}")
         env = dict(os.environ)
         env["PXR_PLUGINPATH_NAME"] = (os.path.abspath(os.path.join(
             repo_dir, "..", "..", "..", "..", "pxr", "usd", "usdGeospatial",
-            "resources")) + ":" + env.get("PXR_PLUGINPATH_NAME", ""))
-        env.setdefault("PROJ_DATA", "/usr/share/proj")
+            "resources")) + os.pathsep + env.get("PXR_PLUGINPATH_NAME", ""))
+        # PROJ_DATA is left to the environment (portable); no /usr/share/proj.
         import subprocess
         with open(tsv, "w") as f:
             r = subprocess.run([dumper, os.path.join(repo_dir, stage_path)],