@india-boundary-corrector/tilefixer

Core library for fetching and applying India boundary corrections to raster map tiles.

Installation

npm install @india-boundary-corrector/tilefixer

Usage

import { TileFixer } from '@india-boundary-corrector/tilefixer';
import { getPmtilesUrl } from '@india-boundary-corrector/data';
import { layerConfigs } from '@india-boundary-corrector/layer-configs';

// Create a boundary corrector
const corrector = new TileFixer(getPmtilesUrl());

// Get corrections for a tile
const corrections = await corrector.getCorrections(z, x, y);
// Returns: { 'to-add-osm': [...], 'to-del-osm': [...], 'to-add-ne': [...], 'to-del-ne': [...], 
//            'to-add-osm-disp': [...], 'to-del-osm-disp': [...], 'to-add-ne-disp': [...], 'to-del-ne-disp': [...],
//            'to-add-osm-internal': [...], 'to-del-osm-internal': [...] }

// Apply corrections to a raster tile
const layerConfig = layerConfigs.get('osm-carto');
const fixedTileData = await corrector.fixTile(
  corrections,
  originalTileArrayBuffer,
  layerConfig,
  z        // zoom level (tile size is derived from image)
);

API

TileFixer

Static Methods

| Method | Returns | Description | |--------|---------|-------------| | TileFixer.getOrCreate(pmtilesUrl) | TileFixer | Get or create a TileFixer for a URL (reuses existing instances) | | TileFixer.setDefaultCacheMaxFeatures(count) | void | Set default max features to cache for new instances (default: 25000) |

Constructor

new TileFixer(pmtilesUrl, options?)

| Parameter | Type | Description | |-----------|------|-------------| | pmtilesUrl | string | URL to the PMTiles file | | options.cacheMaxFeatures | number | Maximum features to cache |

Methods

| Method | Returns | Description | |--------|---------|-------------| | getCorrections(z, x, y) | Promise<Object> | Get correction features for a tile. Supports overzoom beyond zoom 14. | | fixTile(corrections, rasterTile, layerConfig, zoom) | Promise<ArrayBuffer> | Apply corrections to a raster tile and return corrected PNG. Tile size is derived from the image. | | fetchAndFixTile(tileUrl, z, x, y, layerConfig, options?) | Promise<Object> | Fetch a tile, apply corrections, and return result. See below. | | getSource() | PMTiles | Get the underlying PMTiles source object | | clearCache() | void | Clear the tile cache |

fetchAndFixTile Options and Return Value

const result = await corrector.fetchAndFixTile(tileUrl, z, x, y, layerConfig, {
  signal: abortSignal,  // AbortSignal for cancellation
  mode: 'cors',         // Fetch mode
});

// result: {
//   data: ArrayBuffer,           // The tile image data
//   wasFixed: boolean,           // Whether corrections were applied
//   correctionsFailed: boolean,  // Whether corrections fetch failed
//   correctionsError: Error|null // The error if corrections failed
// }

How It Works

1. Fetching corrections: The corrector fetches vector tile data from the PMTiles file containing boundary correction geometries.

2. Overzoom support: For zoom levels > 14 (max data zoom), parent tile data is fetched and transformed to the correct sub-tile quadrant.

3. Applying corrections:

   • Deletions: Uses median blur along deletion paths to erase incorrect boundary lines
   • Additions: Draws correct boundary lines with configurable colors and dash patterns

4. Caching: Parsed vector tiles are cached in an LRU cache to avoid repeated fetches.

License

Unlicense