Add simple geometry visualization example to README

README.md

@@ -26,6 +26,8 @@ After cloning the celerpy repository and installing poetry, run `make setup` to:
 - install all project and development dependencies from `poetry.lock`, and
 - install pre-commit hooks.
 
+After running `make setup`, run `make install` to install celerpy into the Poetry environment.
+
 ## Development and testing
 
 Activating the poetry environment will load the python version and all development dependencies. It is faster than manually invoking `poetry run` or using the included makefile.
@@ -44,3 +46,36 @@ Style and linting should be performed automatically at every `git commit` after
 ## Release/versioning
 
 Not yet implemented:
+
+## Visualizing a geometry
+
+One of the current uses of `celerpy` is to launch the [`celer-geo`](https://celeritas-project.github.io/celeritas/user/usage/execution/utilities.html) visualization application from a Celeritas installation, send it geometry inputs, and render the resulting image in Python. The following example shows how to create an image from a GDML file:
+
+```python
+from pathlib import Path
+import matplotlib.pyplot as plt
+
+from celerpy import model, visualize
+from celerpy.settings import settings
+
+# Point to a Celeritas installation prefix containing bin/celer-geo
+settings.prefix_path = Path("path/to/celeritas/install")
+
+# Input geometry
+geometry = Path("path/to/geometry.gdml")
+
+# Set the image coordinates, direction along the rendered x-axis, and pixels
+# used for ray tracing
+image = model.ImageInput(
+    lower_left=[0, -100, -100],
+    upper_right=[0, 100, 100],
+    rightward=[0.0, 0.0, 1.0],
+    vertical_pixels=1024
+)
+
+# Start celer-geo, trace the geometry, and plot the result
+with visualize.CelerGeo.from_filename(geometry) as celer_geo:
+    trace = visualize.Imager(celer_geo, image)
+    fig, ax = plt.subplots()
+    trace(ax)
+    plt.show()

celerpy/model/input.py

@@ -146,6 +146,12 @@ class TraceInput(TraceSetup):
     image: ImageInput | None = None
     "Reuse the existing image"
 
+    def model_dump_json(self, **kwargs):
+        """Override to ensure _cmd is always set to trace."""
+        result = self.model_dump(**kwargs)
+        result["_cmd"] = "trace"
+        return to_json(result).decode()
+
 
 # celer-geo/celer-geo.cc
 class OrangeStats(_Model):

makefile

@@ -18,10 +18,13 @@ dependencies: poetry.lock
 test-dependencies: poetry.lock
 	poetry install --without=dev --with=test --no-root
 
-.PHONY: setup
+.PHONY: pre-commit
 pre-commit: dependencies
 	$(RUN) pre-commit install
 
+.PHONY: setup
+setup: pre-commit
+
 .PHONY: install
 install:
 	poetry install

test/mock-prefix/bin/celer-geo

@@ -39,15 +39,15 @@ dump(cmd)
 
 log("entering loop")
 expect_trace(
-    '{"geometry":"orange","memspace":null,"volumes":true,"image":{"lower_left":[0,0,0],"upper_right":[1,1,0],"rightward":[1,0,0],"vertical_pixels":4,"horizontal_divisor":null}}',
+    '{"geometry":"orange","memspace":null,"volumes":true,"image":{"lower_left":[0,0,0],"upper_right":[1,1,0],"rightward":[1,0,0],"vertical_pixels":4,"horizontal_divisor":null},"_cmd":"trace"}',
     '{"image":{"_units":"cgs","dims":[4,4],"down":[0.0,-1.0,0.0],"origin":[0.0,1.0,0.0],"pixel_width":0.25,"right":[1.0,0.0,0.0]},"sizeof_int":4,"trace":{"geometry":"orange","memspace":"host","volumes":true},"volumes":["[EXTERIOR]","inner","world"]}\n',
 )
 expect_trace(
-    '{"geometry": "orange", "memspace": null, "volumes": false, "image": null}',
+    '{"geometry":"orange","memspace":null,"volumes":false,"image":null,"_cmd":"trace"}',
     '{"image":{"_units":"cgs","dims":[4,4],"down":[0.0,-1.0,0.0],"origin":[0.0,1.0,0.0],"pixel_width":0.25,"right":[1.0,0.0,0.0]},"sizeof_int":4,"trace":{"geometry":"orange","memspace":"host","volumes":false}}\n',
 )
 expect_trace(
-    '{"geometry":"geant4","memspace":null,"volumes":true,"image":null}',
+    '{"geometry":"geant4","memspace":null,"volumes":true,"image":null,"_cmd":"trace"}',
     '{"image":{"_units":"cgs","dims":[4,4],"down":[0.0,-1.0,0.0],"origin":[0.0,1.0,0.0],"pixel_width":0.25,"right":[1.0,0.0,0.0]},"sizeof_int":4,"trace":{"geometry":"geant4","memspace":"host","volumes":true},"volumes":["inner","world"]}\n',
 )