wxtiles

This is a project for weather data visualization. There are two main parts of the project:

1. Splitter - a service that splits the datasets into tiles (PNG) and some metadata (JSON) served by a fileserver backend.
2. @metoceanapi/wxtiles-leaflet - a JS API providing work with metadata, dataset manager and an implementation of a Custom Leaflet Layer for visualizing the tiles using Leaflet.

API

The API for Leaflet is designed for working with weather data tiles and allows the integration of custom layers for data visualization.

DOCS

• Leaflet

Examples

1. SimpleDemo
2. Animated blur parameter
3. Mouse Interaction

Leaflet

import "leaflet/dist/leaflet.css";
import L from "leaflet";

async function start() {
  const wxapi = new WxAPI({
    dataServerURL: "https://tiles.metoceanapi.com/data/",
    requestInit: {
      headers: new Headers({'x-api-key': 'your_key_here'}),
    },
  });

  const wxdatasetManager = await wxapi.createDatasetManager("gfs.global");
  const variable = "air.temperature.at-2m";
  // 'wind.speed.eastward.at-10m' - Vector example

  const leafletOptions = {
    opacity: 1,
    attribution: "WxTiles",
  };

  // Create a layer
  const wxsource = wxdatasetManager.createSourceLayer(
    { variable },
    leafletOptions
  );

  const map = L.map("map", { center: [0, 0], zoom: 2, zoomControl: true });
  map.addLayer(wxsource);
  await new Promise((done) => wxsource.once("load", done)); // Highly recommended to await the first load
}

Change the time step

await wxsource.setTimeStep(1); // 1 - index of the time step in the dataset

or

await wxsource.setTimeStep("2020-01-01T00:00:00Z"); // '2020-01-01T00:00:00Z' - time step in the dataset

or

await wxsource.setTimeStep(2345323454); //  time in seconds since 1970-01-01T00:00:00Z

or

await wxsource.setTimeStep(new Date("2020-01-01T00:00:00Z")); // Date object

Update the Style

await wxsource.updateCurrentStyleObject({ units: "m/s", levels: undefined }); // set levels to undefined - to automatically calculate the levels from the dataset

Preload the Time Steps

const prom = wxsource.preloadTime(10); // Load the time step 10 to the cache but do not render it
// Do stuff asynchronously
// ...
await prom; // Wait for the time step to finish loading
await wxsource.setTime(10); // Now set the time step to 10; it will render quickly from the cache

Abort Loading

const abortController = new AbortController();
console.log("setTime(5)");
const prom = wxsource.setTime(5, abortController);
abortController.abort(); // Aborts the request
await prom; // Always await, even if aborted
console.log("aborted");

Get the Current Time Step

const timeStep = wxsource.getTime();

Read Lon/Lat Data

map.on("mousemove", (e) => {
  if (!wxsource) return;
  const pos = position(e);
  const tileInfo: WxTileInfo | undefined = wxsource.getLayerInfoAtLatLon(
    pos.wrap(),
    map
  );
  if (tileInfo) {
    console.log(tileInfo);
  }
});

Animated Blur Effect

(async function step(n: number = 0) {
  await wxsource.updateCurrentStyleObject({
    isolineText: false,
    blurRadius: ~~(10 * Math.sin(n / 500) + 10),
  });
  requestAnimationFrame(step);
})();

More Interactive – Additional Level and Red Transparency around the Level Based on Current Mouse Position

await wxsource.updateCurrentStyleObject({ levels: undefined }); // Reset levels if they exist in the style
const levels = wxsource.getCurrentStyleObjectCopy().levels || [];
const colMap: [number, string][] = levels.map((level) => [
  level,
  "#" + Math.random().toString(16).slice(2, 8) + "ff",
]);

let busy = false;
map.on("mousemove", async (e) => {
  if (!wxsource || busy) return;
  busy = true;
  const tileInfo: WxTileInfo | undefined = wxsource.getLayerInfoAtLatLon(
    position(e),
    map
  );
  if (tileInfo) {
    await wxsource.updateCurrentStyleObject({
      colorMap: [...colMap, [tileInfo.inStyleUnits[0], "#ff000000"]],
    });
    console.log(tileInfo);
  }
  busy = false;
});

Legend Usage

The WxCreateLegend function is used to generate a color legend for weather map visualizations. This legend helps represent weather data with corresponding colors, making it easier to interpret the map. Pass the legendSize and style to the WxCreateLegend function to generate the legend. The function returns a WxLegend object containing:

• size: The number of color steps.
• colors: A Uint32Array of color values.
• ticks: An array of WxTick objects representing data points and their corresponding colors.
• units: The units of the data.
• showBelowMin / showAboveMax: Whether values outside the range are shown.

Example: Temperature Legend

Here’s an example of creating a temperature legend:

const style: WxColorStyleStrict = {
  colorMap: [
    [0, "#0000FF"], // blue at 0°C
    [15, "#00FF00"], // green at 15°C
    [30, "#FF0000"], // red at 30°C
  ],
  showBelowMin: true,
  showAboveMax: true,
  units: "°C",
  fill: "gradient",
};

const legend = WxCreateLegend(100, style);
console.log(legend);

This creates legend with:

• 100 color steps interpolating between blue, green, and red.
• Ticks at 0°C, 15°C, and 30°C.
• Support for values below 0°C and above 30°C.

Color Style

The WxColorStyleStrict interface defines the configuration for styling visualizations. It includes properties for controlling colors, gradients, isolines, vectors, streamlines, and more. Below is a detailed explanation of each property.

Properties

Basic Properties

• name: The name of the style.
• parent: The name of a parent style to inherit properties from (optional).

Tile Filling

• fill: Defines how tiles are filled:
  • "none": No fill, leaves the tile transparent.
  • "solid": Solid fill, no gradient between levels.
  • "gradient": Gradient fill between levels.

Isolines

• isolineColor: Defines the color of isolines:
  • "none": Do not render isolines.
  • "fill": Use the value of fill for each pixel.
  • "inverted": Use the inverted value of fill for each pixel.
  • #RGB, #RRGGBB, or #RRGGBBAA: Use a specific web color.
• isolineText: If true, render text values on isolines.
• isolineTextSizeEm: Font size of isoline text values in em units.
• isolineTextBackground: If true, render a solid background behind isoline text values.

Vectors (Wind/Current Fields)

• vectorType: Defines how vectors are represented:
  • "none": Do not render vectors.
  • "arrows": Use arrows to represent winds/currents.
  • "barbs": Use barbs to represent winds/currents.
• vectorColor: Defines the color of vectors:
  • "none": Do not render vectors.
  • "fill": Use the value of fill for each pixel.
  • "inverted": Use the inverted value of fill for each pixel.
  • #RGB, #RRGGBB, or #RRGGBBAA: Use a specific web color.
• vectorFactor: Scaling factor for vector length.

Streamlines

• streamLineColor: Defines the color of streamlines:
  • "none": Do not render streamlines.
  • "fill": Use the value of fill for each pixel.
  • "inverted": Use the inverted value of fill for each pixel.
  • #RGB, #RRGGBB, or #RRGGBBAA: Use a specific web color.
• streamLineSpeedFactor: Scaling factor for streamline length.
• streamLineGridStep: Step to seed streamlines. Smaller values create more streamlines.
• streamLineSteps: Number of steps in each streamline.
• streamLineStatic: If true, render streamlines as static lines. If false, render as animated lines.

Color Configuration

• showBelowMin: If true, fill values below the minimum range.
• showAboveMax: If true, fill values above the maximum range.
• colorScheme: Name of the color scheme from the default set.
• colors: Custom array of colors to use for interpolation (optional).
• colorMap: Array of [level, color] tuples to map specific data values to colors (optional).
• levels: Array of levels to build the legend. If not provided, 10 levels are calculated evenly based on the data.

Additional Styling

• blurRadius: Radius for the BOX filter (used for blurring).
• addDegrees: Additional rotation of wind or current vectors by a specified angle in degrees.
• units: Units of the style (e.g., °C for temperature).
• extraUnits: Additional units to extend the default set (optional).

Masking

• mask: Defines masking behavior:
  • "none": No masking.
  • "sea": Make sea areas transparent.
  • "land": Make land areas transparent.

WebGL Configuration (Optional)

• gl: Configuration for WebGL rendering:
  • animationSpeed: Speed of animations.
  • noiseTexturePow: Power of noise texture.
  • vectorFieldFactor: Scaling factor for vector fields.
  • animationIntensity: Intensity of animations.
  • wavesCount: Number of waves to render.

Default styles

Default styles can be found here