maplibre-gl-layers 0.1.0

package/README.md

@@ -0,0 +1,112 @@
+# maplibre-gl-layers
+
+MapLibre's layer extension library enabling the display, movement, and modification of large numbers of dynamic sprite images
+
+![maplibre-gl-layers](images/maplibre-gl-layers-120.png)
+
+[![Project Status: Concept – Minimal or no implementation has been done yet, or the repository is only intended to be a limited example, demo, or proof-of-concept.](https://www.repostatus.org/badges/latest/concept.svg)](https://www.repostatus.org/#concept)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+----
+
+## What is this?
+
+With [MapLibre GL JS](https://maplibre.org/maplibre-gl-js/docs/), you can place markers on a map, decorate their appearance, and move them freely.
+Markers often need to move smoothly, appear and disappear over time, and you may have countless coordinates to render.
+
+**maplibre-gl-layers** is designed to meet that need.
+
+Using this package, you can place and adjust large collections of sprites (marker images) through a straightforward API:
+
+![demo 1](images/demo1.png)
+
+Here is a minimal example that places a single sprite:
+
+```typescript
+// Use MapLibre GL JS together with maplibre-gl-layers
+import { Map } from 'maplibre-gl';
+import { createSpriteLayer } from 'maplibre-gl-layers';
+
+// Create the MapLibre instance
+const map = new Map({
+  container: 'map',
+  style: 'https://demotiles.maplibre.org/style.json',
+  center: [136.885202573, 35.170006912],
+  zoom: 13,
+});
+
+// Create the SpriteLayer
+const spriteLayer = createSpriteLayer({ id: 'vehicles' });
+
+// Add the layer after the map finishes loading
+map.on('load', async () => {
+  map.addLayer(spriteLayer);
+
+  // Register an image that can be referenced by sprites
+  const MARKER_IMAGE_ID = 'marker';
+  await spriteLayer.registerImage(MARKER_IMAGE_ID, '/assets/marker.png');
+
+  // Place a sprite that uses the registered image
+  const SPRITE_ID = 'vehicle-1';
+  spriteLayer.addSprite(SPRITE_ID, {
+    // Specific location
+    location: { lng: 136.8852, lat: 35.17 },
+    images: [
+      {
+        subLayer: 0,
+        order: 0,
+        imageId: MARKER_IMAGE_ID, // The image ID
+      },
+    ],
+  });
+
+  // ...continue manipulating sprites through the SpriteLayer API
+});
+```
+
+You can place, update, and remove sprites or the images assigned to them at any time through the API.
+
+In addition to images, you can render text alongside sprites and animate them together. That makes it easy to build the kinds of visualizations typically required for assets, vehicles, or other moving features:
+
+![demo 2](images/demo2.png)
+
+### Main Features
+
+- Place, update, and remove large numbers of sprites.
+- Move each sprite's coordinate freely, making it easy to represent moving objects.
+- Specify per-sprite anchor positions for precise rendering.
+- Add multiple images and text to the same sprite, adjusting rotation, offset, scale, opacity, and more.
+- Animate sprite movement, rotation, and offsets with interpolation controls.
+- Control draw order via sub-layers and per-sprite ordering.
+- Bulk update API for many sprite states.
+- No package dependencies except MapLibre.
+
+### Requirements
+
+- MapLibre GL JS 5.9 or higher
+
+---
+
+## Installation
+
+The library is published as an npm package. Install it in your project with:
+
+```bash
+npm install maplibre-gl-layers
+```
+
+----
+
+## Documentation
+
+[See the repository documentation](http://github.com/kekyo/maplibre-gl-layers/).
+
+## Discussions and Pull Requests
+
+For discussions, please refer to the [GitHub Discussions page](https://github.com/kekyo/maplibre-gl-layers/discussions). We have currently stopped issue-based discussions.
+
+Pull requests are welcome! Please submit them as diffs against the `develop` branch and squashed changes before send.
+
+## License
+
+Under MIT.

package/dist/SpriteLayer.d.ts

@@ -0,0 +1,256 @@
+/*!
+ * name: maplibre-gl-layers
+ * version: 0.1.0
+ * description: MapLibre's layer extension library enabling the display, movement, and modification of large numbers of dynamic sprite images
+ * author: Kouji Matsui (@kekyo@mi.kekyo.net)
+ * license: MIT
+ * repository.url: https://github.com/kekyo/maplibre-gl-layers.git
+ * git.commit.hash: 88b09a93779279947d9c6b1e3a7538d4d197dbcb
+ */
+
+import { Map as MapLibreMap } from 'maplibre-gl';
+import { SpriteMode, SpriteLayerInterface, SpriteLayerOptions, SpriteAnchor, SpriteLocation, SpriteImageDefinitionInit, SpriteImageOffset, SpriteInterpolationOptions, SpriteNumericInterpolationOptions, SpriteImageOriginLocation } from './types';
+import { SpriteInterpolationState } from './interpolation';
+import { NumericInterpolationState } from './numericInterpolation';
+/**
+ * Compact representation of an Array-like 4x4 matrix.
+ * Accepts typed arrays sourced from MapLibre internals.
+ */
+type MatrixInput = ArrayLike<number>;
+/**
+ * Cached clip-space context containing the mercator matrix required to project coordinates.
+ * @property {MatrixInput} mercatorMatrix - Matrix mapping Mercator coordinates to clip space.
+ */
+type ClipContext = {
+    readonly mercatorMatrix: MatrixInput;
+};
+/**
+ * Computes the perspective ratio from MapLibre's internal transform.
+ * Used to calculate distance-based scaling that responds to pitch, zoom, and altitude.
+ * @param {MapLibreMap} mapInstance - MapLibre map providing the transform and camera distance.
+ * @param {SpriteLocation} location - Location used to derive mercator coordinates for scaling.
+ * @returns {number} Perspective ratio applied when scaling sprites; defaults to 1 if unavailable.
+ */
+export declare const calculatePerspectiveRatio: (mapInstance: MapLibreMap, location: SpriteLocation) => number;
+/**
+ * Multiplies a 4x4 matrix with a 4-component vector using row-major indexing.
+ * @param {MatrixInput} matrix - Matrix to multiply.
+ * @param {number} x - X component of the vector.
+ * @param {number} y - Y component of the vector.
+ * @param {number} z - Z component of the vector.
+ * @param {number} w - W component of the vector.
+ * @returns {[number, number, number, number]} Resulting homogeneous coordinate.
+ */
+export declare const multiplyMatrixAndVector: (matrix: MatrixInput, x: number, y: number, z: number, w: number) => [number, number, number, number];
+/**
+ * Projects a longitude/latitude/elevation tuple into clip space using the provided context.
+ * @param {number} lng - Longitude in degrees.
+ * @param {number} lat - Latitude in degrees.
+ * @param {number} elevationMeters - Elevation above the ellipsoid in meters.
+ * @param {ClipContext | null} context - Clip-space context; `null` skips projection.
+ * @returns {[number, number, number, number] | null} Clip coordinates or `null` when projection fails.
+ */
+export declare const projectLngLatToClipSpace: (lng: number, lat: number, elevationMeters: number, context: ClipContext | null) => [number, number, number, number] | null;
+/**
+ * Applies auto-rotation to all images within a sprite when movement exceeds the configured threshold.
+ * @template T Arbitrary sprite tag type.
+ * @param {InternalSpriteCurrentState<T>} sprite - Sprite undergoing potential rotation update.
+ * @param {SpriteLocation} nextLocation - Destination location used to derive bearing and distance.
+ * @returns {boolean} `true` when auto-rotation was applied, `false` otherwise.
+ */
+export declare const applyAutoRotation: <T>(sprite: InternalSpriteCurrentState<T>, nextLocation: SpriteLocation) => boolean;
+/**
+ * Compiles a shader from source, throwing if compilation fails.
+ * @param {WebGLRenderingContext} glContext - Active WebGL context.
+ * @param {number} type - Shader type (`VERTEX_SHADER` or `FRAGMENT_SHADER`).
+ * @param {string} source - GLSL source code.
+ * @returns {WebGLShader} Compiled shader object.
+ * @throws When shader creation or compilation fails.
+ */
+export declare const compileShader: (glContext: WebGLRenderingContext, type: number, source: string) => WebGLShader;
+/**
+ * Links a vertex and fragment shader into a WebGL program.
+ * @param {WebGLRenderingContext} glContext - Active WebGL context.
+ * @param {string} vertexSource - Vertex shader GLSL source.
+ * @param {string} fragmentSource - Fragment shader GLSL source.
+ * @returns {WebGLProgram} Linked shader program ready for use.
+ * @throws When linking fails or a program cannot be created.
+ */
+export declare const createShaderProgram: (glContext: WebGLRenderingContext, vertexSource: string, fragmentSource: string) => WebGLProgram;
+/**
+ * Base attributes for an image that composes a sprite.
+ */
+interface InternalSpriteImageState {
+    /**
+     * Sub-layer identifier.
+     */
+    subLayer: number;
+    /**
+     * Ordering value within the sub-layer.
+     */
+    order: number;
+    /**
+     * Image ID referenced for rendering.
+     */
+    imageId: string;
+    /**
+     * Rendering mode. Defaults to surface.
+     */
+    mode: SpriteMode;
+    /**
+     * Opacity applied to the image alpha. Defaults to 1.0.
+     */
+    opacity: number;
+    /**
+     * Multiplier for real-world meters corresponding to one image pixel. 1.0 = 1 meter. Defaults to 1.0.
+     */
+    scale: number;
+    /**
+     * Anchor position within the sprite. Defaults to [0.0, 0.0].
+     */
+    anchor: SpriteAnchor;
+    /**
+     * Offset from the sprite coordinate. Defaults to no offset.
+     */
+    offset: SpriteImageOffset;
+    /**
+     * Requested rotation angle in degrees. Defaults to 0.
+     * Billboard mode: Clockwise rotation relative to the viewport.
+     * Surface mode: Clockwise azimuth from geographic north.
+     */
+    rotateDeg: number;
+    /**
+     * Rotation currently applied during rendering.
+     */
+    displayedRotateDeg: number;
+    /**
+     * Whether auto-rotation is enabled. Defaults to true in surface mode and false in billboard mode.
+     * The sprite orientation is derived from its movement vector when enabled.
+     */
+    autoRotation: boolean;
+    /**
+     * Minimum distance in meters required before auto-rotation updates. Defaults to 20 m.
+     * Values <= 0 trigger immediate updates.
+     */
+    autoRotationMinDistanceMeters: number;
+    /**
+     * Base rotation determined by auto-rotation. Initially 0.
+     */
+    resolvedBaseRotateDeg: number;
+    /**
+     * Reference sub-layer used as the origin for offsets. Defaults to sprite coordinates.
+     */
+    originLocation?: SpriteImageOriginLocation;
+    /**
+     * Interpolation state for display rotation.
+     */
+    rotationInterpolationState: NumericInterpolationState | null;
+    /**
+     * Default interpolation options for display rotation.
+     */
+    rotationInterpolationOptions: SpriteNumericInterpolationOptions | null;
+    /**
+     * Interpolation state used for offset.offsetDeg.
+     */
+    offsetInterpolationState: NumericInterpolationState | null;
+}
+/**
+ * Sprite position interpolation state.
+ */
+type InternalSpriteInterpolationState = SpriteInterpolationState;
+/**
+ * Current sprite state.
+ * @param TTag Tag type.
+ */
+interface InternalSpriteCurrentState<TTag> {
+    /**
+     * Sprite identifier.
+     */
+    spriteId: string;
+    /**
+     * Whether the sprite is enabled.
+     */
+    isEnabled: boolean;
+    /**
+     * Current location (interpolated position when moving).
+     */
+    currentLocation: SpriteLocation;
+    /**
+     * Source location used for movement interpolation.
+     * Feedback mode: previous command location.
+     * Feed-forward mode: current command location.
+     */
+    fromLocation?: SpriteLocation;
+    /**
+     * Destination location used for movement interpolation.
+     * Feedback mode: current command location.
+     * Feed-forward mode: predicted location.
+     */
+    toLocation?: SpriteLocation;
+    /**
+     * Map of image states currently associated with the sprite.
+     */
+    images: Map<number, Map<number, InternalSpriteImageState>>;
+    /**
+     * Optional tag (null when not set).
+     */
+    tag: TTag | null;
+    /**
+     * Active interpolation state, or null when idle.
+     */
+    interpolationState: InternalSpriteInterpolationState | null;
+    /**
+     * Most recently requested interpolation options, or null if none pending.
+     */
+    pendingInterpolationOptions: SpriteInterpolationOptions | null;
+    /**
+     * Most recently commanded location, regardless of interpolation.
+     */
+    lastCommandLocation: SpriteLocation;
+    /**
+     * Latest location used as the basis for auto-rotation calculation.
+     */
+    lastAutoRotationLocation: SpriteLocation;
+    /**
+     * Last resolved base angle from auto-rotation in degrees, reused as the next initial value.
+     */
+    lastAutoRotationAngleDeg: number;
+}
+/**
+ * Clones a sprite anchor, defaulting to the origin when none supplied.
+ * @param {SpriteAnchor} [anchor] - Anchor to clone.
+ * @returns {SpriteAnchor} Safe copy for mutation within the layer state.
+ */
+export declare const cloneAnchor: (anchor?: SpriteAnchor) => SpriteAnchor;
+/**
+ * Clones an image offset, applying defaults when missing.
+ * @param {SpriteImageOffset} [offset] - Offset definition to copy.
+ * @returns {SpriteImageOffset} Cloned offset structure.
+ */
+export declare const cloneOffset: (offset?: SpriteImageOffset) => SpriteImageOffset;
+/**
+ * Deep-clones movement interpolation options to prevent shared references between sprites.
+ * @param {SpriteInterpolationOptions} options - Options provided by the user.
+ * @returns {SpriteInterpolationOptions} Cloned options object.
+ */
+export declare const cloneInterpolationOptions: (options: SpriteInterpolationOptions) => SpriteInterpolationOptions;
+/**
+ * Creates internal sprite image state from initialization data and layer bookkeeping fields.
+ * @param {SpriteImageDefinitionInit} imageInit - Caller-provided image definition.
+ * @param {number} subLayer - Sub-layer index the image belongs to.
+ * @param {number} order - Ordering slot within the sub-layer.
+ * @returns {InternalSpriteImageState} Normalized internal state ready for rendering.
+ */
+export declare const createImageStateFromInit: (imageInit: SpriteImageDefinitionInit, subLayer: number, order: number) => InternalSpriteImageState;
+/**
+ * Factory that creates the MapLibre layer interface for the sprite layer.
+ * Implements the CustomLayerInterface lifecycle (init -> render -> dispose), packing thousands
+ * of sprites into GPU buffers for efficient rendering. Supports optional scaling controls for
+ * billboard and surface modes.
+ *
+ * @template T Arbitrary tag type for per-sprite metadata.
+ * @param {SpriteLayerOptions} [options] Initial layer options such as ID or scaling settings.
+ * @returns {SpriteLayerInterface<T>} Interface for sprite add/update/remove operations and MapLibre hooks.
+ */
+export declare const createSpriteLayer: <T = any>(options?: SpriteLayerOptions) => SpriteLayerInterface<T>;
+export {};

package/dist/easing.d.ts

@@ -0,0 +1,19 @@
+/*!
+ * name: maplibre-gl-layers
+ * version: 0.1.0
+ * description: MapLibre's layer extension library enabling the display, movement, and modification of large numbers of dynamic sprite images
+ * author: Kouji Matsui (@kekyo@mi.kekyo.net)
+ * license: MIT
+ * repository.url: https://github.com/kekyo/maplibre-gl-layers.git
+ * git.commit.hash: 88b09a93779279947d9c6b1e3a7538d4d197dbcb
+ */
+
+import { EasingFunction } from './types';
+/**
+ * Linear interpolation that clamps the value to the [0, 1] range.
+ */
+export declare const linearEasing: EasingFunction;
+/**
+ * Returns the provided easing function or falls back to linear interpolation.
+ */
+export declare const resolveEasing: (easing?: EasingFunction) => EasingFunction;