@osm-editor-kit/street-imagery-react 0.1.0-alpha.3 → 0.1.0-alpha.5

package/README.md

@@ -12,6 +12,7 @@ React + MapLibre UI on top of `@osm-editor-kit/street-imagery`:
 - TanStack Query hooks to load provider data for the viewport
 - Lazy Mapillary and Panoramax viewer panels
 - Helpers for selection, thumbnails, and easing the map to a photo
+- Viewpoints + floating photo viewer: suggested views per direction, history, map layer
 
 ## Usage
 
@@ -52,3 +53,70 @@ const hits = queryStreetImageryFeatures(event)
 **Mapillary:** `createStreetImageryConfig({ mapillaryToken })` or `setStreetImageryConfig` at boot (`@osm-editor-kit/street-imagery`). **Panoramax + Vite:** see `app/vite.config.ts` for the consuming-app setup.
 
 Also: `useAllProviderPhotos`, `useProviderPhotos` / `useProviderSequences` / `useProviderMapFeatures`, `usePhotoThumbnails`, `resolveSelectedSequence`, `StreetLevelImageryViewCone`, `useViewerBearing` / `useViewerActions`, `MapillaryPanel`, `PanoramaxPanel`.
+
+## Viewpoints and floating viewer
+
+Click → viewpoints → ranked Mapillary photos per view direction → floating viewer with chips and history.
+
+```tsx
+import { viewpointFromPoint, viewpointsFromLine } from '@osm-editor-kit/street-imagery'
+import {
+  FloatingPhotoViewer,
+  getViewpointSession,
+  useViewpoints,
+  useViewSuggestions,
+  ViewpointLayer,
+  VIEWPOINT_DIRECTION_LAYER_ID,
+  viewDirectionKeyFromFeatures,
+} from '@osm-editor-kit/street-imagery-react'
+
+// On map click (add VIEWPOINT_DIRECTION_LAYER_ID to interactiveLayerIds):
+getViewpointSession().actions.open({ viewpoints: [viewpointFromPoint([lng, lat])] })
+// or for a clicked line: open({ viewpoints: viewpointsFromLine(line, [lng, lat]), line })
+
+const viewpoints = useViewpoints()
+const { suggestions } = useViewSuggestions(viewpoints, { maxAgeYears: 2 })
+// <ViewpointLayer viewpoints={viewpoints} suggestions={suggestions} activeDirectionKey={…} zoom={zoom} />
+// <FloatingPhotoViewer suggestions={suggestions} … >{viewer}</FloatingPhotoViewer>
+```
+
+Render `FloatingPhotoViewer` inside a positioned map container. Photos from suggestions open in
+`StreetLevelImageryViewer` with `lookAtBearing={suggestion.direction.bearing}`.
+
+**Tailwind:** components use Tailwind classes. Tailwind does not scan `node_modules`, so add to your CSS:
+
+```css
+@source '../node_modules/@osm-editor-kit/street-imagery-react';
+```
+
+## Look at a place, outline detections
+
+```tsx
+import { JUNCTION_DETECTION_GROUPS, matchesAnyGroup, PLACE_TARGET } from '@osm-editor-kit/street-imagery'
+import {
+  StreetLevelImageryViewer,
+  useMapillaryImageDetections,
+  useMapillaryMapFeatureImages,
+  useMapillaryMapFeaturesNear,
+} from '@osm-editor-kit/street-imagery-react'
+
+// Turn any Mapillary photo (360° or flat) towards a junction:
+<StreetLevelImageryViewer photo={photo} lookAt={{ lngLat: node, shape: PLACE_TARGET }} … />
+
+// Turn to a detected sign or object and outline it. `value` lets the viewer find the image's own
+// detection when Mapillary linked no outline for this image:
+const { data } = useMapillaryMapFeatureImages(featureId)
+<StreetLevelImageryViewer photo={…} lookAt={{ lngLat: data.feature.lngLat, value: data.feature.value }} … />
+
+// Features around a point, and only the outlines you care about in the shown image:
+const { data: features } = useMapillaryMapFeaturesNear(node, { radiusMeters: 40 })
+const { data: detections } = useMapillaryImageDetections(photo.photoId, {
+  filter: matchesAnyGroup(JUNCTION_DETECTION_GROUPS),
+  filterKey: 'junction',
+})
+<StreetLevelImageryViewer photo={photo} outlines={detections?.map((d) => ({ id: d.id, outline: d.outline }))} … />
+```
+
+- Map layers: `filter.mapFeatureValue` limits which signs/objects are drawn (`matchesAnyGroup(SIGN_GROUPS)`).
+- Suggested views: `useViewSuggestions(viewpoints, { sources: [mapillaryPhotoSource, streetViewPhotoSource] })`.
+- `turnMapillaryViewerTo` / `setMapillaryViewerOutlines` work on a mapillary-js `Viewer` you own.

package/dist/MapillaryPanel-I5GKT6YT.js

@@ -0,0 +1,2 @@
+export { MapillaryPanel } from './chunk-72HJV6II.js';
+import './chunk-25UGGXIE.js';

package/dist/StreetLevelImagerySourcesAndLayers.d.ts

@@ -6,6 +6,11 @@ import type { DataDrivenPropertyValueSpecification } from 'maplibre-gl';
 export type PhotoFilter = {
     photoTypes?: PhotoTypeFilter[];
     date?: DateRange;
+    /**
+     * Which map features (signs, objects) to draw, by Mapillary value. Use `matchesAnyGroup(...)`
+     * for groups like traffic lights or bike signs. Keep the function identity stable.
+     */
+    mapFeatureValue?: (value: string) => boolean;
 };
 export type StreetLevelImagerySourcesAndLayersProps = {
     providers: ProviderId[];
@@ -15,7 +20,7 @@ export type StreetLevelImagerySourcesAndLayersProps = {
     options: {
         config?: StreetImageryConfig;
         showSequences?: boolean;
-        /** Always-on heading wedges / 360° disks for every photo. Default true. */
+        /** Heading wedges / 360° disks per photo, from zoom 16, capped for dense areas. Default true. */
         showViewfields?: boolean;
         showViewCone?: boolean;
         showSelectionHighlight?: boolean;

package/dist/StreetLevelImageryViewer.d.ts

@@ -1,10 +1,19 @@
 import type { NormalizedPhoto } from '@osm-editor-kit/street-imagery';
+import type { MapillaryLookAt, MapillaryViewerOutline } from './panels/mapillaryLookAt';
 import type { StreetImageryPhotoSelection } from './types';
 type StreetLevelImageryViewerProps = {
     photo: NormalizedPhoto;
     groupPhotos: NormalizedPhoto[];
     onPhotoSelected: (selection: StreetImageryPhotoSelection) => void;
     onEaseMapToPoint: (lng: number, lat: number) => void;
+    /** Mapillary only: full photo data for each image the viewer shows. */
+    onViewerPhoto?: (photo: NormalizedPhoto) => void;
+    /** Mapillary 360° photos: initial view bearing (e.g. a suggested view direction). */
+    lookAtBearing?: number | null;
+    /** Mapillary: turn and zoom to a place (sign, traffic light, junction); wins over `lookAtBearing`. */
+    lookAt?: MapillaryLookAt | null;
+    /** Mapillary: outlines to draw in the shown image. */
+    outlines?: MapillaryViewerOutline[];
 };
-export declare const StreetLevelImageryViewer: ({ photo, groupPhotos, onPhotoSelected, onEaseMapToPoint, }: StreetLevelImageryViewerProps) => import("react").JSX.Element | null;
+export declare const StreetLevelImageryViewer: ({ photo, groupPhotos, onPhotoSelected, onEaseMapToPoint, onViewerPhoto, lookAtBearing, lookAt, outlines, }: StreetLevelImageryViewerProps) => import("react").JSX.Element | null;
 export {};

package/dist/chunk-72HJV6II.js

@@ -0,0 +1,300 @@
+import { useViewerActions } from './chunk-25UGGXIE.js';
+import { viewFromOutline, SIGN_TARGET, viewFromFlatCamera, cameraPitch, panoX, bearingDeg, viewFromLocation, getStreetImageryConfig, fetchImageDetections } from '@osm-editor-kit/street-imagery';
+import 'mapillary-js/dist/mapillary.css';
+import { OutlineTag, PolygonGeometry, Viewer } from 'mapillary-js';
+import { useRef, useEffectEvent, useEffect } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+var isSpherical = (image) => image.cameraType === "spherical" || image.cameraType === "equirectangular";
+var mapillaryViewFor = async (viewer, image, { lngLat, shape = SIGN_TARGET, outline }) => {
+  const spherical = isSpherical(image);
+  if (outline?.length) {
+    return viewFromOutline(outline, spherical, shape.maxZoom);
+  }
+  const position = image.lngLat ?? image.originalLngLat;
+  const imageLngLat = [position.lng, position.lat];
+  const compass = image.computedCompassAngle ?? image.compassAngle;
+  if (!spherical) {
+    const focal = image.cameraParameters?.[0];
+    return focal ? viewFromFlatCamera(
+      {
+        focal,
+        width: image.width,
+        height: image.height,
+        compassAngle: compass,
+        pitch: cameraPitch(image.rotation)
+      },
+      imageLngLat,
+      lngLat,
+      shape
+    ) : void 0;
+  }
+  let x = panoX(bearingDeg(imageLngLat, lngLat), compass);
+  try {
+    viewer.setCenter([x, 0.5]);
+    const pixel = await viewer.project({ lng: lngLat[0], lat: lngLat[1] });
+    const basic = pixel ? await viewer.unprojectToBasic(pixel) : null;
+    const projected = basic?.[0];
+    if (projected != null && projected >= 0 && projected <= 1) {
+      x = projected;
+    }
+  } catch {
+  }
+  return viewFromLocation(x, { lngLat: imageLngLat, isPano: true }, lngLat, shape);
+};
+var xDistance = (a, b, spherical) => {
+  const distance = Math.abs(a - b);
+  return spherical ? Math.min(distance, 1 - distance) : distance;
+};
+var findOwnDetection = async (image, value, estimate) => {
+  const spherical = isSpherical(image);
+  const candidates = await fetchImageDetections(image.id, { filter: (v) => v === value }).catch(
+    () => []
+  );
+  const centerX = (detection) => viewFromOutline(detection.outline, spherical)?.center[0] ?? 0.5;
+  return candidates.sort(
+    (a, b) => estimate ? xDistance(centerX(a), estimate.center[0], spherical) - xDistance(centerX(b), estimate.center[0], spherical) : 0
+  )[0];
+};
+var turnMapillaryViewerTo = async (viewer, image, lookAt) => {
+  let outline = lookAt.outline?.length ? lookAt.outline : void 0;
+  let outlineId = `look-at-${image.id}`;
+  let view;
+  if (!outline) {
+    view = await mapillaryViewFor(viewer, image, lookAt);
+    const own = lookAt.value ? await findOwnDetection(image, lookAt.value, view) : void 0;
+    if (own) {
+      outline = own.outline;
+      outlineId = own.id;
+    }
+  }
+  if (outline) {
+    view = viewFromOutline(outline, isSpherical(image), (lookAt.shape ?? SIGN_TARGET).maxZoom);
+  }
+  if (!view) {
+    return false;
+  }
+  viewer.setCenter(view.center);
+  viewer.setZoom(view.zoom);
+  return outline ? { id: outlineId, outline, label: lookAt.label } : null;
+};
+var setMapillaryViewerOutlines = (viewer, outlines) => {
+  const tags = viewer.getComponent("tag");
+  tags.removeAll();
+  tags.add(
+    outlines.filter(({ outline }) => outline.length >= 3).map(({ id, outline, label, color = 16776960 }) => {
+      const first = outline[0];
+      const last = outline[outline.length - 1];
+      const closed = first[0] === last[0] && first[1] === last[1] ? outline : [...outline, first];
+      return new OutlineTag(id, new PolygonGeometry(closed), {
+        text: label,
+        textColor: color,
+        lineColor: color,
+        lineWidth: 2,
+        fillColor: color,
+        fillOpacity: 0.3
+      });
+    })
+  );
+};
+var panoCenterX = (bearing, compassAngle) => ((0.5 + (bearing - compassAngle) / 360) % 1 + 1) % 1;
+var MapillaryPanel = ({
+  photo,
+  onPhotoSelected,
+  onEaseMapToPoint,
+  onViewerPhoto,
+  lookAtBearing,
+  lookAt,
+  outlines
+}) => {
+  const containerRef = useRef(null);
+  const viewerRef = useRef(null);
+  const navigableRef = useRef(false);
+  const pendingImageIdRef = useRef(null);
+  const lastViewerPhotoIdRef = useRef(null);
+  const bearingRafRef = useRef(null);
+  const pendingBearingRef = useRef(null);
+  const actions = useViewerActions();
+  const initialPhotoIdRef = useRef(photo.photoId);
+  const emitPhotoSelected = useEffectEvent(onPhotoSelected);
+  const emitEaseMapToPoint = useEffectEvent(onEaseMapToPoint);
+  const turnToWantedBearing = useEffectEvent((viewer, image) => {
+    if (image.id !== photo.photoId) {
+      return;
+    }
+    if (lookAt) {
+      void turnMapillaryViewerTo(viewer, image, lookAt).then((aimedAt) => {
+        if (aimedAt && !outlines && lastViewerPhotoIdRef.current === image.id) {
+          setMapillaryViewerOutlines(viewer, [aimedAt]);
+        }
+      }).catch(() => {
+      });
+      return;
+    }
+    const spherical = image.cameraType === "spherical" || image.cameraType === "equirectangular";
+    const compass = image.computedCompassAngle ?? image.compassAngle;
+    if (lookAtBearing != null && spherical && compass != null) {
+      viewer.setCenter([panoCenterX(lookAtBearing, compass), 0.5]);
+    }
+  });
+  const drawOutlines = useEffectEvent((viewer) => {
+    setMapillaryViewerOutlines(viewer, outlines ?? []);
+  });
+  const emitViewerPhoto = useEffectEvent(
+    (viewerPhoto) => onViewerPhoto?.(viewerPhoto)
+  );
+  useEffect(
+    function resetViewerStoreOnProviderChange() {
+      return () => {
+        actions.reset();
+      };
+    },
+    [actions, photo.providerId]
+  );
+  useEffect(
+    function mountMapillaryViewer() {
+      const container = containerRef.current;
+      if (!container) {
+        return;
+      }
+      const viewer = new Viewer({
+        accessToken: getStreetImageryConfig().mapillaryToken,
+        container,
+        imageId: initialPhotoIdRef.current,
+        component: {
+          cover: false,
+          sequence: { visible: true },
+          tag: true
+        }
+      });
+      viewerRef.current = viewer;
+      lastViewerPhotoIdRef.current = initialPhotoIdRef.current;
+      const flushPendingMove = () => {
+        const pendingId = pendingImageIdRef.current;
+        if (!pendingId) {
+          return;
+        }
+        pendingImageIdRef.current = null;
+        void viewer.moveTo(pendingId).catch(() => {
+        });
+      };
+      const onNavigable = (event) => {
+        navigableRef.current = event.navigable;
+        if (event.navigable) {
+          flushPendingMove();
+        }
+      };
+      const onImage = (event) => {
+        const { image } = event;
+        lastViewerPhotoIdRef.current = image.id;
+        turnToWantedBearing(viewer, image);
+        drawOutlines(viewer);
+        emitPhotoSelected({
+          provider: "mapillary",
+          sequenceId: image.sequenceId,
+          photoId: image.id
+        });
+        const position = image.lngLat ?? image.originalLngLat;
+        if (!position) {
+          return;
+        }
+        emitViewerPhoto({
+          providerId: "mapillary",
+          photoId: image.id,
+          sequenceId: image.sequenceId,
+          capturedAt: image.capturedAt,
+          isPano: image.cameraType === "spherical" || image.cameraType === "equirectangular",
+          heading: image.computedCompassAngle ?? image.compassAngle,
+          lngLat: [position.lng, position.lat]
+        });
+        actions.setPov({ lngLat: [position.lng, position.lat] });
+        emitEaseMapToPoint(position.lng, position.lat);
+      };
+      const flushBearing = () => {
+        bearingRafRef.current = null;
+        if (pendingBearingRef.current != null) {
+          actions.setPov({ bearing: pendingBearingRef.current });
+          pendingBearingRef.current = null;
+        }
+        void viewer.getFieldOfView().then((fov) => {
+          actions.setPov({ hfov: fov });
+        }).catch(() => {
+        });
+      };
+      const onBearing = (event) => {
+        pendingBearingRef.current = event.bearing;
+        if (bearingRafRef.current == null) {
+          bearingRafRef.current = requestAnimationFrame(flushBearing);
+        }
+      };
+      viewer.on("navigable", onNavigable);
+      viewer.on("image", onImage);
+      viewer.on("bearing", onBearing);
+      const resizeObserver = new ResizeObserver(() => {
+        viewer.resize();
+      });
+      resizeObserver.observe(container);
+      return () => {
+        if (bearingRafRef.current != null) {
+          cancelAnimationFrame(bearingRafRef.current);
+          bearingRafRef.current = null;
+        }
+        resizeObserver.disconnect();
+        viewer.off("navigable", onNavigable);
+        viewer.off("image", onImage);
+        viewer.off("bearing", onBearing);
+        viewer.remove();
+        viewerRef.current = null;
+      };
+    },
+    [actions]
+  );
+  useEffect(
+    function syncExternalPhotoSelection() {
+      const viewer = viewerRef.current;
+      if (!viewer || photo.photoId === lastViewerPhotoIdRef.current) {
+        return;
+      }
+      actions.reset();
+      lastViewerPhotoIdRef.current = photo.photoId;
+      if (navigableRef.current) {
+        void viewer.moveTo(photo.photoId).catch(() => {
+        });
+      } else {
+        pendingImageIdRef.current = photo.photoId;
+      }
+    },
+    [actions, photo.photoId]
+  );
+  const lookAtKey = lookAt ? `${lookAt.lngLat.join(",")}|${lookAt.outline?.length ?? 0}|${lookAt.value ?? ""}` : String(lookAtBearing);
+  useEffect(
+    function turnToTargetOnChange() {
+      const viewer = viewerRef.current;
+      if (!viewer || lastViewerPhotoIdRef.current !== photo.photoId) {
+        return;
+      }
+      void viewer.getImage().then((image) => turnToWantedBearing(viewer, image)).catch(() => {
+      });
+    },
+    [lookAtKey, photo.photoId]
+  );
+  useEffect(
+    function redrawOutlinesOnChange() {
+      const viewer = viewerRef.current;
+      if (viewer && navigableRef.current) {
+        drawOutlines(viewer);
+      }
+    },
+    [outlines]
+  );
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref: containerRef,
+      className: "min-h-48 overflow-hidden rounded-lg border border-slate-200 bg-slate-900",
+      style: { aspectRatio: "4 / 3" }
+    }
+  );
+};
+
+export { MapillaryPanel, mapillaryViewFor, setMapillaryViewerOutlines, turnMapillaryViewerTo };

package/dist/index.d.ts

@@ -12,3 +12,10 @@ export * from './hooks/usePhotoThumbnails';
 export { MapillaryPanel } from './panels/MapillaryPanel';
 export { PanoramaxPanel } from './panels/PanoramaxPanel';
 export * from './useViewerStore';
+export { FloatingPhotoViewer, type FloatingPhotoViewerProps, } from './viewpoints/FloatingPhotoViewer';
+export { VIEWPOINT_DEFAULT_COLOR, VIEWPOINT_DIRECTION_LAYER_ID, ViewpointLayer, viewDirectionKeyFromFeatures, type ViewpointLayerProps, } from './viewpoints/ViewpointLayer';
+export { viewpointRoleLabel, viewSuggestionLabel } from './viewpoints/viewDirectionLabels';
+export * from './viewpoints/useViewpointSessionStore';
+export * from './viewpoints/useViewSuggestions';
+export { mapillaryViewFor, setMapillaryViewerOutlines, turnMapillaryViewerTo, type MapillaryLookAt, type MapillaryViewerOutline, } from './panels/mapillaryLookAt';
+export * from './mapillary/useMapillaryFeatures';