@naivemap/maplibre-gl-image-layer 0.0.1-alpha.0 → 0.0.1-alpha.2

package/README.md

@@ -0,0 +1,11 @@
+# @naivemap/maplibre-gl-image-layer
+
+ImageLayer ([@naivemap/maplibre-gl-image-layer](https://www.npmjs.com/package/@naivemap/maplibre-gl-image-layer)): A versatile layer for displaying georeferenced images with **various projections** on the map. It supports loading and correctly positioning images from different coordinate systems, making it ideal for integrating non-standard raster data, historical maps, or aerial imagery.
+
+[API References](https://www.naivemap.com/maplibre-gl-layers/api/image-layer/)
+
+## Install
+
+```bash
+pnpm add @naivemap/maplibre-gl-image-layer
+```

package/dist/ImageLayer.d.ts

@@ -1,29 +1,107 @@
 import { default as maplibregl } from 'maplibre-gl';
 import { Coordinates } from './arrugator';
+/**
+ * The properties for masking the image layer.
+ */
 export type MaskProperty = {
+    /**
+     * The type of mask to apply.
+     * - 'in': The mask is applied inside the polygon (default).
+     * - 'out': The mask is applied outside the polygon.
+     */
     type?: 'in' | 'out';
+    /**
+     * The data for the mask, which can be a GeoJSON Polygon or MultiPolygon.
+     * If not provided, no mask will be applied.
+     */
     data: GeoJSON.Polygon | GeoJSON.MultiPolygon;
 };
+/**
+ * The options for the ImageLayer.
+ */
 export type ImageOption = {
+    /**
+     * URL that points to an image.
+     */
     url: string;
+    /**
+     * The projection of the image, typically an EPSG code like 'EPSG:4326'.
+     */
     projection: string;
+    /**
+     * Corners of image specified in longitude, latitude pairs.
+     */
     coordinates: Coordinates;
+    /**
+     * The resampling/interpolation method to use for overscaling.
+     * - 'linear': Linear interpolation (default).
+     * - 'nearest': Nearest neighbor interpolation.
+     * If not specified, the default is 'linear'.
+     */
     resampling?: 'linear' | 'nearest';
+    /**
+     * Opacity of the image layer, ranging from 0 (fully transparent) to 1 (fully opaque).
+     * Defaults to 1.
+     */
     opacity?: number;
+    /**
+     * Cross-origin attribute for the image, which can be used to specify how the image should be fetched.
+     * Defaults to 'anonymous'.
+     */
     crossOrigin?: string;
+    /**
+     * The step size for the Arrugator algorithm, which controls the granularity of the image rendering.
+     */
     arrugatorStep?: number;
+    /**
+     * Masking properties for the image layer.
+     * If not provided, no mask will be applied.
+     */
     mask?: MaskProperty;
-    metadata?: any;
 };
 /**
- * ImageLayer is a custom layer for MapLibre GL that renders an image
- * with support for projection, coordinates, resampling, opacity, and masking.
+ * A custom MapLibre GL JS layer for rendering georeferenced images with arbitrary projections.
+ *
+ * @remarks
+ * This layer uses `proj4js` to transform image coordinates from any source projection
+ * into the map's coordinate system. It triangulates the image corners to correctly
+ * warp and display it on the map canvas. This is ideal for overlaying historical maps,
+ * floor plans, or other non-standard raster data.
+ *
+ * @example
+ * ```ts
+ * import ImageLayer from '@naivemap/maplibre-gl-image-layer';
+ * import proj4 from 'proj4';
+ *
+ * // 1. Define the source projection if it's not standard
+ * proj4.defs('EPSG:2154', '+proj=lcc +lat_0=46.5 +lon_0=3 +lat_1=49 +lat_2=44 +x_0=700000 +y_0=6600000 +ellps=GRS80 +units=m +no_defs');
+ *
+ * // 2. Create the layer instance
+ * const layer = new ImageLayer('image-layer', {
+ *   url: 'https://example.com/my-image.png',
+ *   coordinates: [
+ *     [100000, 6700000], // Top-left corner in source projection
+ *     [110000, 6700000], // Top-right
+ *     [110000, 6600000], // Bottom-right
+ *     [100000, 6600000]  // Bottom-left
+ *   ],
+ *   projection: 'EPSG:2154'
+ * });
+ *
+ * // 3. Add the layer to the map
+ * map.addLayer(layer);
+ * ```
  */
 export default class ImageLayer implements maplibregl.CustomLayerInterface {
     id: string;
+    /**
+     * @ignore
+     */
     type: 'custom';
+    /**
+     * @ignore
+     */
     renderingMode?: '2d' | '3d' | undefined;
-    metadata?: any;
     private option;
     private map?;
     private gl?;
@@ -35,9 +113,22 @@ export default class ImageLayer implements maplibregl.CustomLayerInterface {
     private maskProperty;
     private maskProgramInfo?;
     private maskBufferInfo?;
+    /**
+     * @param id - A unique layer id
+     * @param option - ImageLayer options
+     */
     constructor(id: string, option: ImageOption);
+    /**
+     * @ignore
+     */
     onAdd(map: maplibregl.Map, gl: WebGLRenderingContext): void;
+    /**
+     * @ignore
+     */
     onRemove(_: maplibregl.Map, gl: WebGLRenderingContext): void;
+    /**
+     * @ignore
+     */
     render(gl: WebGLRenderingContext, args: any): void;
     /**
      * Updates the URL, the projection, the coordinates, the opacity or the resampling of the image.