maplibre-gl-layers 0.17.0 → 0.19.0

package/dist/utils/math.d.ts

@@ -1,15 +1,19 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.17.0
+ * version: 0.19.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: 9fe9aa30db6602d13643e32c94af39ae2b26b082
+ * git.commit.hash: 7bc93c11d7855dedb8d60f140af4e413252c32a7
  */
 
-import { SpriteAnchor, SpriteImageOffset, SpriteLocation, SpritePoint, SpriteScalingOptions, SpriteScreenPoint } from '../types';
+import { SpriteAnchor, SpriteLocation, SpritePoint, SpriteScalingOptions, SpriteScreenPoint } from '../types';
 import { InternalSpriteCurrentState, MatrixInput, ProjectionHost, SpriteMercatorCoordinate } from '../internalTypes';
+export type OffsetInput = {
+    offsetMeters?: number;
+    offsetDeg?: number;
+} | undefined;
 /**
  * Produces a deep copy so later updates do not mutate the original object.
  */
@@ -44,18 +48,10 @@ export declare const multiplyMatrixAndVector: (matrix: MatrixInput, x: number, y
 export interface ResolvedSpriteScalingOptions {
     /** Effective number of meters represented by each rendered pixel. */
     metersPerPixel: number;
-    /** Lowest zoom level at which scaling interpolation begins. */
-    zoomMin: number;
-    /** Highest zoom level at which scaling interpolation ends. */
-    zoomMax: number;
-    /** Scale multiplier applied at {@link ResolvedSpriteScalingOptions.zoomMin}. */
-    scaleMin: number;
-    /** Scale multiplier applied at {@link ResolvedSpriteScalingOptions.zoomMax}. */
-    scaleMax: number;
-    /** Lower clamp for sprite size in pixels. */
-    spriteMinPixel: number;
-    /** Upper clamp for sprite size in pixels. */
-    spriteMaxPixel: number;
+    /** Distance at or below which sprites stop growing further. */
+    minScaleDistanceMeters: number;
+    /** Distance at or above which sprites stop shrinking further. */
+    maxScaleDistanceMeters: number;
 }
 /**
  * Fills missing {@link SpriteScalingOptions} values with defaults so downstream math can assume a complete object.
@@ -64,12 +60,12 @@ export interface ResolvedSpriteScalingOptions {
  */
 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.
+ * Computes a scale factor based on camera-to-sprite distance.
+ * @param {number} distanceMeters - Calculated distance from camera to sprite.
  * @param {ResolvedSpriteScalingOptions} scaling - Resolved scaling options.
- * @returns {number} Scale value interpolated between {@link ResolvedSpriteScalingOptions.scaleMin} and {@link ResolvedSpriteScalingOptions.scaleMax}.
+ * @returns {number} Scale multiplier that clamps near/far distances to maintain consistent sizing.
  */
-export declare const calculateZoomScaleFactor: (zoom: number, scaling: ResolvedSpriteScalingOptions) => number;
+export declare const calculateDistanceScaleFactor: (distanceMeters: number, scaling: ResolvedSpriteScalingOptions) => number;
 /**
  * Calculates meters per pixel at the given latitude.
  * Uses Web Mercator scale and applies the latitude-based cosine correction.
@@ -95,32 +91,30 @@ export declare const calculateDistanceAndBearingMeters: (from: SpriteLocation, t
     bearingDeg: number;
 };
 /**
- * Calculates billboard image dimensions in pixels and clamps them to display limits.
+ * Calculates billboard image dimensions in pixels.
  * @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} distanceScaleFactor - Distance-dependent scale multiplier.
  * @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; scaleAdjustment: number }} Pixel dimensions alongside the scale factor applied during clamping.
+ * @returns {{ width: number; height: number; scaleAdjustment: number }} Pixel dimensions alongside the scale factor (always 1 without clamping).
  */
-export declare const calculateBillboardPixelDimensions: (imageWidth: number | undefined, imageHeight: number | undefined, baseMetersPerPixel: number, imageScale: number, zoomScaleFactor: number, effectivePixelsPerMeter: number, spriteMinPixel: number, spriteMaxPixel: number) => {
+export declare const calculateBillboardPixelDimensions: (imageWidth: number | undefined, imageHeight: number | undefined, baseMetersPerPixel: number, imageScale: number, distanceScaleFactor: number, effectivePixelsPerMeter: number) => {
     width: number;
     height: number;
     scaleAdjustment: number;
 };
 /**
  * Computes the billboard offset in screen-space pixels.
- * @param {SpriteImageOffset | undefined} offset - Offset configuration describing length (meters) and heading (degrees).
+ * @param {OffsetInput} 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} distanceScaleFactor - Distance-dependent scale multiplier.
  * @param {number} effectivePixelsPerMeter - Conversion factor from meters to pixels.
  * @param {number} [sizeScaleAdjustment=1] - Additional scale factor applied when sprite size is clamped.
  * @returns {SpriteScreenPoint} Screen-space offset relative to the billboard center.
  */
-export declare const calculateBillboardOffsetPixels: (offset: SpriteImageOffset | undefined, imageScale: number, zoomScaleFactor: number, effectivePixelsPerMeter: number, sizeScaleAdjustment?: number) => SpriteScreenPoint;
+export declare const calculateBillboardOffsetPixels: (offset: OffsetInput, imageScale: number, distanceScaleFactor: number, effectivePixelsPerMeter: number, sizeScaleAdjustment?: number) => SpriteScreenPoint;
 /**
  * Computes the screen-space shift caused by anchor rotation for billboards.
  * @param {number} halfWidth - Half of the sprite width in pixels.
@@ -136,14 +130,10 @@ export declare const calculateBillboardAnchorShiftPixels: (halfWidth: number, ha
  * @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; scaleAdjustment: number }} World dimensions in meters and the applied clamp scale factor.
+ * @param {number} distanceScaleFactor - Distance-dependent scale multiplier.
+ * @returns {{ width: number; height: number; scaleAdjustment: number }} World dimensions in meters and the applied clamp scale factor (always 1 without clamping).
  */
-export declare const calculateSurfaceWorldDimensions: (imageWidth: number | undefined, imageHeight: number | undefined, baseMetersPerPixel: number, imageScale: number, zoomScaleFactor: number, options?: {
-    effectivePixelsPerMeter?: number;
-    spriteMinPixel?: number;
-    spriteMaxPixel?: number;
-}) => {
+export declare const calculateSurfaceWorldDimensions: (imageWidth: number | undefined, imageHeight: number | undefined, baseMetersPerPixel: number, imageScale: number, distanceScaleFactor: number) => {
     width: number;
     height: number;
     scaleAdjustment: number;
@@ -159,13 +149,13 @@ export declare const calculateSurfaceWorldDimensions: (imageWidth: number | unde
 export declare const calculateSurfaceAnchorShiftMeters: (halfWidthMeters: number, halfHeightMeters: number, anchor: SpriteAnchor | undefined, totalRotateDeg: number) => SurfaceCorner;
 /**
  * Calculates surface image offsets in meters.
- * @param {SpriteImageOffset | undefined} offset - Offset configuration for the surface sprite.
+ * @param {OffsetInput} offset - Offset configuration for the surface sprite.
  * @param {number} imageScale - User-provided scale multiplier applied to the offset distance.
- * @param {number} zoomScaleFactor - Zoom-dependent scale multiplier.
+ * @param {number} distanceScaleFactor - Distance-dependent scale multiplier.
  * @param {number} [sizeScaleAdjustment=1] - Additional scale factor applied when sprite size is clamped.
  * @returns {SurfaceCorner} Offset vector in meters.
  */
-export declare const calculateSurfaceOffsetMeters: (offset: SpriteImageOffset | undefined, imageScale: number, zoomScaleFactor: number, sizeScaleAdjustment?: number) => SurfaceCorner;
+export declare const calculateSurfaceOffsetMeters: (offset: OffsetInput, imageScale: number, distanceScaleFactor: number, sizeScaleAdjustment?: number) => SurfaceCorner;
 /**
  * Adds east/north distances (meters) to a longitude/latitude pair.
  * @param {number} location - Base location in degrees.
@@ -269,20 +259,16 @@ export interface BillboardCenterParams {
     baseMetersPerPixel: number;
     /** User-provided scaling multiplier. */
     imageScale: number;
-    /** Zoom-dependent scale multiplier. */
-    zoomScaleFactor: number;
+    /** Distance-dependent scale multiplier. */
+    distanceScaleFactor: number;
     /** Pixels per meter after perspective adjustments. */
     effectivePixelsPerMeter: number;
-    /** Lower clamp for the sprite's largest pixel dimension. */
-    spriteMinPixel: number;
-    /** Upper clamp for the sprite's largest pixel dimension. */
-    spriteMaxPixel: number;
     /** Aggregate rotation applied to the sprite in degrees. */
     totalRotateDeg: number;
     /** Anchor definition normalized between -1 and 1. */
     anchor?: Readonly<SpriteAnchor>;
     /** Offset definition applied in meters/deg. */
-    offset?: Readonly<SpriteImageOffset>;
+    offset?: OffsetInput;
 }
 /**
  * Resolved properties describing the billboard center and derived dimensions.
@@ -290,13 +276,13 @@ export interface BillboardCenterParams {
 export interface BillboardCenterResult {
     /** Screen-space coordinate after offset adjustments. */
     center: SpriteScreenPoint;
-    /** Half of the clamped pixel width. */
+    /** Half of the pixel width. */
     halfWidth: number;
-    /** Half of the clamped pixel height. */
+    /** Half of the pixel height. */
     halfHeight: number;
-    /** Full pixel width after scaling and clamping. */
+    /** Full pixel width after scaling. */
     pixelWidth: number;
-    /** Full pixel height after scaling and clamping. */
+    /** Full pixel height after scaling. */
     pixelHeight: number;
     /** Pixel delta caused by anchor rotation. */
     anchorShift: SpritePoint;
@@ -365,20 +351,14 @@ export interface SurfaceCenterParams {
     baseMetersPerPixel: number;
     /** User-provided scaling multiplier. */
     imageScale: number;
-    /** Zoom-dependent scale multiplier. */
-    zoomScaleFactor: number;
+    /** Distance-dependent scale multiplier. */
+    distanceScaleFactor: number;
     /** Rotation applied to the sprite in degrees. */
     totalRotateDeg: number;
     /** Anchor definition normalized between -1 and 1. */
     anchor?: Readonly<SpriteAnchor>;
     /** Offset definition applied in meters/deg. */
-    offset?: Readonly<SpriteImageOffset>;
-    /** Conversion rate from meters to on-screen pixels. */
-    effectivePixelsPerMeter?: number;
-    /** Lower clamp for the sprite's largest pixel dimension. */
-    spriteMinPixel?: number;
-    /** Upper clamp for the sprite's largest pixel dimension. */
-    spriteMaxPixel?: number;
+    offset?: OffsetInput;
     /** Projection function mapping longitude/latitude to screen space. */
     project?: ProjectLngLatFn;
     /** Projection into clip space when available. */

package/dist/utils/utils.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.17.0
+ * version: 0.19.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: 9fe9aa30db6602d13643e32c94af39ae2b26b082
+ * git.commit.hash: 7bc93c11d7855dedb8d60f140af4e413252c32a7
  */
 
 import { ImageHandleBufferController, IdHandler, RenderTargetBucketBuffers, RenderTargetEntryLike, SpriteOriginReference } from '../internalTypes';

package/dist/wasm/config.json.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.17.0
+ * version: 0.19.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: 9fe9aa30db6602d13643e32c94af39ae2b26b082
+ * git.commit.hash: 7bc93c11d7855dedb8d60f140af4e413252c32a7
  */
 
 declare const _default: {

package/package.json

@@ -1,20 +1,20 @@
 {
   "git": {
     "tags": [
-      "0.17.0"
+      "0.19.0"
     ],
     "branches": [
       "main"
     ],
-    "version": "0.17.0",
+    "version": "0.19.0",
     "commit": {
-      "hash": "9fe9aa30db6602d13643e32c94af39ae2b26b082",
-      "shortHash": "9fe9aa3",
-      "date": "2025-11-20T13:44:53+09:00Z",
+      "hash": "7bc93c11d7855dedb8d60f140af4e413252c32a7",
+      "shortHash": "7bc93c1",
+      "date": "2025-11-23T22:35:51+09:00Z",
       "message": "Merge branch 'develop'"
     }
   },
-  "version": "0.17.0",
+  "version": "0.19.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",

package/dist/interpolation/interpolation.d.ts

@@ -1,48 +0,0 @@
-/*!
- * name: maplibre-gl-layers
- * version: 0.17.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: 9fe9aa30db6602d13643e32c94af39ae2b26b082
- */
-
-import { SpriteInterpolationOptions, SpriteLocation } from '../types';
-import { SpriteInterpolationEvaluationParams, SpriteInterpolationEvaluationResult, SpriteInterpolationState } from '../internalTypes';
-/**
- * Parameters required to create a fresh interpolation state for the next animation segment.
- */
-export interface CreateInterpolationStateParams {
-    /** Sprite location currently rendered on screen. */
-    currentLocation: SpriteLocation;
-    /** Previously commanded target, used for feedforward extrapolation. */
-    lastCommandLocation?: SpriteLocation;
-    /** Upcoming commanded target that the sprite should reach. */
-    nextCommandLocation: SpriteLocation;
-    /** Raw interpolation options supplied by the caller. */
-    options: SpriteInterpolationOptions;
-}
-/**
- * Result of preparing interpolation state, including a flag denoting whether any lerp is needed.
- */
-export interface CreateInterpolationStateResult {
-    /** Prepared interpolation state ready for evaluation. */
-    readonly state: SpriteInterpolationState<SpriteLocation>;
-    /** Indicates whether lerping is needed or an immediate snap is sufficient. */
-    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;
-/**
- * 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: SpriteInterpolationEvaluationParams) => SpriteInterpolationEvaluationResult;