@maptiler/sdk
Version:
The Javascript & TypeScript map SDK tailored for MapTiler Cloud
355 lines (354 loc) • 10.3 kB
TypeScript
import { DoubleClickZoomHandler, DragPanHandler, EaseToOptions, PointLike, TwoFingersTouchZoomRotateHandler, default as MapLibre } from 'maplibre-gl';
import { FlyToOptions, MapDataEvent, MapOptions, JumpToOptions, ScrollZoomHandler, BoxZoomHandler, KeyboardHandler, CooperativeGesturesHandler } from '..';
import { Map } from '../Map';
export type AllowedConstrcutorOptions = "container" | "apiKey" | "maxZoom" | "minZoom" | "zoom" | "bearing";
declare const Evented: typeof MapLibre.Evented;
export type ImageViewerFlyToOptions = Omit<FlyToOptions, "pitch"> & {
center: [number, number];
};
export type ImageViewerJumpToOptions = Omit<JumpToOptions, "pitch"> & {
center: [number, number];
};
export type ImageViewerEaseToOptions = Omit<EaseToOptions, "pitch"> & {
center: [number, number];
};
export type ImageViewerConstructorOptions = Pick<MapOptions, AllowedConstrcutorOptions> & {
/**
* The UUID of the image.
*/
imageUUID: string;
/**
* Whether to show debug information.
*/
debug?: boolean;
/**
* The center of the image.
*/
center?: [number, number];
/**
* Whether to show a control to fit the image to the viewport.
*/
fitToBoundsControl?: boolean;
/**
* Whether to show a navigation control.
*/
navigationControl?: boolean;
};
/**
* The metadata of the image. This is the shape of the response from the API.
* And used to convert px to lnglat and vice versa.
*/
export type ImageMetadata = {
id: string;
description: string;
attribution: string;
width: number;
height: number;
minzoom: number;
maxzoom: number;
tileSize: number;
};
export default class ImageViewer extends Evented {
/**
* The UUID of the image.
*
* @internal
*/
private imageUUID;
/**
* Whether to enable debug mode.
*
* @internal
*/
private debug;
/**
* The metadata of the image.
*
* @internal
*/
private imageMetadata?;
/**
* Why not extend the Map class?
* Because ImageViewer technically operates in screen space and not in map space.
* We wrap map and perform calculations in screen space.
* We do not want to have to extend the Map class and give access to
* methods and properties that operate in LngLat space. *
*/
private sdk;
/**
* The options for the ImageViewer.
*
* @internal
*/
private options;
/**
* The size of the image.
*
* @internal
*/
private imageSize?;
/**
* The padded size max.
*
* @internal
*/
private paddedSizeMax?;
/**
* The version of the ImageViewer / SDK.
*/
get version(): string;
/**
* The constructor for the ImageViewer.
*
* @param {Partial<ImageViewerConstructorOptions>} imageViewerConstructorOptions - The options for the ImageViewer.
* @example
* ```ts
* import "@maptiler/sdk/dist/maptiler-sdk.css"; // import css
* import { ImageViewer } from "@maptiler/sdk"; // import the sdk
*
* const imageViewer = new ImageViewer({
* container: document.getElementById("map"),
* imageUUID: "01986025-ceb9-7487-9ea6-7a8637dcc1a1",
* debug: true, // show tile boundaries, padding, collision boxes etc
* fitToBoundsControl: true, // show a control to fit the image to the viewport
* navigationControl: true, // show a navigation control
* center: [0, 0], // center in pixels
* zoom: 1, // zoom level
* bearing: 0, // bearing
* });
* ```
*/
constructor(imageViewerConstructorOptions: Partial<ImageViewerConstructorOptions>);
/**
* Waits for the ImageViewer to be ready.
*
* @returns {Promise<void>}
*/
onReadyAsync(): Promise<void>;
shouldFitImageToViewport: boolean;
/**
* Initializes the ImageViewer
* - fetches the image metadata
* - adds the image source to the sdk instance
* - sets the center to the middle of the image (if center is not provided)
* - monkeypatches the maplibre-gl sdk transform method to allow for overpanning and underzooming.
* - sets up global event forwarding / intercepting from the map instance
* - sets the center to the middle of the image (if center is not provided)
*
* @internal
* @returns {Promise<void>}
*/
private init;
/**
* Fits the image to the viewport.
*
* @param {Object} options - The options for the fit image to viewport.
* @param {boolean} options.ease - Whether to ease to the viewport bounds.
*/
fitImageToViewport({ ease }?: {
ease?: boolean;
}): void;
/**
* Fetches the image metadata from the API.
*
* @internal
* @returns {Promise<void>}
*/
private fetchImageMetadata;
/**
* Adds the image source to the sdk instance.
*
* @internal
* @returns {void}
*/
private addImageSource;
/**
* Triggers a repaint of the ImageViewer. Same as map.triggerRepaint().
*
* @internal
* @returns {void}
*/
triggerRepaint(): void;
/**
* The scroll zoom handler.
*
* @internal
* @returns {ScrollZoomHandler}
*/
get scrollZoom(): ScrollZoomHandler;
/**
* The scroll zoom handler.
*
* @internal
* @param {ScrollZoomHandler} value - The scroll zoom handler.
*/
set scrollZoom(value: ScrollZoomHandler);
/**
* The box zoom handler.
*
* @internal
* @returns {BoxZoomHandler}
*/
get boxZoom(): BoxZoomHandler;
/**
* The box zoom handler.
*
* @internal
* @param {BoxZoomHandler} value - The box zoom handler.
*/
set boxZoom(value: BoxZoomHandler);
/**
* The drag pan handler.
*
* @internal
* @returns {DragPanHandler}
*/
get dragPan(): DragPanHandler;
/**
* The drag pan handler.
*
* @internal
* @param {DragPanHandler} value - The drag pan handler.
*/
set dragPan(value: DragPanHandler);
/**
* The keyboard handler.
*
* @internal
* @returns {KeyboardHandler}
*/
get keyboard(): KeyboardHandler;
/**
* The keyboard handler.
*
* @internal
* @param {KeyboardHandler} value - The keyboard handler.
*/
set keyboard(value: KeyboardHandler);
/**
* The double click zoom handler.
*
* @internal
* @returns {DoubleClickZoomHandler}
*/
get doubleClickZoom(): DoubleClickZoomHandler;
/**
* The double click zoom handler.
*
* @internal
* @param {DoubleClickZoomHandler} value - The double click zoom handler.
*/
set doubleClickZoom(value: DoubleClickZoomHandler);
/**
* The touch zoom rotate handler.
*
* @internal
* @returns {TwoFingersTouchZoomRotateHandler}
*/
get touchZoomRotate(): TwoFingersTouchZoomRotateHandler;
/**
* The touch zoom rotate handler.
*
* @internal
* @param {TwoFingersTouchZoomRotateHandler} value - The touch zoom rotate handler.
*/
set touchZoomRotate(value: TwoFingersTouchZoomRotateHandler);
/**
* The cooperative gestures handler.
*
* @internal
* @returns {CooperativeGesturesHandler}
*/
get cooperativeGestures(): CooperativeGesturesHandler;
/**
* The cooperative gestures handler.
*
* @internal
* @param {CooperativeGesturesHandler} value - The cooperative gestures handler.
*/
set cooperativeGestures(value: CooperativeGesturesHandler);
/**
* Converts a LngLat to a px coordinate, based on the image metadata.
*
* @internal
* @param {LngLat} lngLat - The LngLat to convert.
* @returns {[number, number]} The px coordinate.
*/
private lngLatToPx;
/**
* Converts a px coordinate to a LngLat, based on the image metadata.
*
* @internal
* @param {LngLat} lngLat - The LngLat to convert.
* @returns {[number, number]} The px coordinate.
*/
private pxToLngLat;
/**
* Fly to a given center.
*
* @param {ImageViewerFlyToOptions} options - The options for the fly to.
* @param {MapDataEvent} eventData - The event data.
*/
flyTo(options: ImageViewerFlyToOptions, eventData?: MapDataEvent): Map;
/**
* Jump to a given center.
*
* @param {ImageViewerJumpToOptions} options - The options for the jump to.
* @param {MapDataEvent} eventData - The event data.
*/
jumpTo(options: ImageViewerJumpToOptions, eventData?: MapDataEvent): Map;
/**
* Set the zoom level.
*
* @param {number} zoom - The zoom level.
*/
setZoom(zoom: number): void;
/**
* Get the zoom level.
*
* @returns {number} The zoom level.
*/
getZoom(): number;
/**
* Get the center of the ImageViewer in pixels.
*
* @internal
* @returns {[number, number]} The center of the ImageViewer.
*/
getCenter(): [number, number];
/**
* Set the center of the ImageViewer in pixels.
*
* @param {number} center - The center of the ImageViewer.
*/
setCenter(center: [number, number]): void;
/**
* Set the bearing of the ImageViewer in degrees.
*
* @param {number} bearing - The bearing of the ImageViewer.
*/
setBearing(bearing: number): void;
/**
* Get the bearing of the ImageViewer in degrees.
*
* @returns {number} The bearing of the ImageViewer.
*/
getBearing(): number;
/**
* Pan by a given delta in pixels.
*
* @param {PointLike} delta - The delta to pan by.
* @param {ImageViewerEaseToOptions} options - The options for the pan.
* @param {any} eventData - The event data.
*/
panBy(delta: PointLike, options?: ImageViewerEaseToOptions, eventData?: any): void;
/**
* Pan to a given center in pixels.
*
* @param {number} center - The center to pan to.
* @param {ImageViewerEaseToOptions} options - The options for the pan.
* @param {any} eventData - The event data.
*/
panTo(center: [number, number], options?: ImageViewerEaseToOptions, eventData?: any): void;
}
export {};