https://github.com/cphyc/halo-viewer
https://github.com/cphyc/halo-viewer
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/cphyc/halo-viewer
- Owner: cphyc
- Created: 2025-11-14T14:30:23.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-02-12T18:04:01.000Z (5 months ago)
- Last Synced: 2026-02-12T23:01:02.136Z (5 months ago)
- Language: TypeScript
- Size: 280 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Megatron Data Viewer
This repository contains a web-based viewer for visualizing Megatron simulation data.
It is built using React, and allows to interact with the data through a web interface without the need to install any software
on the webserver (apart from a static file server).
## Features
- 3D visualization of halo catalogues using [three.js](https://threejs.org/),
- Display of content of halo catalogues,
- Display of precomputed data (e.g., images and spectra),
- Interactive Python environment running in the browser using [Pyodide](https://pyodide.org/en/stable/) and [yt](https://yt-project.org/).
## Installation
In order to use the viewer, you need to have a working distribution of Python 3 and npm installed on your system.
We assume you have `uv` installed. If not, follow the instructions at https://docs.astral.sh/uv/getting-started/installation/#installation-methods.
## Cloning the repository
```bash
# Clone the repository
git clone https://github.com/cphyc/halo-viewer.git
cd halo-viewer
# Initialize submodules
git submodule update --init --recursive
```
## Setting up Pyodide
The viewer uses Pyodide to run Python in the browser. Download and extract version 0.29.3:
```bash
# Download and extract Pyodide
(
cd public
wget https://github.com/pyodide/pyodide/releases/download/0.29.3/pyodide-0.29.3.tar.bz2
tar -xjf pyodide-0.29.3.tar.bz2
mv pyodide pyodide-0.29.3
rm pyodide-0.29.3.tar.bz2
)
```
### Updating Pyodide to a newer version
1. Download from [Pyodide releases](https://github.com/pyodide/pyodide/releases)
2. Extract to `public/pyodide-X.Y.Z/`
3. Update `indexURL` in `src/pyodide/pyWorker.ts`
4. Update `pyodide` version in `package.json`
5. Run `npm install`
## Building 'wheels'
The viewer includes a Python environment running in the browser. This allows
interacting with the cutouts (raw data products) using Python code.
It, however, requires two packages to be shipped as pre-compiled wheels:
`yt_derived_fields` and `yt_experiments`.
```bash
# Create wheels for yt_derived_fields
(
cd external/yt_derived_fields
uv build --wheel -o ../../../public/wheels/
)
# Create pyodide wheels for yt_experiments
(
cd external/yt_experiments
uvx cibuildwheel --platform pyodide
cp wheelhouse/*.whl ../../../public/wheels/
)
```
## Building the web application
First, you'll need to create a local environment file, `.env.local`,
in the root of the repository. This file should contain the base URL
where your data is hosted.
```bash
# // File .env.local
# This is the base URL where the data is hosted. For example,
# if your data is hosted at https://example.com/data/,
# set BASE_URL to https://example.com/data/
BASE_URL=
# Don't change the line below unless you know what you're doing
VITE_DATA_BASE_URL=${BASE_URL}
```
Once this is done, you can build the application using npm:
```bash
# Install dependencies
npm install
# Build the application
npm run build
```
And voilà! Your application is ready to be deployed.
### Testing locally
You can test the application locally using
```bash
npm run dev
```
Alternatively, after you've built the application (see previous section), you can serve the local folder, e.g. with
```bash
python -m http.server
```
Don't forget to modify the `.env.local` file to use the same port as the one used by the Python server (default is 8000).
## Configuring Data Resources
The viewer supports dynamic configuration of data resources through a `resources.json` file in the `public/` folder. This allows you to define what data types (1D, 2D, 3D) are available for each halo without modifying the code.
### Resource Configuration
Create or edit `public/resources.json` to define available resources. The schema is defined in `public/resources.schema.json`.
Example configuration (also available as `public/resources.example.json`):
```json
{
"$schema": "./resources.schema.json",
"resources": [
{
"id": "spectrum",
"name": "Spectrum",
"type": "1D",
"bundled": true,
"pathTemplate": "demo-halos/spectra/output_00100/halos_{bucketId}.json.gz",
"dataKey": "total",
"xAxis": {
"label": "λ",
"unit": "Å",
"key": "wavelength"
},
"yAxis": {
"label": "fλ",
"unit": "arbitrary units",
"key": "data"
},
"downloadable": true
}
]
}
```
### Resource Types
- **1D data**: Line plots (e.g., spectra, time series)
- **2D data**: Images (e.g., projections, slices) - *coming soon*
- **3D data**: Data cubes (e.g., position-position-velocity) - *coming soon*
### Bundled vs Non-bundled Resources
- **Bundled** (`bundled: true`): Multiple halos stored in a single file. Use `{bucketId}` in `pathTemplate` for bucket-based organization (e.g., `haloId / 1000`).
- **Non-bundled** (`bundled: false`): One file per halo. Use `{haloId}` in `pathTemplate`.
### Data Download
Each resource card includes a download button that exports the data as JSON. For bundled resources, the data is automatically unbundled to provide only the selected halo's data.