@osm-editor-kit/street-imagery 0.1.0-alpha.0

package/dist/map/viewCone.d.ts

@@ -0,0 +1,4 @@
+import type { Feature, Polygon } from 'geojson';
+/** View cone radius in meters; ~50 m at z14, scales with zoom like click search radius. */
+export declare const coneRadiusMeters: (zoom: number) => number;
+export declare const viewConeGeoJson: (lngLat: [number, number], bearingDeg: number, fovDeg: number, radiusMeters: number) => Feature<Polygon>;

package/dist/map/viewfields.d.ts

@@ -0,0 +1,24 @@
+import type { Feature, FeatureCollection, Polygon } from 'geojson';
+import type { NormalizedPhoto } from '../providers/model';
+/** Narrow heading wedge for flat (directional) photos — iD-style viewfield. */
+export declare const FLAT_VIEWFIELD_FOV_DEG = 55;
+/** Full disk for 360° / equirectangular photos. */
+export declare const PANO_VIEWFIELD_FOV_DEG = 360;
+/** Lightweight triangle wedge (apex + left/right rays) for dense coverage layers. */
+export declare const flatViewfieldTriangle: (lngLat: [number, number], bearingDeg: number, fovDeg: number, radiusMeters: number) => Feature<Polygon>;
+export type ViewfieldPhotoProps = {
+    providerId: string;
+    photoId: string;
+    sequenceId: string | null;
+    capturedAt: number | null;
+    isPano: boolean | null;
+    heading: number | null;
+};
+/**
+ * Build viewfield polygons for every photo that can show direction:
+ * - panorama → full 360° disk
+ * - flat with heading → narrow triangle wedge
+ * Photos without heading that are not panos are skipped.
+ */
+export declare const photosToViewfieldsFeatureCollection: (photos: NormalizedPhoto[], zoom: number) => FeatureCollection<Polygon, ViewfieldPhotoProps>;
+export declare const emptyPolygonCollection: () => FeatureCollection<Polygon>;

package/dist/providers/adapters/kartaview.d.ts

@@ -0,0 +1,18 @@
+import type { NormalizedPhoto, ProviderAdapter } from '../model';
+export type KartaviewItem = {
+    id?: string | number;
+    sequence_id?: string | number;
+    sequence_index?: string | number;
+    name?: string;
+    lth_name?: string;
+    heading?: string | number;
+    shot_date?: string;
+    date_added?: string;
+    lat?: string | number;
+    lng?: string | number;
+};
+export declare const kartaviewImageUrl: (imagePath: string) => string;
+export declare const maxPageAtZoom: (z: number) => number;
+export declare const parseKartaviewDate: (value: unknown) => number | null;
+export declare const normalizeKartaviewItem: (item: KartaviewItem) => Omit<NormalizedPhoto, 'providerId'> | null;
+export declare const kartaviewAdapter: ProviderAdapter;

package/dist/providers/adapters/lookaround.d.ts

@@ -0,0 +1,17 @@
+import type { ProviderAdapter } from '../model';
+/**
+ * Encode Apple Maps Look Around `_mvs` view state.
+ * Share links from Maps include this protobuf; without it, `/look-around?coordinate=`
+ * opens the place/map card instead of Look Around.
+ *
+ * Layout: length-delimited message with little-endian fixed64 fields
+ * 1=latitude, 2=longitude, 3=altitude (meters).
+ */
+export declare const encodeLookAroundMvs: (lat: number, lng: number, altitudeMeters?: number) => string;
+/** Apple Maps Look Around deep link (no API key). Includes `_mvs` so Maps opens Look Around. */
+export declare const lookAroundDeepLink: (lat: number, lng: number) => string;
+/**
+ * Link-out-only provider: no official bulk coverage listing API.
+ * Map clicks open Apple Maps Look Around at the clicked coordinate.
+ */
+export declare const lookaroundAdapter: ProviderAdapter;

package/dist/providers/adapters/mapilio.d.ts

@@ -0,0 +1,7 @@
+import type { Feature } from 'geojson';
+import type { NormalizedPhoto, NormalizedSequence, ProviderAdapter } from '../model';
+export declare const parseMapilioCaptureTime: (value: unknown) => number | null;
+export declare const parseMapilioResolution: (resolution: unknown) => boolean | null;
+export declare const normalizeMapilioPointFeature: (feature: Feature) => Omit<NormalizedPhoto, 'providerId'> | null;
+export declare const normalizeMapilioRoadFeature: (feature: Feature) => Omit<NormalizedSequence, 'providerId'> | null;
+export declare const mapilioAdapter: ProviderAdapter;

package/dist/providers/adapters/mapillary-map-features.d.ts

@@ -0,0 +1,4 @@
+import type { Feature } from 'geojson';
+import type { NormalizedMapFeature, ProviderAdapter } from '../model';
+export declare const normalizeMapillaryMapFeature: (feature: Feature) => Omit<NormalizedMapFeature, 'providerId'> | null;
+export declare const mapillaryMapFeaturesAdapter: ProviderAdapter;

package/dist/providers/adapters/mapillary-signs.d.ts

@@ -0,0 +1,4 @@
+import type { Feature } from 'geojson';
+import type { NormalizedMapFeature, ProviderAdapter } from '../model';
+export declare const normalizeMapillaryTrafficSignFeature: (feature: Feature) => Omit<NormalizedMapFeature, 'providerId'> | null;
+export declare const mapillarySignsAdapter: ProviderAdapter;

package/dist/providers/adapters/mapillary.d.ts

@@ -0,0 +1,5 @@
+import type { Feature } from 'geojson';
+import type { NormalizedPhoto, NormalizedSequence, ProviderAdapter } from '../model';
+export declare const normalizeMapillaryImageFeature: (feature: Feature) => Omit<NormalizedPhoto, 'providerId'> | null;
+export declare const normalizeMapillarySequenceFeature: (feature: Feature) => Omit<NormalizedSequence, 'providerId'> | null;
+export declare const mapillaryAdapter: ProviderAdapter;

package/dist/providers/adapters/panoramax.d.ts

@@ -0,0 +1,6 @@
+import type { Feature } from 'geojson';
+import type { NormalizedPhoto, NormalizedSequence, ProviderAdapter } from '../model';
+export declare const parsePanoramaxTimestamp: (value: unknown) => number | null;
+export declare const normalizePanoramaxPictureFeature: (feature: Feature) => Omit<NormalizedPhoto, 'providerId'> | null;
+export declare const normalizePanoramaxSequenceFeature: (feature: Feature) => Omit<NormalizedSequence, 'providerId'> | null;
+export declare const panoramaxAdapter: ProviderAdapter;

package/dist/providers/adapters/streetside.d.ts

@@ -0,0 +1,16 @@
+import type { NormalizedPhoto, ProviderAdapter } from '../model';
+export type StreetsideBubble = {
+    id?: string;
+    imageUrl?: string;
+    imageUrlSubdomains?: string[];
+    lon?: number;
+    longitude?: number;
+    lat?: number;
+    latitude?: number;
+    he?: number;
+    heading?: number;
+    vintageEnd?: string;
+};
+export declare const parseStreetsideDate: (value: unknown) => number | null;
+export declare const normalizeStreetsideBubble: (bubble: StreetsideBubble) => Omit<NormalizedPhoto, 'providerId'> | null;
+export declare const streetsideAdapter: ProviderAdapter;

package/dist/providers/adapters/streetview.d.ts

@@ -0,0 +1,16 @@
+import type { NormalizedPhoto, ProviderAdapter } from '../model';
+export type StreetViewMetadataResponse = {
+    status: string;
+    copyright?: string;
+    date?: string;
+    location?: {
+        lat?: number;
+        lng?: number;
+    };
+    pano_id?: string;
+};
+export declare const getGoogleMapsApiKey: () => string | undefined;
+export declare const parseStreetViewDate: (value: unknown) => number | null;
+export declare const normalizeStreetViewMetadata: (data: StreetViewMetadataResponse, clickLng: number, clickLat: number) => Omit<NormalizedPhoto, 'providerId'> | null;
+export declare const fetchStreetViewMetadata: (lat: number, lng: number, signal: AbortSignal) => Promise<NormalizedPhoto | null>;
+export declare const streetViewAdapter: ProviderAdapter;

package/dist/providers/adapters/vegbilder.d.ts

@@ -0,0 +1,14 @@
+import type { Feature } from 'geojson';
+import type { Bbox, NormalizedPhoto, ProviderAdapter } from '../model';
+export type VegbilderLayerInfo = {
+    name: string;
+    is360: boolean;
+    year: number;
+};
+export declare const parseVegbilderLayerNames: (capabilitiesXml: string) => VegbilderLayerInfo[];
+export declare const selectVegbilderLayers: (layers: VegbilderLayerInfo[], minYear?: number, maxLayers?: number) => string[];
+export declare const parseVegbilderTimestamp: (value: unknown) => number | null;
+export declare const buildVegbilderSequenceId: (props: Record<string, unknown>) => string | null;
+export declare const normalizeVegbilderFeature: (feature: Feature, layerYear?: number) => Omit<NormalizedPhoto, 'providerId'> | null;
+export declare const intersectsNorway: (bbox: Bbox) => boolean;
+export declare const vegbilderAdapter: ProviderAdapter;

package/dist/providers/fetchMvt.d.ts

@@ -0,0 +1,5 @@
+import type { Feature } from 'geojson';
+import type { TileCoord } from './model';
+export type MvtLayers = Record<string, Feature[]>;
+export declare const pointLngLat: (feature: Feature) => [number, number] | null;
+export declare const fetchMvt: (url: string, tile: TileCoord, signal: AbortSignal) => Promise<MvtLayers>;

package/dist/providers/mapillaryShared.d.ts

@@ -0,0 +1,6 @@
+import { pointLngLat } from './fetchMvt';
+import type { Bbox, TileCoord } from './model';
+export { pointLngLat };
+export declare const MAPILLARY_TILE_ZOOM = 14;
+export declare const mapillaryTileUrl: (path: string, tile: TileCoord) => string;
+export declare const fetchMapillaryMvtTiles: (cachePrefix: string, path: string, bbox: Bbox, signal: AbortSignal) => Promise<import("./fetchMvt").MvtLayers[]>;

package/dist/providers/model.d.ts

@@ -0,0 +1,67 @@
+import type { LineString, MultiLineString } from 'geojson';
+export declare const PROVIDER_IDS: readonly ['mapillary', 'panoramax', 'kartaview', 'mapilio', 'streetside', 'vegbilder', 'streetview', 'lookaround', 'mapillary-signs', 'mapillary-map-features'];
+export type ProviderId = (typeof PROVIDER_IDS)[number];
+/** Bounding box as [west, south, east, north] in WGS84 degrees. */
+export type Bbox = [west: number, south: number, east: number, north: number];
+export type TileCoord = {
+    z: number;
+    x: number;
+    y: number;
+};
+export type ProviderKind = 'photo' | 'mapFeature';
+export type NormalizedPhoto = {
+    providerId: ProviderId;
+    photoId: string;
+    sequenceId: string | null;
+    /** KartaView sequence_index for deep links; undefined for other providers. */
+    sequenceIndex?: number;
+    capturedAt: number | null;
+    isPano: boolean | null;
+    heading: number | null;
+    lngLat: [number, number];
+    /** Direct thumbnail URL when the list API already provides one. */
+    thumbUrl?: string;
+    /** Full-resolution image URL when the list API already provides one. */
+    fullUrl?: string;
+    /** Vegbilder atlas year for external viewer links. */
+    viewerYear?: number;
+    /** Bing Streetside cubemap tile template from the metadata API. */
+    streetside?: {
+        urlTemplate: string;
+        subdomains: string[];
+    };
+};
+export type NormalizedMapFeature = {
+    providerId: ProviderId;
+    featureId: string;
+    value: string;
+    firstSeenAt: number | null;
+    lastSeenAt: number | null;
+    lngLat: [number, number];
+};
+export type NormalizedSequence = {
+    providerId: ProviderId;
+    sequenceId: string;
+    geometry: LineString | MultiLineString;
+    /** Sequence capture time (ms), when the tile/API provides it (e.g. Mapillary). */
+    capturedAt: number | null;
+    /** Whether the sequence is panoramic, when known. */
+    isPano: boolean | null;
+};
+export type ProviderAdapter = {
+    id: ProviderId;
+    kind: ProviderKind;
+    label: string;
+    color: string;
+    /** Minimum map zoom before photo markers are fetched. */
+    minZoom: number;
+    /** Minimum map zoom before sequence lines are fetched (defaults to minZoom). */
+    sequencesMinZoom?: number;
+    /** When false, provider is omitted from the default enabled set. */
+    defaultEnabled?: boolean;
+    /** When set, map layers cannot load in the browser (e.g. upstream CORS). */
+    browserUnavailableReason?: string;
+    fetchPhotos?: (bbox: Bbox, zoom: number, signal: AbortSignal) => Promise<NormalizedPhoto[]>;
+    fetchSequences?: (bbox: Bbox, zoom: number, signal: AbortSignal) => Promise<NormalizedSequence[]>;
+    fetchMapFeatures?: (bbox: Bbox, zoom: number, signal: AbortSignal) => Promise<NormalizedMapFeature[]>;
+};

package/dist/providers/registry.d.ts

@@ -0,0 +1,29 @@
+import type { ProviderAdapter, ProviderId, ProviderKind } from './model';
+export type ProviderMeta = {
+    id: ProviderId;
+    kind: ProviderKind;
+    label: string;
+    color: string;
+    minZoom: number;
+    sequencesMinZoom: number;
+    homepageUrl?: string;
+    browserUnavailableReason?: string;
+};
+export declare const PROVIDER_ADAPTERS: ProviderAdapter[];
+export declare const adapterById: Record<ProviderId, ProviderAdapter>;
+export declare const PROVIDERS: ProviderMeta[];
+export declare const DEFAULT_PROVIDER_IDS: ProviderId[];
+export declare const isClickOnlyPhotoProvider: (providerId: ProviderId) => boolean;
+export declare const isBrowserAvailableProvider: (providerId: ProviderId) => boolean;
+export declare const providerById: Record<ProviderId, ProviderMeta>;
+export declare const photoLayerId: (providerId: ProviderId) => string;
+export declare const featureLayerId: (providerId: ProviderId) => string;
+export declare const sequenceLayerId: (providerId: ProviderId) => string;
+export declare const viewfieldLayerId: (providerId: ProviderId) => string;
+export declare const viewfieldLineLayerId: (providerId: ProviderId) => string;
+export declare const photoSourceId: (providerId: ProviderId) => string;
+export declare const featureSourceId: (providerId: ProviderId) => string;
+export declare const sequenceSourceId: (providerId: ProviderId) => string;
+export declare const viewfieldSourceId: (providerId: ProviderId) => string;
+export declare const isPhotoProviderId: (providerId: ProviderId) => boolean;
+export declare const isMapFeatureProviderId: (providerId: ProviderId) => boolean;

package/dist/providers/tileCache.d.ts

@@ -0,0 +1,9 @@
+export declare const getTileCacheKey: (providerId: string, tile: {
+    z: number;
+    x: number;
+    y: number;
+}) => string;
+export declare const fetchTileCached: <T>(key: string, fetcher: (signal: AbortSignal) => Promise<T>, signal: AbortSignal) => Promise<T>;
+/** Await all tile fetches, tolerating partial failures. Throws only when every tile failed. */
+export declare const collectSettledTiles: <T>(promises: Promise<T>[]) => Promise<Awaited<T>[]>;
+export declare const clearTileCache: () => void;

package/dist/providers/tileMath.d.ts

@@ -0,0 +1,16 @@
+import type { Bbox, TileCoord } from './model';
+export declare const lonToTileX: (lon: number, z: number) => number;
+export declare const latToTileY: (lat: number, z: number) => number;
+export declare const tileToLon: (x: number, z: number) => number;
+export declare const tileToLat: (y: number, z: number) => number;
+export declare const tileBbox: (tile: TileCoord) => Bbox;
+export declare const clampZoom: (zoom: number, min: number, max: number) => number;
+type TilesForBboxOptions = {
+    skipNullIsland?: boolean;
+};
+/** Null Island guard — skip tiles whose center lies within ~1° of (0, 0). */
+export declare const isNullIslandTile: (tile: TileCoord) => boolean;
+export declare const tilesForBbox: (bbox: Bbox, z: number, options?: TilesForBboxOptions) => TileCoord[];
+export declare const bboxIntersects: (a: Bbox, b: Bbox) => boolean;
+export declare const tilePixelSizeAtZoom: (zoom: number) => number;
+export {};

package/dist/viewer/clickRadius.d.ts

@@ -0,0 +1,4 @@
+/** Great-circle distance in meters between two WGS84 points. */
+export declare const haversineDistanceMeters: (lng1: number, lat1: number, lng2: number, lat2: number) => number;
+/** Click search radius in meters; ~50 m at z14, scales with zoom. */
+export declare const clickRadiusMeters: (zoom: number) => number;

package/dist/viewer/externalLinks.d.ts

@@ -0,0 +1,5 @@
+import type { NormalizedMapFeature, NormalizedPhoto, ProviderId } from '../providers/model';
+export declare const providerExternalLink: (photo: NormalizedPhoto) => string;
+export declare const mapFeatureExternalLink: (feature: NormalizedMapFeature) => string;
+/** Deep link to a provider's viewer at a map location (no specific photo selected). */
+export declare const providerLocationLink: (providerId: ProviderId, lat: number, lng: number, zoom?: number) => string;

package/dist/viewer/groupClickedPhotos.d.ts

@@ -0,0 +1,20 @@
+import type { NormalizedPhoto, ProviderId } from '../providers/model';
+export type PhotoSequenceGroup = {
+    providerId: ProviderId;
+    sequenceId: string;
+    groupKey: string;
+    photos: NormalizedPhoto[];
+    distanceMeters: number;
+};
+export declare const sequenceGroupKey: (providerId: ProviderId, sequenceId: string) => string;
+export declare const photoGroupSequenceId: (photo: NormalizedPhoto) => string;
+export declare const distanceToPhoto: (photo: NormalizedPhoto, lng: number, lat: number) => number;
+export declare const findNearestPhoto: (photos: NormalizedPhoto[], lng: number, lat: number) => NormalizedPhoto | null;
+/** Remove photos within minDistanceMeters of an earlier photo in the same sequence. */
+export declare const dedupeNearbyPhotos: (photos: NormalizedPhoto[], minDistanceMeters?: number) => NormalizedPhoto[];
+export declare const groupClickedPhotos: (photos: NormalizedPhoto[], lng: number, lat: number) => PhotoSequenceGroup[];
+export declare const findGroupBySelection: (groups: PhotoSequenceGroup[], providerId: ProviderId, sequenceId: string) => PhotoSequenceGroup | null;
+export declare const findPhotoIndexInGroup: (group: PhotoSequenceGroup, photoId: string) => number;
+export declare const STREETSIDE_NEARBY_LIMIT = 15;
+/** Nearby Streetside bubbles across all clicked groups, sorted by distance to the active photo. */
+export declare const collectNearbyStreetsidePhotos: (groups: PhotoSequenceGroup[], activePhoto: NormalizedPhoto, limit?: number) => NormalizedPhoto[];

package/dist/viewer/photoThumbnails.d.ts

@@ -0,0 +1,17 @@
+import type { NormalizedPhoto } from '../providers/model';
+type MapilioSequenceItem = {
+    id?: number | string;
+    filename?: string;
+    uploaded_hash?: string;
+};
+export declare const fetchMapilioSequenceItem: (sequenceId: string, photoId: string) => Promise<MapilioSequenceItem | null>;
+export declare const fetchMapillaryThumbnail: (photoId: string) => Promise<string | null>;
+export declare const fetchPanoramaxThumbnail: (sequenceId: string, photoId: string) => Promise<string | null>;
+export declare const fetchMapilioThumbnail: (sequenceId: string, photoId: string) => Promise<string | null>;
+export declare const fetchMapilioFullUrl: (sequenceId: string, photoId: string) => Promise<string | null>;
+export declare const resolvePhotoFullUrl: (photo: NormalizedPhoto) => Promise<string | null>;
+export declare const resolvePhotoPanoramaUrl: (photo: NormalizedPhoto) => Promise<string | null>;
+export declare const resolvePhotoThumbnailUrl: (photo: NormalizedPhoto) => Promise<string | null>;
+export declare const photoFullUrlQueryKey: (photo: NormalizedPhoto) => readonly ['photo-full-url', "kartaview" | "lookaround" | "mapilio" | "mapillary" | "mapillary-map-features" | "mapillary-signs" | "panoramax" | "streetside" | "streetview" | "vegbilder", string | null, string];
+export declare const photoThumbnailQueryKey: (photo: NormalizedPhoto) => readonly ['photo-thumbnail', "kartaview" | "lookaround" | "mapilio" | "mapillary" | "mapillary-map-features" | "mapillary-signs" | "panoramax" | "streetside" | "streetview" | "vegbilder", string | null, string];
+export {};

package/dist/viewer/streetsidePreview.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Streetside preview strategy: when the API returns an imageUrl template we substitute
+ * `{subdomain}` → `t0`, `{faceId}` → `01`, and `{tileId}` → empty string to request a
+ * single cubemap face tile. This is a best-effort static preview — cubemap stitching is
+ * not implemented in v1. When the template is missing or substitution fails, the viewer
+ * shows metadata + "Open in Bing Maps" instead of an image.
+ */
+export declare const buildStreetsidePreviewUrl: (imageUrlTemplate: string | undefined) => string | null;

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@osm-editor-kit/street-imagery",
+  "version": "0.1.0-alpha.0",
+  "description": "Street-level imagery providers, GeoJSON, viewfields, tiles, and viewer helpers (Mapillary, Panoramax, and more).",
+  "license": "MIT",
+  "author": "Tobias Jordans",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/osmberlin/street-space-editor.git",
+    "directory": "packages/street-imagery"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  },
+  "scripts": {
+    "build": "tsup && rm -f .tsbuildinfo && tsc -p tsconfig.build.json",
+    "type-check": "tsc --noEmit",
+    "test-run": "bun test src",
+    "prepublishOnly": "bun run build && bun ../../scripts/package-exports-for-publish.ts",
+    "postpublish": "bun ../../scripts/package-exports-restore.ts",
+    "prepack": "bun ../../scripts/package-exports-for-publish.ts",
+    "postpack": "bun ../../scripts/package-exports-restore.ts"
+  },
+  "dependencies": {
+    "@mapbox/vector-tile": "^3.0.0",
+    "pbf": "^5.1.0"
+  },
+  "devDependencies": {
+    "@types/geojson": "^7946.0.16",
+    "bun-types": "^1.2.20",
+    "maplibre-gl": "^5.7.1",
+    "tsup": "^8.5.1",
+    "typescript": "^7.0.0",
+    "vite": "^8.0.0"
+  },
+  "publishExports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  }
+}