g4web is a browser-based graphical user interface for defining detector geometry for Geant4-based particle physics simulations. It is built on top of the official Three.js Editor and extends it with Geant4-specific solid geometries, material assignment, and geometry export to the Text-based Geometry (TG) format accepted by GEARS.

A live demo is available at https://jintonic.github.io/g4web/.

• What does g4web do?
• Who is it for?
• Features
• Usage
  • Adding a Solid
  • Selecting and Moving Objects
  • Editing Geometry Parameters
  • Assigning a Geant4 Material
  • Inspecting the Geometry
  • Saving the Scene
  • Exporting for Geant4
  • Importing Geometry
  • Keyboard Shortcuts
• Screenshots
• Citation
• Contributing
• License

g4web provides a point-and-click interface for constructing Geant4 detector geometries without writing any C++ or macro code. Users can:

• Place and configure Geant4 solid shapes (Box, Tube, Sphere, Cone, Torus, and more) in a 3D viewport.
• Assign Geant4 NIST materials (including elements, compounds, HEP/nuclear materials, space materials, and bio-chemical materials) to volumes.
• Inspect the detector geometry interactively in the browser.
• Export the geometry to .tg (Text-based Geometry) and .mac (Geant4 macro) files for use with Geant4-based simulation tools such as GEARS.

g4web is designed for:

• Experimental physicists who need to prototype detector geometries quickly without deep C++ expertise.
• Nuclear and particle physics students learning Geant4 simulation for the first time.
• Educators teaching detector simulation in courses or workshops.
• Researchers who use Geant4-based tools (e.g., GEARS) and want a visual geometry editor.

• 20+ Geant4 solid types: G4Box, G4Tubs, G4Cons, G4Sphere, G4Torus, G4Para, G4Trd, G4Trap, G4Polycone, G4Polyhedra, G4Ellipsoid, twisted solids, and more.
• Full NIST material database browsable by category (elements, NIST compounds, HEP & nuclear, space, bio-chemical).
• Export to .tg (Text-based Geometry) and .mac (Geant4 run macro) formats.
• Auto-save of the scene to browser local storage.
• File drag-and-drop import.
• Non-destructive customization pattern — vendor (Three.js) files are never modified.
• Deployed automatically to GitHub Pages on every push to main.

g4web presents a 3D viewport in the centre of the screen, a left panel of Geant4 solid shapes, and a right sidebar with Object, Geometry, and Material tabs for configuration.

Click any shape icon in the left panel to place it in the 3D scene. Available shapes include:

You can also drag a shape icon into the viewport to place the solid at the cursor position.

• Left-click an object in the viewport to select it.
• Use the transform gizmo (top-left toolbar) to translate or rotate.
• Numeric values can also be edited directly in the Object tab of the sidebar.

1. Select an object in the viewport.
2. Open the Geometry tab in the right sidebar.
3. Adjust the dimension parameters (e.g., half-lengths, radii, angles).

Parameters correspond 1-to-1 to Geant4 constructor arguments. Units are in centimetres for lengths and degrees for angles.

1. Select an object in the viewport.
2. Open the Material tab in the right sidebar.
3. Choose a Category:
   • Elements (Periodic Table) — pure elements, e.g. G4_H, G4_Fe
   • NIST Compounds — pre-defined NIST materials, e.g. G4_WATER, G4_AIR
   • HEP & Nuclear — detector-specific materials, e.g. G4_lH2, G4_lN2
   • Space Materials — e.g. G4_KEVLAR
   • Bio-Chemical — e.g. G4_CYTOSINE
4. Select the desired material from the drop-down list.

The selected material is stored in object.userData.g4Material and serialised with the scene.

• Orbit: left-click and drag.
• Zoom: scroll wheel.
• Pan: right-click and drag (or middle-click and drag).
• Use the View menu to toggle helpers (grid, axes, etc.).

The scene is auto-saved to browser local storage as you work. To save it as a JSON file for backup or sharing, use File → Export → Scene (JSON) from the menubar.

g4web can export the scene to two files:

• detector.tg — A human-readable Text-based Geometry description accepted by GEARS and other tools that support the Geant4 text geometry reader.
• run.mac — A starter Geant4 macro that initialises the geometry, configures a 2.6 MeV isotropic gamma-ray source, and runs 100 events.

To export:

1. Click File → Export → TG in the menubar.
2. A preview panel shows both the .tg and .mac content.
3. Use the download buttons to save the files to your computer.

For details on the .tg format, supported solids, units convention, and current limitations (e.g. CSG boolean operations are not yet exported), see docs/geometry-export.md.

Drag and drop a previously exported .json scene file, or a supported 3D file (OBJ, STL, GLTF), onto the viewport to import it.

A screenshot of the g4web user interface showing the 3D viewport, left solid palette, and Geant4 material selection panel.

If you use g4web in research that leads to a publication, please cite:

@article{g4web_joss,
  author  = {Liu, Jing},
  title   = {g4web: A web-based user interface for Geant4 detector definition},
  journal = {Journal of Open Source Software},
  year    = {2026},
  note    = {(submitted)}
}

See CITATION.cff for machine-readable citation metadata.

Contributions are welcome! Please read CONTRIBUTING.md first — this project uses a non-destructive customization pattern to keep vendor (Three.js) files pristine.

For bug reports and feature requests, use the GitHub issue tracker.

g4web is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

The bundled Three.js editor (vendor/threejs/) is licensed under the MIT License.