### Install g4edge-testdata package

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/loading.html

Installs the g4edge-testdata package, which provides example files used by the loading examples on this page.

```bash
pip install g4edge-testdata

```

--------------------------------

### Create and visualise a simple box geometry

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/creating.html

Shows the required import and a complete example of creating a simple geometry with a world box and a smaller box placed at the origin, then visualising it with the VTK viewer. The example uses a Registry to store all objects and sets the world volume.

```python
import pyg4ometry
```

```python
 1# load pyg4ometry
 2import pyg4ometry
 3
 4# registry to store gdml data
 5reg  = pyg4ometry.geant4.Registry()
 6
 7# world solid and logical
 8ws   = pyg4ometry.geant4.solid.Box("ws",50,50,50,reg)
 9wl   = pyg4ometry.geant4.LogicalVolume(ws,"G4_Galactic","wl",reg)
10reg.setWorld(wl.name)
11
12# box placed at origin
13b1   = pyg4ometry.geant4.solid.Box("b1",10,10,10,reg)
14b1_l = pyg4ometry.geant4.LogicalVolume(b1,"G4_Fe","b1_l",reg)
15b1_p = pyg4ometry.geant4.PhysicalVolume([0,0,0],[0,0,0],b1_l,"b1_p",wl,reg)
16
17# visualise geometry
18v = pyg4ometry.visualisation.VtkViewer()
19v.addLogicalVolume(wl)
20v.addAxes(20)
21v.view()
```

--------------------------------

### Build the documentation

Source: https://pyg4ometry.readthedocs.io/en/stable/devmanual.html

Commands to install documentation dependencies, build the manual, and view the generated HTML output.

```bash
pip install '.[docs]' # to install docs building dependencies
cd pyg4ometry/docs
make
<your browser> build/html/index.html` # to view the docs
```

--------------------------------

### Complete overlap check and visualization example

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/validating.html

A full example demonstrating reading a GDML file, performing an overlap check with specific parameters, and visualizing the result using VtkViewer.

```python
1# cd pyg4ometry/test/pythonGeant4
2import pyg4ometry
3r  = pyg4ometry.freecad.Reader("./T103_overlap_copl.gdml")
4l = r.getRegistry().getWorldVolume()
5l.checkOverlaps(recursive=False,coplanar=True,debugIO=False)
6v = pyg4ometry.visualisation.VtkViewer()
7v.addLogicalVolume(l)
8v.view()
```

--------------------------------

### Example comparison output

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/comparing.html

Displays an example of the output generated when a comparison test fails.

```text
Overall result>  TestResult.Failed
Test>  position
(av): a_assembly: (pv): a_a_pv1: a_a_pv1_pos: TestResult.Failed: z: (reference): 100.0, (other): -100.0

Test>  shapeExtentBoundingBoxMin
a_assembly_a_a_pv1: TestResult.Failed: axis-aligned bounding box lower edge: dimension: z, (reference): 85.0, (other): -115.0

Test>  shapeExtentBoundingBoxMax
a_assembly_a_a_pv1: TestResult.Failed: axis-aligned bounding box upper edge: dimension: z, (reference): 115.0, (other): -85.0
```

--------------------------------

### Build and install pyg4ometry from source

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/installation.html

Clones the pyg4ometry repository and installs the package from the root directory. Requires the listed C/C++ dependencies and CMake.

```bash
$ git clone https://github.com/g4edge/pyg4ometry
$ cd pyg4ometry
$ pip install .
```

--------------------------------

### Install pyg4ometry from PyPI

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/installation.html

Installs the latest stable version of pyg4ometry from PyPI. All required C++ libraries are bundled with the wheel.

```bash
pip install pyg4ometry
```

--------------------------------

### Create and visualize a geometry with pyg4ometry

Source: https://pyg4ometry.readthedocs.io/en/stable/index.html

This example demonstrates initializing a registry, building a world volume, importing an STL file, placing it in the world, exporting to GDML, and launching a VTK viewer.

```python
import pyg4ometry as pg4
from g4edgetestdata import G4EdgeTestData

g4data = G4EdgeTestData()
# define a geometry registry
reg = pg4.geant4.Registry()

# build the world volume
world_s = pg4.geant4.solid.Orb("WorldAir", 1.5, reg, lunit="cm")
world_l = pg4.geant4.LogicalVolume(world_s, "G4_AIR", "WorldAir", reg)
reg.setWorld(world_l)

# import an STL file
reader = pg4.stl.Reader(g4data["stl/utah_teapot.stl"], registry=reg)
teapot_s = reader.getSolid()

# place the teapot in the world
teapot_l = pg4.geant4.LogicalVolume(teapot_s, "G4_Cu", "UtahTeapot", reg)
pg4.geant4.PhysicalVolume([0, 0, 0], [0, 0, 0], teapot_l, "UtahTeapot", world_l, reg)

# export to GDML file "geometry.gdml"
writer = pg4.gdml.Writer()
writer.addDetector(reg)
writer.write("./geometry.gdml")

# start an interactive VTK viewer instance
viewer = pg4.visualisation.VtkViewer()
viewer.addLogicalVolume(reg.getWorldVolume())
viewer.view()
```

--------------------------------

### Create a simple FLUKA region and visualize

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/creating.html

This example demonstrates creating a FLUKA region with an RPP body, adding it to a registry, converting it to Geant4, and visualizing the result using VtkViewer.

```python
 1import pyg4ometry.convert as convert
 2import pyg4ometry.visualisation as vi
 3from pyg4ometry.fluka import RPP, Region, Zone, FlukaRegistry
 4
 5freg = FlukaRegistry()
 6
 7rpp = RPP("RPP_BODY", 0, 10, 0, 10, 0, 10, flukaregistry=freg)
 8z = Zone()
 9z.addIntersection(rpp)
10region = Region("RPP_REG", material="COPPER")
11region.addZone(z)
12freg.addRegion(region)
13
14greg = convert.fluka2Geant4(freg)
15greg.getWorldVolume().clipSolid()
16
17v = vi.VtkViewer()
18v.addAxes(length=20)
19v.addLogicalVolume(greg.getWorldVolume())
20v.view()
```

--------------------------------

### Run Ubuntu Docker image for building

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/installation.html

Starts an interactive shell in the Ubuntu Docker image recommended for building pyg4ometry from source. The output shows the root prompt.

```bash
$ docker run -it g4edge/ubuntu:latest
root@b260417746a1:~#
```

--------------------------------

### Pull request message example

Source: https://pyg4ometry.readthedocs.io/en/stable/devmanual.html

Example of a concise pull request message for the change log.

```text
FLUKA region viewer
```

--------------------------------

### Run tests

Source: https://pyg4ometry.readthedocs.io/en/stable/devmanual.html

Commands to install test dependencies and execute the test suite using pytest.

```bash
pip install '.[test]' # to install test running dependencies
pytest
```

--------------------------------

### List logical volume keys

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/analysing.html

Prints the keys of the logicalVolumeDict, which are the names of all logical volumes in the registry. The output shows an example list of volume names.

```python
reg.logicalVolumeDict.keys()
```

```text
In [4]: reg.logicalVolumeDict.keys()
Out[4]: odict_keys(['vMonitor', 'vMonitorBack', 'vTarget', 'vTargetInnerCover', 'vTargetColumn', 'vTargetInnerColumn',
                    'vTargetVacuumSpace', 'vTargetOuterCover', 'vCrystal', 'vCrystalRow', 'vCalorimeter', 'vVetoCounter',
                    'vOuterFerrumRing', 'vInnerFerrumRing', 'vInnerCuprumRing', 'vTargetWindow', 'vTargetWindowCap',
                    'vTargetWindowMylarCover', 'vTargetWindowAluminiumCover', 'vWorldVisible', 'World'])
```

--------------------------------

### Generate two GDML files (T001_Box and T002_Tubs)

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/combining.html

Run the two example scripts to create T001_Box.gdml and T002_Tubs.gdml. The second call uses T002_Tubs(True,True) without the .Test attribute.

```python
import T001_Box
T001_Box.Test(True,True)

import T002_Tubs
T002_Tubs(True,True)

```

--------------------------------

### Create a box solid with default and explicit units

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/creating.html

Shows how to create a box solid with default units (mm) and then with explicit length unit "cm". The first example uses the default units, the second passes "cm" as the length unit kwarg.

```python
reg = pyg4ometry.geant4.Registry()
boxSolid = pyg4ometry.genat4.solid.Box("aBox", 10, 20, 30, reg)
```

```python
boxSolid = pyg4ometry.genat4.solid.Box("aBox", 10, 20, 30, reg, "cm")
```

--------------------------------

### Convert CAD to GDML using pyg4ometry

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/converting.html

This example demonstrates reading a STEP file, processing the shapes with OpenCASCADE, and writing the result to a GDML file. The mesh dictionary allows for control over the tessellation parameters for specific named bodies.

```python
 1import pyg4ometry
 2reader = pyg4ometry.pyoce.Reader("./file.stp”) # read the cad file
 3fs = reader.freeShapes() # this is a little like the CAD equivalent of the world volume
 4worldName = pyg4ometry.pyoce.pythonHelpers.get_TDataStd_Name_From_Label(fs.Value(1)) # get the actual string of the name
 5mats={} # assignment of material to named objects
 6mesh={} # control of the mesh generated for a named object
 7skip=[] # list of named objects to skip
 8reg = pyg4ometry.convert.oce2Geant4(reader.shapeTool, worldName, mats, skip, mesh, oceName=True) # oceName is essential as there are lots of degenerate names in the CAD
 9
10# to write to GDML
11writer = pyg4ometry.gdml.Writer()
12writer.addDetector(reg)
13writer.write("./file.gdml”)
```

--------------------------------

### Export scene to VTK/Paraview VTP format

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/exporting.html

Reads a GDML file, gets the world volume, and exports the scene to a VTP file using VtkViewer.

```python
import pyg4ometry
r = pyg4ometry.gdml.Reader("./Chamber.gdml")
l = r.getRegistry().getWorldVolume()
v = pyg4ometry.visualisation.VtkViewer()
v.addLogicalVolume(l)
v.exportVTPScene("Chamber")
```

--------------------------------

### Inspect volumes in a GDML file (T002_Tubs.gdml)

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/combining.html

Read a GDML file and print the names of logical and physical volumes. The example retrieves the logical volume 'tl' from the registry.

```python
import pyg4ometry
r = pyg4ometry.gdml.Reader("T002_Tubs.gdml")
reg = r.getRegistry()

# printing the names of the logical volumes
print(reg.logicalVolumeDict.keys())

# printing the names of the physical volumes
print(reg.physicalVolumeDict.keys())

lv = reg.logicalVolume["tl"]

```

--------------------------------

### Format commit messages

Source: https://pyg4ometry.readthedocs.io/en/stable/devmanual.html

Standard format for commit messages, including an example of a submodule-specific change.

```text
submodule : (type of change) detailed notes
```

```text
pycgal : (extra functionality) more 2d mesh processing
```

--------------------------------

### Only Volume: create Tests and compare GDML files

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/comparing.html

Two ways to create a test set that only checks shape volume. The first starts with all tests disabled and enables only shapeVolume; the second constructs Tests with the test name directly. Both then run gdmlFiles on two files and print the comparison.

```python
>>> import pyg4ometry
>>> t = pyg4ometry.compare.Tests()
>>> pyg4ometry.compare.Tests.printAllTestNames()
    "names"
    "namesIgnorePointer"
    "nDaughters"
    "solidExact"
    "solidExtent"
    "shapeExtent"
    "shapeVolume"
    "shapeArea"
    "placement"
    "scale"
    "copyNumber"
    "materials"
    "materialClassType"
    "materialCompositionType"
    "testDaughtersByName"
>>> t.setAllFalse()
>>> t.shapeVolume = True
>>> comparison = pyg4ometry.compare.gdmlFiles("file1.gdml", "file2.gdml", t)
>>> comparison.print()

```

```python
>>> import pyg4ometry
>>> t2 = pyg4ometry.compare.Tests("shapeVolume")
>>> comparison = pyg4ometry.compare.gdmlFiles("file1.gdml", "file2.gdml", t2)
>>> comparison.print()

```

--------------------------------

### Run pyg4ometry Docker image

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/installation.html

Runs the latest stable pyg4ometry Docker image from Docker Hub and starts a Python interpreter. The output shows the Python version and a successful import of pyg4ometry.

```bash
$ docker run g4edge/pyg4ometry:latest python
Python 3.10.12 (main, Jun 11 2023, 05:26:28) [GCC 11.4.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import pyg4ometry
>>>
```

--------------------------------

### Read GDML file and get registry

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/analysing.html

Creates a pyg4ometry GDML reader for 'lht.gdml' and retrieves the registry instance. The registry is used to access logical volumes.

```python
import pyg4ometry
r = pyg4ometry.gdml.Reader("lht.gdml")
reg = r.getRegistry()
```

--------------------------------

### Configure VtkViewerNew pipelines

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/viewing.html

Demonstrates the pipeline building methods for the new development viewer, noting that buildPipelinesAppend and buildPipelinesTransformed are faster alternatives to the old behavior.

```python
v = pyg4ometry.visualisation.VtkViewerNew()
v.addLogicalVolume(lv)
v.buildPipelinesSeparate()  # (old behaviour) or
v.buildPipelinesAppend()  # (much faster) or
v.buildPipelinesTransformed()  # (alternative faster)
v.view()  # or
v.view(interactive=False)
```

--------------------------------

### Create and view geometry with VtkViewer

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/viewing.html

Creates a VtkViewer, adds a logical volume, and displays it. Use view(interactive=False) to avoid blocking the terminal.

```python
v = pyg4ometry.visualisation.VtkViewer()
v.addLogicalVolume(lv)
v.view()  # or
v.view(interactive=False)  # to not block the terminal
```

--------------------------------

### CLI Usage and Options

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/cli.html

Displays the full list of available command-line options and flags for the pyg4ometry executable.

```text
Usage: pyg4ometry [options]

Options:
  -h, --help            show this help message and exit
  -a, --analysis        geometry information
  -b, --bounding        calculate bounding box
  -c, --checkoverlaps   check overlaps
  -C CLIP, --clip=CLIP  clip to a box of full widths px,py,pz in mm
  -d COMPAREFILE, --compare=COMPAREFILE
                        comp(a)re geometry
  -e APPENDFILE, --append=APPENDFILE
                        append geometry
  -f FEATUREDATA, --feature=FEATUREDATA
                        feature extraction from simple geometry
                        (planeQuality,circumference)
  -F FEATUREFILE, --featureExtractOutput=FEATUREFILE
                        feature extract output
  -i INFILE, --file=INFILE
                        (i)nput file (gdml, stl, inp, step)
  -I INFO, --info=INFO  information on geometry (tree, reg, instance)
  -l LVNAME, --logical=LVNAME
                        extract logical LVNAME
  -m MATERIAL, --material=MATERIAL
                        material dictionary ("lvname":"nist")
  -n, --nullmesh        disable null mesh exception
  -o OUTFILE, --output=OUTFILE
                        (o)utout file (gdml, inp, usd, vtp)
  -p PLANECUTTER, --planeCutter=PLANECUTTER
                        add (p)plane cutter -p x,y,z,nx,ny,nz
  -P CUTTERFILE, --planeCutterOutput=CUTTERFILE
                        plane cutter output file
  -r TX,TY,TZ, --rotation=TX,TY,TZ
                        rotation (Tait-Bryan) tx,ty,tz (used with
                        append/exchange)
  -s PYTHONSOLID, --solid=PYTHONSOLID
                        solid in python constructor syntax (used with
                        exchange). Registry must be reg and _np used for numpy
  -S SCALE, --gltfScale=SCALE
                        scale factor for gltf conversion
  -t X,Y,Z, --translation=X,Y,Z
                        translation x,y,z (used with append/exchange)
  -v, --view            view geometry
  -V, --verbose         verbose script
  -x LVNAME, --exchange=LVNAME
                        replace solid for logical volume, LVNAME is logical
                        volume name
  -z, --citation        print citation text
```

--------------------------------

### Configure USD Visualization Options

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/rendering.html

Set visualization options like color for specific logical volumes before saving the USD file.

```python
1r = pyg4ometry.gdml.Reader("lht.gdml")
2reg = r.getRegistry()
3reg.logicalVolumeDict["vCalorimeter"].visOptions.color = [1, 0, 0]
4v = pyg4ometry.visualisation.UsdViewer("lht.usd")
5v.traverseHierarchy(reg.getWorldVolume())
6v.save()
```

--------------------------------

### Get logical volume by name

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/analysing.html

Retrieves a LogicalVolume object from the registry's logicalVolumeDict using its name. The resulting 'lv' can be used for geometry manipulation and visualisation.

```python
lv = reg.logicalVolumeDict['vTargetInnerColumn']
```

--------------------------------

### Rotation and Translation Flags

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/cli.html

Examples of specifying Tait-Bryan rotations and translations using comma-separated values. These flags are used in conjunction with other commands like append or exchange.

```bash
-r 0,pi/2,0
-r -3*pi/2,0,0
-t 10,123.45,100
```

--------------------------------

### Configure pre-commit hooks

Source: https://pyg4ometry.readthedocs.io/en/stable/devmanual.html

Commands to initialize and run pre-commit hooks for code quality checks.

```bash
pre-commit install  # to setup pre-commit in source dir (only once)
pre-commit run --all-files # run pre-commit locally
pre-commit run --all-files black  #run only black
```

--------------------------------

### Create a Physical Volume with No Rotation

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/creating.html

Demonstrates placing a water box inside a vacuum world volume with no offset or rotation.

```python
 1import pyg4ometry
 2
 3r = pyg4ometry.geant4.Registry()
 4vacuum = _g4.MaterialPredefined("G4_Galactic")
 5water = _g4.MaterialPredefined("G4_WATER")
 6worldSolid = pyg4ometry.geant4.solid.Box("world_solid", 100, 100, 100, reg)
 7boxSolid = pyg4ometry.geant4.solid.Box("box_solid", 10, 20, 40, reg)
 8worldLV = pyg4ometry.geant4.LogicalVolume(worldSolid, vacuum, "world_lv", reg)
 9boxLV = pyg4ometry.geant4.LogicalVolume(boxSolid, water, "box_lv", reg)
10
11pyg4ometry.geant4.PhysicalVolume([0, 0, 0], [0, 0, 0], boxLV, "box_pv", worldLV, reg)
```

--------------------------------

### Load STEP file and convert to Geant4

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/loading.html

Loads a STEP file, converts it to a Geant4 model with pyg4ometry.convert.oce2Geant4, and visualises the world volume. Basic loading only; no material assignment is performed.

```python
 1import pyg4ometry
 2import g4edgetestdata
 3
 4d = g4edgetestdata.G4EdgeTestData()
 5r = pyg4ometry.pyoce.Reader(d["step/1_BasicSolids_Bodies.step"])
 6ls = r.freeShapes()
 7worldName = pyg4ometry.pyoce.pythonHelpers.get_TDataStd_Name_From_Label(ls.Value(1))
 8mats, skip, mesh = {}, [], {}
 9reg = pyg4ometry.convert.oce2Geant4(r.shapeTool, worldName, mats, skip, mesh)
10wl = reg.logicalVolumeDict[worldName]
11v = pyg4ometry.visualisation.VtkViewerColouredMaterial()
12v.addLogicalVolume(wl)
13v.view()

```

--------------------------------

### Load STL mesh and create logical volume

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/loading.html

Loads an STL file, converts the mesh to a TesselatedSolid, creates a logical volume with a predefined copper material, and visualises it. Press 's' in the visualiser for solid mode and 'w' for wireframe.

```python
 1import pyg4ometry
 2import g4edgetestdata
 3
 4d = g4edgetestdata.G4EdgeTestData()
 5reg = pyg4ometry.geant4.Registry()
 6r = pyg4ometry.stl.Reader(d["stl/utah_teapot.stl"], reg)
 7s = r.getSolid()
 8copper = pyg4ometry.geant4.MaterialPredefined("G4_Cu", reg)
 9l = pyg4ometry.geant4.LogicalVolume(s, copper, "utahteapot_lv", reg)
10v = pyg4ometry.visualisation.VtkViewerColouredMaterial()
11v.addLogicalVolume(l)
12v.view()

```

--------------------------------

### Write GDML file with gdml.Writer

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/exporting.html

Creates a GDML file from a registry instance. Also writes a GMAD tester file for a quick bdsim job.

```python
import pyg4ometry
w = pyg4ometry.gdml.Writer()
w.addDetector(reg)
w.write('file.gdml')
# make a quick bdsim job for the one component in a beam line
w.writeGmadTester('file.gmad', 'file.gdml')
```

--------------------------------

### G4Box Constructor Comparison

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/creating.html

Comparison between the pyg4ometry Python constructor and the standard Geant4 C++ constructor for G4Box.

```python
pyg4ometry.geant4.solid.Box(name, pX, pY, pZ, registry, lunit)
```

```cpp
G4Box(const G4String& pName, G4double  pX, G4double  pY, G4double pZ)
```

--------------------------------

### Create OpticalSurface and assign to SkinSurface or BorderSurface

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/creating.html

Defines optical surfaces with specific finish, model, and type, then assigns them to volumes using SkinSurface or BorderSurface.

```python
 1opa = _g4.solid.OpticalSurface(
 2    "AirSurface",
 3    finish="polished",
 4    model="glisur",
 5    surf_type="dielectric_dielectric",
 6    value="1",
 7    registry=reg,
 8)
 9opw = _g4.solid.OpticalSurface(
10    "WaterSurface",
11    finish="ground",
12    model="unified",
13    surf_type="dielectric_dielectric",
14    value="0",
15    registry=reg,
16)
17
18_g4.SkinSurface("AirSurface", air_lv, opa, reg)
19_g4.BorderSurface("WaterSurface", water_phys, world_phys, opw, reg)
```

--------------------------------

### Construct Geometry with Constants

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/creating.html

Build a box geometry using GDML constants for dimensions and visualize the result.

```python
 1# load pyg4ometry
 2import pyg4ometry
 3
 4# registry to store gdml data
 5reg  = pyg4ometry.geant4.Registry()
 6
 7bx = pyg4ometry.gdml.Constant("bx","10",reg,True)
 8by = pyg4ometry.gdml.Constant("by",2*bx,reg,True)
 9bz = pyg4ometry.gdml.Constant("bz",2*by,reg,True)
10
11# world solid and logical
12ws   = pyg4ometry.geant4.solid.Box("ws",50,50,50,reg)
13wl   = pyg4ometry.geant4.LogicalVolume(ws,"G4_Galactic","wl",reg)
14
15# box placed at origin
16b1   = pyg4ometry.geant4.solid.Box("b1",bx,by,bz,reg)
17b1_l = pyg4ometry.geant4.LogicalVolume(b1,"G4_Fe","b1_l",reg)
18b1_p = pyg4ometry.geant4.PhysicalVolume([0,0,0],[0,0,0],b1_l,"b1_p",wl,reg)
19
20# visualise geometry
21v = pyg4ometry.visualisation.VtkViewer()
22v.addLogicalVolume(wl)
23v.addAxes(20)
24v.view()
```

--------------------------------

### Export scene to OBJ for Unity/Unreal/Blender

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/exporting.html

Creates an OBJ file from a GDML geometry using VtkViewer. Writes Chamber.obj and Chamber.mtl.

```python
import pyg4ometry
r = pyg4ometry.gdml.Reader("./Chamber.gdml")
l = r.getRegistry().getWorldVolume()
v = pyg4ometry.visualisation.VtkViewer()
v.addLogicalVolume(l)
v.exportOBJScene("Chamber")
```

--------------------------------

### Create a GDML Constant

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/creating.html

Initialize a registry and define a constant named 'x' with a value of 10.

```python
# registry to store gdml data
reg = pyg4ometry.geant4.Registry()

# constant called x
x = pyg4ometry.gdml.Constant("x",10,reg)
```

--------------------------------

### Create a Physical Volume with Rotation

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/creating.html

Demonstrates placing a volume with a rotation of π/3 radians about the y-axis using Tait-Bryan angles.

```python
1import numpy as np
2
3pyg4ometry.geant4.PhysicalVolume(
4    [0, np.pi / 3.0, 0], [0, 0, 0], boxLV, "box_pv", worldLV, reg
5)
```

--------------------------------

### Export per-object meshes with RenderWriter

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/exporting.html

Writes each mesh in OBJ format to a directory along with an instance file 0_instances.dat.

```python
import pyg4ometry

r = pyg4ometry.gdml.Reader("./Chamber.gdml")
l = r.getRegistry().getWorldVolume()
w = pyg4ometry.visualisation.RenderWriter()
w.addLogicalVolumeRecursive(l)
w.write("./SphericalChamber")
```

--------------------------------

### Visualize an individual solid

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/viewing.html

Use VtkViewer to render an instance from the pyg4ometry.geant4.solid module. The solid is placed at the center of the scene by default.

```python
s  # e.g. a pyg4ometry.geant4.solid.Box instance
v = pyg4ometry.visualisation.VtkViewer()
v.addSolid(s)
v.view()
```

--------------------------------

### Write Flair file from FLUKA input

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/converting.html

Writes a Flair file based on an existing FLUKA input file. Requires the logical volume's extent (including bounding solid) to define the geometry bounds. The resulting .flair file can be loaded into Flair.

```python
1 extent = logical.extent(includeBoundingSolid=True)
2 f = pyg4ometry.fluka.Flair("FileName.inp",extent)
3 f.write("FileName.flair")
```

--------------------------------

### Define Compound Materials by Mass Fraction

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/creating.html

Creating a compound material by adding elements using their mass fraction.

```python
1import pyg4ometry.geant4 as _g4
2wm = _g4.MaterialCompound("air",1.290e-3,2,reg)
3ne = _g4.ElementSimple("nitrogen","N",7,14.01)
4oe = _g4.ElementSimple("oxygen","O",8,16.0)
5wm.add_element_massfraction(ne,0.7)
6wm.add_element_massfraction(oe,0.3)
7bm = _g4.MaterialSingleElement("iron",26,55.8452,7.874,reg)    # iron at near room temp
```

--------------------------------

### View Geometry

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/cli.html

Commands to visualize geometry files, including local files and those from the g4edge test data repository.

```bash
pyg4ometry -i box.gdml -v
```

```bash
pyg4ometry -i g4edgetestdata/gdml/CompoundExamples/bdsim/vkickers.gdml -v
```

--------------------------------

### Load ROOT TGeo geometry with pyg4ometry.io.ROOTTGeo.Reader

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/loading.html

Loads a ROOT TGeo file using pyg4ometry.io.ROOTTGeo.Reader, retrieves the world volume, and visualises it.

```python
1import pyg4ometry
2import g4edgetestdata
3
4d = g4edgetestdata.G4EdgeTestData()
5r = pyg4ometry.io.ROOTTGeo.Reader(d["root/lht.root"])
6l = r.getRegistry().getWorldVolume()
7v = pyg4ometry.visualisation.VtkViewerColouredMaterial()
8v.addLogicalVolume(l)
9v.view()

```

--------------------------------

### Visualize a LogicalVolume

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/viewing.html

Add a LogicalVolume instance to the VtkViewer to display it in the center of the coordinate system.

```python
1lv  # pyg4ometry.geant4.LogicalVolume instance
2v = pyg4ometry.visualisation.VtkViewer()
3v.addLogicalVolume(lv)
4v.view()
```

--------------------------------

### Add properties to materials

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/creating.html

Demonstrates adding constant and vector-based properties to a material instance for use in Geant4 processes.

```python
1scint = _g4.Material(...)
2scint.addConstProperty("SCINTILLATIONTIMECONSTANT1", 2.5, vunit="ns")
3scint.addConstProperty("SCINTILLATIONYIELD", 8000, vunit="/MeV")
4scint.addVecProperty("RINDEX", [1, 10], [1.3, 1.05])
```

--------------------------------

### Convert GDML to USD

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/rendering.html

Load a GDML file and convert it to a USD file using the UsdViewer.

```python
1r = pyg4ometry.gdml.Reader("lht.gdml")
2l = r.getRegistry().getWorldVolume()
3v = pyg4ometry.visualisation.UsdViewer("lht.usd")
4v.traverseHierarchy(l)
5v.save()
```

--------------------------------

### Define Elements from Isotopes

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/creating.html

Creating an element by defining its isotope mixture.

```python
1import pyg4ometry.geant4 as _g4
2u235 = _g4.Isotope("U235", 92, 235, 235.044)
3u238 = _g4.Isotope("U238", 92, 238, 238.051)
4uranium = _g4.ElementIsotopeMixture("uranium", "U", 2)
5uranium.add_isotope(u235, 0.00716)
6uranium.add_isotope(u238, 0.99284)
7bm = _g4.MaterialCompound("natural_uranium", 19.1, 1, reg)
8bm.add_element_massfraction(uranium, 1)
```

--------------------------------

### Load GDML geometry with pyg4ometry.gdml.Reader

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/loading.html

Loads a GDML file using pyg4ometry.gdml.Reader, retrieves the world volume from the registry, and displays it with VtkViewerColouredMaterial.

```python
1import pyg4ometry
2import g4edgetestdata
3
4d = g4edgetestdata.G4EdgeTestData()
5r = pyg4ometry.gdml.Reader(d["gdml/ChargeExchangeMC/lht.gdml"])
6l = r.getRegistry().getWorldVolume()
7v = pyg4ometry.visualisation.VtkViewerColouredMaterial()
8v.addLogicalVolume(l)
9v.view()

```

--------------------------------

### Compare GDML files

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/comparing.html

Compares two GDML files using the pyg4ometry.compare.gdmlFiles function and prints the result.

```python
>>> comparison = pyg4ometry.compare.gdmlFiles("file_reference.gdml", "file_other.gdml")
>>> comparison.print()
```

--------------------------------

### Visualize FLUKA geometry with VtkViewerNew

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/viewing.html

Basic workflow to read a FLUKA input file and visualize its regions using the VtkViewerNew.

```python
r = pyg4ometry.fluka.Reader("./FLUKA_FILE.inp")
v = pyg4ometry.visualisation.VtkViewerNew()
v.addFlukaRegions(r.getRegistry())
v.buildPipelinesAppend()
v.view()
```

--------------------------------

### Apply rotation and translation to a LogicalVolume

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/viewing.html

Use Tait-Bryan angles to define a rotation matrix and apply it along with a translation when adding a LogicalVolume to the viewer.

```python
1import numpy as np
2
3rotation = [0, np.pi / 2, 0]  # for example
4matrix = np.linalg.inv(pyg4ometry.transformation.tbxyz2matrix(rotation))
5l  # a pyg4ometry.geant4.LogicalVolume instance
6v = pyg4ometry.visualisation.VtkViewer()
7v.addLogicalVolume(l, mtra=rotation, tra=[0, 0, 500])
```

--------------------------------

### Convert GDML to FLUKA input file

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/converting.html

Converts a GDML geometry to a FLUKA input file. The conversion is a work in progress; not all Geant4-GDML constructions are implemented. All GDML placements are respected, but materials, scaled solids, reflections, and division/replica/parameterised placements are not yet supported.

```python
1import pyg4ometry
2reader = pyg4ometry.gdml.Reader("input.gdml")
3greg = reader.getRegistry()
4freg = pyg4ometry.convert.geant4Reg2FlukaReg(greg)
5w = pyg4ometry.fluka.Writer()
6w.addDetector(freg)
7w.write("FileName.inp")
```

--------------------------------

### Export FLUKA geometry to OBJ

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/exporting.html

Converts a FLUKA file to Geant4, then exports the scene to OBJ using VtkViewer.

```python
import pyg4ometry
r = pyg4ometry.fluka.Reader("./Chamber.inp")
greg = pyg4ometry.convert.fluka2Geant4(r.getRegistry())
l = greg.getWorldVolume()
v = pyg4ometry.visualisation.VtkViewer()
v.addLogicalVolume(l)
v.exportOBJScene("Chamber")
```

--------------------------------

### Define Compound Materials by Number of Atoms

Source: https://pyg4ometry.readthedocs.io/en/stable/manual/creating.html

Creating a compound material by specifying the number of atoms for each element.

```python
1import pyg4ometry.geant4 as _g4
2bm = _g4.MaterialCompound("plastic",1.38,3,reg)    # Generic PET C_10 H_8 O_4
3he = _g4.ElementSimple("hydrogen","H",1,1.008)
4ce = _g4.ElementSimple("carbon","C",6,12.0096)
5oe = _g4.ElementSimple("oxygen","O",8,16.0)
6bm.add_element_natoms(he,8)
7bm.add_element_natoms(ce,10)
8bm.add_element_natoms(oe,4)
```