@maptiler/sdk 3.10.0 → 3.10.1

package/dist/src/custom-layers/CubemapLayer/types.d.ts

@@ -0,0 +1,67 @@
+export declare enum CubemapImagesPresets {
+    UNIVERSE_DARK = "universe-dark"
+}
+/**
+ * Constructor options for the CubemapLayer.
+ * This type is equivalent to {@link CubemapDefinition} with no additional properties.
+ */
+export type CubemapLayerConstructorOptions = CubemapDefinition & {};
+export declare const cubemapPresets: Record<string, CubemapDefinition>;
+/**
+ * Defines how a cubemap should be constructed from source materials.
+ * This is a discriminated union type with four possible formats:
+ *
+ * 1. Path-based: Specify a base URL and optional format for cube face images
+ * 2. Faces-based: Provide explicit URLs for each cube face
+ * 3. Preset-based: Use a predefined cubemap from available presets
+ * 4. Color-based: Use a single color for all faces
+ *
+ * Only one of `path`, `faces`, `preset`, or `color` should be provided.
+ *
+ * @example
+ * // Path-based cubemap
+ * const pathCubemap: CubemapDefinition = {
+ *   path: {
+ *     baseUrl: 'https://example.com/cubemap',
+ *     format: 'png'
+ *   }
+ * };
+ *
+ * // Color-based cubemap
+ * const colorCubemap: CubemapDefinition = {
+ *   color: '#ff0000'
+ * };
+ */
+export type CubemapDefinition = {
+    path: {
+        baseUrl: string;
+        format?: "png" | "jpg" | "webp";
+    };
+    faces?: never;
+    preset?: never;
+    color?: string;
+} | {
+    faces: CubemapFaces;
+    path?: never;
+    preset?: never;
+    color?: string;
+} | {
+    preset: keyof typeof cubemapPresets;
+    path?: never;
+    faces?: never;
+    color?: string;
+} | {
+    color: string;
+    path?: never;
+    faces?: never;
+    preset?: never;
+};
+export declare enum CubemapFaceNames {
+    POSITIVE_X = "pX",
+    NEGATIVE_X = "nX",
+    POSITIVE_Y = "pY",
+    NEGATIVE_Y = "nY",
+    POSITIVE_Z = "pZ",
+    NEGATIVE_Z = "nZ"
+}
+export type CubemapFaces = Record<CubemapFaceNames, string>;

package/dist/src/custom-layers/RadialGradientLayer/RadialGradientLayer.d.ts

@@ -0,0 +1,149 @@
+import { CustomLayerInterface, CustomRenderMethodInput } from 'maplibre-gl';
+import { Map as MapSDK } from '../../Map';
+import { GradientDefinition, RadialGradientLayerConstructorOptions } from './types';
+/**
+ * A custom map layer that renders a radial gradient effect, typically used as a halo around a globe.
+ * This layer uses WebGL for rendering and provides animation capabilities.
+ *
+ * The layer is implemented as a 3D custom layer that renders a billboard quad with a radial gradient shader.
+ * The gradient can be configured with multiple color stops and can be animated.
+ *
+ * @example
+ * ```typescript
+ * // Create a simple halo layer with default settings
+ * const haloLayer = new RadialGradientLayer(true);
+ * map.addLayer(haloLayer);
+ *
+ * // Create a customized halo layer
+ * const customHalo = new RadialGradientLayer({
+ *   scale: 1.5,
+ *   stops: [
+ *     [0, "rgba(255, 255, 255, 0.8)"],
+ *     [1, "rgba(255, 255, 255, 0)"]
+ *   ]
+ * });
+ * map.addLayer(customHalo);
+ * ```
+ * @remarks You shouldn't have to use this class directly.
+ * Instead, use the `Map.setHalo` method to create and add a halo layer to the map.
+ */
+export declare class RadialGradientLayer implements CustomLayerInterface {
+    id: string;
+    type: CustomLayerInterface["type"];
+    renderingMode: CustomLayerInterface["renderingMode"];
+    /**
+     * The gradient definition used by this layer.
+     * It contains the stops and scale for the radial gradient.
+     * @private
+     * @type {GradientDefinition}
+     */
+    private gradient;
+    /**
+     * The scale of the radial gradient, which determines its size.
+     * This value is animated from 0 to the target scale during the layer's appearance.
+     * @private
+     * @type {number}
+     */
+    private scale;
+    /**
+     * The animation delta value used to control the progress of the gradient's appearance animation.
+     * It is incremented during each frame of the animation until it reaches 1.
+     * @private
+     * @type {number}
+     */
+    private animationDelta;
+    /**
+     * The MapSDK instance to which this layer is added.
+     * This is set when the layer is added to the map.
+     * @private
+     * @type {MapSDK}
+     */
+    private map;
+    /**
+     * The 3D object representing the radial gradient plane.
+     * This object is created when the layer is added to the map and contains the shader program and buffers.
+     * It is used for rendering the radial gradient effect.
+     * @private
+     * @type {Object3D<(typeof ATTRIBUTES_KEYS)[number], (typeof UNIFORMS_KEYS)[number]>}
+     */
+    private plane?;
+    /**
+     * Whether the halo should be animated in and out.
+     * @private
+     * @type {boolean}
+     */
+    private animationActive;
+    /**
+     * Creates a new RadialGradientLayer instance.
+     *
+     * @param {RadialGradientLayerConstructorOptions | boolean} gradient - Configuration options for the radial gradient or a boolean value.
+     * If a boolean is provided, default configuration options will be used.
+     * If an `RadialGradientLayerConstructorOptions` is provided, it will be merged with default options.
+     */
+    constructor(gradient: RadialGradientLayerConstructorOptions | boolean);
+    /**
+     * Adds the radial gradient layer to the specified map.
+     * This method is called by the map when the layer is added to it.
+     *
+     * @param {MapSDK} map - The MapSDK instance to which this layer is being added
+     * @param {WebGLRenderingContext | WebGL2RenderingContext} gl - The WebGL rendering context used for rendering the layer
+     * @returns void
+     */
+    onAdd(map: MapSDK, gl: WebGLRenderingContext | WebGL2RenderingContext): void;
+    /**
+     * Returns the current gradient configuration of the radial gradient layer.
+     *
+     * @returns {GradientDefinition} The current gradient configuration.
+     */
+    getConfig(): GradientDefinition;
+    /**
+     * Checks if the gradient needs to be updated based on the provided specification.
+     *
+     * @param {GradientDefinition} spec - The gradient specification to compare with the current gradient.
+     * @returns {boolean} True if the gradient needs to be updated, false otherwise.
+     */
+    shouldUpdate(newSpec?: GradientDefinition | boolean): boolean;
+    /**
+     * Animates the radial gradient into view by gradually scaling from 0 to the target scale.
+     *
+     * This method uses requestAnimationFrame to create a smooth scaling animation effect.
+     * During each frame, it:
+     *   1. Interpolates the scale value between 0 and the target scale
+     *   2. Increments the animation progress (animationDelta)
+     *   3. Triggers a map repaint
+     *
+     * @private
+     * @returns {Promise<void>} A promise that resolves when the animation completes
+     */
+    private animateIn;
+    /**
+     * Animates the radial gradient layer out by gradually reducing its scale to zero.
+     *
+     * This method creates a smooth transition effect by linearly interpolating the scale
+     * from its current value to zero over multiple animation frames. During each frame,
+     * the animation progresses by incrementing the internal animation delta value.
+     *
+     * The map is repainted after each animation step to reflect the updated scale.
+     *
+     * @private
+     * @returns A Promise that resolves when the animation is complete.
+     */
+    private animateOut;
+    onRemove(_map: MapSDK, gl: WebGLRenderingContext | WebGL2RenderingContext): void;
+    prerender(_gl: WebGLRenderingContext | WebGL2RenderingContext, _options: CustomRenderMethodInput): void;
+    render(gl: WebGLRenderingContext | WebGL2RenderingContext, options: CustomRenderMethodInput): void;
+    /**
+     * Sets a new gradient for the radial gradient layer and animates the transition.
+     *
+     * This method first animates the current gradient out, then updates the gradient
+     * property with the new gradient definition, and finally animates the new gradient in.
+     *
+     * @param {GradientDefinition} gradient - The new gradient definition to set for this layer.
+     * @returns {Promise<void>} A promise that resolves when the new gradient is set and animated in.
+     */
+    setGradient(gradient: GradientDefinition | boolean): Promise<void>;
+    setAnimationActive(active: boolean): void;
+    show(): void;
+    hide(): void;
+}
+export declare function validateHaloSpecification(halo: RadialGradientLayerConstructorOptions | boolean): Array<string>;

package/dist/src/custom-layers/RadialGradientLayer/index.d.ts

@@ -0,0 +1,2 @@
+export * from './RadialGradientLayer';
+export * from './types';

package/dist/src/custom-layers/RadialGradientLayer/types.d.ts

@@ -0,0 +1,50 @@
+import { Object3D } from '../../utils/webgl-utils';
+/**
+ * Represents a color string. Can be any valid CSS color format such as hex (#RRGGBB),
+ * RGB/RGBA (rgb(r, g, b) / rgba(r, g, b, a)), HSL/HSLA, or named colors (e.g., 'red', 'blue').
+ * Used within RadialGradientLayer implementations.
+ */
+export type GradientStopColor = string;
+/**
+ * Represents a position in a radial gradient.
+ * The numeric value typically indicates the position along the gradient where a color stop should be placed.
+ * Usually normalized between 0 and 1, where 0 represents the center of the gradient and 1 represents the outer edge.
+ */
+export type GradientStop = number;
+/**
+ * Options for constructing a RadialGradientLayer.
+ * This type is an alias for {@link GradientDefinition}, which defines the properties
+ * needed to create a radial gradient visualization on a map.
+ */
+export type RadialGradientLayerConstructorOptions = GradientDefinition;
+/**
+ * Defines a gradient for use in a radial gradient layer.
+ *
+ * @typedef {Object} GradientDefinition
+ * @property {Array<[GradientStop, GradientStopColor]>} stops - Array of gradient stops, where each stop is a tuple containing a position and a color
+ * @property {number} scale - Scale factor that affects the size/reach of the gradient
+ */
+export type GradientDefinition = {
+    stops: Array<[GradientStop, GradientStopColor]>;
+    scale: number;
+};
+export type GradientAttributeKey = "vertexPosition";
+/**
+ * Keys for gradient uniform values used in the RadialGradientLayer.
+ *
+ * @typedef {string} GradientUniformKey
+ * @property {"stopsNumber"} stopsNumber - Key for the number of stops in the gradient.
+ * @property {"stops"} stops - Key for the positions of color stops in the gradient.
+ * @property {"colors"} colors - Key for the color values at each stop in the gradient.
+ */
+export type GradientUniformKey = "stopsNumber" | "stops" | "colors";
+/**
+ * Represents a subset of a 3D object used for gradient rendering.
+ *
+ * This type picks only the essential properties from Object3D that are needed
+ * for rendering radial gradients.
+ *
+ * @template GradientAttributeKey - The type defining attribute keys for the gradient
+ * @template GradientUniformKey - The type defining uniform keys for the gradient
+ */
+export type GradientPlaneObject3D = Pick<Object3D<GradientAttributeKey, GradientUniformKey>, "shaderProgram" | "programInfo" | "positionBuffer">;

package/dist/src/custom-layers/extractCustomLayerStyle.d.ts

@@ -0,0 +1,17 @@
+import { Map as MapSDK } from '../Map';
+import { StyleSpecification } from 'maplibre-gl';
+import { CubemapLayerConstructorOptions, RadialGradientLayerConstructorOptions } from '../custom-layers';
+export type StyleSpecificationWithMetaData = StyleSpecification & {
+    metadata?: {
+        "maptiler:copyright": string;
+        maptiler?: {
+            halo: RadialGradientLayerConstructorOptions;
+            space: CubemapLayerConstructorOptions;
+        };
+    };
+};
+export interface IExtractCustomLayerStyleOptions {
+    map: MapSDK;
+    property: "halo" | "space";
+}
+export default function extractCustomLayerStyle<T extends CubemapLayerConstructorOptions | RadialGradientLayerConstructorOptions | null>(options: IExtractCustomLayerStyleOptions): T | null;

package/dist/src/custom-layers/index.d.ts

@@ -0,0 +1,6 @@
+import { RadialGradientLayer } from './RadialGradientLayer';
+import { CubemapLayer } from './CubemapLayer';
+export { RadialGradientLayer, CubemapLayer };
+export * from './RadialGradientLayer/types';
+export * from './CubemapLayer/types';
+export type { StyleSpecificationWithMetaData } from './extractCustomLayerStyle';

package/dist/src/helpers/index.d.ts

@@ -0,0 +1,5 @@
+export * from './screenshot';
+export * from './vectorlayerhelpers';
+export type * from './vectorlayerhelpers';
+export type * from './stylehelper';
+export * from './stylehelper';

package/dist/src/helpers/screenshot.d.ts

@@ -0,0 +1,18 @@
+import { Map as MapSDK } from '../Map';
+/**
+ * Takes a screenshot (PNG file) of the curent map view.
+ * Depending on the options, this function can automatically trigger a download of te file.
+ */
+export declare function takeScreenshot(map: MapSDK, options?: {
+    /**
+     * If `true`, this function will trigger a download in addition to returning a blob.
+     * Default: `false`
+     */
+    download?: boolean;
+    /**
+     * Only if `options.download` is `true`. Indicates the filename under which
+     * the file will be downloaded.
+     * Default: `"maptiler_screenshot.png"`
+     */
+    filename?: string;
+}): Promise<Blob>;

package/dist/src/helpers/stylehelper.d.ts

@@ -0,0 +1,28 @@
+import { DataDrivenPropertyValueSpecification, ExpressionSpecification } from 'maplibre-gl';
+import { ColorRamp } from '../ColorRamp';
+import { DataDrivenStyle, PropertyValues, ZoomNumberValues, ZoomStringValues } from './vectorlayerhelpers';
+export type ColorPalette = [string, string, string, string];
+export declare const colorPalettes: Array<ColorPalette>;
+export declare function getRandomColor(): string;
+export declare function generateRandomSourceName(): string;
+export declare function generateRandomLayerName(): string;
+/**
+ * Linera interpolation to find a value at an arbitrary zoom level, given a list of tuple zoom-value
+ */
+export declare function lerpZoomNumberValues(znv: ZoomNumberValues, z: number): number;
+export declare function paintColorOptionsToPaintSpec(color: ZoomStringValues): DataDrivenPropertyValueSpecification<string>;
+export declare function rampedOptionsToLayerPaintSpec(ramp: ZoomNumberValues): DataDrivenPropertyValueSpecification<number>;
+export declare function computeRampedOutlineWidth(lineWidth: number | ZoomNumberValues, outlineWidth: number | ZoomNumberValues): number | DataDrivenPropertyValueSpecification<number>;
+export declare function rampedPropertyValueWeight(ramp: PropertyValues, property: string): DataDrivenPropertyValueSpecification<number>;
+/**
+ * Create a dash array from a string pattern that uses underscore and whitespace characters
+ */
+export declare function dashArrayMaker(pattern: string): Array<number>;
+export declare function colorDrivenByProperty(style: DataDrivenStyle, property: string): DataDrivenPropertyValueSpecification<string>;
+export declare function radiusDrivenByProperty(style: DataDrivenStyle, property: string, zoomCompensation?: boolean): DataDrivenPropertyValueSpecification<number>;
+export declare function radiusDrivenByPropertyHeatmap(style: PropertyValues, property: string, zoomCompensation?: boolean): DataDrivenPropertyValueSpecification<number>;
+/**
+ * Turns a ColorRamp instance into a MapLibre style for ramping the opacity, driven by a property
+ */
+export declare function opacityDrivenByProperty(colorramp: ColorRamp, property: string): DataDrivenPropertyValueSpecification<number>;
+export declare function heatmapIntensityFromColorRamp(colorRamp: ColorRamp, steps?: number): ExpressionSpecification;