@osmix/shared 0.0.1 → 0.0.6

package/src/relation-kind.ts

@@ -0,0 +1,446 @@
+/**
+ * Relation kind detection and geometry building.
+ *
+ * Determines the semantic type of OSM relations (area, line, point, logic, super)
+ * based on their type tag and member structure. Also provides utilities for
+ * building geometries from relation members.
+ *
+ * @module
+ */
+
+import type {
+	LonLat,
+	OsmRelation,
+	OsmRelationMember,
+	OsmWay,
+	RelationKind,
+	RelationKindMetadata,
+} from "./types"
+
+/**
+ * Get the semantic kind of a relation based on its type tag.
+ * Based on [OSM relation documentation](https://wiki.openstreetmap.org/wiki/Relation):
+ * - Areas: multipolygon, boundary, site
+ * - Lines: route, waterway, multilinestring, canal
+ * - Points: multipoint
+ * - Logic: restriction, route_master, network, collection
+ * - [Super: relations that contain other relations](https://wiki.openstreetmap.org/wiki/Super-relation)
+ */
+export function getRelationKind(relation: OsmRelation): RelationKind {
+	const typeTag = relation.tags?.["type"]
+	if (!typeTag || typeof typeTag !== "string") {
+		// If no type tag, check if it has relation members (super-relation)
+		if (relation.members.some((m) => m.type === "relation")) {
+			return "super"
+		}
+		// Default to logic for untyped relations
+		return "logic"
+	}
+
+	const normalizedType = typeTag.toLowerCase()
+
+	// Area relations
+	if (
+		normalizedType === "multipolygon" ||
+		normalizedType === "boundary" ||
+		normalizedType === "site"
+	) {
+		return "area"
+	}
+
+	// Line relations
+	if (
+		normalizedType === "route" ||
+		normalizedType === "waterway" ||
+		normalizedType === "multilinestring" ||
+		normalizedType === "canal"
+	) {
+		return "line"
+	}
+
+	// Point relations
+	if (normalizedType === "multipoint") {
+		return "point"
+	}
+
+	// Check for super-relation (has relation members)
+	if (relation.members.some((m) => m.type === "relation")) {
+		return "super"
+	}
+
+	// Default to logic for other types (restriction, route_master, network, collection, etc.)
+	return "logic"
+}
+
+/**
+ * Get metadata about a relation kind.
+ */
+export function getRelationKindMetadata(
+	relation: OsmRelation,
+): RelationKindMetadata {
+	const kind = getRelationKind(relation)
+
+	switch (kind) {
+		case "area":
+			return {
+				kind: "area",
+				expectedRoles: ["outer", "inner"],
+				orderMatters: false,
+				description: "Area relation (multipolygon, boundary, site)",
+			}
+		case "line":
+			return {
+				kind: "line",
+				expectedRoles: undefined, // Routes can have various roles
+				orderMatters: true,
+				description: "Line relation (route, waterway, multilinestring)",
+			}
+		case "point":
+			return {
+				kind: "point",
+				expectedRoles: undefined,
+				orderMatters: false,
+				description: "Point relation (multipoint)",
+			}
+		case "super":
+			return {
+				kind: "super",
+				expectedRoles: undefined,
+				orderMatters: false,
+				description: "Super-relation (contains other relations)",
+			}
+		case "logic":
+			return {
+				kind: "logic",
+				expectedRoles: undefined,
+				orderMatters: false,
+				description:
+					"Logical relation (restriction, route_master, network, collection, etc.)",
+			}
+	}
+}
+
+/**
+ * Check if a relation is an area relation.
+ */
+export function isAreaRelation(relation: OsmRelation): boolean {
+	return getRelationKind(relation) === "area"
+}
+
+/**
+ * Check if a relation is a line relation.
+ */
+export function isLineRelation(relation: OsmRelation): boolean {
+	return getRelationKind(relation) === "line"
+}
+
+/**
+ * Check if a relation is a point relation.
+ */
+export function isPointRelation(relation: OsmRelation): boolean {
+	return getRelationKind(relation) === "point"
+}
+
+/**
+ * Check if a relation is a super-relation (contains other relations).
+ */
+export function isSuperRelation(relation: OsmRelation): boolean {
+	return getRelationKind(relation) === "super"
+}
+
+/**
+ * Check if a relation is a logical relation (non-geometric).
+ */
+export function isLogicRelation(relation: OsmRelation): boolean {
+	return getRelationKind(relation) === "logic"
+}
+
+/**
+ * Build MultiLineString geometry from a line relation by connecting way members.
+ * Orders way members using their refs and handles role-based reversal.
+ * Returns an array of LineString coordinates (each LineString is an array of LonLat).
+ */
+export function buildRelationLineStrings(
+	relation: OsmRelation,
+	getWay: (wayId: number) => OsmWay | null,
+	getNodeCoordinates: (nodeId: number) => LonLat | undefined,
+): LonLat[][] {
+	const lineStrings: LonLat[][] = []
+	const wayMembers = relation.members.filter((m) => m.type === "way")
+
+	if (wayMembers.length === 0) return lineStrings
+
+	// Group ways by role if roles are used
+	const roleGroups = new Map<string, OsmRelationMember[]>()
+	for (const member of wayMembers) {
+		const role = member.role?.toLowerCase() ?? ""
+		if (!roleGroups.has(role)) {
+			roleGroups.set(role, [])
+		}
+		roleGroups.get(role)!.push(member)
+	}
+
+	// If no roles or single role group, process all ways together
+	const groupsToProcess =
+		roleGroups.size === 1 || !relation.members.some((m) => m.role)
+			? [wayMembers]
+			: Array.from(roleGroups.values())
+
+	for (const group of groupsToProcess) {
+		// Try to connect ways into continuous linestrings
+		const connected = connectWaysToLineStrings(
+			group,
+			getWay,
+			getNodeCoordinates,
+		)
+		lineStrings.push(...connected)
+	}
+
+	return lineStrings
+}
+
+/**
+ * Connect ways that share endpoints to form continuous LineStrings.
+ * Returns an array of LineStrings (each is an array of LonLat coordinates).
+ */
+function connectWaysToLineStrings(
+	wayMembers: OsmRelationMember[],
+	getWay: (wayId: number) => OsmWay | null,
+	getNodeCoordinates: (nodeId: number) => LonLat | undefined,
+): LonLat[][] {
+	if (wayMembers.length === 0) return []
+
+	const lineStrings: LonLat[][] = []
+	const used = new Set<number>()
+	const wayMap = new Map<number, OsmWay>()
+
+	// Build map of way ID to way
+	for (const member of wayMembers) {
+		const way = getWay(member.ref)
+		if (way) {
+			wayMap.set(member.ref, way)
+		}
+	}
+
+	// Build linestrings by connecting ways
+	for (const member of wayMembers) {
+		if (used.has(member.ref)) continue
+		const startWay = wayMap.get(member.ref)
+		if (!startWay || startWay.refs.length < 2) continue
+
+		const coords: LonLat[] = []
+		const currentWay = startWay
+		used.add(member.ref)
+
+		// Get coordinates for the starting way
+		for (const nodeId of currentWay.refs) {
+			const coord = getNodeCoordinates(nodeId)
+			if (coord) coords.push(coord)
+		}
+
+		// Try to extend forward
+		while (true) {
+			let found = false
+			const lastCoord = coords[coords.length - 1]
+			if (!lastCoord) break
+
+			for (const nextMember of wayMembers) {
+				if (used.has(nextMember.ref)) continue
+				const nextWay = wayMap.get(nextMember.ref)
+				if (!nextWay || nextWay.refs.length < 2) continue
+
+				const nextStart = getNodeCoordinates(nextWay.refs[0]!)
+				const nextEnd = getNodeCoordinates(
+					nextWay.refs[nextWay.refs.length - 1]!,
+				)
+
+				if (!nextStart || !nextEnd) continue
+
+				// Check if next way connects to current end
+				if (lastCoord[0] === nextStart[0] && lastCoord[1] === nextStart[1]) {
+					// Connect normally
+					for (let i = 1; i < nextWay.refs.length; i++) {
+						const nodeId = nextWay.refs[i]
+						if (nodeId === undefined) continue
+						const coord = getNodeCoordinates(nodeId)
+						if (coord) coords.push(coord)
+					}
+					used.add(nextMember.ref)
+					found = true
+					break
+				}
+				if (lastCoord[0] === nextEnd[0] && lastCoord[1] === nextEnd[1]) {
+					// Need to reverse next way
+					for (let i = nextWay.refs.length - 2; i >= 0; i--) {
+						const nodeId = nextWay.refs[i]
+						if (nodeId === undefined) continue
+						const coord = getNodeCoordinates(nodeId)
+						if (coord) coords.push(coord)
+					}
+					used.add(nextMember.ref)
+					found = true
+					break
+				}
+			}
+
+			if (!found) break
+		}
+
+		// Try to extend backward
+		while (true) {
+			let found = false
+			const firstCoord = coords[0]
+			if (!firstCoord) break
+
+			for (const prevMember of wayMembers) {
+				if (used.has(prevMember.ref)) continue
+				const prevWay = wayMap.get(prevMember.ref)
+				if (!prevWay || prevWay.refs.length < 2) continue
+
+				const prevStart = getNodeCoordinates(prevWay.refs[0]!)
+				const prevEnd = getNodeCoordinates(
+					prevWay.refs[prevWay.refs.length - 1]!,
+				)
+
+				if (!prevStart || !prevEnd) continue
+
+				// Check if prev way connects to current start
+				if (firstCoord[0] === prevEnd[0] && firstCoord[1] === prevEnd[1]) {
+					// Connect normally (prepend)
+					const newCoords: LonLat[] = []
+					for (let i = 0; i < prevWay.refs.length - 1; i++) {
+						const nodeId = prevWay.refs[i]
+						if (nodeId === undefined) continue
+						const coord = getNodeCoordinates(nodeId)
+						if (coord) newCoords.push(coord)
+					}
+					coords.unshift(...newCoords)
+					used.add(prevMember.ref)
+					found = true
+					break
+				}
+				if (firstCoord[0] === prevStart[0] && firstCoord[1] === prevStart[1]) {
+					// Need to reverse prev way (prepend reversed)
+					const newCoords: LonLat[] = []
+					for (let i = prevWay.refs.length - 1; i > 0; i--) {
+						const nodeId = prevWay.refs[i]
+						if (nodeId === undefined) continue
+						const coord = getNodeCoordinates(nodeId)
+						if (coord) newCoords.push(coord)
+					}
+					coords.unshift(...newCoords)
+					used.add(prevMember.ref)
+					found = true
+					break
+				}
+			}
+
+			if (!found) break
+		}
+
+		if (coords.length >= 2) {
+			lineStrings.push(coords)
+		}
+	}
+
+	return lineStrings
+}
+
+/**
+ * Collect point coordinates from a point relation.
+ * Returns an array of LonLat coordinates from node members.
+ */
+export function collectRelationPoints(
+	relation: OsmRelation,
+	getNodeCoordinates: (nodeId: number) => LonLat | undefined,
+): LonLat[] {
+	const points: LonLat[] = []
+	for (const member of relation.members) {
+		if (member.type === "node") {
+			const coord = getNodeCoordinates(member.ref)
+			if (coord) {
+				points.push(coord)
+			}
+		}
+	}
+	return points
+}
+
+/**
+ * Resolve nested relation members, flattening the hierarchy with cycle detection.
+ * Returns all nodes, ways, and relations that are members (directly or indirectly).
+ * @param relation - The relation to resolve
+ * @param getRelation - Function to get a relation by ID
+ * @param maxDepth - Maximum recursion depth (default: 10)
+ * @param visited - Set of relation IDs already visited (for cycle detection)
+ */
+export function resolveRelationMembers(
+	relation: OsmRelation,
+	getRelation: (relationId: number) => OsmRelation | null,
+	maxDepth = 10,
+	visited = new Set<number>(),
+): {
+	nodes: number[]
+	ways: number[]
+	relations: number[]
+} {
+	const nodes = new Set<number>()
+	const ways = new Set<number>()
+	const relations = new Set<number>()
+
+	// Cycle detection or max depth reached
+	if (visited.has(relation.id) || maxDepth <= 0) {
+		return { nodes: [], ways: [], relations: [] }
+	}
+
+	visited.add(relation.id)
+
+	for (const member of relation.members) {
+		if (member.type === "node") {
+			if (!nodes.has(member.ref)) {
+				nodes.add(member.ref)
+			}
+		} else if (member.type === "way") {
+			if (!ways.has(member.ref)) {
+				ways.add(member.ref)
+			}
+		} else if (member.type === "relation") {
+			if (!relations.has(member.ref)) {
+				relations.add(member.ref)
+
+				// Recursively resolve nested relation
+				const nestedRelation = getRelation(member.ref)
+				if (nestedRelation) {
+					const nested = resolveRelationMembers(
+						nestedRelation,
+						getRelation,
+						maxDepth - 1,
+						visited,
+					)
+					// Merge nested results
+					for (const nodeId of nested.nodes) {
+						if (!nodes.has(nodeId)) {
+							nodes.add(nodeId)
+						}
+					}
+					for (const wayId of nested.ways) {
+						if (!ways.has(wayId)) {
+							ways.add(wayId)
+						}
+					}
+					for (const relId of nested.relations) {
+						if (!relations.has(relId)) {
+							relations.add(relId)
+						}
+					}
+				}
+			}
+		}
+	}
+
+	return {
+		nodes: Array.from(nodes),
+		ways: Array.from(ways),
+		relations: Array.from(relations),
+	}
+}

package/src/relation-multipolygon.ts

@@ -0,0 +1,225 @@
+/**
+ * Multipolygon relation building utilities.
+ *
+ * Implements the OSM multipolygon relation specification to construct
+ * polygon geometries from way members. Handles outer/inner roles,
+ * way connection, and ring closure.
+ *
+ * @see https://wiki.openstreetmap.org/wiki/Relation:multipolygon
+ *
+ * @module
+ */
+
+import type { LonLat, OsmRelation, OsmRelationMember, OsmWay } from "./types"
+
+/**
+ * Get way members from a relation, grouped by role (outer/inner).
+ */
+export function getWayMembersByRole(relation: OsmRelation): {
+	outer: OsmRelationMember[]
+	inner: OsmRelationMember[]
+} {
+	const outer: OsmRelationMember[] = []
+	const inner: OsmRelationMember[] = []
+
+	for (const member of relation.members) {
+		if (member.type !== "way") continue
+		const role = member.role?.toLowerCase() ?? ""
+		if (role === "outer") {
+			outer.push(member)
+		} else if (role === "inner") {
+			inner.push(member)
+		}
+	}
+
+	return { outer, inner }
+}
+
+/**
+ * Connect ways that share endpoints to form a continuous ring.
+ * Returns an array of rings (each ring is an array of way IDs in order).
+ *
+ * This function handles:
+ * - Ways that are reversed (end matches end, or start matches start).
+ * - Closed ways (single ways that form a ring).
+ * - Disconnected chains (multiple independent rings).
+ */
+export function connectWaysToRings(wayMembers: OsmWay[]): OsmWay[][] {
+	if (wayMembers.length === 0) return []
+
+	const rings: OsmWay[][] = []
+	const used = new Set<number>()
+	const wayMap = new Map<number, OsmWay>()
+
+	// Build map of way ID to member
+	for (const member of wayMembers) {
+		wayMap.set(member.id, member)
+	}
+
+	// Helper to reverse a way's refs
+	const reverseWay = (way: OsmWay): OsmWay => ({
+		...way,
+		refs: [...way.refs].reverse(),
+	})
+
+	// Build rings by connecting ways
+	for (const startWay of wayMembers) {
+		if (used.has(startWay.id)) continue
+		if (startWay.refs.length < 2) throw Error("Way has less than 2 refs")
+
+		const ring: OsmWay[] = [startWay]
+		used.add(startWay.id)
+
+		let currentStart = startWay.refs[0]!
+		let currentEnd = startWay.refs[startWay.refs.length - 1]!
+
+		// Try to extend the ring forward
+		while (true) {
+			let found = false
+			for (const nextWay of wayMembers) {
+				if (used.has(nextWay.id)) continue
+				if (nextWay.refs.length < 2) throw Error("Way has less than 2 refs")
+				const nextStart = nextWay.refs[0]!
+				const nextEnd = nextWay.refs[nextWay.refs.length - 1]!
+
+				// Check if next way connects to current end
+				if (currentEnd === nextStart) {
+					ring.push(nextWay)
+					used.add(nextWay.id)
+					currentEnd = nextEnd
+					found = true
+					break
+				}
+				if (currentEnd === nextEnd) {
+					// Need to reverse next way
+					ring.push(reverseWay(nextWay))
+					used.add(nextWay.id)
+					currentEnd = nextStart
+					found = true
+					break
+				}
+			}
+
+			if (!found) break
+		}
+
+		// Try to extend the ring backward
+		currentStart = startWay.refs[0]!
+		currentEnd = startWay.refs[startWay.refs.length - 1]!
+
+		while (true) {
+			let found = false
+			for (const nextWay of wayMembers) {
+				if (used.has(nextWay.id)) continue
+				if (nextWay.refs.length < 2) throw Error("Way has less than 2 refs")
+
+				const nextStart = nextWay.refs[0]!
+				const nextEnd = nextWay.refs[nextWay.refs.length - 1]!
+
+				// Check if next way connects to current start
+				if (currentStart === nextEnd) {
+					ring.unshift(nextWay)
+					used.add(nextWay.id)
+					currentStart = nextStart
+					found = true
+					break
+				}
+				if (currentStart === nextStart) {
+					// Need to reverse next way
+					ring.unshift(reverseWay(nextWay))
+					used.add(nextWay.id)
+					currentStart = nextEnd
+					found = true
+					break
+				}
+			}
+
+			if (!found) break
+		}
+
+		// Only add ring if it's closed (first and last node are the same)
+		if (ring.length > 0) {
+			const firstWay = ring[0]
+			const lastWay = ring[ring.length - 1]
+			if (firstWay?.refs[0] === lastWay?.refs[lastWay.refs.length - 1]) {
+				rings.push(ring)
+			}
+		}
+	}
+
+	return rings
+}
+
+/**
+ * Build polygon rings from way members of a relation.
+ * Returns an array where each element is an array of coordinate rings (outer + inner).
+ *
+ * Based on OSM multipolygon relation specification:
+ * https://wiki.openstreetmap.org/wiki/Relation:multipolygon
+ *
+ * This implementation connects way members into closed rings, and then groups them
+ * into polygons. Currently, it associates all inner rings with every outer ring
+ * found in the relation, which is a simplification. A robust implementation would
+ * use point-in-polygon checks to strictly nest holes inside their parent outer ring.
+ */
+export function buildRelationRings(
+	relation: OsmRelation,
+	getWay: (wayId: number) => OsmWay | null,
+	getNodeCoordinates: (nodeId: number) => LonLat | undefined,
+): LonLat[][][] {
+	const { outer, inner } = getWayMembersByRole(relation)
+
+	// Connect outer ways into rings
+	const outerRings = connectWaysToRings(
+		outer.map((m) => getWay(m.ref)).filter((w) => w !== null),
+	)
+	// Connect inner ways into rings
+	const innerRings = connectWaysToRings(
+		inner.map((m) => getWay(m.ref)).filter((w) => w !== null),
+	)
+
+	const wayRingToCoords = (ring: OsmWay[]): LonLat[] => {
+		const coords: LonLat[] = []
+		for (const way of ring) {
+			for (const nodeId of way.refs) {
+				const coord = getNodeCoordinates(nodeId)
+				if (coord) coords.push(coord)
+			}
+		}
+
+		// Ensure ring is closed
+		if (coords.length > 0) {
+			const first = coords[0]
+			const last = coords[coords.length - 1]
+			if (first && last && (first[0] !== last[0] || first[1] !== last[1])) {
+				coords.push([first[0], first[1]])
+			}
+		}
+		return coords
+	}
+
+	// Convert way rings to coordinate rings
+	const coordinateRings: LonLat[][][] = []
+
+	for (const outerRing of outerRings) {
+		const outerCoordinates: LonLat[] = wayRingToCoords(outerRing)
+
+		if (outerCoordinates.length >= 3) {
+			// Find inner rings that belong to this outer ring
+			const innerCoordinates: LonLat[][] = []
+			for (const innerRing of innerRings) {
+				const innerCoords: LonLat[] = wayRingToCoords(innerRing)
+
+				if (innerCoords.length >= 3) {
+					// TODO: do proper point-in-polygon test with https://github.com/rowanwins/point-in-polygon-hao
+					innerCoordinates.push(innerCoords)
+				}
+			}
+
+			// Create polygon: [outer ring, ...inner rings]
+			coordinateRings.push([outerCoordinates, ...innerCoordinates])
+		}
+	}
+
+	return coordinateRings
+}

package/src/stream-to-bytes.ts

@@ -1,5 +1,22 @@
+/**
+ * Stream to byte array conversion.
+ *
+ * Consumes a ReadableStream and concatenates all chunks into a single Uint8Array.
+ *
+ * @module
+ */
+
 import { concatBytes } from "./concat-bytes"
 
+/**
+ * Consume a ReadableStream and return all data as a single Uint8Array.
+ *
+ * Reads all chunks from the stream and concatenates them.
+ * The stream will be fully consumed after this function returns.
+ *
+ * @param stream - The stream to consume.
+ * @returns A Promise resolving to the concatenated bytes.
+ */
 export async function streamToBytes(
 	stream: ReadableStream<Uint8Array<ArrayBuffer>>,
 ): Promise<Uint8Array<ArrayBuffer>> {