Python environment (uv)
ParticleViz uses uv to manage its Python dependencies.
- Install uv (installation guide):
curl -LsSf https://astral.sh/uv/install.sh | sh
- From the repository root, create the virtual environment and install packages:
cd particleviz
uv sync
This reads pyproject.toml, creates .venv/, and installs numpy, xarray, netCDF4, zarr, cartopy, and the other Python libraries needed for preprocessing.
- Run commands through
uv run:
uv run python ParticleViz.py --input_file ExampleData/Global_Marine_Debris.nc
Development / tests
uv sync --extra dev
uv run pytest tests/
Alternative: Conda
A legacy conda environment file is still available:
conda env create -f particleviz.yml
conda activate particleviz
Docker
You can run ParticleViz in a container without installing Python or Node.js on your host. The image includes uv, the Python dependencies, npm packages for the web app, and the example data under ExampleData/.
Build and run (default example)
From the repository root:
git clone https://github.com/olmozavala/particleviz.git
cd particleviz
docker build --pull --rm -f Dockerfile -t particleviz .
docker run --rm -it -p 3000:3000 particleviz:latest
The container runs preprocessing and starts the React dev server. Open http://localhost:3000/ in your browser.
The default command (in entrypoint.sh) uses the bundled example:
uv run python ParticleViz.py --input_file ExampleData/Global_Marine_Debris.nc
Use your own dataset
Mount a NetCDF or Zarr store into the container and override the command:
docker run --rm -it -p 3000:3000 \
-v "$(pwd)/path/to/output.nc:/app/data/output.nc:ro" \
particleviz:latest \
uv run python ParticleViz.py --input_file /app/data/output.nc
For a Zarr directory:
docker run --rm -it -p 3000:3000 \
-v "$(pwd)/path/to/output.zarr:/app/data/output.zarr:ro" \
particleviz:latest \
uv run python ParticleViz.py --input_file /app/data/output.zarr
Use a config file
Mount a config and run the full pipeline:
docker run --rm -it -p 3000:3000 \
-v "$(pwd)/ConfigExamples/Config_Simplest.json:/app/config.json:ro" \
particleviz:latest \
uv run python ParticleViz.py all --config_file /app/config.json
To change the default dataset baked into the image, edit entrypoint.sh before building, or pass a custom command as shown above.
JS dependencies (npm)
The web interface is a React app under ParticleViz_WebApp/. You need Node.js installed on your system.
The first time you run the web app, ParticleViz will call npm install automatically if node_modules is missing. You can also install manually:
cd ParticleViz_WebApp
npm install