GDML Editor

A professional GUI application for editing GDML (Geometry Description Markup Language) files with advanced user-defined materials support.

Features

🎯 Core Functionality

• Visual GDML Editing: Browse and modify GDML geometry files with an intuitive GUI
• Volume Properties: Rename logical volumes, change materials, and inspect placements/solid parameters
• VTK Visualization: Integrated 3D geometry viewer
• NIST Database: Access to 400+ Geant4/NIST materials
• Save/Load: Read and write GDML files seamlessly
• Insert/Delete Volumes: Create simple shapes and keep the hierarchy up-to-date

🔬 User-Defined Materials

• Compound Materials: Define materials using molecular formulas (H2O, SiO2, PbF2, etc.)
• Mixture Materials: Create materials by element mass fractions
• Persistent Database: Materials saved in JSON database for reuse
• Element Dropdown: Select from all 118 periodic table elements
• Type-Ahead Filtering: Quick element search with autocomplete
• Advanced Properties: Optional state, temperature, and pressure settings
• Material Manager: Edit, delete, and organize custom materials

🚀 Professional Features

• pyg4ometry Integration: Leverages native pyg4ometry features
• Unit Conversions: Automatic handling of density, temperature, pressure units
• Error Prevention: Validation and helpful error messages
• Search: Filter the volume tree quickly

Installation

From PyPI (Recommended)

pip install gdml-editor

From Source

git clone https://github.com/drflei/gdml-editor.git
cd gdml-editor
pip install -e .

Requirements

• Python 3.8+
• pyg4ometry >= 1.0.0
• VTK >= 9.0.0

Quick Start

Launch the GUI

gdml-editor

Or from Python:

from gdml_editor.gui import main
main()

Basic Workflow

1. Open GDML File: File → Open GDML...
2. Select Volume: Click on volume in the tree
3. Edit Properties (right panel):
   • Name: edit and click Rename
   • Material: choose from the dropdown (existing registry + Geant4/NIST + user-defined) and click Apply
4. Save: File → Save or Save As...

To view the geometry in 3D: View → View in VTK

User-Defined Materials

Creating a Compound Material

Example: Lead Fluoride Crystal

1. Materials → Define New Material
2. Name: LeadFluoride
3. Type: Compound (Formula)
4. Density: 7.77 g/cm³
5. Formula: PbF2
6. Click "Save Material"

Creating a Mixture Material

Example: Stainless Steel 316

1. Materials → Define New Material
2. Name: StainlessSteel316
3. Type: Mixture (Elements)
4. Density: 8.0 g/cm³
5. Add elements:
   - Fe: 0.68
   - Cr: 0.17
   - Ni: 0.12
   - Mo: 0.03
6. Click "Save Material"

Element Selection

The element dropdown provides:

• All 118 periodic table elements
• Type-ahead filtering (type "Fe" to find Iron)
• Common elements quick reference
• Error prevention (no typos)

Material Database

Materials are stored in ~/.gdml_editor/user_materials.json and persist across sessions.

Manage Materials:

• Materials → Manage User Materials
• View, edit, or delete existing materials
• Export/import by copying JSON file

Documentation

• User Materials Guide - Creating custom materials
• Element Dropdown Guide - Element selection features

Examples

Compound Materials

from gdml_editor import UserMaterialDatabase

db = UserMaterialDatabase()

# Water
db.add_material('Water', {
    'type': 'compound',
    'density': 1.0,
    'density_unit': 'g/cm3',
    'composition': 'H2O',
    'state': 'liquid',
    'temperature': 293.15,
    'temp_unit': 'K'
})

# Silicon Dioxide
db.add_material('SiliconDioxide', {
    'type': 'compound',
    'density': 2.65,
    'density_unit': 'g/cm3',
    'composition': 'SiO2',
    'state': 'solid'
})

Mixture Materials

# Brass
db.add_material('Brass', {
    'type': 'mixture',
    'density': 8.4,
    'density_unit': 'g/cm3',
    'composition': [
        {'element': 'Cu', 'fraction': 0.65},
        {'element': 'Zn', 'fraction': 0.35}
    ],
    'state': 'solid'
})

Architecture

pyg4ometry-First Design

The application is built on pyg4ometry's native features:

• Uses MaterialCompound for chemical formulas
• Uses Material.add_element_massfraction() for mixtures
• Leverages NIST element database
• Follows Geant4 unit conventions

Modular Code Structure

• Helper Methods: Unit conversions, element management
• Single Responsibility: Each method has one clear purpose
• Clean Code: 40% reduction in code complexity
• Testable: Isolated functions for easy testing

Development

Setup Development Environment

git clone https://github.com/drflei/gdml-editor.git
cd gdml-editor
pip install -e ".[dev]"

Run Tests

pytest tests/

Code Quality

# Format code
black gdml_editor/

# Lint
flake8 gdml_editor/

# Type check
mypy gdml_editor/

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Roadmap

• Material import/export (CSV, XML)
• Material templates library
• Optical properties support
• Batch material operations
• Element tooltips with properties
• Recently used materials
• Material comparison tools
• Add/remove CSGs

License

This project is licensed under the MIT License - see the LICENSE file for details.

Citation

If you use GDML Editor in your research, please cite:

@software{gdml_editor,
  title = {GDML Editor: GUI for GDML Geometry Files},
  author = {GDML Editor Contributors},
  year = {2026},
  url = {https://github.com/drflei/gdml-editor}
}

Acknowledgments

• Built on pyg4ometry by the Geant4 community
• Uses VTK for 3D visualization
• Inspired by the needs of space particle physics detector design

Support

• 📫 Issues: GitHub Issues
• 📖 Documentation: Wiki
• 💬 Discussions: GitHub Discussions

Screenshots

Main Interface

Material Definition

Element Dropdown

---

Made with ❤️ for the particle physics community