nodehammer

---

Detector geometries (ROOT/TGeo, DD4hep, GDML, GeoModel, …) are huge, deeply nested, and built for simulation — not for looking at. nodehammer converts them into a clean, semantically-tagged scene graph and renders it in real time with a physically-based pipeline, natively or straight in the browser.

   TGeo / DD4hep / GDML (Geant4) / GeoModel
              │
              ▼
    Semantic scene graph (.nhb / .nhb.zst)
    nodes · shapes · materials · deduplicated transforms
              │
       ┌──────┴──────┐
       ▼             ▼
  glTF / OBJ    Render IR (NHR8, FlatBuffers)
                       │
                       ▼
              Interactive viewer
        native (Metal / GLCORE / D3D11) · web (WebGPU / GLES3, wasm)

Every stage is driven by declarative TOML config — keep_if/drop_if selection rules with a small predicate-expression language (tag.sensitive == "true" && any(path ~= "**/Pixels/**")), material remapping, and analytical boolean cuts — so you can go from "the whole detector" to "just the Pixel barrel" without touching code.

Status

nodehammer is under active, pre-1.0 development. Here's what's real today versus what's on the roadmap.

✅ Implemented

• Importers: ROOT/TGeo, DD4hep, and GDML through Geant4, switchable at build time (NODEHAMMER_WITH_TGEO, NODEHAMMER_WITH_DD4HEP, NODEHAMMER_WITH_GEANT4). See GDML import for coverage and Homebrew build instructions.
• Exporters: glTF/GLB and OBJ (render IR), plus the native .nhb/.nhb.zst FlatBuffers semantic-scene container — a documented, zstd-compressible on-disk format.
• Analytical geometry surgery: semantic-level azimuthal wedge cuts and boolean operations via manifold, correct on non-manifold swept primitives, cooperative with UI progress.
• CLI: convert, inspect, config, project, viewer.
• Viewer rendering pipeline, live today:
  • Full offscreen HDR pipeline with ACES / Reinhard / AgX tonemapping and exposure control
  • GTAO screen-space ambient occlusion, with selectable quality presets
  • Nishita single-scattering atmospheric sky (real Rayleigh + Mie, a real sun disc) baked into the IBL pipeline, plus a visible background dome
  • FXAA 3.11 console-quality antialiasing
  • Dynamic, GPU-load-adaptive render scale with a power-saving idle profile — renders on demand and caps the idle frame rate
  • Live ImPlot performance graphs in the debug panel
  • High-resolution, supersampled PNG screenshot export (nodehammer viewer shot -o out.png ...) — verified on Metal; the WebGL2/GLES3 and WebGPU readback paths compile and link but are not yet verified in-browser
• Builds on macOS, Linux, and Windows natively (Metal, GLCORE, and D3D11 respectively), plus a wasm build targeting both GLES3 and WebGPU from one configure, with the browser shell auto-picking the right bundle via navigator.gpu. All five configurations build and pass the (headless) test suite in CI. A headless compute-worker wasm module (nodehammer-compute) runs tessellation and boolean cuts off the main thread. macOS is the primary hand-verified target for the interactive viewer itself — see below for what's untested elsewhere.
• Modern C++: C++23 throughout (<print>, the works); requires GCC ≥ 14, Clang ≥ 18/libc++, or MSVC ≥ 19.37.

🚧 Planned / in progress

• GeoModel SQLite importer — optional prototype; see fidelity and limitations.
• Windows viewer verification — the D3D11 backend builds and passes CI's headless tests, but the maintainer has no Windows machine to manually verify interactive rendering; the PNG-export readback for D3D11 is a build-time #error stub for now.
• Bloom and IBL-quality levels — UI controls exist and are wired through RenderQualitySettings, but both are no-ops for now.
• Project save/export system — the archive-as-project model below is landing now (working set, IndexedDB persistence, sidecar viewer mode, layered steer, Publish package); in-viewer editor windows and a named multi-document switcher are still to come. See docs/viewer-project-strategy.md.
• Single-instance enforcement + a real macOS .app bundle — designed, not implemented; see docs/viewer-single-instance.md.

Project model: the archive is the project

One ZipWorkingSet is both the thing you author (edit / curate / drop files into) and the thing you publish (serialize → host → share). Authoring and publishing are the same object flowing in two directions.

A nodehammer project is a .nhproj archive: a ZIP container holding the config, geometry, and materials for a scene, plus an optional root nodehammer.toml that makes it self-describing. The same archive opens natively, in the browser, and behind a published link.

Term	Meaning
Working set	the live, editable in-memory project (ZipWorkingSet) — what the viewer edits
Archive	a serialized .nhproj of a working set — the portable, publishable unit
Project manifest	root nodehammer.toml inside the archive: [project] entry keys + [view] initial steer
Sidecar	nh_manifest.json next to index.html — points at archive(s), carries deployment presentation (lock, steer overrides)
Steer	view-state (camera, angle cut, rotation, toggles) — the ephemeral per-link layer, committed to the URL query
Provenance	Empty | Local(name) | Remote(url) — where the working set came from; drives persistence and posture
Package	the self-contained static folder emitted by Publish — drop it on any static host, zero server code

The web build has two postures from one wasm binary, branched on whether a sidecar is present:

• Application mode (no sidecar) — empty start, editable, native-like; the working set auto-persists to IndexedDB and restores on reload. Your document.
• Viewer mode (sidecar present) — fetches the archive, content locked, re-fetched from source on reload. A publication.

Content-lock is a deployment property of the sidecar; steer is never frozen, so a shared link keeps camera and cuts live. The only viewer→app bridge is explicit: save the .nhproj and open it in application mode.

Full design of record, including backend mapping and mode transitions: docs/viewer-project-strategy.md.

CLI

nodehammer convert   # geometry in, anything out — the pipeline
nodehammer inspect   # summary | tree | tags — ask about a scene
nodehammer config    # validate | flatten — TOML and Lua configs
nodehammer project   # pack | publish | info — .nhproj archives
nodehammer viewer    # open | serve | shot | bench — the app
nodehammer skills    # list | install — the agent skills shipped in the binary

Five nouns and one verb. The design of record, including the vocabulary and why each old name went, is docs/cli-design.md.

convert spans the whole pipeline, and the output format decides how far it runs: -o scene.nhb stops at the semantic scene, -o scene.glb tessellates first, and asking for both in one command is one pass rather than two. Tessellation is lossy by construction — solids become triangles — so .nhb is the faithful stop and .glb is a one-way door.

nodehammer project pack -c scene.toml -i odd.xml -o odd.nhproj
nodehammer viewer odd.nhproj serve          # open it in a browser
nodehammer project publish odd.nhproj -o site/

Agent skills

--help says what the flags are. It does not say which command blocks until a human closes a window, which output is a stable contract and which is prose for a reader, or that a missing importer is a compile-time option rather than a broken file. skills/nodehammer/SKILL.md says those things, and it ships inside the binary — so installing nodehammer, by any route, is enough to have it:

nodehammer skills install                  # ~/.agents/skills, linked from ~/.claude
nodehammer skills install --scope project  # this repository instead
nodehammer skills list                     # what this build carries

The real copy goes to .agents/skills/<name>/, the cross-agent location read by Claude Code, Codex CLI, Gemini CLI, Copilot and Cursor alike. .claude/skills/ gets a symlink to it — Claude Code reads only its own directory but follows a link out of it, so one copy serves both and they cannot drift. That link is created only if .claude/ already exists; inventing a config directory for a tool you may not have is not this command's business.

Because the bytes are compiled in, uvx nodehammer skills install works exactly the same way — the wheel's nodehammer command and the compiled executable are one implementation, so there is no packaging knob to get wrong and no way for a development install to carry a different skill than a released one.

This repository links its own skill into .agents/skills/ and .claude/skills/, so a checkout is already live. That also means skills install --scope project here refuses without --force, which is the point: those links go to the source file, and writing through one would edit the tree.

DD4hep plugins that require the global detector

Some detector plugins, including ALLEGRO's k4geo readout segmentation, look up constants and geometry through dd4hep::Detector::getInstance(). The default XML importer creates a private detector. In a DD4hep-enabled native build, opt into the global detector for these plugins:

nodehammer convert -i ALLEGRO_o1_v03.xml --dd4hep-global -c scene.toml -o allegro.glb

Source the experiment's DD4hep/plugin environment first. The flag works before or after the subcommand, including inspect, and applies only to DD4hep XML loading. It loads one compact into a fresh default detector and leaves it alive until process exit. An already populated detector or a second global import is rejected; nodehammer never resets or replaces an existing detector. Selection and export run normally in the same process, with plugin output on stderr.

If a plugin calls exit() during XML import, the native CLI prints NH0302 before exiting. In private-detector mode the warning suggests retrying with --dd4hep-global. Successful imports and caught exceptions do not trigger it. This uses atexit: it does not catch abort(), _Exit(), or fatal signals, and it preserves the plugin's exit status.

The flag is also available through runCli and the Python console script in DD4hep-enabled builds. Programmatic callers can pass backend options explicitly:

auto result = nodehammer::readSemantic("detector.xml", {
    .importerOptions = {{"dd4hep.useGlobalDetector", true}},
});

import nodehammer as nh

result = nh.read_semantic(
    "detector.xml",
    importer_options={"dd4hep.useGlobalDetector": True},
)

Omitting these options keeps private-detector behavior. Each call or CLI invocation owns its options; they do not affect subsequent calls. Supplying DD4hep options for another format, or without the backend compiled in, raises NH0105. Unknown keys and incorrect value types also raise NH0105; values are not coerced. The option map accepts bool, signed 64-bit integers, double, and strings (Python: bool, int, float, str). Backends declare supported keys and defaults; dd4hep.useGlobalDetector is a boolean defaulting to false. Explicit options, including false, must belong to the selected backend.

Global mode rejects an already populated detector and any second load, including retries after a failed load. It never destroys the singleton. Applications that already own a detector can use fromDD4hep(detector).

The exit-warning handler and stdout redirection remain native executable policy. Library and Python calls do not install a process exit handler; a plugin that exits can terminate their host process. No helper executable or subprocess is required.

Building

Dependencies are managed with Conan; builds with CMake + Ninja.

just recipes    # export vendored recipes (sokol-shdc)
just deps       # conan install (viewer=True)
just configure  # cmake --preset conan-relwithdebinfo
just build
just test

To build the native executable with a co-shipped WASM runtime for viewer serve and project publish, activate Emscripten and build the bundle:

source ~/emsdk/emsdk_env.sh
just bundle
build/bundle/bin/nodehammer viewer serve --no-browser

just bundle prepares both Conan configurations, builds both halves, installs them under build/bundle, and checks that the executable serves the runtime without --web-assets or NODEHAMMER_WEB_ASSETS. Use just bundle-build for incremental rebuilds, or just bundle-install to assemble existing builds and just bundle-check to check them. Both builds use RelWithDebInfo. The native build has the same importer options as just configure.

For native Geant4/GDML, DD4hep/ROOT and GeoModel SQLite support from installed Homebrew packages, use just bundle-homebrew instead of just bundle. just configure-homebrew also configures these backends independently. Subsequent just bundle-build runs preserve those options. The WASM build keeps its existing importer set. See the Homebrew backend instructions for the DD4hep plugin environment needed when importing detector XML. These native backends remain linked to your Homebrew installation; the bundle does not copy their libraries.

The runtime lives in share/nodehammer/web beside bin/; keep those directories together when moving the bundle. To choose another install prefix, pass just --set bundle_dir /absolute/path bundle (use the same override for later rebuilds and checks).

Or drive conan/cmake directly — see the Justfile for the exact flags, including the Emscripten/wasm targets (just wasm-deps, requires emsdk) and the spack-based dev configuration (configure-full) that turns on the TGeo and DD4hep importers together.

Key CMake options:

Option	Purpose	Status
NODEHAMMER_WITH_VIEWER	Build the sokol/Dear ImGui interactive viewer	✅
NODEHAMMER_WITH_TGEO	ROOT/TGeo importer	✅
NODEHAMMER_WITH_DD4HEP	DD4hep importer	✅
NODEHAMMER_WITH_GEANT4	GDML/Geant4 importer	✅ GDML via Geant4 (requires GDML support)
NODEHAMMER_WITH_GEOMODEL	GeoModel SQLite importer	Prototype; fidelity notes
NODEHAMMER_FETCH_GEOMODEL	Build pinned GeoModel Core/IO (default OFF; requires prerequisites)	Build notes
NODEHAMMER_BUILD_TESTS	Build the Catch2 unit-test binary	✅
NODEHAMMER_BUILD_SHARED	Also build and install libnodehammer and libnodehammer_ingest + the public headers + a CMake package config	🚧 packaging works; the API it exposes is still being written

With NODEHAMMER_BUILD_SHARED=ON, cmake --install adds both shared libraries, include/nodehammer/, and a package config, so a consumer needs only:

find_package(nodehammer CONFIG REQUIRED COMPONENTS Shared)
target_link_libraries(app PRIVATE nodehammer::shared)

No find_dependency for zstd, flatbuffers, manifold or the rest — the shared library absorbs them. ci/shared-build.sh runs the whole thing end to end and, on ELF, checks that nothing third-party or internal escaped into the export table. CI runs it on every native platform.

A consumer needs only C++20. nodehammer itself is built as C++23, but the installed headers do not require it, and the exported target asks for no more than cxx_std_20. ci/shared_consumer compiles at exactly that floor, so a public header reaching past it fails there rather than in your build.

On Windows the library and its consumer must agree on the C runtime (/MD vs /MT) and on _ITERATOR_DEBUG_LEVEL — so a Debug consumer needs a Debug nodehammer. This is not specific to nodehammer; it is what passing std:: types across a DLL boundary requires, and mismatches usually surface as heap corruption rather than as a link error.

Try it

The repo ships a real detector fixture — the Open Data Detector — ready to convert:

just odd    # full ODD → glb (see the Justfile for single-stave recipes too)
build/RelWithDebInfo/nodehammer viewer open

…in a browser

Every push to main publishes the wasm viewer to https://paulgessinger.github.io/nodehammer/, in both of the postures the web build supports:

/app/	the open application — empty start; drop a .nhproj or loose config/geometry files onto it
/odd/	the full Open Data Detector, preconfigured and content-locked
/odd-simple/	the simplified ODD — same, lighter to build

Each directory is a self-contained static package of the kind the viewer's Publish command emits. Reproduce the whole site locally with just pages-site after just wasm-release.

Project layout

src/           core pipeline: cli, config, ir (intermediate representation),
               scene building, tessellation, selection, the viewer, web glue
shaders/       sokol-shdc GLSL sources for the full render pipeline
schemas/       FlatBuffers schemas (render.fbs, semantic.fbs)
profiles/      Conan profiles (Emscripten cross-compilation)
recipes/       vendored/patched Conan recipes (sokol, sokol-shdc, imgui, implot, nfd)
fixtures/      sample detector geometries and configs
docs/          format specs and design docs (nhb format, predicate expressions,
               orbit navigation, rendering-fidelity strategy, PNG export)
web/           browser viewer entry point

License

MIT © Paul Gessinger — see LICENSE. Third-party license texts for vendored/bundled assets live under LICENSES/.

Embedding geometry ingestion

For experiment integration without the processing/viewer dependency stack, see the C++20 ingestion library. It reuses existing ROOT and DD4hep installations and provides nodehammer::ingest.