@osmix/vt 0.0.1 → 0.0.6

package/src/encode.ts

@@ -1,8 +1,19 @@
-import type { Osmix } from "@osmix/core"
-import { wayIsArea } from "@osmix/json"
+/**
+ * Vector tile encoding for OSM data.
+ *
+ * The OsmixVtEncoder class converts Osmix datasets into Mapbox Vector Tiles,
+ * handling geometry projection, clipping, area detection, and proper
+ * MVT encoding for nodes, ways, and relations.
+ *
+ * @module
+ */
+
+import type { Osm } from "@osmix/core"
+import { bboxContainsOrIntersects } from "@osmix/shared/bbox-intersects"
 import { clipPolygon, clipPolyline } from "@osmix/shared/lineclip"
-import SphericalMercatorTile from "@osmix/shared/spherical-mercator"
+import { llToTilePx, tileToBbox } from "@osmix/shared/tile"
 import type { GeoBbox2D, LonLat, Tile, XY } from "@osmix/shared/types"
+import { wayIsArea } from "@osmix/shared/way-is-area"
 import type {
 	VtSimpleFeature,
 	VtSimpleFeatureGeometry,
@@ -10,7 +21,9 @@ import type {
 } from "./types"
 import writeVtPbf from "./write-vt-pbf"
 
+/** Default tile extent (coordinate resolution). */
 const DEFAULT_EXTENT = 4096
+/** Default buffer around tile in extent units. */
 const DEFAULT_BUFFER = 64
 
 const SF_TYPE: VtSimpleFeatureType = {
@@ -34,48 +47,79 @@ function dedupePoints(points: XY[]): XY[] {
 	return result
 }
 
+/**
+ * Returns a projection function that converts [lon, lat] to [x, y] pixel coordinates
+ * relative to the given tile. The extent determines the resolution of the tile
+ * (e.g. 4096 means coordinates range from 0 to 4096).
+ */
 export function projectToTile(
 	tile: Tile,
 	extent = DEFAULT_EXTENT,
 ): (ll: LonLat) => XY {
-	const sm = new SphericalMercatorTile({ size: extent, tile })
-	return (lonLat) => sm.llToTilePx(lonLat)
+	return (lonLat) => llToTilePx(lonLat, tile, extent)
 }
 
+/**
+ * Encode an Osm instance into a Mapbox Vector Tile PBF.
+ */
 export class OsmixVtEncoder {
-	private readonly nodeLayerName: string
-	private readonly wayLayerName: string
-	private readonly osmix: Osmix
+	readonly nodeLayerName: string
+	readonly wayLayerName: string
+	readonly relationLayerName: string
+	private readonly osm: Osm
 	private readonly extent: number
 	private readonly extentBbox: [number, number, number, number]
 
-	constructor(osmix: Osmix, extent = DEFAULT_EXTENT, buffer = DEFAULT_BUFFER) {
-		this.osmix = osmix
+	static layerNames(id: string) {
+		return {
+			nodeLayerName: `@osmix:${id}:nodes`,
+			wayLayerName: `@osmix:${id}:ways`,
+			relationLayerName: `@osmix:${id}:relations`,
+		}
+	}
+
+	constructor(osm: Osm, extent = DEFAULT_EXTENT, buffer = DEFAULT_BUFFER) {
+		this.osm = osm
 
 		const min = -buffer
 		const max = extent + buffer
 		this.extent = extent
 		this.extentBbox = [min, min, max, max]
 
-		const layerName = `@osmix:${osmix.id}`
+		const layerName = `@osmix:${osm.id}`
 		this.nodeLayerName = `${layerName}:nodes`
 		this.wayLayerName = `${layerName}:ways`
+		this.relationLayerName = `${layerName}:relations`
 	}
 
+	/**
+	 * Get a vector tile PBF for a specific tile coordinate.
+	 * Returns an empty buffer if the tile does not intersect with the OSM dataset.
+	 */
 	getTile(tile: Tile): ArrayBuffer {
-		const sm = new SphericalMercatorTile({ size: this.extent, tile })
-		// const proj = projectToTile(tile, this.extent)
-		const bbox = sm.bbox(tile[0], tile[1], tile[2]) as GeoBbox2D
-		return this.getTileForBbox(bbox, (ll) => sm.llToTilePx(ll))
+		const bbox = tileToBbox(tile)
+		const osmBbox = this.osm.bbox()
+		if (!bboxContainsOrIntersects(bbox, osmBbox)) {
+			return new ArrayBuffer(0)
+		}
+		return this.getTileForBbox(bbox, (ll) => llToTilePx(ll, tile, this.extent))
 	}
 
+	/**
+	 * Get a vector tile PBF for a specific geographic bounding box.
+	 * @param bbox The bounding box to include features from.
+	 * @param proj A function to project [lon, lat] to [x, y] within the tile extent.
+	 */
 	getTileForBbox(bbox: GeoBbox2D, proj: (ll: LonLat) => XY): ArrayBuffer {
-		const layer = writeVtPbf([
+		// Get way IDs that are part of relations (to exclude from individual rendering)
+		const relationWayIds = this.osm.relations.getWayMemberIds()
+
+		const layers = [
 			{
 				name: this.wayLayerName,
 				version: 2,
 				extent: this.extent,
-				features: this.wayFeatures(bbox, proj),
+				features: this.wayFeatures(bbox, proj, relationWayIds),
 			},
 			{
 				name: this.nodeLayerName,
@@ -83,26 +127,32 @@ export class OsmixVtEncoder {
 				extent: this.extent,
 				features: this.nodeFeatures(bbox, proj),
 			},
-		])
-		return layer
+			{
+				name: this.relationLayerName,
+				version: 2,
+				extent: this.extent,
+				features: this.relationFeatures(bbox, proj),
+			},
+		]
+		return writeVtPbf(layers)
 	}
 
 	*nodeFeatures(
 		bbox: GeoBbox2D,
 		proj: (ll: LonLat) => XY,
 	): Generator<VtSimpleFeature> {
-		const nodeIndexes = this.osmix.nodes.withinBbox(bbox)
+		const nodeIndexes = this.osm.nodes.findIndexesWithinBbox(bbox)
 		for (let i = 0; i < nodeIndexes.length; i++) {
 			const nodeIndex = nodeIndexes[i]
 			if (nodeIndex === undefined) continue
-			const tags = this.osmix.nodes.tags.getTags(nodeIndex)
+			const tags = this.osm.nodes.tags.getTags(nodeIndex)
 			if (!tags || Object.keys(tags).length === 0) continue
-			const id = this.osmix.nodes.ids.at(nodeIndex)
-			const ll = this.osmix.nodes.getNodeLonLat({ index: nodeIndex })
+			const id = this.osm.nodes.ids.at(nodeIndex)
+			const ll = this.osm.nodes.getNodeLonLat({ index: nodeIndex })
 			yield {
 				id,
 				type: SF_TYPE.POINT,
-				properties: { type: "node", ...tags },
+				properties: { ...tags, type: "node" },
 				geometry: [[proj(ll)]],
 			}
 		}
@@ -111,36 +161,48 @@ export class OsmixVtEncoder {
 	*wayFeatures(
 		bbox: GeoBbox2D,
 		proj: (ll: LonLat) => XY,
+		relationWayIds?: Set<number>,
 	): Generator<VtSimpleFeature> {
-		const wayIndexes = this.osmix.ways.intersects(bbox)
+		const wayIndexes = this.osm.ways.intersects(bbox)
 		for (let i = 0; i < wayIndexes.length; i++) {
 			const wayIndex = wayIndexes[i]
 			if (wayIndex === undefined) continue
-			const id = this.osmix.ways.ids.at(wayIndex)
-			const tags = this.osmix.ways.tags.getTags(wayIndex)
-			const count = this.osmix.ways.refCount.at(wayIndex)
-			const start = this.osmix.ways.refStart.at(wayIndex)
-			const points: XY[] = new Array(count)
-			for (let i = 0; i < count; i++) {
-				const ref = this.osmix.ways.refs.at(start + i)
-				const ll = this.osmix.nodes.getNodeLonLat({ id: ref })
-				points[i] = proj(ll)
-			}
-			const isArea = wayIsArea({ id, refs: new Array(count).fill(0), tags })
+			const id = this.osm.ways.ids.at(wayIndex)
+			// Skip ways that are part of relations (they will be rendered via relations)
+			if (id !== undefined && relationWayIds?.has(id)) continue
+			const tags = this.osm.ways.tags.getTags(wayIndex)
+			// Skip ways without tags (they are likely only for relations)
+			if (!tags || Object.keys(tags).length === 0) continue
+			const wayLine = this.osm.ways.getCoordinates(wayIndex)
+			const points: XY[] = wayLine.map((ll) => proj(ll))
+
+			const isArea = wayIsArea({
+				id,
+				refs: this.osm.ways.getRefIds(wayIndex),
+				tags,
+			})
 			const geometry: VtSimpleFeatureGeometry = []
 			if (isArea) {
-				// 1. clip polygon in tile coords
-				const clippedPoly = this.clipProjectedPolygon(points)
-				// clipProjectedPolygon currently returns XY[], not XY[][]
-				// i.e. assumes single ring. We'll treat it as one ring.
+				// 1. clip polygon in tile coords (returns array of rings)
+				const clippedRings = this.clipProjectedPolygon(points)
 
-				// 2. round/clamp, dedupe, close, orient
-				const processedRing = this.processClippedPolygonRing(clippedPoly)
+				// 2. process each ring (first is outer, rest would be holes if from relations)
+				for (let ringIndex = 0; ringIndex < clippedRings.length; ringIndex++) {
+					const clippedRing = clippedRings[ringIndex]
+					if (!clippedRing) continue
 
-				// TODO handle MultiPolygons with holes
+					// Normalize winding order using rewind before processing
+					// GeoJSON: outer counterclockwise, inner clockwise
+					// MVT: outer clockwise, inner counterclockwise
+					const isOuter = ringIndex === 0
+					const processedRing = this.processClippedPolygonRing(
+						clippedRing,
+						isOuter,
+					)
 
-				if (processedRing.length > 0) {
-					geometry.push(processedRing)
+					if (processedRing.length > 0) {
+						geometry.push(processedRing)
+					}
 				}
 			} else {
 				const clippedSegmentsRaw = this.clipProjectedPolyline(points)
@@ -156,7 +218,7 @@ export class OsmixVtEncoder {
 			yield {
 				id,
 				type: isArea ? SF_TYPE.POLYGON : SF_TYPE.LINE,
-				properties: { type: "way", ...tags },
+				properties: { ...tags, type: "way" },
 				geometry,
 			}
 		}
@@ -166,11 +228,14 @@ export class OsmixVtEncoder {
 		return clipPolyline(points, this.extentBbox)
 	}
 
-	clipProjectedPolygon(points: XY[]): XY[] {
-		return clipPolygon(points, this.extentBbox)
+	clipProjectedPolygon(points: XY[]): XY[][] {
+		// clipPolygon returns a single ring, but we return as array for consistency
+		// with multi-ring support (e.g., from relations)
+		const clipped = clipPolygon(points, this.extentBbox)
+		return [clipped]
 	}
 
-	processClippedPolygonRing(rawRing: XY[]): XY[] {
+	processClippedPolygonRing(rawRing: XY[], isOuter: boolean): XY[] {
 		// 1. round & clamp EVERY point
 		const snapped = rawRing.map((xy) => this.clampAndRoundPoint(xy))
 
@@ -178,12 +243,130 @@ export class OsmixVtEncoder {
 		const cleaned = cleanRing(snapped)
 		if (cleaned.length === 0) return []
 
-		// 3. enforce clockwise for outer ring
-		const oriented = ensureClockwise(cleaned)
+		// 3. enforce winding order per MVT spec:
+		//    - Outer rings: clockwise
+		//    - Inner rings (holes): counterclockwise
+		const oriented = isOuter
+			? ensureClockwise(cleaned)
+			: ensureCounterclockwise(cleaned)
 
 		return oriented
 	}
 
+	/**
+	 * Super relations and logical relations are not directly rendered; they would need recursive expansion.
+	 */
+	*relationFeatures(
+		bbox: GeoBbox2D,
+		proj: (ll: LonLat) => XY,
+	): Generator<VtSimpleFeature> {
+		const relationIndexes = this.osm.relations.intersects(bbox)
+
+		for (const relIndex of relationIndexes) {
+			const relation = this.osm.relations.getByIndex(relIndex)
+			const relationGeometry = this.osm.relations.getRelationGeometry(relIndex)
+			if (
+				!relation ||
+				(!relationGeometry.lineStrings &&
+					!relationGeometry.rings &&
+					!relationGeometry.points)
+			)
+				continue
+
+			const id = this.osm.relations.ids.at(relIndex)
+			const tags = this.osm.relations.tags.getTags(relIndex)
+
+			if (relationGeometry.rings) {
+				// Area relations (multipolygon, boundary)
+				const { rings } = relationGeometry
+				if (rings.length === 0) continue
+
+				// Process each polygon in the relation
+				for (const polygon of rings) {
+					const geometry: VtSimpleFeatureGeometry = []
+
+					// Process outer ring and inner rings (holes)
+					for (let ringIndex = 0; ringIndex < polygon.length; ringIndex++) {
+						const ring = polygon[ringIndex]
+						if (!ring || ring.length < 3) continue
+
+						// Project ring to tile coordinates
+						const projectedRing: XY[] = ring.map((ll: LonLat) => proj(ll))
+
+						// Clip polygon ring
+						const clipped = clipPolygon(projectedRing, this.extentBbox)
+						if (clipped.length < 3) continue
+
+						// Process ring (round/clamp, dedupe, close, orient)
+						const isOuter = ringIndex === 0
+						const processedRing = this.processClippedPolygonRing(
+							clipped,
+							isOuter,
+						)
+
+						if (processedRing.length > 0) {
+							geometry.push(processedRing)
+						}
+					}
+
+					if (geometry.length === 0) continue
+
+					yield {
+						id: id ?? 0,
+						type: SF_TYPE.POLYGON,
+						properties: { ...tags, type: "relation" },
+						geometry,
+					}
+				}
+			} else if (relationGeometry.lineStrings) {
+				// Line relations (route, multilinestring)
+				const { lineStrings } = relationGeometry
+				if (lineStrings.length === 0) continue
+
+				for (const lineString of lineStrings) {
+					const geometry: VtSimpleFeatureGeometry = []
+					const points: XY[] = lineString.map((ll) => proj(ll))
+					const clippedSegmentsRaw = this.clipProjectedPolyline(points)
+					for (const segment of clippedSegmentsRaw) {
+						const rounded = segment.map((xy) => this.clampAndRoundPoint(xy))
+						const deduped = dedupePoints(rounded)
+						if (deduped.length >= 2) {
+							geometry.push(deduped)
+						}
+					}
+					if (geometry.length === 0) continue
+
+					yield {
+						id: id ?? 0,
+						type: SF_TYPE.LINE,
+						properties: { ...tags, type: "relation" },
+						geometry,
+					}
+				}
+			} else if (relationGeometry.points) {
+				// Point relations (multipoint)
+				const { points } = relationGeometry
+				if (points.length === 0) continue
+
+				const geometry: VtSimpleFeatureGeometry = []
+				for (const point of points) {
+					const projected = proj(point)
+					const clamped = this.clampAndRoundPoint(projected)
+					geometry.push([clamped])
+				}
+
+				if (geometry.length === 0) continue
+
+				yield {
+					id: id ?? 0,
+					type: SF_TYPE.POINT,
+					properties: { ...tags, type: "relation" },
+					geometry,
+				}
+			}
+		}
+	}
+
 	clampAndRoundPoint(xy: XY): XY {
 		const clampedX = Math.round(
 			clamp(xy[0], this.extentBbox[0], this.extentBbox[2]),
@@ -195,6 +378,10 @@ export class OsmixVtEncoder {
 	}
 }
 
+/**
+ * Ensures the ring is closed (first and last points are identical).
+ * If not, appends the first point to the end.
+ */
 function closeRing(ring: XY[]): XY[] {
 	const first = ring[0]
 	const last = ring[ring.length - 1]
@@ -205,8 +392,10 @@ function closeRing(ring: XY[]): XY[] {
 	return ring
 }
 
-// Signed area via shoelace formula.
-// Positive area => CCW, Negative => CW.
+/**
+ * Signed area via shoelace formula.
+ * Positive area => CCW, Negative => CW.
+ */
 function ringArea(ring: XY[]): number {
 	let sum = 0
 	for (let i = 0; i < ring.length - 1; i++) {
@@ -221,15 +410,14 @@ function ensureClockwise(ring: XY[]): XY[] {
 	return ringArea(ring) < 0 ? ring : [...ring].reverse()
 }
 
-/**
- * TODO handle MultiPolygons with holes
- *
-function _ensureCounterClockwise(ring: XY[]): XY[] {
+function ensureCounterclockwise(ring: XY[]): XY[] {
 	return ringArea(ring) > 0 ? ring : [...ring].reverse()
 }
-*/
 
-// Remove consecutive duplicates *after* rounding
+/**
+ * Clean a polygon ring by removing consecutive duplicates, ensuring it's closed,
+ * and checking that it has at least 4 coordinates (3 unique points).
+ */
 function cleanRing(ring: XY[]): XY[] {
 	const deduped = dedupePoints(ring)
 	// After dedupe, we still must ensure closure, and a polygon

package/src/index.ts

@@ -1 +1,33 @@
-export { OsmixVtEncoder } from "./encode"
+/**
+ * @osmix/vt - Mapbox Vector Tile encoding for OSM data.
+ *
+ * Converts `@osmix/core` OSM datasets into Mapbox Vector Tiles (MVT) format.
+ * Generates PBF-encoded tiles with separate layers for nodes, ways, and relations.
+ *
+ * Key features:
+ * - **Per-entity layers**: Separate layers for nodes, ways, and relations.
+ * - **Geometry conversion**: Ways become lines or polygons based on area heuristics.
+ * - **Multipolygon support**: Renders multipolygon relations as proper polygons with holes.
+ * - **Clipping**: Geometry is clipped to tile bounds with configurable buffer.
+ * - **Winding order**: Automatically enforces MVT spec (CW outer, CCW inner rings).
+ *
+ * @example
+ * ```ts
+ * import { OsmixVtEncoder } from "@osmix/vt"
+ *
+ * const encoder = new OsmixVtEncoder(osm)
+ * const pbfBuffer = encoder.getTile([9372, 12535, 15])
+ *
+ * // Use with MapLibre or other vector tile renderers
+ * map.addSource("osmix", {
+ *   type: "vector",
+ *   tiles: [/* ... generate tile URLs ... *\/]
+ * })
+ * ```
+ *
+ * @module @osmix/vt
+ */
+
+export { OsmixVtEncoder, projectToTile } from "./encode"
+export * from "./types"
+export { default as writeVtPbf } from "./write-vt-pbf"

package/src/types.ts

@@ -1,20 +1,43 @@
-import type { OsmEntityType, OsmTags } from "@osmix/json"
-import type { XY } from "@osmix/shared/types"
+/**
+ * Type definitions for vector tile encoding.
+ *
+ * These types represent the intermediate format used when converting
+ * OSM entities to Mapbox Vector Tile features.
+ *
+ * @module
+ */
 
+import type { OsmTags, XY } from "@osmix/shared/types"
+
+/**
+ * Geometry for a vector tile feature.
+ * Array of rings/segments, where each ring/segment is an array of [x, y] coordinates.
+ */
 export type VtSimpleFeatureGeometry = XY[][]
 
+/**
+ * Properties attached to a vector tile feature.
+ * Includes OSM tags plus optional source metadata.
+ */
 export type VtSimpleFeatureProperties = {
 	sourceId?: string
-	type: OsmEntityType
 	tileKey?: string
 } & OsmTags
 
+/**
+ * MVT geometry type constants.
+ * Point = 1, Line = 2, Polygon = 3.
+ */
 export type VtSimpleFeatureType = {
 	POINT: 1
 	LINE: 2
 	POLYGON: 3
 }
 
+/**
+ * A simplified vector tile feature ready for encoding.
+ * Geometry coordinates are in tile extent units (typically 0-4096).
+ */
 export interface VtSimpleFeature {
 	id: number
 	type: VtSimpleFeatureType[keyof VtSimpleFeatureType]
@@ -22,6 +45,10 @@ export interface VtSimpleFeature {
 	geometry: VtSimpleFeatureGeometry
 }
 
+/**
+ * A layer to be written to the vector tile PBF.
+ * Features are provided via a generator to support lazy evaluation.
+ */
 export type VtPbfLayer = {
 	name: string
 	version: number

package/src/write-vt-pbf.ts

@@ -1,6 +1,20 @@
+/**
+ * Vector tile PBF writer.
+ *
+ * Encodes vector tile layers and features into the Mapbox Vector Tile
+ * binary format (PBF/protobuf). Handles key/value deduplication,
+ * geometry encoding with delta compression, and proper command sequences.
+ *
+ * @see https://github.com/mapbox/vector-tile-spec
+ *
+ * @module
+ */
+
+import { zigzag, zigzag32 } from "@osmix/shared/zigzag"
 import Pbf from "pbf"
 import type { VtPbfLayer, VtSimpleFeature } from "./types"
 
+/** Internal context for encoding a layer's features. */
 type VtLayerContext = {
 	feature: VtSimpleFeature
 	keys: string[]
@@ -10,7 +24,10 @@ type VtLayerContext = {
 }
 
 /**
- * Write Vector Tile Layers to a PBF buffer
+ * Write vector tile layers to a PBF buffer.
+ *
+ * @param layers - Array of layers to encode.
+ * @returns ArrayBuffer containing the encoded vector tile.
  */
 export default function writeVtPbf(layers: VtPbfLayer[]) {
 	const pbf = new Pbf()
@@ -53,7 +70,12 @@ function writeLayer(layer: VtPbfLayer, pbf: Pbf) {
 
 function writeFeature(ctx: VtLayerContext, pbf: Pbf) {
 	if (ctx.feature.id !== undefined) {
-		pbf.writeVarintField(1, ctx.feature.id)
+		const id = ctx.feature.id
+
+		// Use zigzag encoding for IDs to convert negative IDs to positive numbers
+		// that can be properly decoded. Uses arithmetic-based encoding to support
+		// the full safe integer range.
+		pbf.writeVarintField(1, zigzag(id))
 	}
 
 	pbf.writeMessage(2, writeProperties, ctx)
@@ -93,10 +115,6 @@ function command(cmd: number, length: number) {
 	return (length << 3) + (cmd & 0x7)
 }
 
-function zigzag(num: number) {
-	return (num << 1) ^ (num >> 31)
-}
-
 function writeGeometry(feature: VtSimpleFeature, pbf: Pbf) {
 	const type = feature.type
 	let x = 0
@@ -116,8 +134,9 @@ function writeGeometry(feature: VtSimpleFeature, pbf: Pbf) {
 			}
 			const dx = xy[0] - x
 			const dy = xy[1] - y
-			pbf.writeVarint(zigzag(dx))
-			pbf.writeVarint(zigzag(dy))
+			// Use bitwise zigzag for geometry deltas (small values, 32-bit is sufficient)
+			pbf.writeVarint(zigzag32(dx))
+			pbf.writeVarint(zigzag32(dy))
 			x += dx
 			y += dy
 		})