vizmo 0.1.7

Real-time 3D fly-through explorer for mesh-free/unstructured simulation data

vizmo

Real-time 3D fly-through explorer for unstructured simulation data. Loads HDF5 snapshots from GIZMO/Gadget/AREPO simulations and renders interactive surface density maps, mass-weighted averages, velocity dispersions, and composite CoolMap visualizations on the GPU via WebGPU.

This is a vibecoded app. I have no idea how its front- or backends work, and am not sure if I could really properly support or get it running for you 10 years from now! But it would not exist otherwise. Software is weird now. It is what it is.

But I hope you enjoy it and please feel free to report bugs, request features, or develop your own and send a PR. Making it work for more data formats is well within scope, just ask!

Installation

pypi

pip install vizmo

Local source

pip install -e .

Requirements

• Python >= 3.9
• WebGPU-capable GPU (Metal on macOS, Vulkan on Linux, D3D12 on Windows)

Quickstart

Point vizmo at an HDF5 snapshot file:

vizmo path/to/snapshot.hdf5

The snapshot must contain at least one PartTypeN group with Coordinates and Masses. Smoothing lengths are taken from SmoothingLength/KernelMaxRadius/Hsml if present, otherwise from a per-type softening in the header (e.g. SofteningTypeN, SofteningTable), and as a last resort computed on the fly via meshoid.Meshoid(x, boxsize=boxsize).SmoothingLength(). Star particles (PartType5) are rendered as point sources when present.

Particle type selection

A row of six tickboxes labeled 0–5 at the top of the user menu controls which PartTypeN groups are loaded into the active particle pool. Disabled (greyed out) ticks correspond to types that are not present in the snapshot. Toggling a tick reloads the pool, refreshes the Weight/Field 2/Data dropdowns to show only the scalar/vector fields that are common to all selected types, and re-runs auto-range. The default selection is PartType0 if present, otherwise the first available type.

CLI options

vizmo snapshot.hdf5 [--width 1920] [--height 1080] [--fov 90]
                        [--fullscreen] [--screenshot OUT.png]
                        [--profile OUT.pstats]

Rendering backend

vizmo uses a WebGPU backend (wgpu-py) with GPU-resident particle data. Compute shaders perform frustum culling, LOD selection, and per-cell summary gathering with zero CPU↔GPU per-frame transfer. On unified-memory systems (Apple Silicon) field switches are also near-zero copy.

The renderer uses progressive refinement and an auto-LOD subsample cap that adapts within a user-controlled ceiling to keep interaction smooth during motion and sharpen on idle.

Algorithms

Getting this to work on 100M+ particle datasets has been tricky. Here is what has worked so far:

• Adaptive random subsampling, rescaling masses and radii appropriately, wired up to a PID loop to achieve a smooth framerate.
• Fully-sampled renders when the camera stops, resuming adaptive subsampling when it moves again.
• Multi-grid kernel splatting, implementing the algorithm of meshoid on the GPU, so that particles appearing large on the screen do not have to splat a huge number of pixels.
• GPU-side brute-force frustum culling. Experimented extensively with tree-based algorithms, but at ~100M bruteforce works fine.

Controls

Camera:

• W/A/S/D — Move forward/left/back/right
• Z/X — Move up/down
• Q/E — Roll left/right
• Mouse (click + drag) — Look around
• Scroll wheel — Adjust speed

Visualization:

• Tab — Hide/show all UI
• C — Cycle colormap
• L — Toggle log/linear scale
• R — Auto-range color scale (composite: Color slot)
• T — Auto-range composite Lightness slot
• +/- — Contract/expand color range
• [/] — Coarser/finer LOD pixel size
• ,/. — Lower/raise the auto-LOD subsample-cap ceiling
• P — Save screenshot
• F1 or \ — Toggle dev overlay
• Esc — Quit

Render Modes

Select from the Mode dropdown in the user menu:

• SurfaceDensity — Projected surface density of a weight field. Supports combining two fields with arithmetic operators (Op / Field 2).
• WeightedAverage — Mass-weighted line-of-sight average of a data field.
• WeightedVariance — Mass-weighted line-of-sight standard deviation (e.g. velocity dispersion).
• Composite — CoolMap-style dual-field visualization. Encodes one field in lightness and another in colormap hue. Each channel has independent render mode, field selection, limits, and scaling.

Vector Fields

3D vector fields (e.g. Velocities) are automatically detected. When selected as a weight or data field, a Proj dropdown appears:

• LOS — Per-particle line-of-sight component (dot product with the unit vector from the camera to the particle). Invariant under camera rotation; recomputed when the camera translates past a small threshold.
• |v| — Euclidean norm.
• |v|^2 — Squared norm.

Architecture

vizmo/
  app.py            - CLI entry point
  wgpu_app.py       - Main loop, key actions, progressive refinement, auto-LOD
  wgpu_renderer.py  - WGPURenderer: RenderMode, accumulate + resolve + composite passes
  gpu_compute.py    - GPUCompute: GPU-resident data, compute cull/LOD/gather
  wgpu_overlay.py   - WGPUDevOverlay, WGPUUserMenu (wgpu panel rendering)
  overlay.py        - Panel/PanelStyle base, DevOverlay, UserMenu
  camera.py         - 6DOF camera with cached basis vectors
  data_manager.py   - HDF5 I/O with lazy loading and cosmological corrections
  field_ops.py      - Field arithmetic and vector projections
  colormaps.py      - Matplotlib colormap to GPU texture
  shaders/          - WGSL shaders (common, splat_subsample, resolve, composite,
                      star, text)