Cross-platform scientific platform for beam trajectory analysis, optical surface reconstruction, Monte Carlo post-processing, and biological tissue dosimetry.
I study Physics (4th year, Universidad Santa María — Chile). Not Computer Science.
I built v0.1.0 in roughly two weeks while preparing for exams, taking my IELTS (got C1), and surviving a Quantum Mechanics II test that went... let's just say "character building". v0.2.0 adds a real biological simulator: Bethe-Bloch energy loss through tissue, muon tracking, scoring planes. Also built between exams.
If you find a bug, please fix it — I'm probably at KIT in Germany by the time you read this. Pull requests are extremely welcome.
— José
BeamLabStudio is the full professional rewrite of MuonSimViewer. MuonSimViewer was the weekend hack. This is the version you can actually use in a real lab.
This software was created for science, by a physicist tired of bad tools. It exists for students, researchers, and anyone working on muon beam therapy for cancer — at CCTVal-USM or anywhere on Earth.
COMMERCIAL USE, SALE, OR MONETIZATION IS STRICTLY PROHIBITED without my explicit written permission — including all forks, derivatives, and spiritual successors (MuonSimViewer included).
I built this unpaid, during exam season. If you want to use it commercially, talk to me first. I'm not against making money. I'm against people making money off my all-nighters and QM II stress.
A complete, self-contained scientific computing platform that takes raw particle trajectory data — from Geant4, COMSOL, or CERN ROOT — and turns it into:
| Output | Description |
|---|---|
| 🎨 3D Visualizations | Interactive beam rendering with VTK + time slider |
| 📊 Beam Physics Metrics | Focus position, RMS radius, envelope area, efficiency |
| 🫁 Biological Dosimetry | (New) Bethe-Bloch energy loss through tissue |
| 🧊 3D Meshes | Caustic surfaces, effective lens bodies (OBJ, 3D-printable) |
| 📄 Reports | Multi-page PDF with embedded figures |
| 🎬 Videos | MP4 animation of beam evolution (via ffmpeg) |
| 📐 Equations | Parametric surface descriptions in .txt + sampled .csv |
🫁 Biological Tissue Simulator — click to expand
The centerpiece of this update. BeamLabStudio now simulates muon beam propagation through biological tissue using the Bethe-Bloch stopping power formula.
| Component | Description |
|---|---|
BetheBlochEngine |
Mean energy loss per unit length for muons in any material |
MuonTrackSimulator |
Propagates tracks through arbitrary tissue slab sequences |
TissueRegistry |
Configurable library: muscle, bone, water, fat — with physical properties |
ScoringPlaneDetector |
Records fluence, energy spectrum, and dose at arbitrary planes |
🖥️ New UI Tabs — click to expand
- Simulator tab (
SimulatorWidget): configure tissue geometry, run simulations, visualize energy deposition profiles in real time — all inside the GUI - Math docs tab (
InfoWidget): every formula used in the pipeline, rendered as HTML — no more digging through source code to understand what r_rms means
📦 New Export + Bug Fixes — click to expand
New:
EnergyProfileExporter: exports the full longitudinal energy deposition curve (Bragg peak) to CSV
Fixed:
- Numerical instability in
FocusDetectornear degenerate beam configurations - Edge cases in
SliceExtractorfor very sparse time steps - Accumulation bug in
FrameStatisticsEnginewhen particles are lost before the first frame LensDiskBuildergenerating non-manifold meshes on certain envelope geometriesGeant4CsvImporterfailing on files with inconsistent column countsAxisFrameResolverselecting the wrong propagation axis for near-diagonal beamsDatasetNormalizerapplying the wrong scale factor when input units are ambiguous
| Format | Details |
|---|---|
| COMSOL CSV | Auto-detects wide (@t=... columns) and long format. Handles Spanish-accented headers. |
| Geant4 CSV | Full support. Auto-converts cm→m and ns→s. |
| CERN ROOT | Native on Linux (optional build flag). Windows: convert to CSV first. |
Raw CSV
└─► FrameStatisticsEngine
└─► FocusCurveBuilder ──► FocusDetector
└─► SliceExtractor
└─► ConvexHullEnvelopeExtractor
└─► SurfaceBuilder ──► LensDiskBuilder
└─► Export (OBJ / PDF / MP4 / CSV)
- Automatic axis frame detection or manual override (
--axis x/y/z) - Focus detection via RMS radius, convex hull area, or particle count
- Caustic surface reconstruction (parametric + mesh)
- Effective lens body generation — lofted with realistic thickness
- Frame-by-frame statistics: active, arrived, lost, efficiency, r_rms, σ_x, σ_z
Tissue Config
└─► TissueRegistry + TissueSlab
└─► BetheBlochEngine
└─► MuonTrackSimulator
└─► ScoringPlaneDetector
└─► EnergyProfileExporter (Bragg peak CSV)
- Dark theme — optimized for long sessions
- Interactive 3D VTK viewer with time slider
- Real-time dashboards: focus curve, envelope area, radial distribution
- Simulator tab with live energy deposition plots
- Math docs tab with all formulas rendered in HTML
- One-click export: PDF · MP4 · OBJ · CSV · PNG
# Basic
beamlab data/run.csv --output outputs/run_001
# Full options
beamlab data/geant4_muons.csv \
--output results/muon_therapy_v3 \
--axis z \
--reference-mode axial-bins \
--axial-bins 501 \
--window 7 \
--caustic-points 128 \
--lens-points 256 \
--lens-layers 32 \
--preview-trajectories 5000The original Windows post-processing used PowerShell and produced geometrically different lens bodies than the Python reference. I rewrote every single line in pure C++20 — same floating-point operations, same iteration order, same output formatting (%.12e).
diff between Linux and Windows outputs: zero differences.
outputs/ui_run_<filename>_<timestamp>/
│
├── geometry/
│ ├── beam_caustic_surface.obj ← full resolution caustic mesh
│ ├── beam_caustic_surface_preview.obj ← decimated for fast viewing
│ ├── effective_lens_disk.obj
│ ├── effective_lens_body.obj ← 3D printable
│ └── trajectories_preview.obj
│
├── visualization/
│ ├── visualization_manifest.json ← index of every output file
│ ├── trajectories_preview.csv
│ ├── focal_slice_points.csv
│ └── envelope_rings.csv
│
├── plots/ ← PNG figures (ready for papers)
│
├── reports/
│ ├── analysis_summary.md
│ ├── quality_report.md
│ ├── run_metadata.json
│ └── BeamLabStudio_Report.pdf ← multi-page, embedded images
│
├── equations/
│ ├── beam_caustic_parametric_equation.txt
│ └── effective_lens_body_parametric_equation.txt
│
├── tables/
│ ├── focus_curve.csv
│ ├── envelope_summary.csv
│ └── energy_profile.csv ← [New] Bragg peak data
│
└── logs/
| Option | Steps |
|---|---|
| Installer (recommended) | Download BeamLabStudio_Setup_Windows_x64.exe from Releases → double-click → Next → Install |
| Portable | Download BeamLabStudio_Portable_Windows_x64.exe → extract anywhere → run |
⚠️ OneDrive users: do NOT run the installer from a OneDrive-synced folder. OneDrive sometimes leaves large.exefiles as unsynced placeholders → "Installer integrity check has failed". Move toC:\Downloads\first.
Fedora / RHEL
sudo dnf install cmake ninja gcc-c++ qt6-qtbase-devel qt6-qtcharts-devel \
vtk-devel nlohmann-json-develUbuntu / Debian
sudo apt install cmake ninja-build g++ qt6-base-dev qt6-charts-dev \
libvtk9-dev nlohmann-json3-devBuild
git clone https://github.com/kegouro/BeamLabStudio.git
cd BeamLabStudio
# Standard (no ROOT)
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
# With CERN ROOT (optional, Linux only)
cmake -S . -B build-root -G Ninja -DBEAMLAB_ENABLE_ROOT=ON
cmake --build build-root -j$(nproc)
./build/beamlab --help
./build/beamlab_ui| Layer | Components |
|---|---|
| Data model | Trajectory, TrajectorySample, TrajectoryDataset, AxisFrame, BeamEnvelope, LensSurfaceModel, ParticleInfo |
| Import | ComsolCsvImporter, Geant4CsvImporter, RootNativeImporter |
| Analysis | FrameStatisticsEngine → FocusCurveBuilder → FocusDetector → SliceExtractor → ConvexHullEnvelopeExtractor → SurfaceBuilder → LensDiskBuilder |
| Simulation | BetheBlochEngine → MuonTrackSimulator → TissueRegistry / TissueSlab → ScoringPlaneDetector |
| UI | MainWindow, Scene3DWidget, StatsDashboardWidget, SimulatorWidget, InfoWidget, ObjViewerWidget |
| Export | MeshExporter, AnalysisReportExporter, VisualizationDataExporter, ParametricSurfaceExporter, EnergyProfileExporter |
- Core analysis engine — Linux + Windows bit-equivalent
- Qt6 GUI with 3D VTK viewer
- PDF + MP4 + OBJ export
- Biological tissue simulator (Bethe-Bloch + muon tracking)
- Interactive simulator UI tab
- Math documentation tab
- Energy profile (Bragg peak) export
- GitHub Actions CI — auto-build releases on tag (Linux + Windows matrix)
- Code signing for Windows (eliminate SmartScreen warning)
- AppImage for Linux
- CERN ROOT support in Windows build
- Automated bit-equivalence regression tests in CI
- Full Landau straggling in simulator (currently Gaussian approximation)
MIT — see LICENSE for details.
Extra clause: commercial use, sale, or any form of monetization of this software or any derivative — including MuonSimViewer — is strictly prohibited without explicit written permission from the author.
- Author & Architect: José Labarca — Universidad Santa María / CCTVal, muon beam cancer therapy project
- Dependencies: Qt 6 (LGPL) · VTK (BSD) · nlohmann/json (MIT) · CERN ROOT (LGPL) · MinGW-w64 · NSIS (zlib)
If you use BeamLabStudio in your research, please cite it and drop me an email. I would love to know this thing I built during exam hell is actually helping real science.
See you at KIT, October 2026.
— José
Plataforma científica multiplataforma para análisis de trayectorias de haces, reconstrucción de superficies ópticas, post-proceso de simulaciones Monte Carlo y dosimetría en tejido biológico.
Estudio Licenciatura en Física (4to año, Universidad Santa María — Chile). No Ingeniería Informática.
Hice v0.1.0 en dos semanas mientras rendía certámenes, daba el IELTS (saqué C1) y sobrevivía un examen de Cuántica II que fue... digamos que "formador de carácter". v0.2.0 agrega un simulador biológico de verdad: pérdida de energía Bethe-Bloch en tejido, tracking de muones, planos de scoring. También hecho entre exámenes.
Si encontrás un bug, arreglalo por mí — probablemente ya estoy en KIT en Alemania cuando leas esto. Los pull requests son extremadamente bienvenidos.
— José
BeamLabStudio es la reescritura profesional completa de MuonSimViewer. MuonSimViewer fue el hack de fin de semana. Esta es la versión que podés usar en un laboratorio real.
Este software fue creado para la ciencia, por un físico harto de herramientas malas. Existe para estudiantes, investigadores y cualquiera que trabaje en terapia con muones contra el cáncer — en el CCTVal-USM o en cualquier lugar del planeta.
EL USO COMERCIAL, VENTA O MONETIZACIÓN ESTÁN ESTRICTAMENTE PROHIBIDOS sin mi permiso expreso por escrito — incluyendo todos los forks, derivados y sucesores espirituales (MuonSimViewer incluido).
Lo construí sin cobrar, durante época de exámenes. Si querés usarlo comercialmente, hablame primero. No estoy en contra de hacer plata. Estoy en contra de que alguien haga plata con mis noches en blanco y estrés por Cuántica II.
Una plataforma completa de computación científica que toma datos crudos de trayectorias de partículas — de Geant4, COMSOL o CERN ROOT — y los convierte en:
| Salida | Descripción |
|---|---|
| 🎨 Visualizaciones 3D | Renderizado interactivo del haz con VTK + slider de tiempo |
| 📊 Métricas de Física | Posición de foco, radio RMS, área de envolvente, eficiencia |
| 🫁 Dosimetría Biológica | (Nuevo) Pérdida de energía Bethe-Bloch en tejido |
| 🧊 Mallas 3D | Superficies caústicas, cuerpos de lente efectivos (OBJ, imprimibles en 3D) |
| 📄 Reportes | PDF multi-página con figuras embebidas |
| 🎬 Videos | Animación MP4 de la evolución del haz (vía ffmpeg) |
| 📐 Ecuaciones | Descripciones paramétricas en .txt + muestreo en .csv |
🫁 Simulador de Tejido Biológico — click para expandir
El núcleo de esta actualización. BeamLabStudio ahora simula la propagación de haces de muones a través de tejido biológico usando la fórmula de Bethe-Bloch.
| Componente | Descripción |
|---|---|
BetheBlochEngine |
Pérdida de energía media por unidad de longitud para muones en cualquier material |
MuonTrackSimulator |
Propaga trayectorias a través de secuencias arbitrarias de tejido |
TissueRegistry |
Biblioteca configurable: músculo, hueso, agua, grasa — con propiedades físicas |
ScoringPlaneDetector |
Registra fluencia, espectro de energía y dosis en planos arbitrarios |
🖥️ Nuevas Pestañas de la Interfaz — click para expandir
- Pestaña Simulador (
SimulatorWidget): configurá geometría de tejido, corré simulaciones y visualizá perfiles de deposición de energía en tiempo real — todo desde la GUI - Pestaña Explicaciones (
InfoWidget): cada fórmula usada en el pipeline, renderizada en HTML — se acabó buscar en el código fuente qué significa r_rms
📦 Nueva Exportación + Correcciones — click para expandir
Nuevo:
EnergyProfileExporter: exporta la curva de deposición de energía longitudinal (pico de Bragg) a CSV
Corregido:
- Inestabilidad numérica en
FocusDetectorcerca de configuraciones de haz degeneradas - Casos extremos en
SliceExtractorpara pasos de tiempo muy dispersos - Bug de acumulación en
FrameStatisticsEnginecuando partículas se pierden antes del primer frame LensDiskBuildergenerando mallas no-manifold en ciertas geometrías de envolventeGeant4CsvImporterfallando en archivos con conteo de columnas inconsistenteAxisFrameResolverseleccionando el eje de propagación incorrecto en haces casi-diagonalesDatasetNormalizeraplicando el factor de escala incorrecto con unidades de entrada ambiguas
| Formato | Detalles |
|---|---|
| COMSOL CSV | Detecta automáticamente formato ancho (@t=...) y largo. Maneja encabezados con acentos. |
| Geant4 CSV | Soporte completo. Convierte automáticamente cm→m y ns→s. |
| CERN ROOT | Nativo en Linux (flag opcional). Windows: convertir a CSV primero. |
CSV crudo
└─► FrameStatisticsEngine
└─► FocusCurveBuilder ──► FocusDetector
└─► SliceExtractor
└─► ConvexHullEnvelopeExtractor
└─► SurfaceBuilder ──► LensDiskBuilder
└─► Export (OBJ / PDF / MP4 / CSV)
- Detección automática del sistema de ejes o sobrescritura manual (
--axis x/y/z) - Detección de foco: radio RMS, área de casco convexo, conteo de partículas
- Reconstrucción de superficie caústica (paramétrica + malla)
- Cuerpo de lente efectivo con lofting y espesor realista
- Estadísticas frame por frame: activas, llegadas, perdidas, eficiencia, r_rms, σ_x, σ_z
Configuración de tejido
└─► TissueRegistry + TissueSlab
└─► BetheBlochEngine
└─► MuonTrackSimulator
└─► ScoringPlaneDetector
└─► EnergyProfileExporter (CSV pico de Bragg)
- Tema oscuro — optimizado para sesiones largas
- Visor 3D interactivo con VTK y slider de tiempo
- Dashboards en tiempo real: curva de foco, área de envolvente, distribución radial
- Pestaña Simulador con gráficos de deposición de energía en vivo
- Pestaña Explicaciones con todas las fórmulas renderizadas en HTML
- Exportación con un clic: PDF · MP4 · OBJ · CSV · PNG
# Básico
beamlab datos/corrida.csv --output outputs/corrida_001
# Opciones completas
beamlab datos/geant4_muones.csv \
--output resultados/terapia_muones_v3 \
--axis z \
--reference-mode axial-bins \
--axial-bins 501 \
--window 7 \
--caustic-points 128 \
--lens-points 256 \
--lens-layers 32 \
--preview-trajectories 5000El post-proceso original de Windows usaba PowerShell y producía cuerpos de lente geométricamente diferentes que la referencia Python. Reescribí cada línea en C++20 puro — mismas operaciones de punto flotante, mismo orden de iteración, mismo formato de salida (%.12e).
diff entre salidas de Linux y Windows: cero diferencias.
outputs/ui_run_<archivo>_<timestamp>/
│
├── geometry/
│ ├── beam_caustic_surface.obj ← malla caústica resolución completa
│ ├── beam_caustic_surface_preview.obj ← decimada para vista rápida
│ ├── effective_lens_disk.obj
│ ├── effective_lens_body.obj ← imprimible en 3D
│ └── trajectories_preview.obj
│
├── visualization/
│ ├── visualization_manifest.json ← índice de todos los archivos de salida
│ ├── trajectories_preview.csv
│ ├── focal_slice_points.csv
│ └── envelope_rings.csv
│
├── plots/ ← figuras PNG (listas para papers)
│
├── reports/
│ ├── analysis_summary.md
│ ├── quality_report.md
│ ├── run_metadata.json
│ └── BeamLabStudio_Report.pdf ← multi-página, imágenes embebidas
│
├── equations/
│ ├── beam_caustic_parametric_equation.txt
│ └── effective_lens_body_parametric_equation.txt
│
├── tables/
│ ├── focus_curve.csv
│ ├── envelope_summary.csv
│ └── energy_profile.csv ← [Nuevo] datos del pico de Bragg
│
└── logs/
| Opción | Pasos |
|---|---|
| Instalador (recomendado) | Descargá BeamLabStudio_Setup_Windows_x64.exe desde Releases → doble clic → Siguiente → Instalar |
| Portable | Descargá BeamLabStudio_Portable_Windows_x64.exe → extraé donde quieras → ejecutá |
⚠️ Usuarios de OneDrive: NO ejecutes el instalador desde una carpeta sincronizada con OneDrive. OneDrive a veces deja archivos.exegrandes como placeholders sin sincronizar → "Installer integrity check has failed". Mové el archivo aC:\Downloads\primero.
Fedora / RHEL
sudo dnf install cmake ninja gcc-c++ qt6-qtbase-devel qt6-qtcharts-devel \
vtk-devel nlohmann-json-develUbuntu / Debian
sudo apt install cmake ninja-build g++ qt6-base-dev qt6-charts-dev \
libvtk9-dev nlohmann-json3-devCompilación
git clone https://github.com/kegouro/BeamLabStudio.git
cd BeamLabStudio
# Estándar (sin ROOT)
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
# Con CERN ROOT (opcional, solo Linux)
cmake -S . -B build-root -G Ninja -DBEAMLAB_ENABLE_ROOT=ON
cmake --build build-root -j$(nproc)
./build/beamlab --help
./build/beamlab_ui| Capa | Componentes |
|---|---|
| Modelo de datos | Trajectory, TrajectorySample, TrajectoryDataset, AxisFrame, BeamEnvelope, LensSurfaceModel, ParticleInfo |
| Importación | ComsolCsvImporter, Geant4CsvImporter, RootNativeImporter |
| Análisis | FrameStatisticsEngine → FocusCurveBuilder → FocusDetector → SliceExtractor → ConvexHullEnvelopeExtractor → SurfaceBuilder → LensDiskBuilder |
| Simulación | BetheBlochEngine → MuonTrackSimulator → TissueRegistry / TissueSlab → ScoringPlaneDetector |
| UI | MainWindow, Scene3DWidget, StatsDashboardWidget, SimulatorWidget, InfoWidget, ObjViewerWidget |
| Exportación | MeshExporter, AnalysisReportExporter, VisualizationDataExporter, ParametricSurfaceExporter, EnergyProfileExporter |
- Motor de análisis central — Linux + Windows bit-equivalente
- GUI Qt6 con visor 3D VTK
- Exportación PDF + MP4 + OBJ
- Simulador de tejido biológico (Bethe-Bloch + tracking de muones)
- Pestaña de simulador interactivo
- Pestaña de documentación matemática
- Exportación de perfil de energía (pico de Bragg)
- GitHub Actions CI — releases automáticos en tag (matrix Linux + Windows)
- Firma de código para Windows (eliminar advertencia SmartScreen)
- AppImage para Linux
- Soporte CERN ROOT en build de Windows
- Tests de regresión bit-equivalencia Linux vs Windows en CI
- Straggling de Landau completo en el simulador (actualmente aproximación gaussiana)
MIT — ver LICENSE para los detalles.
Cláusula extra: el uso comercial, venta o cualquier forma de monetización de este software o cualquier derivado — incluyendo MuonSimViewer — está estrictamente prohibido sin permiso expreso por escrito del autor.
- Autor y Arquitecto: José Labarca — Universidad Santa María / CCTVal (terapia con haces de muones contra el cáncer)
- Librerías: Qt 6 (LGPL) · VTK (BSD) · nlohmann/json (MIT) · CERN ROOT (LGPL) · MinGW-w64 · NSIS (zlib)
Si usás BeamLabStudio en tu investigación, por favor citame y mandame un mail. Me encantaría saber que esta cosa que construí durante el infierno de exámenes está ayudando a ciencia real.
Nos vemos en Karlsruhe, octubre 2026.
— José