npm package: @india-boundary-corrector/openlayers-layer
Description: OpenLayers TileLayer with India boundary corrections
Author: ramSeraph
Latest version: 0.2.2

# @india-boundary-corrector/openlayers-layer

[![npm version](https://img.shields.io/npm/v/@india-boundary-corrector/openlayers-layer)](https://www.npmjs.com/package/@india-boundary-corrector/openlayers-layer)

OpenLayers TileLayer extension that automatically applies India boundary corrections.

[Try it on JSFiddle](https://jsfiddle.net/waoepz78/)

## Installation

```bash
npm install @india-boundary-corrector/openlayers-layer ol
```

## Usage

### Script Tag (IIFE) - Simplest Setup

No bundler required! Just include the script and use the global `IndiaBoundaryCorrector`:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@10.3.1/ol.css">
<script src="https://cdn.jsdelivr.net/npm/ol@10.3.1/dist/ol.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@india-boundary-corrector/openlayers-layer/dist/index.global.js"></script>

<div id="map" style="height: 400px;"></div>

<script>
  const { IndiaBoundaryCorrectedTileLayer } = IndiaBoundaryCorrector;

  const map = new ol.Map({
    target: 'map',
    layers: [
      new IndiaBoundaryCorrectedTileLayer({
        url: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
        sourceOptions: {
          attributions: '© OpenStreetMap contributors'
        }
      })
    ],
    view: new ol.View({
      center: ol.proj.fromLonLat([75.3412, 33.2778]),
      zoom: 5
    })
  });
</script>
```

### ES Modules

```javascript
import { Map, View } from 'ol';
import { fromLonLat } from 'ol/proj';
import { IndiaBoundaryCorrectedTileLayer } from '@india-boundary-corrector/openlayers-layer';

const map = new Map({
  target: 'map',
  layers: [
    new IndiaBoundaryCorrectedTileLayer({
      url: 'https://{a-c}.tile.openstreetmap.org/{z}/{x}/{y}.png',
      sourceOptions: {
        attributions: '© OpenStreetMap contributors'
      }
    })
  ],
  view: new View({
    center: fromLonLat([75.3412, 33.2778]),
    zoom: 5
  })
});
```

### With Explicit Layer Config

```javascript
import { IndiaBoundaryCorrectedTileLayer } from '@india-boundary-corrector/openlayers-layer';

const layer = new IndiaBoundaryCorrectedTileLayer({
  url: 'https://{a-c}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png',
  layerConfig: 'cartodb-dark',
  sourceOptions: {
    attributions: '© CARTO © OpenStreetMap contributors'
  }
});
```

### With Custom Layer Config

```javascript
import { IndiaBoundaryCorrectedTileLayer, LayerConfig } from '@india-boundary-corrector/openlayers-layer';

const osmDeConfig = new LayerConfig({
  id: 'osm-de',
  tileUrlTemplates: ['https://tile.openstreetmap.de/{z}/{x}/{y}.png'],
  lineWidthStops: { 1: 0.5, 2: 0.6, 3: 0.7, 4: 1.0, 10: 3.75 },
  lineStyles: [
    // layerSuffix determines which PMTiles layer to use
    { color: 'rgb(180, 200, 180)', layerSuffix: 'osm' },
    { color: 'rgb(121, 146, 127)', layerSuffix: 'osm', widthFraction: 1/3, dashArray: [30, 2, 8, 2] },
  ],
});

const layer = new IndiaBoundaryCorrectedTileLayer({
  url: 'https://tile.openstreetmap.de/{z}/{x}/{y}.png',
  layerConfig: osmDeConfig,
  sourceOptions: {
    attributions: '© OpenStreetMap contributors'
  }
});

// Or use extraLayerConfigs for auto-detection
const layer2 = new IndiaBoundaryCorrectedTileLayer({
  url: 'https://tile.openstreetmap.de/{z}/{x}/{y}.png',
  extraLayerConfigs: [osmDeConfig],
  sourceOptions: {
    attributions: '© OpenStreetMap contributors'
  }
});
```

### Factory Function

```javascript
import { indiaBoundaryCorrectedTileLayer } from '@india-boundary-corrector/openlayers-layer';

const layer = indiaBoundaryCorrectedTileLayer({
  url: 'https://{a-c}.tile.openstreetmap.org/{z}/{x}/{y}.png',
  sourceOptions: {
    attributions: '© OpenStreetMap contributors'
  }
});
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `url` | string | Tile URL template with `{z}`, `{x}`, `{y}` placeholders |
| `pmtilesUrl` | string | URL to PMTiles file (auto-detected if not provided) |
| `layerConfig` | LayerConfig \| string | Layer config object or config ID |
| `extraLayerConfigs` | LayerConfig[] | Additional configs for auto-detection |
| `tileSize` | number | Tile size in pixels for OpenLayers source (default: 256) |
| `fallbackOnCorrectionFailure` | boolean | Return original tile if corrections fail (default: true) |
| `sourceOptions` | Object | Additional options passed to XYZ source |
| `...layerOptions` | Object | Additional options passed to TileLayer |

## Methods

| Method | Returns | Description |
|--------|---------|-------------|
| `getTileFixer()` | `TileFixer` | Get the underlying TileFixer instance |
| `getLayerConfig()` | `LayerConfig` | Get the resolved layer configuration |
| `getRegistry()` | `LayerConfigRegistry` | Get the layer config registry |

## Events

### `correctionerror`

Fired when the corrections data fails to load (e.g., PMTiles fetch failure). The tile will still display using the original uncorrected image.

```javascript
layer.on('correctionerror', (e) => {
  console.warn('Corrections unavailable:', e.error);
  console.log('Tile coords:', e.coords); // { z, x, y }
  console.log('Tile URL:', e.tileUrl);
});
```

| Property | Type | Description |
|----------|------|-------------|
| `error` | Error | The error that occurred |
| `coords` | object | Tile coordinates `{ z, x, y }` |
| `tileUrl` | string | URL of the tile being loaded |

## Bundling

If you're bundling your application (Rollup, Webpack, Vite, etc.), you may need to copy the PMTiles data file to your output directory. See **[Bundling the PMTiles Asset](../data/bundling-pmtiles.md)** for instructions.

## License

Unlicense