Examples

Showcases

Published research visualizations built with ParticleViz. Each showcase includes an interactive map you can explore in the browser, with particle trajectories from Lagrangian ocean models.

Global Marine Litter

Basin-scale view of marine litter transport from a global Lagrangian model, illustrating how debris accumulates along coastlines and in subtropical gyres over multi-year simulations. Described in this Frontiers in Marine Science paper.

Region: Global oceans

Open visualization

Configurations & Datasets

These configurations use datasets shipped in ExampleData/. Each example below has been run with the commands shown; the animations are captured from the generated web interface.

OceanParcels — Global_Marine_Debris.nc

Simplest config

Minimal JSON: one experiment and the default subsampling.

uv run python ParticleViz.py all --config_file ConfigExamples/Config_Simplest.json

{
  "preprocessing": {
    "experiments": [{
      "name": "Dataset 1",
      "file_name": "./ExampleData/Global_Marine_Debris.nc",
      "subsample": { "desktop": 2, "mobile": 4 }
    }]
  }
}

Simplest Global Marine Debris example

Colored particles (Config_GlobalLitter.json)

Same dataset with a per-particle color scheme for country-based styling.

uv run python ParticleViz.py all --config_file ConfigExamples/Config_GlobalLitter.json

{
  "preprocessing": {
    "experiments": [{
      "name": "January 2010",
      "file_name": "./ExampleData/Global_Marine_Debris.nc",
      "subsample": { "desktop": 1, "mobile": 1 },
      "color_scheme": "./data/color_schemes/ColorSchemeWorldLitter.json"
    }]
  }
}

The color scheme maps particle indexes to RGBA colors by country. Excerpt from data/color_schemes/ColorSchemeWorldLitter.json (indexes truncated):

{
  "Countries": [
    {
      "name": "Albania",
      "color": "rgb(216.8, 65.0, 65.0, 255.0)",
      "index": "2726,2731,2732,2733,2742,..."
    },
    {
      "name": "Algeria",
      "color": "rgb(53.3, 108.4, 242.2, 255.0)",
      "index": "2040,2041,2049,2062,2091,..."
    }
  ]
}

Global litter color scheme example

Advanced multi-experiment (Config_Advanced_Example.json)

Three experiments on the same file: single color, color by country, and color by mismanaged plastic waste (MPW).

uv run python ParticleViz.py all --config_file ConfigExamples/Config_Advanced_Example.json

Full config: ConfigExamples/Config_Advanced_Example.json

{
  "preprocessing": {
    "experiments": [
      {
        "name": "Single Color",
        "file_name": "./ExampleData/Global_Marine_Debris.nc",
        "subsample": { "desktop": 2, "mobile": 2 }
      },
      {
        "name": "Color by Country",
        "file_name": "./ExampleData/Global_Marine_Debris.nc",
        "subsample": { "desktop": 1, "mobile": 9 },
        "color_scheme": "./data/color_schemes/ColorSchemeWorldLitterCountries.json"
      },
      {
        "name": "Color by MPW",
        "file_name": "./ExampleData/Global_Marine_Debris.nc",
        "subsample": { "desktop": 2, "mobile": 2 },
        "color_scheme": "./data/color_schemes/ColorSchemeWorldLitterMPW.json"
      }
    ]
  }
}

The file also includes webapp (title, map extent, logos, extra layers) and advanced (timesteps, file prefix, port) sections — see the full config on GitHub.

Use the Experiment dropdown in the navbar to switch between the three views.

Advanced multi-experiment example

One-line CLI (no config file)

Equivalent to the simplest example:

uv run python ParticleViz.py --input_file ExampleData/Global_Marine_Debris.nc

See Quick Start for a walkthrough and Configuration to customize the web map.