autumnplot-gl 2.0.0-beta.1

package/README.md

@@ -0,0 +1,156 @@
+# autumnplot-gl
+Hardware-accelerated geospatial data plotting in the browser
+
+## Links
+[Github](https://github.com/tsupinie/autumnplot-gl) | [API docs](https://tsupinie.github.io/autumnplot-gl/)
+
+## What is this?
+Lots of meteorological data web sites have a model where the data live on a central server, get plotted on the server, and then the server serves static images to the client. This creates a bottleneck where adding fields and view sectors takes exponentially more processing power for the server. One way around this is to offload the plotting to the client and to have the browser plot the data on a pan-and-zoomable map. Unfortunately, in the past, this has required developing low-level plotting code, and depending on the mapping library, the performance may be poor.
+
+autumnplot-gl provides a solution to this problem by making hardware-accelerated data plotting in the browser easy. This was designed with meteorological data in mind, but anyone wanting to contour geospatial data on a map can use autumnplot-gl.
+
+## Usage
+autumnplot-gl is designed to be used with either [Mapbox GL JS](https://docs.mapbox.com/mapbox-gl-js/guides/) or [MapLibre GL JS](https://maplibre.org/maplibre-gl-js-docs/) mapping libraries. Pre-built autumnplot-gl javascript files area available [here](https://tsupinie.github.io/autumnplot-gl/dist/). Adding them to your page exposes the API via the `apgl` environment variable.
+
+### A basic contour plot
+The first step in plotting data is to create a grid. Currently, the only supported grids are PlateCarree (a.k.a. Lat/Lon) and Lambert Conformal Conic.
+
+```javascript
+// Create a grid object that covers the continental United States
+const nx = 121, ny = 61;
+const grid = new apgl.PlateCarreeGrid(nx, ny, -130, 20, -65, 55);
+```
+
+Next, create a RawScalarField with the data. autumnplot-gl doesn't care about how data get to the browser, but it should end up in a Float32Array in row-major order with the first element being at the southwest corner of the grid. A future version might include support for reading from, say, a Zarr file. Once you have your data in that format, to create the raw data field:
+
+```javascript
+// Create the raw data field
+const height_field = new apgl.RawScalarField(grid, height_data);
+```
+
+Next, to contour the field, create a Contour object and pass it some options. At this time, a somewhat limited set of options is supported, but I do plan to expand this.
+
+```javascript
+// Contour the data
+const height_contour = new apgl.Contour(height_field, {color: '#000000', interval: 30});
+```
+
+Next, create the actual layer that gets added to the map. The first argument (`'height-contour'` here) is an id. It doesn't mean much, but it does need to be unique between the different `PlotLayer`s you add to the map.
+
+```javascript
+// Create the map layer
+const height_layer = new apgl.PlotLayer('height-contour', height_contour);
+```
+
+Finally, add it to the map. The interface for Mapbox and MapLibre are the same, at least currently, though there's nothing that says they'll stay that way in the future. Assuming you're using MapLibre:
+
+```javascript
+const map = new maplibregl.Map({
+    container: 'map',
+    style: 'https://api.maptiler.com/maps/basic-v2/style.json?key=' + maptiler_api_key,
+    center: [-97.5, 38.5],
+    zoom: 4
+});
+
+map.on('load', () => {
+    map.addLayer(height_layer, 'railway_transit_tunnel');
+});
+```
+
+The `'railway_transit_tunnel'` argument is a layer in the map style, and this means to add your layer just below that layer on the map. This usually produces better results than just blindly slapping all your layers on top of all the map (though the map style itself may require some tweaking to produce the best results).
+
+### Barbs
+
+Wind barb plotting is similar to the contours, but it requires using a `RawVectorField` with u and v data.
+
+```javascript
+const vector_field = new apgl.RawVectorField(grid, u_data, v_data);
+const barbs = new apgl.Barbs(vector_field, {color: '#000000', thin_fac: 16});
+const barb_layer = new apgl.PlotLayer('barbs', barbs);
+
+map.on('load', () => {
+    map.addLayer(barb_layer, 'railway_transit_tunnel');
+});
+```
+
+The wind barbs are automatically rotated based on the grid projection. Also, the density of the wind barbs is automatically varied based on the map zoom level. The `'thin_fac': 16` option means to plot every 16th wind barb in the i and j directions, and this is defined at zoom level 1. So at zoom level 2, it will plot every 8th wind barb, and at zoom level 3 every 4th wind barb, and so on. Because it divides in 2 for every deeper zoom level, `'thin_fac'` should be a power of 2.
+
+### Filled contours
+
+Plotting filled contours is also similar to plotting regular contours, but there's some additional steps for the color map. A couple color maps are available by default (see [here](#built-in-color-maps) for more details), but if you have the colors you want, creating your own is (relatively) painless (hopefully). First, set up the colormap. Here, we'll just use the bluered colormap included by default.
+
+```javascript
+const colormap = apgl.colormaps.bluered(-10, 10, 20);
+const fills = new apgl.ContourFilled(height, {cmap: colormap});
+const height_fill_layer = new apgl.PlotLayer('height-fill', fills);
+
+map.on('load', () => {
+    map.addLayer(height_fill_layer, 'railway_transit_tunnel');
+});
+```
+
+Normally, when you have color-filled contours, you have a color bar on the plot. To create an SVG color bar:
+
+```javascript
+const colorbar_svg = apgl.makeColorBar(colormap, {label: "Height Perturbation (m)", 
+                                                  ticks: [-10, -8, -6, -4, -2, 0, 2, 4, 6, 8, 10],
+                                                  orientation: 'horizontal', 
+                                                  tick_direction: 'bottom'});
+
+document.getElementById('colorbar-container').appendChild(colorbar_svg);
+```
+
+### Varying the data plots
+The previous steps have gone through plotting a static dataset on a map, but in many instances, you want to view a dataset that changes, say over time. Rather than continually remove and add new layers when the user changes the time, which would get tedious, waste video RAM, and probably wouldn't perform very well, autumnplot-gl provides `MultiPlotLayer`, which allows the plotted data to easily and quickly change over time (or height or any other axis that might be relevant).
+
+```javascript
+// Contour some data
+const height_contour_f00 = new apgl.Contour(grid, height_f00);
+const height_contour_f01 = new apgl.Contour(grid, height_f01);
+const height_contour_f02 = new apgl.Contour(grid, height_f02);
+
+// Create a varying map layer
+const height_layer_time = new apgl.MultiPlotLayer('height-contour-time');
+
+// Add the contoured data to it
+height_layer_time.addField(height_contour_f00, '20230112_1200');
+height_layer_time.addField(height_contour_f01, '20230112_1300');
+height_layer_time.addField(height_contour_f02, '20230112_1400');
+
+// Add to the map like normal
+map.on('load', () => {
+    map.addLayer(height_layer_time, 'railway_transit_tunnel');
+});
+```
+
+The second argument to `addField()` is the key to associate with this field. This example uses the absolute time, but you could just as easily use `'f00'`, `'f01'`, ... or anything else that's relevant as long as it's unique. Now to set the active time (i.e., the time that gets plotted):
+
+```javascript
+// Set the active field in the map layer (the map updates automatically)
+height_layer.setActiveKey('20230112_1200');
+```
+
+## Built-in color maps
+autumnplot-gl comes with several built-in color maps, accessible from `apgl.colormaps`. These are basic blue/red and red/blue diverging color maps plus a selection from [PivotalWeather](https://www.pivotalweather.com). The blue/red and red/blue are functions that take a minimum contour level, a maximum contour level, and a number of colors. For example, this creates a blue/red colormap starting at -10, ending at 10, and with 20 colors:
+
+```javascript
+const colormap = apgl.colormaps.bluered(-10, 10, 20);
+```
+
+Here are all the colormaps available:
+
+![colormaps](https://user-images.githubusercontent.com/885575/219983547-b5dd5603-f882-43f5-b57a-e19295fb4b64.png)
+
+## Map tiles
+The above exmple uses map tiles from [Maptiler](https://www.maptiler.com/). Map tiles from Maptiler or Mapbox or others are free up to a (reasonably generous) limit, but the pricing can be a tad steep after reaching the limit. The tiles from these services are extremely detailed, and really what you're paying for there is the hardware to store, process, and serve that data. While these tiles are very nice, the detail is way overkill for a lot of uses in meteorology. 
+
+So, I've created some [less-detailed map tiles](https://tsupinie.github.io/autumnplot-gl/tiles/) that are small enough that they can be hosted without dedicated hardware. However the tradeoff is that they're only useful down to zoom level 8 or 9 on the map, such that the viewport is somewhere between half a US state and a few counties in size. If that's good enough for you, then these tiles could be useful.
+
+## Conspicuous absences
+A few capabilities are missing from this library as of v2.0.
+* Helper functions for reading from specific data formats. For instance, I'd like to add support for reading from a zarr file.
+* A whole bunch of little things that ought to be fairly straightforward like tweaking the size of the wind barbs and contour thicknesses.
+* Support for contour labeling. I'd like to add it, but I'm not really sure how I'd do it with the contours as I've implemented them. Any WebGL gurus, get in touch.
+
+## Closing thoughts
+Even though autumnplot-gl is currently an extremely new package with relatively limited capability, I hope folks see potential and find it useful. Any contributions to fill out some missing features are welcome.

package/lib/AutumnTypes.d.ts

@@ -0,0 +1,37 @@
+interface WindProfile {
+    lat: number;
+    lon: number;
+    jlat: number;
+    ilon: number;
+    smu: number;
+    smv: number;
+    u: Float32Array;
+    v: Float32Array;
+    z: Float32Array;
+}
+interface BillboardSpec {
+    BB_WIDTH: number;
+    BB_HEIGHT: number;
+    BB_TEX_WIDTH: number;
+    BB_TEX_HEIGHT: number;
+    BB_MAG_BIN_SIZE: number;
+    BB_MAG_WRAP: number;
+    BB_MAG_MAX: number;
+}
+interface PolylineSpec {
+    origin: Float32Array;
+    verts: Float32Array;
+    extrusion: Float32Array;
+    zoom: Float32Array;
+    texcoords: Float32Array;
+}
+interface LineSpec {
+    verts: [number, number][];
+    origin: [number, number];
+    zoom: number;
+    texcoords: [number, number][];
+}
+type WebGLAnyRenderingContext = WebGLRenderingContext | WebGL2RenderingContext;
+declare function isWebGL2Ctx(gl: WebGLAnyRenderingContext): gl is WebGL2RenderingContext;
+export { isWebGL2Ctx };
+export type { WindProfile, BillboardSpec, PolylineSpec, LineSpec, WebGLAnyRenderingContext };

package/lib/AutumnTypes.js

@@ -0,0 +1,4 @@
+function isWebGL2Ctx(gl) {
+    return gl.getParameter(gl.VERSION).includes('WebGL 2.0');
+}
+export { isWebGL2Ctx };

package/lib/Barbs.d.ts

@@ -0,0 +1,56 @@
+import { PlotComponent } from "./PlotComponent";
+import { BillboardCollection } from './BillboardCollection';
+import { RawVectorField } from "./RawField";
+import { MapType } from "./Map";
+import { WebGLAnyRenderingContext } from "./AutumnTypes";
+interface BarbsOptions {
+    /**
+     * The color to use for the barbs as a hex color string;.
+     * @default '#000000'
+     */
+    color?: string;
+    /**
+     * How much to thin the barbs at zoom level 1 on the map. This effectively means to plot every `n`th barb in the i and j directions, where `n` =
+     * `thin_fac`. `thin_fac` should be a power of 2.
+     * @default 1
+     */
+    thin_fac?: number;
+}
+interface BarbsGLElems {
+    map: MapType | null;
+    barb_billboards: BillboardCollection | null;
+}
+/**
+ * A class representing a field of wind barbs. The barbs are automatically thinned based on the zoom level on the map; the user only has to provide a
+ * thinning factor at zoom level 1.
+ * @example
+ * // Create a barb field with black barbs and plotting every 16th wind barb in both i and j at zoom level 1
+ * const vector_field = new RawVectorField(grid, u_data, v_data);
+ * const barbs = new Barbs(vector_field, {color: '#000000', thin_fac: 16});
+ */
+declare class Barbs extends PlotComponent {
+    /** The vector field */
+    readonly fields: RawVectorField;
+    readonly color: [number, number, number];
+    readonly thin_fac: number;
+    /** @private */
+    gl_elems: BarbsGLElems | null;
+    /**
+     * Create a field of wind barbs
+     * @param fields - The vector field to plot as barbs
+     * @param opts   - Options for creating the wind barbs
+     */
+    constructor(fields: RawVectorField, opts: BarbsOptions);
+    /**
+     * @internal
+     * Add the barb field to a map
+     */
+    onAdd(map: MapType, gl: WebGLAnyRenderingContext): Promise<void>;
+    /**
+     * @internal
+     * Render the barb field
+     */
+    render(gl: WebGLAnyRenderingContext, matrix: number[]): void;
+}
+export default Barbs;
+export type { BarbsOptions };

package/lib/Barbs.js

@@ -0,0 +1,155 @@
+import { PlotComponent } from "./PlotComponent";
+import { BillboardCollection } from './BillboardCollection';
+import { hex2rgba } from './utils';
+const BARB_DIMS = {
+    BB_WIDTH: 85,
+    BB_HEIGHT: 256,
+    BB_TEX_WIDTH: 1024,
+    BB_TEX_HEIGHT: 1024,
+    BB_MAG_MAX: 235,
+    BB_MAG_WRAP: 60,
+    BB_MAG_BIN_SIZE: 5,
+};
+function _createBarbTexture() {
+    let canvas = document.createElement('canvas');
+    canvas.width = BARB_DIMS.BB_TEX_WIDTH;
+    canvas.height = BARB_DIMS.BB_TEX_HEIGHT;
+    function drawWindBarb(ctx, tipx, tipy, mag) {
+        const elem_full_size = BARB_DIMS.BB_WIDTH / 2 - 4;
+        const elem_spacing = elem_full_size / 2;
+        if (mag < 2.5) {
+            ctx.beginPath();
+            ctx.arc(tipx, tipy, elem_full_size / 2, 0, 2 * Math.PI);
+            ctx.stroke();
+        }
+        else {
+            let elem_pos = 0;
+            let mag_countdown = mag;
+            let staff_length = 0;
+            const n_flags = Math.floor((mag_countdown + 2.5) / 50);
+            staff_length += n_flags * elem_full_size / 2 + elem_spacing
+                + (n_flags - 1) * elem_spacing / 2;
+            mag_countdown -= n_flags * 50;
+            const n_full_barbs = Math.floor((mag_countdown + 2.5) / 10);
+            staff_length += n_full_barbs * elem_spacing;
+            mag_countdown -= n_full_barbs * 10;
+            const n_half_barbs = Math.floor((mag_countdown + 2.5) / 5);
+            staff_length += n_half_barbs * elem_spacing;
+            if (mag < 7.5) {
+                staff_length += elem_spacing;
+            }
+            staff_length = Math.max(120, staff_length);
+            // staff
+            ctx.beginPath();
+            ctx.moveTo(tipx, tipy);
+            ctx.lineTo(tipx, tipy + staff_length);
+            mag_countdown = mag;
+            elem_pos = tipy + staff_length;
+            let last_was_flag = false;
+            let first_elem = true;
+            while (mag_countdown > 47.5) {
+                if (last_was_flag)
+                    elem_pos += elem_spacing / 2;
+                // flag
+                if (!first_elem) {
+                    ctx.moveTo(tipx, elem_pos);
+                }
+                ctx.lineTo(tipx - elem_full_size, elem_pos);
+                ctx.lineTo(tipx, elem_pos - elem_full_size / 2);
+                elem_pos -= elem_full_size / 2 + elem_spacing;
+                mag_countdown -= 50;
+                last_was_flag = true;
+                first_elem = false;
+            }
+            while (mag_countdown > 7.5) {
+                // full barb
+                if (!first_elem) {
+                    ctx.moveTo(tipx, elem_pos);
+                }
+                ctx.lineTo(tipx - elem_full_size, elem_pos + elem_full_size / 2);
+                elem_pos -= elem_spacing;
+                mag_countdown -= 10;
+                first_elem = false;
+            }
+            if (mag < 7.5) {
+                elem_pos -= elem_spacing;
+            }
+            while (mag_countdown > 2.5) {
+                // half barb
+                ctx.moveTo(tipx, elem_pos);
+                ctx.lineTo(tipx - elem_full_size / 2, elem_pos + elem_full_size / 4);
+                mag_countdown -= 5;
+            }
+            ctx.stroke();
+        }
+    }
+    let ctx = canvas.getContext('2d');
+    if (ctx === null) {
+        throw "Could not get rendering context for the wind barb canvas";
+    }
+    ctx.lineWidth = 8;
+    ctx.miterLimit = 4;
+    for (let ibarb = 0; ibarb <= BARB_DIMS.BB_MAG_MAX; ibarb += BARB_DIMS.BB_MAG_BIN_SIZE) {
+        const x_pos = (ibarb % BARB_DIMS.BB_MAG_WRAP) / BARB_DIMS.BB_MAG_BIN_SIZE * BARB_DIMS.BB_WIDTH + BARB_DIMS.BB_WIDTH / 2;
+        const y_pos = Math.floor(ibarb / BARB_DIMS.BB_MAG_WRAP) * BARB_DIMS.BB_HEIGHT + BARB_DIMS.BB_WIDTH / 2;
+        drawWindBarb(ctx, x_pos, y_pos, ibarb);
+    }
+    return canvas;
+}
+let BARB_TEXTURE = null;
+/**
+ * A class representing a field of wind barbs. The barbs are automatically thinned based on the zoom level on the map; the user only has to provide a
+ * thinning factor at zoom level 1.
+ * @example
+ * // Create a barb field with black barbs and plotting every 16th wind barb in both i and j at zoom level 1
+ * const vector_field = new RawVectorField(grid, u_data, v_data);
+ * const barbs = new Barbs(vector_field, {color: '#000000', thin_fac: 16});
+ */
+class Barbs extends PlotComponent {
+    /**
+     * Create a field of wind barbs
+     * @param fields - The vector field to plot as barbs
+     * @param opts   - Options for creating the wind barbs
+     */
+    constructor(fields, opts) {
+        super();
+        this.fields = fields;
+        const color = hex2rgba(opts.color || '#000000');
+        this.color = [color[0], color[1], color[2]];
+        this.thin_fac = opts.thin_fac || 1;
+        this.gl_elems = null;
+    }
+    /**
+     * @internal
+     * Add the barb field to a map
+     */
+    async onAdd(map, gl) {
+        gl.getExtension('OES_texture_float');
+        gl.getExtension('OES_texture_float_linear');
+        const map_max_zoom = map.getMaxZoom();
+        if (BARB_TEXTURE === null) {
+            BARB_TEXTURE = _createBarbTexture();
+        }
+        const barb_image = { format: gl.RGBA, type: gl.UNSIGNED_BYTE, image: BARB_TEXTURE, mag_filter: gl.NEAREST };
+        const barb_billboards = new BillboardCollection(gl, this.fields, this.thin_fac, map_max_zoom, barb_image, BARB_DIMS, this.color, 0.1);
+        this.gl_elems = {
+            map: map, barb_billboards: barb_billboards
+        };
+    }
+    /**
+     * @internal
+     * Render the barb field
+     */
+    render(gl, matrix) {
+        if (this.gl_elems === null)
+            return;
+        const gl_elems = this.gl_elems;
+        const zoom = gl_elems.map.getZoom();
+        const map_width = gl_elems.map.getCanvas().width;
+        const map_height = gl_elems.map.getCanvas().height;
+        const bearing = gl_elems.map.getBearing();
+        const pitch = gl_elems.map.getPitch();
+        gl_elems.barb_billboards.render(gl, matrix, [map_width, map_height], zoom, bearing, pitch);
+    }
+}
+export default Barbs;

package/lib/BillboardCollection.d.ts

@@ -0,0 +1,17 @@
+import { BillboardSpec, WebGLAnyRenderingContext } from "./AutumnTypes";
+import { RawVectorField } from "./RawField";
+import { WGLBuffer, WGLProgram, WGLTexture, WGLTextureSpec } from "autumn-wgl";
+declare class BillboardCollection {
+    readonly spec: BillboardSpec;
+    readonly color: [number, number, number];
+    readonly size_multiplier: number;
+    readonly program: WGLProgram;
+    vertices: WGLBuffer | null;
+    texcoords: WGLBuffer | null;
+    readonly texture: WGLTexture;
+    readonly u_texture: WGLTexture;
+    readonly v_texture: WGLTexture;
+    constructor(gl: WebGLAnyRenderingContext, field: RawVectorField, thin_fac: number, max_zoom: number, billboard_image: WGLTextureSpec, billboard_spec: BillboardSpec, billboard_color: [number, number, number], billboard_size_mult: number);
+    render(gl: WebGLAnyRenderingContext, matrix: number[], [map_width, map_height]: [number, number], map_zoom: number, map_bearing: number, map_pitch: number): void;
+}
+export { BillboardCollection };

package/lib/BillboardCollection.js

@@ -0,0 +1,149 @@
+import { isWebGL2Ctx } from "./AutumnTypes";
+import { WGLProgram, WGLTexture } from "autumn-wgl";
+const billboard_vertex_shader_src = `uniform mat4 u_matrix;
+
+attribute vec3 a_pos;    
+attribute vec2 a_tex_coord;
+uniform lowp float u_bb_size;
+uniform lowp float u_map_aspect;
+uniform lowp float u_zoom;
+uniform highp float u_map_bearing;
+uniform lowp float u_bb_width;  
+uniform lowp float u_bb_height; 
+uniform highp float u_bb_mag_bin_size;
+
+uniform highp float u_bb_mag_wrap;
+
+uniform sampler2D u_u_sampler;
+uniform sampler2D u_v_sampler;
+
+varying highp vec2 v_tex_coord;
+
+mat4 scalingMatrix(float x_scale, float y_scale, float z_scale) {
+    return mat4(x_scale, 0.0,     0.0,     0.0,
+                0.0,     y_scale, 0.0,     0.0,
+                0.0,     0.0,     z_scale, 0.0,
+                0.0,     0.0,     0.0,     1.0);
+}
+
+mat4 rotationZMatrix(float angle) {
+    float s = sin(angle);
+    float c = cos(angle);
+
+    return mat4( c,  s,  0., 0.,
+                -s,  c,  0., 0.,
+                 0., 0., 1., 0.,
+                 0., 0., 0., 1.);
+}
+
+mat4 rotationXMatrix(float angle) {
+    float s = sin(angle);
+    float c = cos(angle);
+
+    return mat4( 1.,  0., 0., 0.,
+                 0.,  c,  s,  0.,
+                 0., -s,  c,  0.,
+                 0.,  0., 0., 1.);
+}
+
+void main() {
+    vec4 pivot_pos = u_matrix * vec4(a_pos.xy, 0.0, 1.0);
+    highp float zoom_corner = a_pos.z;
+    lowp float min_zoom = floor(zoom_corner / 4.0);
+    lowp float corner = mod(zoom_corner, 4.0);
+
+    highp float u = texture2D(u_u_sampler, a_tex_coord).r;
+    highp float v = texture2D(u_v_sampler, a_tex_coord).r;
+
+    lowp float bb_aspect = u_bb_width / u_bb_height;
+    lowp float ang = atan(v, u) - 3.141592654 / 2.0;
+    highp float mag = length(vec2(u, v));
+    mag = floor(mag / u_bb_mag_bin_size + 0.5) * u_bb_mag_bin_size;
+
+    vec4 offset = vec4(0.0, 0.0, 0.0, 0.0);
+    vec2 texcoord = vec2(0.0, 0.0);
+    
+    if (u_zoom >= min_zoom) {
+        vec2 tex_loc = vec2(mod(mag, u_bb_mag_wrap) / u_bb_mag_bin_size * u_bb_width, floor(mag / u_bb_mag_wrap) * u_bb_height);
+
+        if (corner < 0.5) {
+            offset = vec4(-u_bb_size, u_bb_size, 0., 0.);
+            texcoord = tex_loc;
+        }
+        else if (corner < 1.5) {
+            offset = vec4(u_bb_size, u_bb_size, 0., 0.);
+            texcoord = tex_loc + vec2(u_bb_width, 0.0);
+        }
+        else if (corner < 2.5) {
+            offset = vec4(-u_bb_size, -u_bb_size * (2. / bb_aspect - 1.), 0., 0.);
+            texcoord = tex_loc + vec2(0.0, u_bb_height);
+        }
+        else if (corner < 3.5) {
+            offset = vec4(u_bb_size, -u_bb_size * (2. / bb_aspect - 1.), 0., 0.);
+            texcoord = tex_loc + vec2(u_bb_width, u_bb_height);
+        }
+
+        mat4 barb_rotation = rotationZMatrix(ang + radians(u_map_bearing));
+        mat4 map_stretch_matrix = scalingMatrix(1.0, 1. / u_map_aspect, 1.0);
+        offset = map_stretch_matrix * barb_rotation * offset;
+    }
+
+    gl_Position = pivot_pos + offset;
+    v_tex_coord = texcoord;
+}`
+const billboard_fragment_shader_src = `varying highp vec2 v_tex_coord;
+
+uniform sampler2D u_sampler;
+uniform lowp vec3 u_bb_color;
+
+void main() {
+    lowp vec4 tex_color = texture2D(u_sampler, v_tex_coord);
+    gl_FragColor = vec4(u_bb_color, tex_color.a); 
+}`
+class BillboardCollection {
+    constructor(gl, field, thin_fac, max_zoom, billboard_image, billboard_spec, billboard_color, billboard_size_mult) {
+        this.spec = billboard_spec;
+        this.color = billboard_color;
+        this.size_multiplier = billboard_size_mult;
+        this.program = new WGLProgram(gl, billboard_vertex_shader_src, billboard_fragment_shader_src);
+        this.vertices = null;
+        this.texcoords = null;
+        const n_density_tiers = Math.log2(thin_fac);
+        const n_inaccessible_tiers = Math.max(n_density_tiers + 1 - max_zoom, 0);
+        const trim_inaccessible = Math.pow(2, n_inaccessible_tiers);
+        const earth_relative = field.getThinnedField(trim_inaccessible, trim_inaccessible).toEarthRelative();
+        const u_thin = earth_relative.u;
+        const v_thin = earth_relative.v;
+        (async () => {
+            const { vertices, texcoords } = await earth_relative.grid.getWGLBillboardBuffers(gl, thin_fac / trim_inaccessible, max_zoom);
+            this.vertices = vertices;
+            this.texcoords = texcoords;
+        })();
+        const format = isWebGL2Ctx(gl) ? gl.R32F : gl.LUMINANCE;
+        const u_image = { 'format': format, 'type': gl.FLOAT,
+            'width': u_thin.grid.ni, 'height': u_thin.grid.nj, 'image': u_thin.data,
+            'mag_filter': gl.NEAREST,
+        };
+        const v_image = { 'format': format, 'type': gl.FLOAT,
+            'width': v_thin.grid.ni, 'height': v_thin.grid.nj, 'image': v_thin.data,
+            'mag_filter': gl.NEAREST,
+        };
+        this.texture = new WGLTexture(gl, billboard_image);
+        this.u_texture = new WGLTexture(gl, u_image);
+        this.v_texture = new WGLTexture(gl, v_image);
+    }
+    render(gl, matrix, [map_width, map_height], map_zoom, map_bearing, map_pitch) {
+        if (this.vertices === null || this.texcoords === null)
+            return;
+        const bb_size = this.spec.BB_HEIGHT * (map_height / map_width) * this.size_multiplier;
+        const bb_width = this.spec.BB_WIDTH / this.spec.BB_TEX_WIDTH;
+        const bb_height = this.spec.BB_HEIGHT / this.spec.BB_TEX_HEIGHT;
+        this.program.use({ 'a_pos': this.vertices, 'a_tex_coord': this.texcoords }, { 'u_bb_size': bb_size, 'u_bb_width': bb_width, 'u_bb_height': bb_height,
+            'u_bb_mag_bin_size': this.spec.BB_MAG_BIN_SIZE, 'u_bb_mag_wrap': this.spec.BB_MAG_WRAP,
+            'u_bb_color': this.color, 'u_matrix': matrix, 'u_map_aspect': map_height / map_width, 'u_zoom': map_zoom, 'u_map_bearing': map_bearing }, { 'u_sampler': this.texture, 'u_u_sampler': this.u_texture, 'u_v_sampler': this.v_texture });
+        gl.enable(gl.BLEND);
+        gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
+        this.program.draw();
+    }
+}
+export { BillboardCollection };

package/lib/ColorBar.d.ts

@@ -0,0 +1,70 @@
+import { Color, ColorMap } from "./Colormap";
+type ColorbarOrientation = 'horizontal' | 'vertical';
+type ColorbarTickDirection = 'top' | 'bottom' | 'left' | 'right';
+interface ColorBarOptions {
+    /** The label to place along the color bar */
+    label?: string;
+    /**
+     * An array of numbers to use as the tick locations.
+     * @default Use all the levels in the color map provided to {@link makeColorBar}.
+     */
+    ticks?: number[];
+    /**
+     * The direction the ticks should face. Valid values are 'left' and 'right' if orientation is 'vertical' and 'top' and
+     * 'bottom' if orientation is 'horizontal'.
+     * @default 'left' if orientation is 'vertical' and 'bottom' if orientation is 'horizontal'
+     */
+    tick_direction?: ColorbarTickDirection;
+    /**
+     * The orientation for the color bar. Valid values are 'horizontal' and 'vertical'.
+     * @default 'vertical'
+     */
+    orientation?: ColorbarOrientation;
+    /**
+     * A font face to use for the label and tick values.
+     * @default 'sans-serif'
+     */
+    fontface?: string;
+}
+/**
+ * Make an SVG containing a color bar. The color bar can either be oriented horizontal or vertical, and a label can be provided.
+ * @param colormap - The color map to use
+ * @param opts     - The options for creating the color bar
+ * @returns An SVGElement containing the color bar image.
+ * @example
+ * // Create the color bar
+ * const svg = makeColorBar(color_map, {label: 'Wind Speed (kts)', orientation: 'horizontal',
+ *                                      fontface: 'Trebuchet MS'});
+ *
+ * // Add colorbar to the page
+ * document.getElementById('colorbar-container').appendChild(svg);
+ */
+declare function makeColorBar(colormap: ColorMap, opts: ColorBarOptions): SVGElement;
+interface PaintballKeyOptions {
+    /**
+     * The number of columns of entries in the key
+     * @default 1
+     */
+    n_cols?: number;
+    /**
+     * A font face to use for the label and tick values.
+     * @default 'sans-serif'
+     */
+    fontface?: string;
+}
+/**
+ * Make an SVG containing a color key for a paintball plot. The key can be split over any number of columns.
+ * @param colors - A list of colors
+ * @param labels - The labels corresponding to each color
+ * @param opts   - The options for creating the color key
+ * @returns An SVGElement containing the color bar image.
+ * @example
+ * // Create the color key
+ * const svg = makePaintballKey(colors, labels, {n_cols: 2, fontface: 'Trebuchet MS'});
+ *
+ * // Add the color key to the page
+ * document.getElementById('pb-key-container').appendChild(svg);
+ */
+declare function makePaintballKey(colors: (Color | string)[], labels: string[], opts?: PaintballKeyOptions): SVGElement;
+export { makeColorBar, makePaintballKey };
+export type { ColorbarOrientation, ColorbarTickDirection, ColorBarOptions, PaintballKeyOptions };