root-geo-tree-editor

Navigate, search, and edit CERN ROOT TGeo geometry trees in JavaScript/TypeScript. Works with geometry structures produced by JSROOT.

Install

npm install @dexvis/root-geo-tree-editor

Node structure

The library operates on ROOT TGeo node objects with this shape:

node.fName           — node name
node.fVolume         — associated volume (contains fNodes, fGeoAtt)
node.fMasterVolume   — master volume (used instead of fVolume when present)
node.fMother         — parent volume
node.fVolume.fNodes.arr — child nodes array
node.fVolume.fGeoAtt    — visibility attribute bitmask

Full paths are built as "Root/Child/GrandChild" during traversal.

API

Navigation

walkGeoNodes(node, callback, maxLevel?, level?, path?, pattern?)

Recursively traverses the geometry tree. The callback receives each node, its full path, and depth level. Return false from the callback to stop descending into children.

import { walkGeoNodes } from '@dexvis/root-geo-tree-editor';

// Count all nodes up to depth 3
let count = walkGeoNodes(topNode, null, 3);

// Walk with a callback
walkGeoNodes(topNode, (node, fullPath, level) => {
  console.log(`${fullPath} (level ${level})`);
  return true; // continue into children
}, Infinity);

// Walk only nodes matching a wildcard pattern
walkGeoNodes(topNode, (node, fullPath, level) => {
  console.log('Matched:', fullPath);
  return true;
}, Infinity, 0, "", "*Tracker*");

findGeoNodes(node, pattern, maxLevel?)

Finds all nodes whose full path matches a wildcard pattern. Returns { geoNode, fullPath }[].

import { findGeoNodes } from '@dexvis/root-geo-tree-editor';

const results = findGeoNodes(topNode, "*Calorimeter*");
results.forEach(r => console.log(r.fullPath));

// Limit search depth
const shallow = findGeoNodes(topNode, "*Child*", 2);

findSingleGeoNode(topNode, pattern, maxLevel?)

Returns a single matching node or null. Throws if more than one node matches.

import { findSingleGeoNode } from '@dexvis/root-geo-tree-editor';

const node = findSingleGeoNode(topNode, "*InnerTracker*");

getGeoNodesByLevel(topNode, selectLevel?)

Collects all nodes at a specific depth. Returns { geoNode, fullPath }[].

import { getGeoNodesByLevel } from '@dexvis/root-geo-tree-editor';

// Get all level-1 (direct children) nodes
const children = getGeoNodesByLevel(topNode, 1);

analyzeGeoNodes(node)

Logs a summary of top-level subcomponents and their total descendant counts.

import { analyzeGeoNodes } from '@dexvis/root-geo-tree-editor';

analyzeGeoNodes(geoManager.fMasterVolume);
// Output:
//   --- Detector subcomponents [num]-[name]: 5
//     12034: Root/Tracker
//     8921: Root/Calorimeter
//     ...
//   --- End of analysis --- Total elements: 34210

findGeoManager(file)

Finds and reads the TGeoManager object from a ROOT file.

import { findGeoManager } from '@dexvis/root-geo-tree-editor';

const geoManager = await findGeoManager(file);
const topNode = geoManager.fMasterVolume;

Editing

EditActions enum

Action	Description
Nothing	No action
Remove	Remove the matched node from its parent
RemoveSiblings	Keep only the matched node, remove its siblings
RemoveChildren	Remove all children of the matched node
RemoveBySubLevel	Remove descendants below N levels (set pruneSubLevel)
SetGeoBit	Set a visibility bit on the node's volume
UnsetGeoBit	Clear a visibility bit
ToggleGeoBit	Toggle a visibility bit

GeoNodeEditRule

class GeoNodeEditRule {
  pattern: string;                    // wildcard pattern to match node paths
  action?: EditActions;               // action to perform
  pruneSubLevel?: number;             // depth for RemoveBySubLevel
  geoBit?: GeoAttBits;               // bit for Set/Unset/ToggleGeoBit actions
  childrenRules?: GeoNodeEditRule[];  // rules applied to children first
  childrenRulesMaxLevel?: number;     // max depth for children rules
}

editGeoNodes(topNode, rules, maxLevel?)

Applies edit rules to matching nodes in the geometry tree.

import { editGeoNodes, EditActions, GeoNodeEditRule } from '@dexvis/root-geo-tree-editor';
import { GeoAttBits } from '@dexvis/root-geo-tree-editor';

// Remove specific nodes
editGeoNodes(topNode, [
  { pattern: "*/SupportStructure*", action: EditActions.Remove }
]);

// Keep only one subdetector, remove its siblings
editGeoNodes(topNode, [
  { pattern: "*/Tracker", action: EditActions.RemoveSiblings }
]);

// Remove all children of a node
editGeoNodes(topNode, [
  { pattern: "*/Beampipe", action: EditActions.RemoveChildren }
]);

// Set visibility on matched nodes
editGeoNodes(topNode, [
  {
    pattern: "*/Tracker",
    action: EditActions.SetGeoBit,
    geoBit: GeoAttBits.kVisThis
  }
]);

// Nested rules: apply children rules before the main action
editGeoNodes(topNode, [
  {
    pattern: "*/Calorimeter",
    action: EditActions.Nothing,
    childrenRules: [
      { pattern: "*/Absorber*", action: EditActions.Remove }
    ],
    childrenRulesMaxLevel: 3
  }
]);

removeGeoNode(node) / removeChildren(node)

Low-level helpers to remove a single node from its parent or clear all children.

import { removeGeoNode, removeChildren } from '@dexvis/root-geo-tree-editor';

removeGeoNode(someNode);   // splices node out of parent's array
removeChildren(someNode);  // empties node's children array

Attribute Bits

GeoAttBits enum

Maps to ROOT's TGeoAtt visibility flags:

Flag	Description
kVisOverride	Volume's visibility attributes are overwritten
kVisNone	Volume and daughters are invisible
kVisThis	This volume is visible
kVisDaughters	All leaves are visible
kVisOneLevel	First-level daughters are visible
kVisContainers	All containers visible
kVisOnly	Only this volume visible
kVisBranch	Only a given branch visible
kVisRaytrace	Raytracing flag

testGeoBit(volume, flag) / setGeoBit(volume, flag, value) / toggleGeoBit(volume, flag)

Read, set, or toggle individual visibility bits on a volume's fGeoAtt.

import { GeoAttBits, testGeoBit, setGeoBit, toggleGeoBit } from '@dexvis/root-geo-tree-editor';

if (!testGeoBit(volume, GeoAttBits.kVisThis)) {
  setGeoBit(volume, GeoAttBits.kVisThis, 1);  // make visible
}

toggleGeoBit(volume, GeoAttBits.kVisDaughters);

setGeoBit(volume, GeoAttBits.kVisNone, 0);  // clear "invisible" flag

printAllGeoBitsStatus(volume)

Logs the state of all visibility flags for a volume.

import { printAllGeoBitsStatus } from '@dexvis/root-geo-tree-editor';

printAllGeoBitsStatus(volume);
// kVisOverride  : No
// kVisNone      : No
// kVisThis      : Yes
// ...

Wildcard patterns

Pattern matching uses * (any characters) and ? (single character) against full node paths.

Pattern	Matches
*Tracker*	Any path containing "Tracker"
*/Child1	Direct or nested node named "Child1"
Root/*/Sensor?	"Sensor" + one char, two levels below Root

License

MIT