maplibre-gl-layers 0.14.0 → 0.15.0

package/dist/internalTypes.d.ts

@@ -1,15 +1,15 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.14.0
+ * version: 0.15.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: a531802b05777e1f54a8828a247254293df1415d
+ * git.commit.hash: d850b7e9c713f54f0630248dc4ea370721b6965b
  */
 
-import { SpriteMode, SpriteAnchor, SpriteImageOffset, SpriteInterpolationOptions, SpriteImageOriginLocation, SpriteLocation, SpriteTextGlyphHorizontalAlign, SpriteTextureMagFilter, SpriteTextureMinFilter, SpriteInterpolationMode, EasingFunction, SpriteScreenPoint, SpritePoint } from './types';
-import { ResolvedSpriteScalingOptions, SurfaceCorner } from './math';
+import { SpriteMode, SpriteAnchor, SpriteInterpolationOptions, SpriteImageOriginLocation, SpriteLocation, SpriteTextGlyphHorizontalAlign, SpriteTextureMagFilter, SpriteTextureMinFilter, SpriteInterpolationMode, EasingFunction, SpriteScreenPoint, SpritePoint, SpriteEasingPresetName } from './types';
+import { ResolvedSpriteScalingOptions, SurfaceCorner } from './utils/math';
 /**
  * The handle value that using the instance.
  */
@@ -167,13 +167,26 @@ export interface SpriteMercatorCoordinate {
     readonly y: number;
     readonly z: number;
 }
-export interface Releaseable {
+/**
+ * Mutable counterpart to {@link InterpolatedValues}, used internally so SpriteLayer
+ * can reuse object references while still exposing readonly snapshots publicly.
+ */
+export interface MutableInterpolatedValues<T> {
+    current: T;
+    from: T | undefined;
+    to: T | undefined;
+}
+export interface MutableSpriteImageInterpolatedOffset {
+    offsetMeters: MutableInterpolatedValues<number>;
+    offsetDeg: MutableInterpolatedValues<number>;
+}
+export interface Releasable {
     readonly release: () => void;
 }
 /**
  * Abstraction that exposes projection-related helpers.
  */
-export interface ProjectionHost extends Releaseable {
+export interface ProjectionHost extends Releasable {
     /**
      * Get current zoom level.
      * @returns Zoom level.
@@ -209,6 +222,7 @@ export interface ProjectionHost extends Releaseable {
      * @returns The ratio.
      */
     readonly calculatePerspectiveRatio: (location: Readonly<SpriteLocation>, cachedMercator?: SpriteMercatorCoordinate) => number;
+    readonly getCameraLocation: () => SpriteLocation | null;
 }
 export interface PrepareDrawSpriteImageParamsBase {
     readonly imageResources: ImageResourceTable;
@@ -247,7 +261,8 @@ export interface PreparedDrawSpriteImageParams<T> {
     readonly imageEntry: InternalSpriteImageState;
     readonly imageResource: RegisteredImage;
     readonly vertexData: Float32Array;
-    readonly opacity: number;
+    opacity: number;
+    readonly cameraDistanceMeters: number;
     readonly hitTestCorners: readonly [
         Readonly<SpriteScreenPoint>,
         Readonly<SpriteScreenPoint>,
@@ -273,13 +288,50 @@ export interface PreparedDrawSpriteImageParams<T> {
         readonly cos: number;
     } | null;
 }
+/**
+ * Common frame parameters shared with interpolation processing.
+ */
+export interface RenderInterpolationFrameContext {
+    readonly baseMetersPerPixel: number;
+    readonly spriteMinPixel: number;
+    readonly spriteMaxPixel: number;
+}
+/**
+ * Parameters consumed when processing sprite interpolations.
+ */
+export interface RenderInterpolationParams<TTag> {
+    readonly sprites: readonly InternalSpriteCurrentState<TTag>[];
+    readonly timestamp: number;
+    readonly frameContext?: RenderInterpolationFrameContext;
+}
+/**
+ * Result produced by sprite interpolation processing.
+ */
+export interface RenderInterpolationResult {
+    readonly handled: boolean;
+    readonly hasActiveInterpolation: boolean;
+}
+/**
+ * Parameters passed into RenderCalculationHost.processDrawSpriteImages.
+ */
+export interface ProcessDrawSpriteImagesParams<TTag> {
+    readonly interpolationParams?: RenderInterpolationParams<TTag>;
+    readonly prepareParams?: PrepareDrawSpriteImageParams<TTag>;
+}
+/**
+ * Result returned from RenderCalculationHost.processDrawSpriteImages.
+ */
+export interface ProcessDrawSpriteImagesResult<TTag> {
+    readonly preparedItems: PreparedDrawSpriteImageParams<TTag>[];
+    readonly interpolationResult: RenderInterpolationResult;
+}
 /**
  * The render calculation host.
  * Abstraction that render calculations.
  * @param TTag Tag type.
  */
-export interface RenderCalculationHost<TTag> extends Releaseable {
-    readonly prepareDrawSpriteImages: (params: PrepareDrawSpriteImageParams<TTag>) => PreparedDrawSpriteImageParams<TTag>[];
+export interface RenderCalculationHost<TTag> extends Releasable {
+    readonly processDrawSpriteImages: (params: ProcessDrawSpriteImagesParams<TTag>) => ProcessDrawSpriteImagesResult<TTag>;
 }
 /**
  * Corner model describing world displacements and resulting geographic coordinates for shader validation.
@@ -350,6 +402,7 @@ export interface SpriteInterpolationState {
     readonly mode: SpriteInterpolationMode;
     readonly durationMs: number;
     readonly easing: EasingFunction;
+    readonly easingPreset: SpriteEasingPresetName | null;
     startTimestamp: number;
     readonly from: SpriteLocation;
     readonly to: SpriteLocation;
@@ -366,6 +419,7 @@ export interface SpriteInterpolationState {
 export interface DegreeInterpolationState {
     readonly durationMs: number;
     readonly easing: EasingFunction;
+    readonly easingPreset: SpriteEasingPresetName | null;
     readonly from: number;
     readonly to: number;
     readonly finalValue: number;
@@ -374,11 +428,39 @@ export interface DegreeInterpolationState {
 export interface DistanceInterpolationState {
     readonly durationMs: number;
     readonly easing: EasingFunction;
+    readonly easingPreset: SpriteEasingPresetName | null;
     readonly from: number;
     readonly to: number;
     readonly finalValue: number;
     startTimestamp: number;
 }
+export interface DistanceInterpolationEvaluationParams {
+    readonly state: DistanceInterpolationState;
+    readonly timestamp: number;
+}
+export interface DistanceInterpolationEvaluationResult {
+    readonly value: number;
+    readonly completed: boolean;
+    readonly effectiveStartTimestamp: number;
+}
+export interface DegreeInterpolationEvaluationParams {
+    readonly state: DegreeInterpolationState;
+    readonly timestamp: number;
+}
+export interface DegreeInterpolationEvaluationResult {
+    readonly value: number;
+    readonly completed: boolean;
+    readonly effectiveStartTimestamp: number;
+}
+export interface SpriteInterpolationEvaluationParams {
+    readonly state: SpriteInterpolationState;
+    readonly timestamp: number;
+}
+export interface SpriteInterpolationEvaluationResult {
+    readonly location: SpriteLocation;
+    readonly completed: boolean;
+    readonly effectiveStartTimestamp: number;
+}
 /**
  * Alias for the interpolation state used internally by sprites.
  */
@@ -482,11 +564,12 @@ export interface InternalSpriteImageState {
     imageId: string;
     imageHandle: number;
     mode: SpriteMode;
-    opacity: number;
+    opacity: MutableInterpolatedValues<number>;
     scale: number;
     anchor: Readonly<SpriteAnchor>;
-    offset: SpriteImageOffset;
-    rotateDeg: number;
+    offset: MutableSpriteImageInterpolatedOffset;
+    rotateDeg: MutableInterpolatedValues<number>;
+    rotationCommandDeg: number;
     displayedRotateDeg: number;
     autoRotation: boolean;
     autoRotationMinDistanceMeters: number;
@@ -498,9 +581,15 @@ export interface InternalSpriteImageState {
     rotationInterpolationOptions: Readonly<SpriteInterpolationOptions> | null;
     offsetDegInterpolationState: Readonly<DegreeInterpolationState> | null;
     offsetMetersInterpolationState: Readonly<DistanceInterpolationState> | null;
+    opacityInterpolationState: Readonly<DistanceInterpolationState> | null;
+    opacityInterpolationOptions: Readonly<SpriteInterpolationOptions> | null;
+    opacityTargetValue: number;
+    lodLastCommandOpacity: number;
     lastCommandRotateDeg: number;
     lastCommandOffsetDeg: number;
     lastCommandOffsetMeters: number;
+    lastCommandOpacity: number;
+    interpolationDirty: boolean;
     surfaceShaderInputs?: Readonly<SurfaceShaderInputs>;
     hitTestCorners?: [
         MutableSpriteScreenPoint,
@@ -516,9 +605,8 @@ export interface InternalSpriteCurrentState<TTag> {
     spriteId: string;
     handle: IdHandle;
     isEnabled: boolean;
-    currentLocation: Readonly<SpriteLocation>;
-    fromLocation?: Readonly<SpriteLocation>;
-    toLocation?: Readonly<SpriteLocation>;
+    visibilityDistanceMeters?: number;
+    location: MutableInterpolatedValues<Readonly<SpriteLocation>>;
     images: Map<number, Map<number, InternalSpriteImageState>>;
     tag: TTag | null;
     interpolationState: InternalSpriteInterpolationState | null;
@@ -526,6 +614,7 @@ export interface InternalSpriteCurrentState<TTag> {
     lastCommandLocation: Readonly<SpriteLocation>;
     lastAutoRotationLocation: Readonly<SpriteLocation>;
     lastAutoRotationAngleDeg: number;
+    interpolationDirty: boolean;
     cachedMercator: Readonly<SpriteMercatorCoordinate>;
     cachedMercatorLng: number;
     cachedMercatorLat: number;

package/dist/{degreeInterpolation.d.ts → interpolation/degreeInterpolation.d.ts}

@@ -1,15 +1,15 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.14.0
+ * version: 0.15.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: a531802b05777e1f54a8828a247254293df1415d
+ * git.commit.hash: d850b7e9c713f54f0630248dc4ea370721b6965b
  */
 
-import { SpriteInterpolationOptions } from './types';
-import { DegreeInterpolationState } from './internalTypes';
+import { SpriteInterpolationOptions } from '../types';
+import { DegreeInterpolationState, DegreeInterpolationEvaluationResult, InternalSpriteImageState } from '../internalTypes';
 /**
  * Parameters required to construct a {@link DegreeInterpolationState}.
  * @property {number} currentValue - Current numeric value rendered on screen.
@@ -64,3 +64,18 @@ export interface EvaluateDegreeInterpolationResult {
  * @returns {EvaluateDegreeInterpolationResult} Current value, completion flag, and effective start time.
  */
 export declare const evaluateDegreeInterpolation: (params: EvaluateDegreeInterpolationParams) => EvaluateDegreeInterpolationResult;
+type DegreeInterpolationStateKey = 'rotationInterpolationState' | 'offsetDegInterpolationState';
+interface DegreeInterpolationChannelDescriptor {
+    readonly stateKey: DegreeInterpolationStateKey;
+    readonly normalize?: (value: number) => number;
+    readonly applyValue: (image: InternalSpriteImageState, value: number) => void;
+    readonly applyFinalValue?: (image: InternalSpriteImageState, value: number) => void;
+}
+export interface DegreeInterpolationWorkItem {
+    readonly descriptor: DegreeInterpolationChannelDescriptor;
+    readonly image: InternalSpriteImageState;
+    readonly state: DegreeInterpolationState;
+}
+export declare const collectDegreeInterpolationWorkItems: (image: InternalSpriteImageState, workItems: DegreeInterpolationWorkItem[]) => void;
+export declare const applyDegreeInterpolationEvaluations: (workItems: readonly DegreeInterpolationWorkItem[], evaluations: readonly DegreeInterpolationEvaluationResult[], timestamp: number) => boolean;
+export {};

package/dist/interpolation/distanceInterpolation.d.ts

@@ -0,0 +1,46 @@
+/*!
+ * name: maplibre-gl-layers
+ * version: 0.15.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: d850b7e9c713f54f0630248dc4ea370721b6965b
+ */
+
+import { SpriteInterpolationOptions } from '../types';
+import { DistanceInterpolationEvaluationParams, DistanceInterpolationEvaluationResult, DistanceInterpolationState, InternalSpriteImageState } from '../internalTypes';
+export interface CreateDistanceInterpolationStateParams {
+    currentValue: number;
+    targetValue: number;
+    previousCommandValue?: number;
+    options: SpriteInterpolationOptions;
+}
+export interface CreateDistanceInterpolationStateResult {
+    readonly state: DistanceInterpolationState;
+    readonly requiresInterpolation: boolean;
+}
+export declare const createDistanceInterpolationState: (params: CreateDistanceInterpolationStateParams) => CreateDistanceInterpolationStateResult;
+export declare const evaluateDistanceInterpolation: (params: DistanceInterpolationEvaluationParams) => DistanceInterpolationEvaluationResult;
+type DistanceInterpolationStateKey = 'offsetMetersInterpolationState' | 'opacityInterpolationState';
+interface DistanceInterpolationChannelDescriptor {
+    readonly stateKey: DistanceInterpolationStateKey;
+    readonly normalize?: (value: number) => number;
+    readonly applyValue: (image: InternalSpriteImageState, value: number) => void;
+    readonly applyFinalValue?: (image: InternalSpriteImageState, value: number) => void;
+}
+declare const DISTANCE_INTERPOLATION_CHANNELS: Record<'offsetMeters' | 'opacity', DistanceInterpolationChannelDescriptor>;
+export type DistanceInterpolationChannelDescriptorMap = typeof DISTANCE_INTERPOLATION_CHANNELS;
+export type DistanceInterpolationChannelName = keyof DistanceInterpolationChannelDescriptorMap;
+export interface DistanceInterpolationWorkItem {
+    readonly descriptor: DistanceInterpolationChannelDescriptorMap[DistanceInterpolationChannelName];
+    readonly image: InternalSpriteImageState;
+    readonly state: DistanceInterpolationState;
+}
+export interface CollectDistanceInterpolationWorkItemOptions {
+    readonly includeOffsetMeters?: boolean;
+    readonly includeOpacity?: boolean;
+}
+export declare const collectDistanceInterpolationWorkItems: (image: InternalSpriteImageState, workItems: DistanceInterpolationWorkItem[], options?: CollectDistanceInterpolationWorkItemOptions) => void;
+export declare const applyDistanceInterpolationEvaluations: (workItems: readonly DistanceInterpolationWorkItem[], evaluations: readonly DistanceInterpolationEvaluationResult[], timestamp: number) => boolean;
+export {};

package/dist/{easing.d.ts → interpolation/easing.d.ts}

@@ -1,19 +1,24 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.14.0
+ * version: 0.15.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: a531802b05777e1f54a8828a247254293df1415d
+ * git.commit.hash: d850b7e9c713f54f0630248dc4ea370721b6965b
  */
 
-import { EasingFunction } from './types';
+import { EasingFunction, SpriteEasingPresetName, SpriteInterpolationEasing } from '../types';
 /**
  * Linear interpolation that clamps the value to the [0, 1] range.
  */
 export declare const linearEasing: EasingFunction;
+export interface ResolvedEasing {
+    readonly easing: EasingFunction;
+    readonly preset: SpriteEasingPresetName | null;
+}
 /**
  * Returns the provided easing function or falls back to linear interpolation.
+ * When a preset name is supplied the resolved preset identifier is preserved for downstream consumers.
  */
-export declare const resolveEasing: (easing?: EasingFunction) => EasingFunction;
+export declare const resolveEasing: (easing?: SpriteInterpolationEasing) => ResolvedEasing;

package/dist/{interpolation.d.ts → interpolation/interpolation.d.ts}

@@ -1,15 +1,15 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.14.0
+ * version: 0.15.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: a531802b05777e1f54a8828a247254293df1415d
+ * git.commit.hash: d850b7e9c713f54f0630248dc4ea370721b6965b
  */
 
-import { SpriteInterpolationOptions, SpriteLocation } from './types';
-import { SpriteInterpolationState } from './internalTypes';
+import { SpriteInterpolationOptions, SpriteLocation } from '../types';
+import { SpriteInterpolationState, SpriteInterpolationEvaluationParams, SpriteInterpolationEvaluationResult } from '../internalTypes';
 /**
  * Parameters required to create a fresh interpolation state for the next animation segment.
  *
@@ -41,32 +41,10 @@ export interface CreateInterpolationStateResult {
  * @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;
+export declare const evaluateInterpolation: (params: SpriteInterpolationEvaluationParams) => SpriteInterpolationEvaluationResult;

package/dist/{interpolationChannels.d.ts → interpolation/interpolationChannels.d.ts}

@@ -1,15 +1,15 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.14.0
+ * version: 0.15.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: a531802b05777e1f54a8828a247254293df1415d
+ * git.commit.hash: d850b7e9c713f54f0630248dc4ea370721b6965b
  */
 
-import { SpriteInterpolationOptions, SpriteImageOffset } from './types';
-import { InternalSpriteImageState } from './internalTypes';
+import { SpriteInterpolationOptions, SpriteImageOffset } from '../types';
+import { InternalSpriteImageState } from '../internalTypes';
 /**
  * Ensures the rotation channel reflects the latest targets, optionally overriding interpolation.
  */
@@ -22,11 +22,21 @@ export declare const clearOffsetDegInterpolation: (image: InternalSpriteImageSta
  * Clears any running offset distance interpolation in meters.
  */
 export declare const clearOffsetMetersInterpolation: (image: InternalSpriteImageState) => void;
+/**
+ * Clears any running opacity interpolation.
+ */
+export declare const clearOpacityInterpolation: (image: InternalSpriteImageState) => void;
+export declare const applyOpacityUpdate: (image: InternalSpriteImageState, nextOpacity: number, interpolationOptions?: SpriteInterpolationOptions | null) => void;
+export type ImageInterpolationStepperId = 'rotation' | 'offsetDeg' | 'offsetMeters' | 'opacity';
 /**
  * Executes all interpolation steppers for an image and reports whether any remain active.
  */
-export declare const stepSpriteImageInterpolations: (image: InternalSpriteImageState, timestamp: number) => boolean;
-interface ApplyOffsetUpdateOptions {
+export interface StepSpriteImageInterpolationOptions {
+    readonly skipChannels?: Partial<Record<ImageInterpolationStepperId, boolean>>;
+}
+export declare const stepSpriteImageInterpolations: (image: InternalSpriteImageState, timestamp: number, options?: StepSpriteImageInterpolationOptions) => boolean;
+export declare const hasActiveImageInterpolations: (image: InternalSpriteImageState) => boolean;
+export interface ApplyOffsetUpdateOptions {
     readonly deg?: SpriteInterpolationOptions | null;
     readonly meters?: SpriteInterpolationOptions | null;
 }
@@ -34,4 +44,3 @@ interface ApplyOffsetUpdateOptions {
  * Applies offset updates across both angular and radial channels.
  */
 export declare const applyOffsetUpdate: (image: InternalSpriteImageState, nextOffset: SpriteImageOffset, options?: ApplyOffsetUpdateOptions) => void;
-export {};

package/dist/{rotationInterpolation.d.ts → interpolation/rotationInterpolation.d.ts}

@@ -1,21 +1,16 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.14.0
+ * version: 0.15.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: a531802b05777e1f54a8828a247254293df1415d
+ * git.commit.hash: d850b7e9c713f54f0630248dc4ea370721b6965b
  */
 
-import { SpriteInterpolationOptions } from './types';
-import { DegreeInterpolationState } from './internalTypes';
-/**
- * Normalizes an absolute angle in degrees to the range [0, 360).
- * @param {number} angle - Angle provided by the caller which may fall outside a single revolution.
- * @returns {number} Angle wrapped to [0, 360) with negative zero converted to zero.
- */
-export declare const normalizeAngleDeg: (angle: number) => number;
+import { SpriteInterpolationOptions } from '../types';
+import { DegreeInterpolationState } from '../internalTypes';
+export { normalizeAngleDeg } from '../utils/math';
 /**
  * Parameters describing the rotation update request.
  * @property {number} currentAngleDeg - Current angle already applied to the sprite in degrees.

package/dist/types.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.14.0
+ * version: 0.15.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: a531802b05777e1f54a8828a247254293df1415d
+ * git.commit.hash: d850b7e9c713f54f0630248dc4ea370721b6965b
  */
 
 import { CustomLayerInterface } from 'maplibre-gl';
@@ -75,14 +75,16 @@ export interface SpriteImageOriginLocation {
 export type SpriteInterpolationMode = 'feedback' | 'feedforward';
 /** Easing function signature used to map interpolation progress. */
 export type EasingFunction = (progress: number) => number;
+export type SpriteEasingPresetName = 'linear';
+export type SpriteInterpolationEasing = EasingFunction | SpriteEasingPresetName;
 /** Options for interpolating values. */
 export interface SpriteInterpolationOptions {
     /** Interpolation mode; defaults to feedback. */
     mode?: SpriteInterpolationMode;
     /** Duration in milliseconds. */
     durationMs: number;
-    /** Easing function mapping interpolation progress. Defaults to linear. */
-    easing?: EasingFunction;
+    /** Easing mapping applied to progress values. Accepts preset names or custom functions. Defaults to linear. */
+    easing?: SpriteInterpolationEasing;
 }
 /** Interpolation configuration for rotateDeg and offsetDeg. */
 export interface SpriteImageInterpolationOptions {
@@ -92,6 +94,8 @@ export interface SpriteImageInterpolationOptions {
     offsetDeg?: SpriteInterpolationOptions | null;
     /** Interpolation settings for offset.offsetMeters; null disables interpolation. */
     offsetMeters?: SpriteInterpolationOptions | null;
+    /** Interpolation settings for opacity; null disables interpolation. */
+    opacity?: SpriteInterpolationOptions | null;
 }
 /**
  * Initial attributes that define a sprite image.
@@ -180,6 +184,11 @@ export interface SpriteInit<TTag> {
     isEnabled?: boolean;
     /** Initial location. */
     location: SpriteLocation;
+    /**
+     * Pseudo LOD threshold for the sprite. When the camera distance exceeds this value,
+     * all images attached to the sprite become invisible.
+     */
+    visibilityDistanceMeters?: number;
     /** Array of zero or more images. */
     images: SpriteImageDefinitionInitEntry[];
     /** Optional tag value; null or omission means no tag. */
@@ -200,6 +209,27 @@ export interface SpriteInitEntry<TTag> extends SpriteInit<TTag> {
  * @template TTag Tag type.
  */
 export type SpriteInitCollection<TTag> = Record<string, SpriteInit<TTag>> | readonly SpriteInitEntry<TTag>[];
+/**
+ * Interpolated values.
+ * @param T - Value type.
+ */
+export interface InterpolatedValues<T> {
+    /** Current time value. */
+    readonly current: T;
+    /** Requested value. */
+    readonly from: T | undefined;
+    /** Will be reached value. */
+    readonly to: T | undefined;
+}
+/**
+ * Offset with interpolation metadata for both distance and heading.
+ */
+export interface SpriteImageInterpolatedOffset {
+    /** Distance from the anchor in meters. */
+    readonly offsetMeters: InterpolatedValues<number>;
+    /** Heading describing the offset direction in degrees. */
+    readonly offsetDeg: InterpolatedValues<number>;
+}
 /**
  * Sprite image state evaluated at runtime.
  *
@@ -207,11 +237,11 @@ export type SpriteInitCollection<TTag> = Record<string, SpriteInit<TTag>> | read
  * @property {number} order - Ordering slot within the sub-layer.
  * @property {string} imageId - Identifier of the registered image or glyph.
  * @property {SpriteMode} mode - Rendering mode applied to the image.
- * @property {number} opacity - Opacity multiplier applied when rendering.
+ * @property {InterpolatedValues<number>} opacity - Opacity multiplier applied when rendering, with interpolation metadata.
  * @property {number} scale - Scale factor converting pixels to meters.
  * @property {Readonly<SpriteAnchor>} anchor - Anchor coordinates resolved for the image.
- * @property {Readonly<SpriteImageOffset>} offset - Offset applied relative to the anchor point.
- * @property {number} rotateDeg - Additional rotation in degrees.
+ * @property {Readonly<SpriteImageInterpolatedOffset>} offset - Offset applied relative to the anchor point, with interpolation metadata.
+ * @property {InterpolatedValues<number>} rotateDeg - Additional rotation in degrees plus interpolation metadata.
  * @property {boolean} autoRotation - Indicates whether auto-rotation is active.
  * @property {number} autoRotationMinDistanceMeters - Minimum travel distance before auto-rotation updates.
  * @property {number} resolvedBaseRotateDeg - Internal base rotation resolved for the current frame.
@@ -227,16 +257,19 @@ export interface SpriteImageState {
     readonly imageId: string;
     /** Rendering mode applied to the image. */
     readonly mode: SpriteMode;
-    /** Opacity multiplier applied when rendering. */
-    readonly opacity: number;
     /** Scale factor converting pixels to meters. */
     readonly scale: number;
     /** Anchor coordinates resolved for the image. */
     readonly anchor: Readonly<SpriteAnchor>;
+    /** Opacity multiplier applied when rendering. */
+    readonly opacity: InterpolatedValues<number>;
     /** Offset applied relative to the anchor point. */
-    readonly offset: Readonly<SpriteImageOffset>;
-    /** Additional rotation in degrees. */
-    readonly rotateDeg: number;
+    readonly offset: Readonly<SpriteImageInterpolatedOffset>;
+    /**
+     * Additional rotation in degrees with interpolation metadata.
+     * `from`/`to` are `undefined` when no rotation animation is running.
+     */
+    readonly rotateDeg: InterpolatedValues<number>;
     /** Indicates whether auto-rotation is active. */
     readonly autoRotation: boolean;
     /** Minimum travel distance before auto-rotation updates. */
@@ -258,20 +291,16 @@ export interface SpriteCurrentState<TTag> {
     readonly spriteId: string;
     /** Indicates whether the sprite is enabled. */
     readonly isEnabled: boolean;
-    /** Current (possibly interpolated) location. */
-    readonly currentLocation: Readonly<SpriteLocation>;
     /**
-     * Source location during interpolation; undefined when not interpolating.
-     * Feedback mode: previous commanded location.
-     * Feed-forward mode: current commanded location.
+     * Pseudo LOD threshold for the sprite. When the camera distance exceeds this value,
+     * the sprite's images become invisible.
      */
-    readonly fromLocation?: Readonly<SpriteLocation>;
+    readonly visibilityDistanceMeters: number | undefined;
     /**
-     * Destination location during interpolation; undefined when not interpolating.
-     * Feedback mode: current commanded location.
-     * Feed-forward mode: predicted location.
+     * Location information including current, source, and destination coordinates.
+     * `from`/`to` are `undefined` when interpolation is inactive.
      */
-    readonly toLocation?: Readonly<SpriteLocation>;
+    readonly location: InterpolatedValues<Readonly<SpriteLocation>>;
     /** Current image states, grouped by sub-layer and order. */
     readonly images: ReadonlyMap<number, ReadonlyMap<number, SpriteImageState>>;
     /** Optional tag value; null indicates no tag. */
@@ -295,6 +324,11 @@ export interface SpriteUpdateEntryBase<TTag> {
     interpolation?: SpriteInterpolationOptions | null;
     /** Optional tag value to replace the current one; `null` clears the tag. */
     tag?: TTag | null;
+    /**
+     * Pseudo LOD threshold for the sprite. Specify a positive finite value to enable the check,
+     * `null` to clear the current threshold, or leave `undefined` to keep the existing value.
+     */
+    visibilityDistanceMeters?: number | null;
 }
 /**
  * Update entry describing a sprite image modification.

package/dist/{image.d.ts → utils/image.d.ts}

@@ -1,14 +1,14 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.14.0
+ * version: 0.15.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: a531802b05777e1f54a8828a247254293df1415d
+ * git.commit.hash: d850b7e9c713f54f0630248dc4ea370721b6965b
  */
 
-import { SpriteImageRegisterOptions } from './types';
+import { SpriteImageRegisterOptions } from '../types';
 export type SvgSizeResolutionErrorCode = 'size-missing' | 'viewbox-disabled' | 'invalid-dimensions';
 export declare class SvgSizeResolutionError extends Error implements Error {
     readonly code: SvgSizeResolutionErrorCode;