Particles
- Last UpdatedFeb 27, 2025
- 2 minute read
Displays a layer that renders and animates particles (wind, waves, etc.) with multiple configurations like frame rate or velocity. It requires vector data (U and V components) for every point in a grid (for example for every degree of latitude and longitude) to calculate the movement animation.
Data needs to be given in GRIB2 format (specification), similar to the one provided by the US National Oceanic and Atmospheric Administration (NOAA). The file can be accessed through a URL or by passing the binary data encoded in Base64 (so you can download or get the data on a script and send it to the map in runtime).
The GRIB2 files from the Global Forecast System (GFS) with historical and forecasted weather data can be accessed from the NCEP Products Inventory. Data files can be filtered to include only a region and to select the desired metrics. The GFS models are run four times a day and for each run an hourly forecast is generated for the next 384 hours (16 days).
Wind data at 10m above ground can be accessed using the following url template:
https://nomads.ncep.noaa.gov/cgi-bin/filter_gfs_{grid}.pl?dir=%2Fgfs.
{date}%2F{cycle}%2Fatmos&file=gfs.t{cycle}z.pgrb2.
{grid}.f{forecast}&var_UGRD=on&var_VGRD=on&lev_10_m_above_ground=on
|
Parameter |
Description |
Possible Values |
|---|---|---|
|
{grid} |
Longitude-latitude grid size |
1p00 (1 degree), 0p50 (0.5 degrees) or 0p25 (0.25 degrees) |
|
{date} |
Model cycle |
date Date in YYYYMMDD format |
|
{cycle} |
Model cycle runtime |
00, 06, 12 or 18 |
|
{forecast} |
Forecast hour |
000 (current) to 384 |
For example, to get a 1-degree sized grid of current data, for the model run on 2023-12-12 at 6AM the url would be:
https://nomads.ncep.noaa.gov/cgi-bin/filter_gfs_1p00.pl?
dir=%2Fgfs.20231212%2F06%2Fatmos&file=gfs.t06z.pgrb2.1p00.f000&var_UGRD=on&var_VGRD=on&lev_10
_m_above_ground=on
Below are the configurable options for this type of layer:
|
Property |
Type |
Description |
|---|---|---|
|
colorScale [Optional] |
String[] |
Describes particle gradient color configuration. |
|
data [Optional] |
Object |
Defines Base64 encoded GRIB2 file content or decoded data JSON object. For more information, refer https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/. |
|
forceRender [Optional] |
Boolean |
Particles are always displayed when the mouse interacts (zoom and pan).
|
|
frameRate [Optional] |
Number |
Defines animation frame rate (ms).
|
|
lineWidth [Optional] |
Number |
Defines particle path width.
|
|
maxAge [Optional] |
Number |
Defines the maximum number of frames that a particle path exists.
|
|
maxVelocity [Optional] |
Number |
Defines particle maximum speed. Configuring this value primarily affects the color index. |
|
minVelocity [Optional] |
Number |
Defines particle minimum speed. Configuring this value primarily affects the color index. |
|
paths [Optional] |
Number |
Defines the number of particle paths generated.
|
|
type |
particles |
A type of Layer. |
|
url [Optional] |
String |
URL of the GRIB2 file to use. For more information, refer https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/. |
|
velocityScale [Optional] |
Number |
Defines the scale particles animation speed. Set values between 0 and 1 to make it slower and values higher than 1 to increase the speed.
|
Examples of Particles
Below is an example of configuration of a particles layer:
-
Configuration and map preview
-
JSON string configuration
{
"title": "Particles",
"type": "particles",
"isBaseMap": false,
"url": "YOUR_URL",
"velocityScale": 0.
}