@mailwoman/cartographer 1.0.0

package/README.md

@@ -0,0 +1,3 @@
+# Nexus Cartographer
+
+This package contains a collection of modules for working rendering maps and spatial data.

package/base/buildings.ts

@@ -0,0 +1,124 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import { type FillExtrusionLayerSpecification, type LayerSpecification } from "@maplibre/maplibre-gl-style-spec"
+import { interpolateTurbo } from "d3-scale-chromatic"
+import { LayerID } from "../styles/layers.js"
+import { MailwomanBaseTileSetID } from "./theme.js"
+
+const BuildingLayerID = LayerID.bind(null, "buildings")
+
+/**
+ * Layer definitions for building data.
+ */
+export const BuildingLayers: LayerSpecification[] = [
+	createBuildingFillStyleLayer({
+		id: BuildingLayerID("buildings-extruded"),
+
+		paint: {
+			"fill-extrusion-color": [
+				// ---
+				"interpolate",
+				// ["exponential", 0.25],
+				["linear"],
+				[
+					// --
+					"coalesce",
+					["get", "height"],
+					["get", "minheight"],
+					10,
+				],
+				...Array.from({ length: 10 }, (_, i) => {
+					const sizeScalingFactor = 250 - 250 / i
+
+					return [sizeScalingFactor, interpolateTurbo(sizeScalingFactor / 250)] as [number, string]
+				}).flat(),
+			],
+			"fill-extrusion-translate": [0.1, 0.1],
+		},
+	}),
+
+	{
+		id: "basemap-buildings-outline",
+		type: "line",
+		source: MailwomanBaseTileSetID,
+		"source-layer": "buildings",
+		minzoom: 11,
+		filter: ["==", ["%", ["to-number", ["id"]], 2], 0],
+		paint: {
+			"line-width": 1,
+			"line-color": "hsl(240deg 100% 80%)",
+			"line-opacity": ["interpolate", ["linear"], ["zoom"], 11, 0, 20, 1],
+			"line-dasharray": [2, 3],
+		},
+	},
+
+	{
+		id: "basemap-buildings-kind",
+		type: "symbol",
+		source: MailwomanBaseTileSetID,
+		"source-layer": "buildings",
+		minzoom: 11,
+		layout: {
+			visibility: "none",
+			"text-field": ["to-string", ["id"]],
+			"text-offset": [0, 0],
+			"text-anchor": "center",
+			"text-font": ["Fira Sans Regular"],
+		},
+
+		paint: {
+			"text-color": "black",
+			"text-halo-color": "red",
+			"text-halo-width": 1,
+		},
+	},
+]
+
+type BuildingFillStyleSpec = Pick<FillExtrusionLayerSpecification, "id"> &
+	Partial<FillExtrusionLayerSpecification> & {
+		heightOffset?: number
+	}
+
+function createBuildingFillStyleLayer(fillStyleSpec: BuildingFillStyleSpec): LayerSpecification {
+	const baseStyle: LayerSpecification = {
+		...fillStyleSpec,
+		type: "fill-extrusion",
+		source: MailwomanBaseTileSetID,
+		"source-layer": "buildings",
+		minzoom: 12,
+		paint: {
+			...fillStyleSpec.paint,
+			"fill-extrusion-vertical-gradient": true,
+
+			"fill-extrusion-height": [
+				"+",
+				[
+					// --
+					"coalesce",
+					["get", "height"],
+					["get", "minheight"],
+					10,
+				],
+				fillStyleSpec.heightOffset || 0,
+			],
+			"fill-extrusion-translate-anchor": "map",
+			// "fill-extrusion-opacity": 0.7,
+			"fill-extrusion-opacity": [
+				// We fade out the outline at higher zoom levels
+				"interpolate",
+				["linear"],
+				["zoom"],
+				11,
+				0.6,
+				16,
+				0.95,
+			],
+		},
+	}
+
+	return baseStyle
+}

package/base/composition.ts

@@ -0,0 +1,119 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import type { SourceSpecification } from "@maplibre/maplibre-gl-style-spec"
+import type { LightSpecification, SkySpecification, StyleSpecification, TerrainSpecification } from "maplibre-gl"
+import {
+	LayerSpecificationList,
+	type LayerSpecificationListInput,
+	type LayerSpecificationListItem,
+} from "../styles/layers.js"
+import { type TileSetSourceRecord } from "../styles/sources.js"
+import { BaseLayers } from "./layers.js"
+import { createTerrainDEMSource, HillshadeTileSetID, TerrainTileSetID } from "./terrain.js"
+
+//#endregion
+
+//#region Spec Creators
+
+export function createLightSpec(spec?: Partial<LightSpecification>): LightSpecification {
+	return {
+		color: "white",
+		intensity: 0.85,
+		anchor: "viewport",
+		position: [
+			10, // Radial
+			20, // Azimuthal
+			-5, // Polar
+		],
+		...spec,
+	}
+}
+
+export function createSkySpec(spec?: Partial<SkySpecification>): SkySpecification {
+	return {
+		"sky-color": "#000535",
+		"horizon-color": "hsl(54deg 100% 16%)",
+		"fog-color": "hsl(54deg 100% 5%)",
+		"sky-horizon-blend": 0.75,
+		"horizon-fog-blend": 0.75,
+		"fog-ground-blend": 0.1,
+		...spec,
+	}
+}
+
+//#endregion
+
+//#region Style Composition
+
+export interface StyleSpecificationComposition {
+	sources: Record<string, SourceSpecification>
+	layers?: LayerSpecificationListInput[]
+	light?: Partial<LightSpecification>
+	sky?: Partial<SkySpecification>
+	terrain?: Partial<TerrainSpecification>
+}
+
+/**
+ * A stateful class for composing a style specification.
+ */
+export class StyleSpecificationComposer {
+	layersList: LayerSpecificationList
+	light: LightSpecification
+	sky: SkySpecification
+	terrain: TerrainSpecification
+	sources: TileSetSourceRecord
+
+	constructor(spec: StyleSpecificationComposition) {
+		this.light = createLightSpec(spec.light)
+		this.sky = createSkySpec(spec.sky)
+
+		this.terrain = {
+			source: TerrainTileSetID,
+			...spec.terrain,
+		}
+
+		this.sources = {
+			...spec.sources,
+			[TerrainTileSetID]: createTerrainDEMSource(),
+			[HillshadeTileSetID]: createTerrainDEMSource(),
+		}
+
+		this.layersList = new LayerSpecificationList(BaseLayers)
+
+		for (const layer of spec.layers || []) {
+			this.layersList.insert(layer)
+		}
+	}
+
+	public get layers(): LayerSpecificationListItem[] {
+		return Array.from(this.layersList)
+	}
+
+	toJSON(): StyleSpecification {
+		const styleSpec: StyleSpecification = {
+			version: 8,
+			// Sprite must match the basemap schema version — v4 sprites carry the icons referenced
+			// by the v4 theme spec. Currently upstream URLs; we mirror these to nexus-assets/{fonts,
+			// sprites/v4}/ for self-hosting, but no public route fronts that bucket yet.
+			glyphs: "https://public.sister.software/protomaps/fonts/{fontstack}/{range}.pbf",
+			sprite: "https://public.sister.software/protomaps/sprites/v4/light",
+			light: createLightSpec(this.light),
+			sky: createSkySpec(this.sky),
+			terrain: this.terrain,
+			sources: this.sources,
+			layers: this.layers,
+		}
+
+		return styleSpec
+	}
+
+	toJS(): StyleSpecification {
+		return this.toJSON()
+	}
+}
+
+//#endregion

package/base/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+export * from "./buildings.js"
+export * from "./composition.js"
+export * from "./layers.js"
+export * from "./theme.js"

package/base/layers.ts

@@ -0,0 +1,52 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import { layers } from "@protomaps/basemaps"
+import { type LayerSpecification } from "maplibre-gl"
+import { BuildingLayers } from "../base/buildings.js"
+import { MailwomanBaseFlavor, MailwomanBaseTileSetID } from "../base/theme.js"
+import { LayerID } from "../styles/layers.js"
+import { HillshadeTileSetID } from "./terrain.js"
+
+export const HillsLayerID = LayerID(HillshadeTileSetID, "hills")
+
+/**
+ * Splits `layers()` into non-label + label groups so building footprints, water outlines, and
+ * hillshade sit between base geometry and labels. `@protomaps/basemaps@5.x` doesn't expose a
+ * `noLabels` helper — `labelsOnly: true` gives only the label layers; subtracting that set from the
+ * full list yields the non-label group.
+ */
+const allBaseLayers = layers(MailwomanBaseTileSetID, MailwomanBaseFlavor, { lang: "en" })
+const labelLayers = layers(MailwomanBaseTileSetID, MailwomanBaseFlavor, { lang: "en", labelsOnly: true })
+const labelLayerIDs = new Set(labelLayers.map((layer) => layer.id))
+const nonLabelLayers = allBaseLayers.filter((layer) => !labelLayerIDs.has(layer.id))
+
+export const BaseLayers: LayerSpecification[] = [
+	...nonLabelLayers,
+	{
+		id: LayerID(MailwomanBaseTileSetID, "water-outline"),
+		type: "line",
+		source: MailwomanBaseTileSetID,
+		"source-layer": "water",
+		filter: ["any", ["in", "water", "river", "lake", "other"]],
+		paint: {
+			"line-color": "hsl(194deg 100% 30% / 0.5)",
+			"line-width": 1,
+		},
+	},
+	{
+		id: HillsLayerID,
+		type: "hillshade",
+		source: HillshadeTileSetID,
+		paint: {
+			"hillshade-exaggeration": 0.25,
+			"hillshade-accent-color": "hsl(240deg 100% 95%)",
+			"hillshade-shadow-color": "hsl(240deg 100% 5%)",
+		},
+	},
+	...BuildingLayers,
+	...labelLayers,
+]

package/base/terrain.ts

@@ -0,0 +1,33 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import { type RasterDEMSourceSpecification } from "@maplibre/maplibre-gl-style-spec"
+import { TileSetSourceID } from "../styles/sources.js"
+
+/**
+ * Creates a raster DEM source specification for terrain data.
+ */
+export function createTerrainDEMSource(): RasterDEMSourceSpecification {
+	const terrainSource: RasterDEMSourceSpecification = {
+		type: "raster-dem",
+		encoding: "terrarium",
+		tiles: ["https://elevation-tiles-prod.s3.amazonaws.com/terrarium/{z}/{x}/{y}.png"],
+		tileSize: 256,
+		maxzoom: 15,
+	}
+
+	return terrainSource
+}
+
+/**
+ * Identifier for the Nexus terrain tileset.
+ */
+export const TerrainTileSetID = TileSetSourceID("terrain")
+
+/**
+ * Identifier for the Nexus terrain tileset.
+ */
+export const HillshadeTileSetID = TileSetSourceID("hillshade")

package/base/theme.ts

@@ -0,0 +1,118 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import { type Flavor } from "@protomaps/basemaps"
+import { TileSetSourceID } from "../styles/sources.js"
+
+/**
+ * Identifier for the Mailwoman base tileset. Matches the R2 object basename
+ * (`nexus-assets/tiles/basemap-v4.pmtiles`) — `tiles.sister.software/basemap-v4.json` returns its
+ * tilejson, `tiles.sister.software/basemap-v4/{z}/{x}/{y}.mvt` returns vector tiles.
+ */
+export const MailwomanBaseTileSetID = TileSetSourceID("basemap-v4")
+
+/**
+ * The Mailwoman theme for Protomaps via MapLibre. Keys follow `@protomaps/basemaps@5.x` which
+ * targets the v4 tile schema (`["==","kind","..."]` filters), matching the basemap-v4 PMTiles on
+ * R2.
+ */
+export const MailwomanBaseFlavor: Flavor = {
+	//#region Base
+	background: "hsl(0deg 10% 5%)",
+	earth: "hsl(0deg 10% 5%)",
+
+	park_a: "hsl(120deg 45.75% 1%)",
+	park_b: "hsl(120deg 65.75% 10%)",
+
+	hospital: "#252424",
+	industrial: "#222222",
+	school: "#262323",
+	wood_a: "#202121",
+	wood_b: "#202121",
+	pedestrian: "#1e1e1e",
+	scrub_a: "#222323",
+	scrub_b: "#222323",
+	glacier: "#1c1c1c",
+	sand: "#212123",
+	beach: "hsl(44.24deg 100% 20% / 0.1)",
+	aerodrome: "#1e1e1e",
+	runway: "#333333",
+
+	water: "hsl(194deg 100% 10%)",
+
+	pier: "#222222",
+	zoo: "#222323",
+	military: "#242323",
+
+	//#endregion
+	//#region Tunnel
+	tunnel_other_casing: "#141414",
+	tunnel_minor_casing: "#141414",
+	tunnel_link_casing: "#141414",
+	tunnel_major_casing: "#141414",
+	tunnel_highway_casing: "#141414",
+	tunnel_other: "#292929",
+	tunnel_minor: "#292929",
+	tunnel_link: "#292929",
+	tunnel_major: "#292929",
+	tunnel_highway: "#292929",
+
+	//#endregion
+	buildings: "#111111",
+
+	//#region Casing
+	minor_service_casing: "#1f1f1f",
+	minor_casing: "#1f1f1f",
+	link_casing: "#1f1f1f",
+	major_casing_late: "#1f1f1f",
+	highway_casing_late: "#1f1f1f",
+	other: "#333333",
+	minor_service: "#333333",
+	minor_a: "#3d3d3d",
+	minor_b: "#333333",
+	link: "#3d3d3d",
+	major_casing_early: "#1f1f1f",
+	major: "#3d3d3d",
+	highway_casing_early: "#1f1f1f",
+	highway: "hsl(36deg 10% 50%)",
+
+	//#endregion
+	railway: "#000000",
+	boundaries: "hsl(240deg 100% 90%)",
+
+	//#region Bridges
+	bridges_other_casing: "#2b2b2b",
+	bridges_minor_casing: "#1f1f1f",
+	bridges_link_casing: "#1f1f1f",
+	bridges_major_casing: "#1f1f1f",
+	bridges_highway_casing: "#1f1f1f",
+	bridges_other: "#333333",
+	bridges_minor: "#333333",
+	bridges_link: "#3d3d3d",
+	bridges_major: "#3d3d3d",
+	bridges_highway: "#474747",
+
+	//#endregion
+	//#region Roads
+	roads_label_minor: "hsl(240deg 100% 90%)",
+	roads_label_minor_halo: "#1f1f1f",
+	roads_label_major: "hsl(240deg 100% 90%)",
+	roads_label_major_halo: "#1f1f1f",
+
+	//#endregion
+	ocean_label: "#717784",
+	subplace_label: "hsl(50deg 50% 70%)",
+	subplace_label_halo: "hsl(40deg 100% 10%)",
+
+	city_label: "hsl(50deg 100% 90%)",
+	city_label_halo: "hsl(240deg 100% 10%)",
+
+	state_label: "hsl(240deg 100% 90%)",
+	state_label_halo: "#1f1f1f",
+	country_label: "hsl(240deg 50% 80% / 0.5)",
+	address_label: "hsl(240deg 100% 90%)",
+	address_label_halo: "hsl(240deg 100% 10%)",
+}