Development Item: python displaying infrastructure

[asalzburger]

Currently, various options exist to display geometry and other objects using the python bindings.
Either direct converters (to obj, svg are used), or python plotting backends are used directly in scripts.

The aim of this project is to centralize this infrastructure, clearly divide workload on the C++ and on the python side, and make coherent entry point for extendable displaying options.

Geometry visualization

All geometry objects are composed by surfaces, hence supporting a display for surfaces (or compounds of) should be the basis of the geometry visualization.

Surfaces can be visited for display, using the IVisualization3D visitor pattern:

  /// Visualize the surface for debugging and inspection
  /// @param helper Visualization helper for 3D rendering
  /// @param gctx Geometry context for coordinate transformations
  /// @param viewConfig Visual configuration (color, style, etc.)
  void visualize(IVisualization3D& helper, const GeometryContext& gctx,
                 const ViewConfig& viewConfig = s_viewSurface) const;

There exist some specific implementations Obj, Ply that transform this directly into text based formats.

---

Workplan first steps:

• Create a GenericVisualization implementation that visits surfaces and gathers the needed information, e.g. 3D point cloud, 2D projects, identifier, coloring
• Interface this to python and display with a chosen python plotting backend

Suggested design principle

classDiagram
      class IVisualization3D {
          <<abstract>>
          +vertex(Vector3, Color)
          +face(vector~Vector3~, Color)
          +faces(vector~Vector3~, vector~FaceType~, Color)
          +line(Vector3, Vector3, Color)
          +write(path)
          +clear()
      }

      class GenericVisualization {
          -m_vertices : vector~tuple~Vector3,Color~~
          -m_faces : vector~tuple~vector~int~,Color~~
          -m_lines : vector~tuple~Vector3,Vector3,Color~~
          +vertex(Vector3, Color)
          +face(vector~Vector3~, Color)
          +faces(vector~Vector3~, vector~FaceType~, Color)
          +line(Vector3, Vector3, Color)
          +write(path)
          +clear()
          +vertices() vector~tuple~Vector3,Color~~
          +faces() vector~tuple~vector~int~,Color~~
          +lines() vector~tuple~Vector3,Vector3,Color~~
      }

      class pybind11Bindings {
          <<Python module: acts>>
          +GenericVisualization()
          +.vertices → list[tuple]
          +.faces → list[tuple]
          +.lines → list[tuple]
      }

      class MatplotlibBackend {
          <<python>>
          +plot(viz: GenericVisualization)
          +uses Poly3DCollection
          +uses Line3D
      }

      class PlotlyBackend {
          <<python>>
          +plot(viz: GenericVisualization)
          +uses go.Mesh3d
          +uses go.Scatter3d
      }

      IVisualization3D <|-- GenericVisualization : extends
      IVisualization3D <|-- ObjVisualization3D : extends
      IVisualization3D <|-- PlyVisualization3D : extends
      GenericVisualization --> pybind11Bindings : exposed via pybind11
      pybind11Bindings --> MatplotlibBackend : feeds data
      pybind11Bindings --> PlotlyBackend : feeds data

Loading

[asalzburger]

Visualization Scripts in Examples/Scripts

Scripts are grouped by subdirectory. Technologies used: Matplotlib, ROOT, PyQt5, OBJ/SVG.

---

MaterialMapping/

material_mapping_check.py

ROOT-based r-z view of material step positions with optional eta lines and projection arrows.
Input: ROOT file (material_tracks tree).
Output: ROOT TCanvas display; optional PDF save.
Key options: --distance/-d, --entries/-e, --z-range, --r-range, --arrows, --eta-lines.

Navigation/

analyze_surface_grids.py

Visualizes navigation surface grid structures (regular and variable axes), including φ-wrap correction.
Input: JSON files with grid information.
Output: Matplotlib patch/scatter plots.

GsfDebugger/

src/drawers.py

Drawer classes for projecting 3D detector state onto 2D views.

• ZRDrawer — cylindrical z-r view
• XYDrawer — transverse x-y view
• XZDrawer — longitudinal x-z view
• CsvCartesianDrawer — CSV-based detector outlines

Each exposes plot(), scatter(), annotate() onto a Matplotlib axis.

src/main.py

Interactive PyQt5 GUI for GSF algorithm debugging. Parses verbose GSF logs and shows step-by-step state evolution.
Input: GSF log file (or stdin); optional detector CSV.
Output: Interactive window with multiple Matplotlib views (z-r + x-y, or telescope mode z-x + x-y).

Python/

geometry.py

Exports tracking geometry to CSV, OBJ (3D mesh via ObjVisualization3D), and JSON.
Output: csv/, obj/geometry.obj, JSON surfaces.

blueprint.py

Creates a detector blueprint and exports it.
Output: blueprint.dot (Graphviz), blueprint.obj (3D OBJ mesh).

material_merge_rz_view.py

Matplotlib r-z plane view of volume boundaries, highlighting material discarded during merging.
Input: Tracking geometry JSON.
Output: SVG image (default geometry_rz.svg). --title sets plot title.

toroidal_field_benchmark.py

Heatmap visualization of toroidal magnetic field strength and errors.
Output: Matplotlib heatmaps (XY at z=0.20 m, ZX at y=0.10 m, error plots) with LogNorm scaling.

toroidal_field_map_benchmark.py

LUT vs analytical toroidal field comparison — performance and accuracy.
Key options: --resolution [low|medium|high], --n-points.
Output: Matplotlib field magnitude maps and error heatmaps.

[baraafanah21]

Hi! I'd like to work on this, taking on the full project across a few PRs
to keep review manageable: first the GenericVisualization C++ class (step 1
in your workplan), then the pybind11 bindings, then a matplotlib backend.

For the C++ class I mirrored the faces()/face() semantics of
ObjVisualization3D so the captured in-memory data matches the obj writer
output element-for-element, validated by a cross-validation unit test.

PR just opened — let me know if you'd prefer a different split or naming
(I used GenericVisualization3D with the 3D suffix for sibling consistency).

[andiwand]

I believe work for this has started in the context of a summer student project. @asalzburger @benjaminhuth will know more about that and if there is still room to contribute

[github-actions]

This issue/PR has been automatically marked as stale because it has not had recent activity. The stale label will be removed if any interaction occurs.