Repository navigation
3D Matrix Analysis and Web Viewer
The cmat3d_webviewer.py server and companion cmat3d_webviewer.html client provide an ultra-responsive, browser-based spectroscopy environment for navigating 3D matrix cubes in the .cmat format (e.g.
The viewer couples pure Python/NumPy memory-mapped slice decompression with a high-performance HTML5 Canvas frontend featuring real-time multi-plane orthoslicing, 3D multi-gate coincidence cuts, 2D graphical Banana ROI gates, 1D/2D photopeak fitting, and publication-quality vector PDF export.
Run the 3D viewer from your terminal, pointing to a 3D .cmat file:
# Open a 3D matrix cube
python cmat3d_webviewer.py /path/to/matrix3d.cmat
# Open multiple 3D matrices for rapid cycling
python cmat3d_webviewer.py cube1.cmat cube2.cmatThe server binds to http://0.0.0.0:8080 (or the configured host/port) and automatically opens your default web browser.
+-----------------------------------------------------------------------------------+
| cmat3d_webviewer.py |
| |
| +---------------------------+ +---------------------------------------------+ |
| | CMAT3DReader (cmat3d.py) | | ThreadingHTTPServer | |
| | - IVF Slice Decompressor | | - Multi-threaded concurrent request handler | |
| | - .cmat3d_cache/ (memmap) | | - /api/tile (Subregion Slicing: ~1.6 ms) | |
| | - 3D Coincidence Slicing | | - /api/projection_region (~2.1 ms) | |
| | - 2D Banana Polygon ROI | | - /api/gate_1d (Coincidence Cuts) | |
| +---------------------------+ +---------------------------------------------+ |
+------------------------------------------^----------------------------------------+
| HTTP / REST (JSON + Binary ArrayBuffers)
+------------------------------------------v----------------------------------------+
| cmat3d_webviewer.html |
| |
| +---------------------------+ +---------------------------------------------+ |
| | 2D Density Heatmap Canvas | | Triple 1D Spectroscopic Displays | |
| | - Turbo/Viridis LUT Engine| | - Det 1 (Axis 0) Stepped Histogram | |
| | - Multi-Plane: 0-1, 0-2, 1-2 | - Det 2 (Axis 1) Stepped Histogram | |
| | - 2D Banana ROI (Shift+G) | | - Rings / dt (Axis 2) Stepped Histogram | |
| | - AbortController Sync | | - 60 FPS Client-Side Instant Channel Zoom | |
| +---------------------------+ +---------------------------------------------+ |
+-----------------------------------------------------------------------------------+
3D .cmat files frequently contain large data volumes (e.g.
-
Zero RAM Bloat:
CMAT3DReaderdecompresses slices on first access into a binary cache file (.cmat3d_cache/<filename>.dat) and accesses the data as a 3Dnumpy.memmap(int32). -
Instant Subsequent Startup: Subsequent launches read the cached memory-mapped file instantly (
$<50\text{ ms}$ ).
The viewer allows real-time orthogonal slicing across any pair of dimensions:
-
Plane 0-1 (
Det 1 vs Det 2): Standard$4096 \times 4096$ $\gamma$ -$\gamma$ coincidence matrix, sliced over the visible/gated 3rd axis. -
Plane 0-2 (
Det 1 vs Rings):$4096 \times 128$ matrix showing$\gamma$ -ray energy on Det 1 as a function of detector ring or timing. -
Plane 1-2 (
Det 2 vs Rings):$4096 \times 128$ matrix showing$\gamma$ -ray energy on Det 2 as a function of detector ring or timing.
Switch planes instantly using the header toolbar buttons (0-1, 0-2, 1-2) or dropdown menu.
-
Pre-Sum Slicing: When zooming into a 2D region
$[x_0..x_1, y_0..y_1]$ , the backend extracts only the required subvolume from the 3D memory map before summing over the 3rd axis, accelerating tile generation from$76.5\text{ ms}$ to$1.6\text{ ms}$ (~48× speedup). -
Multi-Threaded Server:
ThreadingHTTPServerprocesses simultaneous tile requests, 1D projections, and peak fits on separate background threads without blocking. -
Debounced 2D Synchronization: 1D wheel zooming and channel panning update the stepped histograms client-side at 60 FPS (
$<1\text{ ms}$ ), while heavy 2D tile rendering is debounced (45 ms) withAbortControllercancellation to prevent network congestion.
Set coincidence gates directly on any 1D spectrum:
- Hover cursor over a 1D spectrum panel (Det 1, Det 2, or Rings).
- Press
Wat the lower gate limit, move cursor to the upper limit, and pressWagain to confirm. - (Optional) Press
XorBtwice to define background subtraction windows. - The remaining spectra and 2D projections immediately update to display the background-subtracted coincidence cut:
- Press
Zor click Clear Gate to reset active coincidence gates.
For particle-gamma identification, ring discrimination, or kinematic curve gating:
- Press
Shift + Gor click Draw Banana [Shift+G] in the toolbar. - Click consecutive points on the active 2D plane (e.g.
Plane 0-2Det 1 vs Rings) to define the boundary vertices of an arbitrary polygon. - Click near the starting vertex to close the polygon.
- The viewer automatically extracts all events lying within the 2D polygon using vectorized ray-casting point-in-polygon containment and projects the gated counts onto the conjugate 3rd axis.
- Click Clear Banana or press
Zto remove the polygon gate.
The 3D viewer incorporates the complete spectroscopy peak fitting engine:
- Gaussian: Standard symmetric photopeak with linear/quadratic continuum baseline.
-
RadWare / SAMPO: Photopeak with an exponential low-energy tail (
$A, \eta$ ) for high-energy HPGe detectors. -
Hypermet EMG: Convolved Gaussian exponential tail plus complementary error function (
$\text{erfc}$ ) Compton step. -
Multiplet Fits: Place multiple candidate markers with
Por click fit region withR, then pressVto perform multi-component non-linear least-squares fitting. -
2D Peak Fit:
Ctrl+Clickon the 2D plane to perform 2D Gaussian peak fitting with Gamba coincidence background decomposition.
The 3D viewer automatically reads and writes configuration files in the working directory:
[General]
port = 8080
colormap = turbo
scale_mode_2d = log
scroll_sensitivity = 0.04
active_plane = 0-1
proj_range_mode = synced
[Axes]
axis0_name = Det 1
axis1_name = Det 2
axis2_name = Rings
[Calibration]
axis0_cal = 0.0, 0.5, 0.0
axis1_cal = 0.0, 0.5, 0.0
axis2_cal = 0.0, 1.0, 0.0
[PeakFit]
fit_type = gaussian
fwhm_est = 4.0
fwhm_mult = 4.0You can also use cmat3d.py programmatically in Python scripts and Jupyter notebooks:
from cmat3d import CMAT3DReader
# 1. Open 3D .cmat file
reader = CMAT3DReader("GeE-Rings3D.cmat")
print(f"Matrix shape: {reader.shape}") # e.g. (4096, 4096, 128)
print(f"Total counts: {reader.total_counts:,}")
# 2. Access memory-mapped 3D volume
mmap_vol = reader.to_memmap() # Shape: (4096, 4096, 128), dtype: int32
# 3. Extract 2D orthogonal plane projection
# Plane options: '0-1' (Det 1 vs 2), '0-2' (Det 1 vs Rings), '1-2' (Det 2 vs Rings)
plane_01 = reader.get_2d_plane("0-1")
plane_gated = reader.get_2d_plane("0-1", gate_3rd=[[10, 12]]) # Gated on Ring 10-12
# 4. Extract 1D total projection
proj_det1 = reader.get_projection_1d(axis=0)
# 5. Coincidence Gating
net_spec, bg_spec = reader.get_gate_1d(
target_axis=0,
w_gates={2: [[11, 11]]}, # Gate on Ring 11
b_gates={2: [[1, 2], [20, 21]]} # Background rings
)
# 6. 2D Banana Gate Polygon
polygon_pts = [[1000, 10], [1500, 12], [1480, 15], [980, 13]] # [[x, y], ...]
banana_res = reader.get_banana_gate(plane="0-2", polygon=polygon_pts)
print(f"Banana cut counts: {banana_res['total_counts']:,}")python-cmat © 2026. Released under the MIT License. Return to GitHub Repository
Interactive 2D & 3D Matrix Analysis & Spectroscopy
- Home
- Interactive Web Viewer
- 3D Matrix Analysis & Web Viewer
- Keyboard Shortcuts & Controls
- ROOT Files & Live Histograms
- ENSDF Isotope Identification
- Spectroscopy Commands & Macros
- Configuration Guide
- Python API & CLI Tools