Skip to main content
GeoPackageTileRetriever wraps a TileDao and fetches tiles by their tile grid coordinates using Web Mercator (XYZ) or WGS84 addressing. It handles the coordinate transformation between the requested tile scheme and the GeoPackage’s native projection internally. 
import { GeoPackageTileRetriever } from '@ngageoint/geopackage';

const tileDao = geoPackage.getTileDao('world_imagery');
const retriever = new GeoPackageTileRetriever(tileDao, 256, 256);

​
Constructor

new GeoPackageTileRetriever(
  tileDao: TileDao,
  width?: number,
  height?: number,
  imageFormat?: string
)
​
tileDao
TileDao
required
A TileDao for the tile table to retrieve from.
​
width
number
Output tile width in pixels. When omitted the tile table’s native width is used.
​
height
number
Output tile height in pixels. When omitted the tile table’s native height is used.
​
imageFormat
string
MIME type for the output image. Defaults to 'image/png'.

​
Web Mercator (XYZ) tiles

​
getTile()

Fetches the Web Mercator tile at the specified XYZ coordinates and returns it as a GeoPackageTile. Returns null if no data is available for that tile. 
async getTile(x: number, y: number, zoom: number): Promise<GeoPackageTile>
​
x
number
required
Tile column in the Web Mercator grid.
​
y
number
required
Tile row in the Web Mercator grid.
​
zoom
number
required
Zoom level.
​
return
Promise<GeoPackageTile | null>
Resolves to a GeoPackageTile or null if the tile does not exist.
const tile = await retriever.getTile(2, 1, 3);
if (tile) {
  const bytes = tile.getData();
}

​
hasTile()

Returns true if a tile exists in the GeoPackage for the specified Web Mercator XYZ coordinates. 
hasTile(x: number, y: number, zoom: number): boolean
​
x
number
required
Tile column.
​
y
number
required
Tile row.
​
zoom
number
required
Zoom level.
​
return
boolean
true if tile data exists, false otherwise.
if (retriever.hasTile(2, 1, 3)) {
  const tile = await retriever.getTile(2, 1, 3);
}

​
WGS84 tiles

​
getTileWGS84()

Fetches a tile using WGS84 (EPSG:4326) tile addressing. 
async getTileWGS84(x: number, y: number, zoom: number): Promise<GeoPackageTile>

​
hasTileWGS84()

Returns true if a tile exists at the given WGS84 tile coordinates. 
hasTileWGS84(x: number, y: number, zoom: number): boolean

​
Custom bounding box

​
getTileWithBounds()

Fetches a tile whose geographic extent is defined by a custom bounding box and projection. 
async getTileWithBounds(
  boundingBox: BoundingBox,
  projection: Projection
): Promise<GeoPackageTile>
​
boundingBox
BoundingBox
required
The geographic extent of the desired tile output.
​
projection
Projection
required
The projection of the provided bounding box.

​
Scaling

​
getScaling()

Returns the TileScaling options currently applied to this retriever. 
getScaling(): TileScaling

​
setScaling()

Applies TileScaling options, enabling zoom-in or zoom-out tile scaling when an exact tile is not available. 
setScaling(scaling: TileScaling): void
​
scaling
TileScaling
required
A TileScaling configuration object from the NGA tile scaling extension.

​
getWebMercatorBoundingBox()

Returns the bounding box of the tile table’s TileMatrixSet reprojected to Web Mercator (EPSG:3857). 
getWebMercatorBoundingBox(): BoundingBox

​
GeoPackageTile

GeoPackageTile is the result object returned by getTile() and getTileWithBounds(). It wraps the raw image bytes along with the tile’s pixel dimensions.

​
getData()

Returns the raw encoded image bytes for this tile. 
getData(): Buffer | Uint8Array
​
return
Buffer | Uint8Array
The image bytes in the format specified when constructing GeoPackageTileRetriever (default: PNG).

​
getGeoPackageImage()

Decodes the raw bytes and returns a Promise<GeoPackageImage> that can be drawn to a canvas. 
async getGeoPackageImage(): Promise<GeoPackageImage>
​
return
Promise<GeoPackageImage>
A decoded image wrapper that can be passed to canvas drawing utilities.

​
getWidth()

Returns the tile width in pixels. 
getWidth(): number

​
getHeight()

Returns the tile height in pixels. 
getHeight(): number

​
getMimeType()

Returns the MIME type of the encoded image data (e.g. 'image/png'). 
getMimeType(): string

​
Full example

import {
  GeoPackageManager,
  GeoPackageTileRetriever,
} from '@ngageoint/geopackage';

const geoPackage = await GeoPackageManager.open('./tiles.gpkg');
const tileDao = geoPackage.getTileDao('world_imagery');
tileDao.adjustTileMatrixLengths();

const retriever = new GeoPackageTileRetriever(tileDao, 256, 256);

// Check and fetch a tile
if (retriever.hasTile(0, 0, 0)) {
  const tile = await retriever.getTile(0, 0, 0);
  if (tile) {
    console.log('Tile size:', tile.getWidth(), 'x', tile.getHeight());
    console.log('Bytes:', tile.getData()?.length);
    console.log('Format:', tile.getMimeType());

    const image = await tile.getGeoPackageImage();
    // pass `image` to a canvas drawing context
  }
}

geoPackage.close();

Build docs developers (and LLMs) love

Get started for freeTalk to us