Skip to main content
FeatureTiles converts vector features stored in a GeoPackage into tile images on demand. It supports Web Mercator (XYZ) and WGS84 tile coordinate schemes. If the feature table has an RTree or GeoPackage spatial index, queries are automatically scoped to the tile’s bounding box for efficiency. 
import { FeatureTiles } from '@ngageoint/geopackage';

const featureDao = geoPackage.getFeatureDao('roads');
const featureTiles = new FeatureTiles(geoPackage, featureDao);

​
Constructor

new FeatureTiles(
  geoPackage: GeoPackage,
  featureDao: FeatureDao,
  width?: number,
  height?: number,
  scale?: number
)
​
geoPackage
GeoPackage
required
An open GeoPackage instance used to load style extensions and feature indexes.
​
featureDao
FeatureDao
required
The FeatureDao for the feature table to render.
​
width
number
Output tile width in pixels. Defaults to TileUtils.TILE_PIXELS_DEFAULT (256).
​
height
number
Output tile height in pixels. Defaults to TileUtils.TILE_PIXELS_DEFAULT (256).
​
scale
number
Pixel scale factor for high-DPI rendering. Defaults to 1.0.

​
Drawing tiles

​
drawTile()

Renders the Web Mercator (XYZ) tile at the given coordinates and returns the result. Uses an index query when available, otherwise falls back to a full-table scan. 
async drawTile(
  x: number,
  y: number,
  z: number,
  canvas?: HTMLCanvasElement | OffscreenCanvas
): Promise<GeoPackageTile>
​
x
number
required
Tile column (x) in the Web Mercator tile grid.
​
y
number
required
Tile row (y) in the Web Mercator tile grid.
​
z
number
required
Zoom level.
​
canvas
HTMLCanvasElement | OffscreenCanvas
Optional canvas to draw into directly. When omitted, a new off-screen canvas is created.
​
return
Promise<GeoPackageTile>
Resolves to a GeoPackageTile containing the encoded image, or null if no features exist in that tile.
const tile = await featureTiles.drawTile(2, 3, 5);
if (tile) {
  const bytes = tile.getData(); // PNG bytes
}

​
drawTileWGS84()

Renders a WGS84 (EPSG:4326) tile at the given coordinates. Behaves identically to drawTile() but uses WGS84 bounding boxes. 
async drawTileWGS84(
  x: number,
  y: number,
  z: number,
  canvas?: HTMLCanvasElement | OffscreenCanvas
): Promise<GeoPackageTile>

​
drawTileQueryAll()

Draws a Web Mercator tile by querying all features in the table regardless of indexing. This can be slow for large tables. 
async drawTileQueryAll(
  x: number,
  y: number,
  zoom: number,
  canvas?: HTMLCanvasElement | OffscreenCanvas
): Promise<GeoPackageTile>

​
close()

Releases the internal FeatureIndexManager and icon caches. Call when done rendering. 
close(): void

​
Styling properties

Styling is controlled through dedicated Paint objects and numeric properties. Call calculateDrawOverlap() after changing stroke widths or the point icon to update the tile overlap padding.

​
pointRadius

Radius in pixels of the circle drawn for each point feature. 
protected pointRadius: number // default: 2.0

featureTiles.pointRadius = 4;

​
pointPaint

A Paint object controlling the fill color and opacity of rendered points. Default color is #000000FF (opaque black). 
protected pointPaint: Paint

featureTiles.pointPaint.setColor('#FF0000FF'); // red

​
pointIcon

An optional FeatureTilePointIcon that replaces the default circle when set. Set to null to revert to a circle. 
protected pointIcon: FeatureTilePointIcon

​
linePaint

A Paint object controlling the stroke color of line features. Default color is #000000FF. 
protected linePaint: Paint

​
lineStrokeWidth

Stroke width in pixels for line features. 
protected lineStrokeWidth: number // default: 2.0

featureTiles.lineStrokeWidth = 3;

​
polygonPaint

A Paint object controlling the stroke color of polygon outlines. Default color is #000000FF. 
protected polygonPaint: Paint

​
polygonStrokeWidth

Stroke width in pixels for polygon outlines. 
protected polygonStrokeWidth: number // default: 2.0

​
fillPolygon

When true (the default), polygons are filled using polygonFillPaint. 
protected fillPolygon: boolean // default: true

​
polygonFillPaint

A Paint object controlling the fill color of polygons. Default is a very transparent black (#00000011). 
protected polygonFillPaint: Paint

featureTiles.polygonFillPaint.setColor('#0000FF33'); // semi-transparent blue

​
Feature limits

​
setMaxFeaturesPerTile()

Sets the maximum number of features that may be drawn in a single tile. When a tile’s feature count exceeds this value, the tile is not drawn (returns null) unless maxFeaturesTileDraw is also set. 
setMaxFeaturesPerTile(max: number): void
​
max
number
required
Maximum feature count per tile. Set to a large number to effectively disable the limit.

​
setMaxFeaturesTileDraw()

Sets a CustomFeaturesTile implementation that is called to render a placeholder tile when the feature count exceeds maxFeaturesPerTile. 
setMaxFeaturesTileDraw(maxFeaturesTileDraw: CustomFeaturesTile): void
​
maxFeaturesTileDraw
CustomFeaturesTile
required
A custom renderer that accepts tile dimensions and a feature count.

​
Overlap and scale

​
calculateDrawOverlap()

Recalculates the pixel overlap added around each tile to prevent geometry clipping at tile edges. Call this after changing pointRadius, lineStrokeWidth, polygonStrokeWidth, or pointIcon. 
calculateDrawOverlap(): void

​
setScale()

Sets the pixel scale factor and updates internal paint stroke widths accordingly. 
setScale(scale: number): void

​
Full example

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

const geoPackage = await GeoPackageManager.open('./data.gpkg');
const featureDao = geoPackage.getFeatureDao('roads');

const featureTiles = new FeatureTiles(geoPackage, featureDao, 512, 512);

// Styling
featureTiles.lineStrokeWidth = 2;
featureTiles.linePaint.setColor('#E03030FF');
featureTiles.calculateDrawOverlap();

// Limit features per tile
featureTiles.setMaxFeaturesPerTile(1000);

// Render a tile
const tile = await featureTiles.drawTile(10, 6, 5);
if (tile) {
  const bytes = tile.getData(); // PNG encoded bytes
}

featureTiles.close();
geoPackage.close();

Build docs developers (and LLMs) love

Get started for freeTalk to us