maplibre-gl-layers 0.1.0

package/dist/interpolation.d.ts

@@ -0,0 +1,90 @@
+/*!
+ * 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, SpriteInterpolationMode, SpriteInterpolationOptions, SpriteLocation } from './types';
+/**
+ * Runtime state describing the active interpolation between two sprite locations.
+ * Consumers reuse the same state across ticks to avoid re-allocations while animation is running.
+ *
+ * @property mode - Strategy used to resolve the target location (feedback or feedforward).
+ * @property durationMs - Total time allocated for the interpolation in milliseconds.
+ * @property easing - Resolved easing function applied to raw progress values.
+ * @property startTimestamp - Epoch millisecond when the interpolation started, or -1 when uninitialised.
+ * @property from - Origin sprite location cloned from the current render state.
+ * @property to - Destination sprite location being interpolated towards.
+ */
+export interface SpriteInterpolationState {
+    readonly mode: SpriteInterpolationMode;
+    readonly durationMs: number;
+    readonly easing: EasingFunction;
+    startTimestamp: number;
+    readonly from: SpriteLocation;
+    readonly to: SpriteLocation;
+}
+/**
+ * Parameters required to create a fresh interpolation state for the next animation segment.
+ *
+ * @property currentLocation - Sprite location currently rendered on screen.
+ * @property lastCommandLocation - Previously commanded target, used for feedforward extrapolation.
+ * @property nextCommandLocation - Upcoming commanded target that the sprite should reach.
+ * @property options - Raw interpolation options supplied by the caller.
+ */
+export interface CreateInterpolationStateParams {
+    currentLocation: SpriteLocation;
+    lastCommandLocation?: SpriteLocation;
+    nextCommandLocation: SpriteLocation;
+    options: SpriteInterpolationOptions;
+}
+/**
+ * Result of preparing interpolation state, including a flag denoting whether any lerp is needed.
+ *
+ * @property state - Prepared interpolation state ready for evaluation.
+ * @property requiresInterpolation - Indicates whether lerping is needed or an immediate snap is sufficient.
+ */
+export interface CreateInterpolationStateResult {
+    readonly state: SpriteInterpolationState;
+    readonly requiresInterpolation: boolean;
+}
+/**
+ * Creates interpolation state for the next sprite movement and signals if interpolation is necessary.
+ *
+ * @param params - The context needed to build interpolation state, including locations and configuration.
+ * @returns The prepared state alongside a boolean indicating whether animation should run.
+ */
+export declare const createInterpolationState: (params: CreateInterpolationStateParams) => CreateInterpolationStateResult;
+/**
+ * Parameters required to evaluate an interpolation tick at a given moment.
+ *
+ * @property state - Active interpolation state previously created.
+ * @property timestamp - Epoch millisecond at which interpolation should be evaluated.
+ */
+export interface EvaluateInterpolationParams {
+    state: SpriteInterpolationState;
+    timestamp: number;
+}
+/**
+ * Result of evaluating interpolation progress at a specific timestamp.
+ *
+ * @property location - Interpolated sprite location corresponding to the evaluated time.
+ * @property completed - Indicates whether the interpolation has reached or exceeded its duration.
+ * @property effectiveStartTimestamp - Timestamp detected or assigned as the interpolation starting point.
+ */
+export interface EvaluateInterpolationResult {
+    readonly location: SpriteLocation;
+    readonly completed: boolean;
+    readonly effectiveStartTimestamp: number;
+}
+/**
+ * Evaluates an interpolation state at a specific point in time and returns the intermediate location.
+ *
+ * @param params - The interpolation state and the reference timestamp for evaluation.
+ * @returns The lerped location, whether the interpolation has finished, and the effective start time.
+ */
+export declare const evaluateInterpolation: (params: EvaluateInterpolationParams) => EvaluateInterpolationResult;

package/dist/location.d.ts

@@ -0,0 +1,24 @@
+/*!
+ * 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 { SpriteLocation } from './types';
+/**
+ * Produces a deep copy so later updates do not mutate the original object.
+ */
+export declare const cloneSpriteLocation: (location: SpriteLocation) => SpriteLocation;
+/**
+ * Linearly interpolates longitude, latitude, and optionally altitude.
+ * The `ratio` may fall outside [0, 1]; callers are responsible for clamping if needed.
+ */
+export declare const lerpSpriteLocation: (from: SpriteLocation, to: SpriteLocation, ratio: number) => SpriteLocation;
+/**
+ * Compares two locations. Treats altitude as equal when either side is undefined.
+ */
+export declare const spriteLocationsEqual: (a: SpriteLocation, b: SpriteLocation) => boolean;

package/dist/math.d.ts

@@ -0,0 +1,467 @@
+/*!
+ * 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 { SpriteAnchor, SpriteImageOffset, SpriteLocation, SpriteScalingOptions } from './types';
+/**
+ * WGS84-compatible Earth radius in meters.
+ * Used to convert one radian of longitude into meters when scaling sprites.
+ * @constant
+ */
+export declare const EARTH_RADIUS_METERS = 6378137;
+/**
+ * Multiplier for converting degrees to radians.
+ * @constant
+ */
+export declare const DEG2RAD: number;
+/**
+ * Multiplier for converting radians to degrees.
+ * @constant
+ */
+export declare const RAD2DEG: number;
+/**
+ * Default MapLibre tile size used for Web Mercator calculations.
+ * @constant
+ */
+export declare const TILE_SIZE = 512;
+/**
+ * Default values that fill in missing {@link SpriteScalingOptions} fields supplied by callers.
+ * @constant
+ */
+export declare const DEFAULT_SPRITE_SCALING_OPTIONS: SpriteScalingOptions;
+/**
+ * Structure holding resolved sprite scaling options.
+ * @property {number} metersPerPixel - Effective number of meters represented by each rendered pixel.
+ * @property {number} zoomMin - Lowest zoom level at which scaling interpolation begins.
+ * @property {number} zoomMax - Highest zoom level at which scaling interpolation ends.
+ * @property {number} scaleMin - Scale multiplier applied at {@link ResolvedSpriteScalingOptions.zoomMin}.
+ * @property {number} scaleMax - Scale multiplier applied at {@link ResolvedSpriteScalingOptions.zoomMax}.
+ * @property {number} spriteMinPixel - Lower clamp for sprite size in pixels.
+ * @property {number} spriteMaxPixel - Upper clamp for sprite size in pixels.
+ */
+export type ResolvedSpriteScalingOptions = {
+    metersPerPixel: number;
+    zoomMin: number;
+    zoomMax: number;
+    scaleMin: number;
+    scaleMax: number;
+    spriteMinPixel: number;
+    spriteMaxPixel: number;
+};
+/**
+ * Fills missing {@link SpriteScalingOptions} values with defaults so downstream math can assume a complete object.
+ * @param options Optional scaling configuration from the caller.
+ * @returns {ResolvedSpriteScalingOptions} Resolved scaling settings covering every field.
+ */
+export declare const resolveScalingOptions: (options?: SpriteScalingOptions) => ResolvedSpriteScalingOptions;
+/**
+ * Computes a linear scale factor based on zoom level.
+ * @param {number} zoom - Current zoom level from MapLibre's camera.
+ * @param {ResolvedSpriteScalingOptions} scaling - Resolved scaling options.
+ * @returns {number} Scale value interpolated between {@link ResolvedSpriteScalingOptions.scaleMin} and {@link ResolvedSpriteScalingOptions.scaleMax}.
+ */
+export declare const calculateZoomScaleFactor: (zoom: number, scaling: ResolvedSpriteScalingOptions) => number;
+/**
+ * Calculates meters per pixel at the given latitude.
+ * Uses Web Mercator scale and applies the latitude-based cosine correction.
+ * @param {number} zoom - Map zoom level used to determine the Mercator scale.
+ * @param {number} latitude - Latitude in degrees where the meters-per-pixel value is resolved.
+ * @returns {number} Distance in meters represented by a single pixel at the provided latitude.
+ */
+export declare const calculateMetersPerPixelAtLatitude: (zoom: number, latitude: number) => number;
+/**
+ * Checks whether a value is finite and not `NaN`.
+ * @param {number} value - Value to validate.
+ * @returns {boolean} `true` when the number is both finite and not `NaN`.
+ */
+export declare const isFiniteNumber: (value: number) => boolean;
+/**
+ * Calculates the distance and bearing between two points in meters.
+ * @param {SpriteLocation} from - Starting point expressed in longitude/latitude (degrees) and optional altitude.
+ * @param {SpriteLocation} to - Destination point expressed in longitude/latitude (degrees) and optional altitude.
+ * @returns {{ distanceMeters: number; bearingDeg: number }} Distance in meters and bearing clockwise from north.
+ */
+export declare const calculateDistanceAndBearingMeters: (from: SpriteLocation, to: SpriteLocation) => {
+    distanceMeters: number;
+    bearingDeg: number;
+};
+/**
+ * Calculates billboard image dimensions in pixels and clamps them to display limits.
+ * @param {number | undefined} imageWidth - Source bitmap width in pixels.
+ * @param {number | undefined} imageHeight - Source bitmap height in pixels.
+ * @param {number} baseMetersPerPixel - Base scale derived from map zoom and latitude.
+ * @param {number} imageScale - User-provided scale multiplier.
+ * @param {number} zoomScaleFactor - Zoom-dependent scale multiplier derived from {@link calculateZoomScaleFactor}.
+ * @param {number} effectivePixelsPerMeter - Conversion between world meters and screen pixels.
+ * @param {number} spriteMinPixel - Lower pixel clamp for the sprite's largest side.
+ * @param {number} spriteMaxPixel - Upper pixel clamp for the sprite's largest side.
+ * @returns {{ width: number; height: number }} Pixel dimensions after scaling and clamping.
+ */
+export declare const calculateBillboardPixelDimensions: (imageWidth: number | undefined, imageHeight: number | undefined, baseMetersPerPixel: number, imageScale: number, zoomScaleFactor: number, effectivePixelsPerMeter: number, spriteMinPixel: number, spriteMaxPixel: number) => {
+    width: number;
+    height: number;
+};
+/**
+ * Computes the billboard offset in screen-space pixels.
+ * @param {SpriteImageOffset | undefined} offset - Offset configuration describing length (meters) and heading (degrees).
+ * @param {number} imageScale - User-provided scale multiplier applied to the offset distance.
+ * @param {number} zoomScaleFactor - Zoom-dependent scale multiplier.
+ * @param {number} effectivePixelsPerMeter - Conversion factor from meters to pixels.
+ * @returns {{ x: number; y: number }} Screen-space offset relative to the billboard center.
+ */
+export declare const calculateBillboardOffsetPixels: (offset: SpriteImageOffset | undefined, imageScale: number, zoomScaleFactor: number, effectivePixelsPerMeter: number) => {
+    x: number;
+    y: number;
+};
+/**
+ * Computes the screen-space shift caused by anchor rotation for billboards.
+ * @param {number} halfWidth - Half of the sprite width in pixels.
+ * @param {number} halfHeight - Half of the sprite height in pixels.
+ * @param {SpriteAnchor | undefined} anchor - Anchor definition normalized to [-1, 1] range.
+ * @param {number} totalRotateDeg - Rotation applied to the sprite, combining user and bearing rotations.
+ * @returns {{ x: number; y: number }} Pixel delta required to bring the anchor back to the requested origin.
+ */
+export declare const calculateBillboardAnchorShiftPixels: (halfWidth: number, halfHeight: number, anchor: SpriteAnchor | undefined, totalRotateDeg: number) => {
+    x: number;
+    y: number;
+};
+/**
+ * Calculates surface image dimensions in world meters.
+ * @param {number | undefined} imageWidth - Source bitmap width in pixels.
+ * @param {number | undefined} imageHeight - Source bitmap height in pixels.
+ * @param {number} baseMetersPerPixel - World meters represented by a pixel at the current zoom.
+ * @param {number} imageScale - User-provided scale multiplier.
+ * @param {number} zoomScaleFactor - Zoom-dependent scale multiplier.
+ * @returns {{ width: number; height: number }} Dimensions expressed as world-space meters.
+ */
+export declare const calculateSurfaceWorldDimensions: (imageWidth: number | undefined, imageHeight: number | undefined, baseMetersPerPixel: number, imageScale: number, zoomScaleFactor: number) => {
+    width: number;
+    height: number;
+};
+/**
+ * Computes east/north shifts from anchor rotation on surface images.
+ * @param {number} halfWidthMeters - Half of the world-space width.
+ * @param {number} halfHeightMeters - Half of the world-space height.
+ * @param {SpriteAnchor | undefined} anchor - Anchor definition normalized to [-1, 1] range.
+ * @param {number} totalRotateDeg - Rotation angle applied to the surface.
+ * @returns {{ east: number; north: number }} Displacement in meters required to apply the anchor.
+ */
+export declare const calculateSurfaceAnchorShiftMeters: (halfWidthMeters: number, halfHeightMeters: number, anchor: SpriteAnchor | undefined, totalRotateDeg: number) => {
+    east: number;
+    north: number;
+};
+/**
+ * Calculates surface image offsets in meters.
+ * @param {SpriteImageOffset | undefined} offset - Offset configuration for the surface sprite.
+ * @param {number} imageScale - User-provided scale multiplier applied to the offset distance.
+ * @returns {{ east: number; north: number }} Offset vector in meters.
+ */
+export declare const calculateSurfaceOffsetMeters: (offset: SpriteImageOffset | undefined, imageScale: number) => {
+    east: number;
+    north: number;
+};
+/**
+ * Adds east/north distances (meters) to a longitude/latitude pair.
+ * @param {number} baseLng - Base longitude in degrees.
+ * @param {number} baseLat - Base latitude in degrees.
+ * @param {number} east - Eastward displacement in meters.
+ * @param {number} north - Northward displacement in meters.
+ * @returns {SpriteLocation} New geographic position after applying the displacement.
+ */
+export declare const applySurfaceDisplacement: (baseLng: number, baseLat: number, east: number, north: number) => SpriteLocation;
+/**
+ * Converts screen coordinates to clip space.
+ * @param {number} x - Screen-space x coordinate in CSS pixels.
+ * @param {number} y - Screen-space y coordinate in CSS pixels.
+ * @param {number} drawingBufferWidth - WebGL drawing buffer width in device pixels.
+ * @param {number} drawingBufferHeight - WebGL drawing buffer height in device pixels.
+ * @param {number} pixelRatio - Device pixel ratio used to scale CSS pixels to device pixels.
+ * @returns {[number, number]} Clip-space coordinates in the range [-1, 1].
+ */
+export declare const screenToClip: (x: number, y: number, drawingBufferWidth: number, drawingBufferHeight: number, pixelRatio: number) => [number, number];
+/**
+ * Index order used to decompose a quad into two triangles.
+ * @constant
+ */
+export declare const TRIANGLE_INDICES: readonly [0, 1, 2, 2, 1, 3];
+/**
+ * UV coordinates for each corner of a quad following the index order in {@link TRIANGLE_INDICES}.
+ * @constant
+ */
+export declare const UV_CORNERS: ReadonlyArray<readonly [number, number]>;
+/**
+ * Calculates the conversion factor between meters and pixels taking perspective into account.
+ * @param {number} metersPerPixelAtLatitude - Meters covered by a single pixel at the sprite latitude.
+ * @param {number} perspectiveRatio - Additional scale factor introduced by perspective settings.
+ * @returns {number} Effective pixels per meter along the camera ray.
+ */
+export declare const calculateEffectivePixelsPerMeter: (metersPerPixelAtLatitude: number, perspectiveRatio: number) => number;
+/**
+ * Projects a geographic coordinate and elevation into homogeneous clip space.
+ * @typedef ProjectToClipSpaceFn
+ * @param {number} lng - Longitude in degrees.
+ * @param {number} lat - Latitude in degrees.
+ * @param {number} elevationMeters - Elevation offset in meters.
+ * @returns {[number, number, number, number] | null} Homogeneous clip coordinates or `null` when outside the view.
+ */
+export type ProjectToClipSpaceFn = (lng: number, lat: number, elevationMeters: number) => [number, number, number, number] | null;
+/**
+ * Unprojects a screen-space point back to longitude/latitude.
+ * @typedef UnprojectPointFn
+ * @param {{ x: number; y: number }} point - Screen-space coordinates in pixels.
+ * @returns {SpriteLocation | null} Geographic location or `null` when unprojection fails.
+ */
+export type UnprojectPointFn = (point: {
+    x: number;
+    y: number;
+}) => SpriteLocation | null;
+/**
+ * Resolves a depth key for billboards by sampling the clip-space Z at the sprite center.
+ * @param {{ x: number; y: number }} center - Screen-space center of the billboard in pixels.
+ * @param {SpriteLocation} spriteLocation - Geographic location including optional altitude.
+ * @param {UnprojectPointFn} unproject - Function for converting screen coordinates to geographic coordinates.
+ * @param {ProjectToClipSpaceFn} projectToClipSpace - Function that projects a geographic coordinate to clip space.
+ * @returns {number | null} Negative normalized device coordinate Z used for depth sorting, or `null` when unavailable.
+ */
+export declare const calculateBillboardDepthKey: (center: {
+    x: number;
+    y: number;
+}, spriteLocation: SpriteLocation, unproject: UnprojectPointFn, projectToClipSpace: ProjectToClipSpaceFn) => number | null;
+/**
+ * Signature for surface depth bias callbacks that tweak clip-space Z/W.
+ * @typedef SurfaceDepthBiasFn
+ * @param {{ index: number; clipZ: number; clipW: number }} params - Geometry index and unmodified clip coordinates.
+ * @returns {{ clipZ: number; clipW: number }} Adjusted clip coordinates used for depth evaluation.
+ */
+export type SurfaceDepthBiasFn = (params: {
+    index: number;
+    clipZ: number;
+    clipW: number;
+}) => {
+    clipZ: number;
+    clipW: number;
+};
+/**
+ * Computes a depth key for surface quads by projecting each corner and tracking the deepest point.
+ * @param {SpriteLocation} baseLngLat - Base longitude/latitude of the quad center.
+ * @param {readonly SurfaceCorner[]} displacements - Corner offsets in meters from the center.
+ * @param {SpriteLocation} spriteLocation - Sprite world location including optional altitude.
+ * @param {ProjectToClipSpaceFn} projectToClipSpace - Projection function used to reach clip space.
+ * @param {{ readonly indices?: readonly number[]; readonly biasFn?: SurfaceDepthBiasFn }} [options] - Optional overrides.
+ * @returns {number | null} Depth key suitable for sorting, or `null` when any corner cannot be projected.
+ */
+export declare const calculateSurfaceDepthKey: (baseLngLat: SpriteLocation, displacements: readonly SurfaceCorner[], spriteLocation: SpriteLocation, projectToClipSpace: ProjectToClipSpaceFn, options?: {
+    readonly indices?: readonly number[];
+    readonly biasFn?: SurfaceDepthBiasFn;
+}) => number | null;
+/**
+ * Projects a longitude/latitude pair to screen-space pixels.
+ * @typedef ProjectLngLatFn
+ * @param {SpriteLocation} lngLat - Geographic coordinate to project.
+ * @returns {{ x: number; y: number } | null} Screen coordinates or `null` when projection fails.
+ */
+export type ProjectLngLatFn = (lngLat: SpriteLocation) => {
+    x: number;
+    y: number;
+} | null;
+/**
+ * Parameters required to resolve a billboard center position.
+ * @typedef BillboardCenterParams
+ * @property {{ x: number; y: number }} base - Reference screen-space position (usually anchor point).
+ * @property {number} [imageWidth] - Source bitmap width in pixels.
+ * @property {number} [imageHeight] - Source bitmap height in pixels.
+ * @property {number} baseMetersPerPixel - Meters represented by a pixel at the sprite latitude.
+ * @property {number} imageScale - User-provided scaling multiplier.
+ * @property {number} zoomScaleFactor - Zoom-dependent scale multiplier.
+ * @property {number} effectivePixelsPerMeter - Pixels per meter after perspective adjustments.
+ * @property {number} spriteMinPixel - Lower clamp for the sprite's largest pixel dimension.
+ * @property {number} spriteMaxPixel - Upper clamp for the sprite's largest pixel dimension.
+ * @property {number} totalRotateDeg - Aggregate rotation applied to the sprite in degrees.
+ * @property {SpriteAnchor} [anchor] - Anchor definition normalized between -1 and 1.
+ * @property {SpriteImageOffset} [offset] - Offset definition applied in meters/deg.
+ */
+export type BillboardCenterParams = {
+    base: {
+        x: number;
+        y: number;
+    };
+    imageWidth?: number;
+    imageHeight?: number;
+    baseMetersPerPixel: number;
+    imageScale: number;
+    zoomScaleFactor: number;
+    effectivePixelsPerMeter: number;
+    spriteMinPixel: number;
+    spriteMaxPixel: number;
+    totalRotateDeg: number;
+    anchor?: SpriteAnchor;
+    offset?: SpriteImageOffset;
+};
+/**
+ * Resolved properties describing the billboard center and derived dimensions.
+ * @typedef BillboardCenterResult
+ * @property {number} centerX - Screen-space x coordinate after offset adjustments.
+ * @property {number} centerY - Screen-space y coordinate after offset adjustments.
+ * @property {number} halfWidth - Half of the clamped pixel width.
+ * @property {number} halfHeight - Half of the clamped pixel height.
+ * @property {number} pixelWidth - Full pixel width after scaling and clamping.
+ * @property {number} pixelHeight - Full pixel height after scaling and clamping.
+ * @property {{ x: number; y: number }} anchorShift - Pixel delta caused by anchor rotation.
+ * @property {{ x: number; y: number }} offsetShift - Pixel delta caused by radial offset.
+ */
+export type BillboardCenterResult = {
+    centerX: number;
+    centerY: number;
+    halfWidth: number;
+    halfHeight: number;
+    pixelWidth: number;
+    pixelHeight: number;
+    anchorShift: {
+        x: number;
+        y: number;
+    };
+    offsetShift: {
+        x: number;
+        y: number;
+    };
+};
+/**
+ * Calculates the final billboard center position, applying scaling, anchor, and offset adjustments.
+ * @param {BillboardCenterParams} params - Inputs describing sprite geometry and scaling context.
+ * @returns {BillboardCenterResult} Computed center position and derived metrics for rendering.
+ */
+export declare const calculateBillboardCenterPosition: (params: BillboardCenterParams) => BillboardCenterResult;
+/**
+ * Parameters controlling how billboard corners are computed in screen space.
+ * @typedef BillboardCornerParams
+ * @property {number} centerX - Screen-space x coordinate for the billboard center after offsets.
+ * @property {number} centerY - Screen-space y coordinate for the billboard center after offsets.
+ * @property {number} halfWidth - Half of the billboard width in pixels.
+ * @property {number} halfHeight - Half of the billboard height in pixels.
+ * @property {SpriteAnchor} [anchor] - Optional anchor definition normalized between -1 and 1.
+ * @property {number} totalRotateDeg - Total rotation applied to the billboard in degrees.
+ */
+export type BillboardCornerParams = {
+    centerX: number;
+    centerY: number;
+    halfWidth: number;
+    halfHeight: number;
+    anchor?: SpriteAnchor;
+    totalRotateDeg: number;
+};
+/**
+ * Screen-space coordinates combined with UV data for a quad corner.
+ * @typedef QuadCorner
+ * @property {number} x - Screen-space x coordinate.
+ * @property {number} y - Screen-space y coordinate.
+ * @property {number} u - Texture u coordinate.
+ * @property {number} v - Texture v coordinate.
+ */
+export type QuadCorner = {
+    x: number;
+    y: number;
+    u: number;
+    v: number;
+};
+/**
+ * Produces the rotated, anchor-adjusted screen-space positions for each billboard corner.
+ * @param {BillboardCornerParams} params - Inputs describing the billboard geometry.
+ * @returns {QuadCorner[]} Array containing screen- and texture-space information per corner.
+ */
+export declare const calculateBillboardCornerScreenPositions: (params: BillboardCornerParams) => QuadCorner[];
+/**
+ * Parameters for projecting a surface sprite's center into screen space.
+ * @typedef SurfaceCenterParams
+ * @property {SpriteLocation} baseLngLat - Base geographic location of the sprite.
+ * @property {number} [imageWidth] - Source bitmap width in pixels.
+ * @property {number} [imageHeight] - Source bitmap height in pixels.
+ * @property {number} baseMetersPerPixel - Base meters per pixel at the sprite latitude.
+ * @property {number} imageScale - User-provided scaling multiplier.
+ * @property {number} zoomScaleFactor - Zoom-dependent scale multiplier.
+ * @property {number} totalRotateDeg - Rotation applied to the sprite in degrees.
+ * @property {SpriteAnchor} [anchor] - Anchor definition normalized between -1 and 1.
+ * @property {SpriteImageOffset} [offset] - Offset definition applied in meters/deg.
+ * @property {ProjectLngLatFn} project - Projection function mapping longitude/latitude to screen space.
+ */
+export type SurfaceCenterParams = {
+    baseLngLat: SpriteLocation;
+    imageWidth?: number;
+    imageHeight?: number;
+    baseMetersPerPixel: number;
+    imageScale: number;
+    zoomScaleFactor: number;
+    totalRotateDeg: number;
+    anchor?: SpriteAnchor;
+    offset?: SpriteImageOffset;
+    project: ProjectLngLatFn;
+};
+/**
+ * Output describing the resolved surface center and displacement details.
+ * @typedef SurfaceCenterResult
+ * @property {{ x: number; y: number } | null} center - Projected screen coordinates or `null` when projection fails.
+ * @property {{ width: number; height: number }} worldDimensions - Sprite dimensions in world meters.
+ * @property {{ east: number; north: number }} totalDisplacement - Combined anchor and offset displacement in meters.
+ * @property {SpriteLocation} displacedLngLat - Geographic coordinates after applying displacement.
+ */
+export type SurfaceCenterResult = {
+    center: {
+        x: number;
+        y: number;
+    } | null;
+    worldDimensions: {
+        width: number;
+        height: number;
+    };
+    totalDisplacement: {
+        east: number;
+        north: number;
+    };
+    displacedLngLat: SpriteLocation;
+};
+/**
+ * Calculates the projected center of a surface sprite and derives related world-space displacements.
+ * @param {SurfaceCenterParams} params - Inputs describing the sprite geometry and projection context.
+ * @returns {SurfaceCenterResult} Result containing projection output and displacement metadata.
+ */
+export declare const calculateSurfaceCenterPosition: (params: SurfaceCenterParams) => SurfaceCenterResult;
+/**
+ * Parameters describing how to compute each surface corner displacement.
+ * @typedef SurfaceCornerParams
+ * @property {number} worldWidthMeters - Width of the sprite footprint in meters.
+ * @property {number} worldHeightMeters - Height of the sprite footprint in meters.
+ * @property {SpriteAnchor} anchor - Anchor definition normalized between -1 and 1.
+ * @property {number} totalRotateDeg - Rotation applied to the surface in degrees.
+ * @property {{ east: number; north: number }} offsetMeters - Additional displacement applied uniformly to all corners.
+ */
+export type SurfaceCornerParams = {
+    worldWidthMeters: number;
+    worldHeightMeters: number;
+    anchor: SpriteAnchor;
+    totalRotateDeg: number;
+    offsetMeters: {
+        east: number;
+        north: number;
+    };
+};
+/**
+ * East/north displacement for an individual surface corner.
+ * @typedef SurfaceCorner
+ * @property {number} east - Eastward offset in meters relative to the base center.
+ * @property {number} north - Northward offset in meters relative to the base center.
+ */
+export type SurfaceCorner = {
+    east: number;
+    north: number;
+};
+/**
+ * Converts normalized surface corners into world-space displacements honoring anchor, rotation, and offsets.
+ * @param {SurfaceCornerParams} params - Inputs describing quad geometry and positioning.
+ * @returns {SurfaceCorner[]} Array of corner displacements in meters relative to the base center.
+ */
+export declare const calculateSurfaceCornerDisplacements: (params: SurfaceCornerParams) => SurfaceCorner[];

package/dist/numericInterpolation.d.ts

@@ -0,0 +1,80 @@
+/*!
+ * 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, SpriteNumericInterpolationOptions } from './types';
+/**
+ * Runtime state tracked for numeric interpolations.
+ * @property {number} durationMs - Total duration of the interpolation in milliseconds.
+ * @property {EasingFunction} easing - Easing function applied to progress samples.
+ * @property {number} from - Start value used for interpolation.
+ * @property {number} to - Adjusted target along the shortest rotation path.
+ * @property {number} finalValue - Caller-requested final value (used once interpolation completes).
+ * @property {number} startTimestamp - Timestamp when interpolation began, `-1` until evaluation starts.
+ */
+export interface NumericInterpolationState {
+    readonly durationMs: number;
+    readonly easing: EasingFunction;
+    readonly from: number;
+    readonly to: number;
+    readonly finalValue: number;
+    startTimestamp: number;
+}
+/**
+ * Parameters required to construct a {@link NumericInterpolationState}.
+ * @property {number} currentValue - Current numeric value rendered on screen.
+ * @property {number} targetValue - Desired value after interpolation completes.
+ * @property {SpriteNumericInterpolationOptions} options - Timing and easing configuration.
+ */
+export interface CreateNumericInterpolationStateParams {
+    currentValue: number;
+    targetValue: number;
+    options: SpriteNumericInterpolationOptions;
+}
+/**
+ * Result returned by {@link createNumericInterpolationState} containing state and a flag for activation.
+ * @property {NumericInterpolationState} state - Resolved state object.
+ * @property {boolean} requiresInterpolation - Indicates whether the caller should animate or snap.
+ */
+export interface CreateNumericInterpolationStateResult {
+    readonly state: NumericInterpolationState;
+    readonly requiresInterpolation: boolean;
+}
+/**
+ * Creates interpolation state describing how to move from the current value to the target value.
+ * @param {CreateNumericInterpolationStateParams} params - Inputs describing the current, target, and options.
+ * @returns {CreateNumericInterpolationStateResult} State data plus a flag indicating if animation is needed.
+ */
+export declare const createNumericInterpolationState: (params: CreateNumericInterpolationStateParams) => CreateNumericInterpolationStateResult;
+/**
+ * Parameters describing interpolation evaluation state.
+ * @property {NumericInterpolationState} state - State generated via {@link createNumericInterpolationState}.
+ * @property {number} timestamp - Timestamp in milliseconds used to sample the interpolation curve.
+ */
+export interface EvaluateNumericInterpolationParams {
+    state: NumericInterpolationState;
+    timestamp: number;
+}
+/**
+ * Result of evaluating a numeric interpolation at a specific timestamp.
+ * @property {number} value - Current interpolated value (or final value after completion).
+ * @property {boolean} completed - Indicates whether interpolation reached the end.
+ * @property {number} effectiveStartTimestamp - Start timestamp applied during evaluation.
+ */
+export interface EvaluateNumericInterpolationResult {
+    readonly value: number;
+    readonly completed: boolean;
+    readonly effectiveStartTimestamp: number;
+}
+/**
+ * Evaluates a numeric interpolation against the provided timestamp.
+ * @param {EvaluateNumericInterpolationParams} params - Inputs containing interpolation state and sample timestamp.
+ * @returns {EvaluateNumericInterpolationResult} Current value, completion flag, and effective start time.
+ */
+export declare const evaluateNumericInterpolation: (params: EvaluateNumericInterpolationParams) => EvaluateNumericInterpolationResult;