English | 日本語

Wind Particle Layer

Experimental Repository This library is currently experimental. Only PNG image loading is supported at this time. Support for other formats such as GeoTIFF is under development.

A library for visualizing vector fields. Enables particle animations and colormap displays on deck.gl.

Demo: https://wind-particle.nokonoko1203.com

Features

• Particle Animation - Renders particles flowing along vector fields
• Colormap Display - Gradient color display based on vector magnitude
• Data Loading from PNG/WebP - Easily load vector field data from image files
• Customizable - Adjustable particle density, speed, lifespan, and more

Installation

npm install particle-layer

Peer Dependencies

The following packages are required:

npm install @deck.gl/core @deck.gl/layers @luma.gl/core @luma.gl/engine @luma.gl/shadertools

Quick Start

import { Deck, MapView } from '@deck.gl/core';
import { WindParticleLayer, WindColormapLayer, PngWindLoader } from 'particle-layer';

// 1. Create a wind data loader
const loader = new PngWindLoader({
	image: '/wind-data.png',
	uRange: [-30.0, 30.0], // U component range (m/s)
	vRange: [-30.0, 30.0], // V component range (m/s)
	bounds: [138, 34, 142, 37] // [west, south, east, north] (degrees)
});

// 2. Create a wind colormap layer (optional)
const colormapLayer = new WindColormapLayer({
	id: 'wind-colormap',
	dataSource: loader,
	maxSpeedMps: 30.0
});

// 3. Create a wind particle layer
const particleLayer = new WindParticleLayer({
	id: 'wind-particles',
	dataSource: loader,
	stateTexSize: 64, // 64² = 4,096 particles
	maxAge: 5, // Particle lifespan (seconds)
	speedFactor: 2000, // Speed multiplier
	randomSpeedMps: 0.1 // Random speed (m/s)
});

// 4. Add to deck.gl
const deck = new Deck({
	parent: document.getElementById('map'),
	_animate: true,
	views: new MapView({ repeat: true }),
	initialViewState: {
		longitude: 140,
		latitude: 35.5,
		zoom: 7
	},
	controller: true,
	layers: [colormapLayer, particleLayer]
});

API Reference

PngWindLoader

A loader that reads wind data from PNG/WebP images.

import { PngWindLoader } from 'particle-layer';

const loader = new PngWindLoader({
	image: '/path/to/wind.png',
	uRange: [-30.0, 30.0],
	vRange: [-30.0, 30.0],
	bounds: [138, 34, 142, 37]
});

Options

| Property | Type | Description | | -------- | ---------------------------------- | ------------------------------------------------------- | | image | string | URL of PNG/WebP image | | uRange | [number, number] | U component (eastward velocity) range [min, max] (m/s) | | vRange | [number, number] | V component (northward velocity) range [min, max] (m/s) | | bounds | [number, number, number, number] | Geographic bounds [west, south, east, north] (degrees) |

PNG Image Format

Wind data must be encoded in PNG images using the following format:

• Red Channel (R): U component (eastward velocity)
  • Pixel value 0 → uRange[0]
  • Pixel value 255 → uRange[1]
• Green Channel (G): V component (northward velocity)
  • Pixel value 0 → vRange[0]
  • Pixel value 255 → vRange[1]
• Blue/Alpha Channels: Unused

Decoding Formula:

u = uRange[0] + (R / 255) * (uRange[1] - uRange[0])
v = vRange[0] + (G / 255) * (vRange[1] - vRange[0])

WindParticleLayer

A GPU-based wind particle animation layer.

import { WindParticleLayer } from 'particle-layer';

const layer = new WindParticleLayer({
	id: 'wind-particles',
	dataSource: loader,
	stateTexSize: 64,
	maxAge: 5,
	speedFactor: 2000,
	randomSpeedMps: 0.1,
	integrationSteps: 16
});

Properties

| Property | Type | Default | Description | | ------------------ | ---------------- | ------------ | ----------------------------------------------------------------- | | dataSource | WindDataSource | Required | Data source providing wind data | | stateTexSize | number | 256 | Particle grid size. Number of particles is stateTexSize² | | maxAge | number | 30 | Maximum particle lifespan (seconds) | | speedFactor | number | 10000.0 | Speed multiplier. Higher values make particles move faster | | randomSpeedMps | number | 0.0 | Random speed variation (m/s) | | integrationSteps | number | 16 | Integration steps per frame. More steps result in smoother motion | | maxSpeedMps | number | 30.0 | Maximum wind speed for point size scaling (m/s) | | minPointSize | number | 0.1 | Minimum particle point size (pixels) | | maxPointSize | number | 3.0 | Maximum particle point size (pixels) | | altitude | number | 0 | Altitude offset for 3D visualization (meters) |

Particle Count Guide

| stateTexSize | Particle Count | Use Case | | -------------- | -------------- | ------------------------------------------ | | 32 | 1,024 | Lightweight demo | | 64 | 4,096 | Standard use | | 128 | 16,384 | High density display | | 256 | 65,536 | Detailed visualization | | 512 | 262,144 | Maximum density (high-end GPU recommended) |

WindColormapLayer

A layer that displays a colormap based on wind speed.

import { WindColormapLayer } from 'particle-layer';

const layer = new WindColormapLayer({
	id: 'wind-colormap',
	dataSource: loader,
	maxSpeedMps: 30.0
});

Properties

| Property | Type | Default | Description | | --------------- | ---------------- | ------------ | ------------------------------------- | | dataSource | WindDataSource | Required | Data source providing wind data | | maxSpeedMps | number | 30.0 | Maximum wind speed for colormap (m/s) | | colormapAlpha | number | 140 | Colormap opacity (0-255) |

Color Gradient

The following color gradient is applied based on wind speed:

| Speed Ratio | Color | Description | | ----------- | ------------ | --------------- | | 0.0 | Dark Blue | Calm | | 0.1 | Blue | Light Air | | 0.2 | Cyan | Light Breeze | | 0.3 | Teal | Gentle Breeze | | 0.4 | Green | Moderate Breeze | | 0.5 | Yellow-Green | Fresh Breeze | | 0.6 | Yellow | Strong Breeze | | 0.7 | Orange | Near Gale | | 0.8 | Dark Orange | Gale | | 0.9 | Red | Strong Gale | | 1.0 | Purple | Storm |

Type Definitions

WindDataSource

An interface for providing wind data. Implement this when creating custom data sources.

interface WindDataSource {
	load(): Promise<WindFieldData>;
}

WindFieldData

The structure of wind field data.

interface WindFieldData {
	/** U/V interleaved array [u0, v0, u1, v1, ...] (m/s) */
	uvMps: Float32Array;

	/** Grid width (pixels) */
	width: number;

	/** Grid height (pixels) */
	height: number;

	/** Geographic bounds [west, south, east, north] (degrees) */
	bounds: [number, number, number, number];
}

Creating Custom Data Sources

You can create custom data sources by implementing the WindDataSource interface.

import type { WindDataSource, WindFieldData } from 'particle-layer';

class MyCustomLoader implements WindDataSource {
	async load(): Promise<WindFieldData> {
		// Fetch data from API
		const response = await fetch('/api/wind-data');
		const data = await response.json();

		// Convert to WindFieldData format
		const uvMps = new Float32Array(data.u.length * 2);
		for (let i = 0; i < data.u.length; i++) {
			uvMps[i * 2] = data.u[i]; // U component
			uvMps[i * 2 + 1] = data.v[i]; // V component
		}

		return {
			uvMps,
			width: data.width,
			height: data.height,
			bounds: data.bounds
		};
	}
}

// Usage
const loader = new MyCustomLoader();
const layer = new WindParticleLayer({
	id: 'wind',
	dataSource: loader
});

Performance Tuning

Recommended Settings

| Scenario | stateTexSize | integrationSteps | maxAge | | ----------- | -------------- | ------------------ | -------- | | Mobile | 32-64 | 8 | 3-5 | | Desktop | 64-128 | 16 | 5-10 | | High-end PC | 256-512 | 16-32 | 10-30 |

Tips

1. Adjust particle count: Reduce stateTexSize for better performance
2. Reduce integration steps: Lower integrationSteps to reduce computational load
3. Shorten lifespan: Decrease maxAge for more frequent particle regeneration and livelier motion
4. Adjust speed multiplier: Tune speedFactor based on zoom level for better visual results

Complete Example

import { Deck, MapView } from '@deck.gl/core';
import { TileLayer } from '@deck.gl/geo-layers';
import { BitmapLayer } from '@deck.gl/layers';
import { WindParticleLayer, WindColormapLayer, PngWindLoader } from 'particle-layer';

// Define geographic bounds
const BOUNDS: [number, number, number, number] = [138, 34, 142, 37];

// Create wind data loader
const loader = new PngWindLoader({
	image: '/wind-data.png',
	uRange: [-30.0, 30.0],
	vRange: [-30.0, 30.0],
	bounds: BOUNDS
});

// Basemap layer (OpenStreetMap)
const basemapLayer = new TileLayer({
	id: 'basemap',
	data: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
	minZoom: 0,
	maxZoom: 19,
	tileSize: 256,
	renderSubLayers: (props) => {
		const { boundingBox } = props.tile;
		return new BitmapLayer(props, {
			data: undefined,
			image: props.data,
			bounds: [boundingBox[0][0], boundingBox[0][1], boundingBox[1][0], boundingBox[1][1]]
		});
	}
});

// Wind colormap layer
const windColormapLayer = new WindColormapLayer({
	id: 'wind-colormap',
	dataSource: loader,
	maxSpeedMps: 30.0
});

// Wind particle layer
const windParticleLayer = new WindParticleLayer({
	id: 'wind-particles',
	dataSource: loader,
	stateTexSize: 64,
	maxAge: 5,
	speedFactor: 2000,
	randomSpeedMps: 0.1
});

// Initialize deck.gl
const deck = new Deck({
	parent: document.getElementById('map'),
	_animate: true, // Enable animation (required)
	views: new MapView({ repeat: true }),
	initialViewState: {
		longitude: 140,
		latitude: 35.5,
		zoom: 7,
		pitch: 0,
		bearing: 0
	},
	controller: true,
	layers: [basemapLayer, windColormapLayer, windParticleLayer]
});

Development

# Install dependencies
npm install

# Start development server
npm run dev

# Build library
npm run build:lib

# Run tests
npm test

Roadmap

The following features are planned for future development:

• GeoTIFF Loader - Direct loading of wind data from GeoTIFF format
• 3D Particle Visualization - Three-dimensional particle representation with altitude information

License

MIT