ParticleViz

Welcome to ParticleViz

ParticleViz is an Open Source software that is used to visualize large number of particles inside dynamic web maps. It is designed mostly for Earth Science scientists that simulate different processes using Lagrangian models.

The objectives of this software are:

• Provide efficient visualizations that can help analyze and understand research made through lagrangian modelling in the Earth Sciences, in a fast and easy way.
• Make it easy to share this research with other colleagues with selfcontained websites.

ParticleViz currently reads NetCDF outputs from OceanParcels.

Status

Install

Classic steps:

1. Clone repository
2. Create conda environment with the proper dependencies
3. Enjoy life

git clone https://github.com/olmozavala/particleviz.git
cd particleviz

Anaconda

Create new environment from yml file and active it.

conda env create -f particleviz.yml
conda activate particleviz

Quick Start

Once you have installed the Python dependencies and JS dependencies, then the simplest way to use ParticleViz is to run it specifying the input netcdf from the command line directly (the netcdf file should have the format from OceanParcels). You need to be patient the first time you run it because it will install all the Javascript dependencies. It will be much faster after that. This will generate the default web interface to display your data.

python ParticleViz.py --input_file <path to netcdf> 

Test it with the Global_Marine_Debris.nc file inside the ExampleData folder with:

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

Advanced Configuration

ParicleViz generates websites in two steps:

• Preprocessing. This first step transforms the lagrangian outputs into multiple binary files that can be transferred efficiently by the internet.
• App builder. The second step generates a website (react app) that reads binary outputs from the preprocessing step.

All the customizations of these two steps are made through a json file. There are several examples at the ConfigExamples folder. The simples config file you can generate will have just information on the location of your dataset, like this:

{
  "preprocessing": {
    "models": [{
        "name": "Dataset 1",
        "file_name": "./ExampleData/Global_Marine_debris.nc"}]
    }
}

To run ParticleViz from a config file you can do it with the following options

  ParticleViz.py  all --config_file <config_file>
  ParticleViz.py  preproc --config_file <config_file>
  ParticleViz.py  webapp --config_file <config_file>

To run both steps, Preprocessing and App builder, you will use the all command. To only preprocess your data you you will use preproc and to only generate the website you will use webapp (you need to run preproc at least once before running webapp).

A configuration file example with all the possible options is the following:

{
  "preprocessing": {
    "models": [
      {
        "name": "January 2010",
        "file_name": "./ExampleData/Global_Marine_Debris.nc",
        "subsample": { "desktop": 2, "mobile": 4 }
      },
      {
        "name": "January 2010",
        "file_name": "./ExampleData/Global_Marine_Debris.nc",
        "subsample": { "desktop": 6, "mobile": 8 }
      }
    ],
    "output_folder": "./ParticleViz_WebApp/data/"
  },
  "webapp": {
    "data_folder": "./data",
    "title": "Marine Plastic Debris Advanced",
    "particles_color": "rgba(255,105,0)",
    "intro_image": "",
    "url": "https://www.coaps.fsu.edu/our-expertise/global-model-for-marine-litter",
    "intro": "This is an example of a ParticleViz visualization of Marine Debris. Try other example configuration files and then with your own data!!!! ",
    "zoom-levels": [ 0.24, 0.12, 0.045, 0.01125, 0.0028125 ],
    "def-zoom": 1,
    "map-extent": [ -180, -90, 180, 90 ],
    "map-center": [ 0, 0 ],
    "logos": [{
      "img": "logos/logo_example.png",
      "url": "https://olmozavala.com"
    }],
    "extra_layers": [
      {
        "name": "World Cities",
        "file": "extra_layers/capitals.geojson",
        "color": "rgb(255,237,0)"
      }
    ]
  },
  "advanced": {
    "timesteps_by_file": 200,
    "file_prefix": "GlobalLitter"
  }
}

You can test this advanced configuration file with:

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

Parameters

Even though most of the parameters are self-explanatory, the meaning of each of them for the Preprocessing section is the following:

The list of parameter for the webapp section is the following:

Server Deployment

If you want to share your visualization with the world, you will need to deploy your site on a computer with a public ip address or in an existing web server. The proper way to do it is to build an optimized version ready for production and add it into an existing web server.

Here are the most common steps to do this:

1. Build your optimized build with npm. Inside the ParticleViz_WebApp folder, use the following command to generate this build (inside a build folder).

   cd ParticleViz_WebApp
   npm run-script build
   

   If you see .

2. Copy your build folder into you web server. For example, if you have an Apache web server at /var/www/html you could copy your project to /var/www/html/myawesomemodel. If you don’t know what I’m talking about ask your IT guy to help you.

Intro video

Here is a presentation made at OceanSciences meeting about ParticleViz in March 2022. YouTube link