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

package/dist/mapillary/MapillaryFeatureBar.d.ts

@@ -0,0 +1,16 @@
+import { type MapFeatureImages, type TargetImage } from '@osm-editor-kit/street-imagery';
+import { type MapillaryFeatureBarLabels } from './featureBarLabels';
+export type MapillaryFeatureBarProps = {
+    data: MapFeatureImages;
+    shownImage: TargetImage | null;
+    onShow: (image: TargetImage) => void;
+    /** Replace single texts, e.g. `name` to map values to your own sign catalogue. */
+    labels?: Partial<MapillaryFeatureBarLabels>;
+};
+/**
+ * A Mapillary sign or object above its photo: what it is, when Mapillary saw it, and one button
+ * per capture day (newest first). The shown day is highlighted; clicking it again steps through
+ * that day's photos. Dates show month and year; the tooltip has the full date and the age.
+ * Texts and dates follow the `StreetImageryLocaleProvider`.
+ */
+export declare const MapillaryFeatureBar: ({ data, shownImage, onShow, labels: labelOverrides, }: MapillaryFeatureBarProps) => import("react").JSX.Element;

package/dist/mapillary/SelectedMapFeatureLayer.d.ts

@@ -0,0 +1,19 @@
+import { type Bbox, type MapFeatureImages, type ProviderId, type TargetImage } from '@osm-editor-kit/street-imagery';
+export type SelectedMapFeatureLayerProps = {
+    /** From `useSelectedMapillaryFeature`. Nothing is drawn without it. */
+    data: MapFeatureImages | null;
+    /** The shown photo of the feature: a dotted line runs from its camera to the feature. */
+    shownImage?: TargetImage | null;
+    /** The providers whose map features are drawn, to ring the dot that is on the map. */
+    providers: ProviderId[];
+    bbox: Bbox | null;
+    zoom: number;
+    /** Color of the dot and disk. Default: the map features' purple. */
+    color?: string;
+};
+/**
+ * The selected sign or object on the map: its dot on a light disk, and a dotted line to it from
+ * the camera position of the shown photo (Mapillary's computed position, which the feature was
+ * located from). Draw it after `StreetLevelImagerySourcesAndLayers`.
+ */
+export declare const SelectedMapFeatureLayer: ({ data, shownImage, providers, bbox, zoom, color, }: SelectedMapFeatureLayerProps) => import("react").JSX.Element;

package/dist/mapillary/featureBarLabels.d.ts

@@ -0,0 +1,16 @@
+import { type StreetImageryLocale } from '@osm-editor-kit/street-imagery';
+/**
+ * Texts of `MapillaryFeatureBar`. Kept out of the package-wide messages, so the German sign names
+ * are only bundled by apps that show the feature bar.
+ */
+export type MapillaryFeatureBarLabels = {
+    /** Name of a Mapillary value like `regulatory--turn-right-ahead--g1`. */
+    name: (value: string) => string;
+    /** Line below the name; `first` and `last` are the rendered dates. */
+    seen: string;
+    noPhotos: string;
+    daysSummary: (photos: number, days: number) => string;
+    /** Third tooltip line of a day button, below date and age. */
+    dayPhotos: (photos: number, canStep: boolean) => string;
+};
+export declare const MAPILLARY_FEATURE_BAR_LABELS: Record<StreetImageryLocale, MapillaryFeatureBarLabels>;

package/dist/mapillary/useMapillaryFeatures.d.ts

@@ -0,0 +1,54 @@
+import { type LngLat, type TargetShape } from '@osm-editor-kit/street-imagery';
+/**
+ * A Mapillary map feature (sign, traffic light, marking) with all images that show it, grouped by
+ * day, and the outlines Mapillary linked to it. Feed `days[0].best` into the viewer with
+ * `lookAt={{ lngLat: feature.lngLat, outline: image.outline }}`.
+ */
+export declare const useMapillaryMapFeatureImages: (featureId: string | null | undefined, { shape }?: {
+    shape?: TargetShape;
+}) => import("@tanstack/react-query").UseQueryResult<NoInfer<import("@osm-editor-kit/street-imagery").MapFeatureImages | null>, Error>;
+/**
+ * Map features within `radiusMeters` of a point (Graph API), nearest first, e.g. the traffic
+ * lights and markings at a junction. `objectValues` accepts wildcards (`object--traffic-light--*`).
+ */
+export declare const useMapillaryMapFeaturesNear: (lngLat: LngLat | null | undefined, { radiusMeters, objectValues, enabled, }?: {
+    radiusMeters?: number;
+    objectValues?: string[];
+    enabled?: boolean;
+}) => import("@tanstack/react-query").UseQueryResult<NoInfer<{
+    id: string;
+    value: string;
+    lngLat: LngLat;
+    firstSeenAt: number | null;
+    lastSeenAt: number | null;
+    facing: number | null;
+    imageIds: string[];
+    distanceMeters: number;
+}[]>, Error>;
+/**
+ * Detection outlines of one image, for `outlines` of the Mapillary viewer. An image has ~500
+ * detections; pass `filter` (e.g. `matchesAnyGroup(JUNCTION_DETECTION_GROUPS)`) and name it with
+ * `filterKey` so the cache can tell filters apart.
+ */
+export declare const useMapillaryImageDetections: (imageId: string | null | undefined, { filter, filterKey }?: {
+    filter?: (value: string) => boolean;
+    filterKey?: string;
+}) => import("@tanstack/react-query").UseQueryResult<NoInfer<import("@osm-editor-kit/street-imagery").MapillaryDetection[]>, Error>;
+/**
+ * A selected Mapillary map feature (sign, object) for a host's feature + photo selection: all its
+ * photos by day, the photo that is shown (`shownPhotoId`), and the one to open first — the best of
+ * the newest day, from within `minCapturedAt` (ms) when set. Feed `data` and `shownImage` to
+ * `MapillaryFeatureBar` and `SelectedMapFeatureLayer`, and `shownImage.outline` to `lookAt`.
+ */
+export declare const useSelectedMapillaryFeature: ({ featureId, shownPhotoId, minCapturedAt, shape, }: {
+    featureId: string | null | undefined;
+    shownPhotoId?: string | null;
+    minCapturedAt?: number | null;
+    shape?: TargetShape;
+}) => {
+    data: NonNullable<NoInfer<import("@osm-editor-kit/street-imagery").MapFeatureImages | null>> | null;
+    isLoading: boolean;
+    isError: boolean;
+    shownImage: import("@osm-editor-kit/street-imagery").TargetImage | null;
+    firstImage: import("@osm-editor-kit/street-imagery").TargetImage | null;
+};

package/dist/openers/LocationPickOnMap.d.ts

@@ -0,0 +1,10 @@
+import { type LocationOpener, type OpenTarget } from '@osm-editor-kit/street-imagery';
+export type LocationPickOnMapProps = {
+    /** Called after the place was opened, e.g. to mark it on the map. */
+    onPick?: (target: OpenTarget, opener: LocationOpener) => void;
+};
+/**
+ * Render inside `<Map>`. While a location opener is armed, the next map click opens the clicked
+ * place in a new tab and disarms; Escape disarms. The map's own click handlers still run.
+ */
+export declare const LocationPickOnMap: ({ onPick }: LocationPickOnMapProps) => null;

package/dist/openers/useLocationPickStore.d.ts

@@ -0,0 +1,9 @@
+import type { LocationOpenerId } from '@osm-editor-kit/street-imagery';
+/** The opener waiting for a map click, or `null`. */
+export declare const useArmedLocationOpenerId: () => LocationOpenerId | null;
+export declare const useLocationPickActions: () => {
+    arm: (openerId: LocationOpenerId) => void;
+    disarm: () => void;
+    /** Arm, or disarm when this opener is armed already. */
+    toggle: (openerId: LocationOpenerId) => void;
+};

package/dist/panels/MapillaryPanel.d.ts

@@ -1,11 +1,29 @@
 import type { NormalizedPhoto } from '@osm-editor-kit/street-imagery';
 import 'mapillary-js/dist/mapillary.css';
 import type { StreetImageryPhotoSelection } from '../types';
+import { type MapillaryLookAt, type MapillaryViewerOutline } from './mapillaryLookAt';
 type MapillaryPanelProps = {
     photo: NormalizedPhoto;
     groupPhotos: NormalizedPhoto[];
     onPhotoSelected: (selection: StreetImageryPhotoSelection) => void;
     onEaseMapToPoint: (lng: number, lat: number) => void;
+    /** Full photo data for each image the viewer shows (incl. native prev/next navigation). */
+    onViewerPhoto?: (photo: NormalizedPhoto) => void;
+    /** 360° photos: turn the view to this map bearing when `photo` opens (e.g. a suggested view). */
+    lookAtBearing?: number | null;
+    /**
+     * Turn (and zoom) the view to a place when `photo` opens: a sign, a traffic light, a junction.
+     * Works for 360° and flat photos; wins over `lookAtBearing`.
+     */
+    lookAt?: MapillaryLookAt | null;
+    /** Outlines to draw in the shown image, e.g. the detections you care about. */
+    outlines?: MapillaryViewerOutline[];
+    /**
+     * Hide the viewer's own attribution (creator and year). The host must then show the creator
+     * (`creatorName` of `onViewerPhoto`) and a link to the image on Mapillary itself; the images
+     * are CC BY-SA.
+     */
+    hideAttribution?: boolean;
 };
-export declare const MapillaryPanel: ({ photo, onPhotoSelected, onEaseMapToPoint, }: MapillaryPanelProps) => import("react").JSX.Element;
+export declare const MapillaryPanel: ({ photo, onPhotoSelected, onEaseMapToPoint, onViewerPhoto, lookAtBearing, lookAt, outlines, hideAttribution, }: MapillaryPanelProps) => import("react").JSX.Element;
 export {};

package/dist/panels/PanoramaxPanel.d.ts

@@ -1,11 +1,21 @@
-import '@panoramax/web-viewer';
 import type { NormalizedPhoto } from '@osm-editor-kit/street-imagery';
+import 'mapillary-js/dist/mapillary.css';
 import type { StreetImageryPhotoSelection } from '../types';
-type PanoramaxPanelProps = {
+export type PanoramaxPanelProps = {
     photo: NormalizedPhoto;
     groupPhotos: NormalizedPhoto[];
     onPhotoSelected: (selection: StreetImageryPhotoSelection) => void;
     onEaseMapToPoint: (lng: number, lat: number) => void;
+    /** The shown picture with creator, licence, local capture time and camera. */
+    onViewerPhoto?: (photo: NormalizedPhoto) => void;
+    /**
+     * Hide the line with creator and licence. The host must then show both itself, from
+     * `onViewerPhoto`.
+     */
+    hideAttribution?: boolean;
 };
-export declare const PanoramaxPanel: ({ photo, onPhotoSelected, onEaseMapToPoint, }: PanoramaxPanelProps) => import("react").JSX.Element;
-export {};
+/**
+ * Panoramax pictures in the Mapillary viewer (`mapillary-js` with a `PanoramaxDataProvider`): no
+ * second viewer engine to load, and the same handling as Mapillary photos.
+ */
+export declare const PanoramaxPanel: ({ photo, onPhotoSelected, onEaseMapToPoint, onViewerPhoto, hideAttribution, }: PanoramaxPanelProps) => import("react").JSX.Element;

package/dist/panels/PanoramaxWebViewerPanel.d.ts

@@ -0,0 +1,20 @@
+import '@panoramax/web-viewer';
+import type { NormalizedPhoto } from '@osm-editor-kit/street-imagery';
+import type { StreetImageryPhotoSelection } from '../types';
+export type PanoramaxWebViewerPanelProps = {
+    photo: NormalizedPhoto;
+    groupPhotos: NormalizedPhoto[];
+    onPhotoSelected: (selection: StreetImageryPhotoSelection) => void;
+    onEaseMapToPoint: (lng: number, lat: number) => void;
+    /** The shown picture with creator, licence, local capture time and camera. */
+    onViewerPhoto?: (photo: NormalizedPhoto) => void;
+    /**
+     * Leave out the viewer's own widgets: the legend (a bottom drawer in narrow containers), the
+     * player and the zoom buttons. The host must then show creator and licence itself, from
+     * `onViewerPhoto`. Stepping through a sequence still works with the arrows in the photo.
+     */
+    hideLegend?: boolean;
+    /** Same as `hideLegend`; the name `StreetLevelImageryViewer` passes. */
+    hideAttribution?: boolean;
+};
+export declare const PanoramaxWebViewerPanel: ({ photo, onPhotoSelected, onEaseMapToPoint, onViewerPhoto, hideLegend: hideLegendProp, hideAttribution, }: PanoramaxWebViewerPanelProps) => import("react").JSX.Element;

package/dist/panels/mapillaryLookAt.d.ts

@@ -0,0 +1,41 @@
+import { type LngLat, type TargetShape, type ViewTarget } from '@osm-editor-kit/street-imagery';
+import { type Image, type Viewer } from 'mapillary-js';
+/** A place the Mapillary viewer should turn to: a sign, a traffic light, a junction … */
+export type MapillaryLookAt = {
+    lngLat: LngLat;
+    /** Size and height of the target; decides zoom and vertical position. Default: a traffic sign. */
+    shape?: TargetShape;
+    /** The target's outline in the shown image, if known; it is more exact than the location. */
+    outline?: [number, number][];
+    /**
+     * Mapillary value of the target (`regulatory--bicycles-only--g1`). Without an `outline`, the
+     * image's own detection of this value is used: Mapillary links a map feature to few of its
+     * images, but almost every image has a detection of it. With several, the one nearest to the
+     * computed position wins (the computed position alone can be far off in 360° images).
+     */
+    value?: string;
+    /** Label for the outline drawn around the target. */
+    label?: string;
+};
+export type MapillaryViewerOutline = {
+    id: string;
+    /** Image ("basic") coordinates, `[0, 0]` top left to `[1, 1]` bottom right. */
+    outline: [number, number][];
+    label?: string;
+    /** CSS color number, e.g. `0xffff00`. Default yellow. */
+    color?: number;
+};
+/**
+ * Where the target is in the image: from its outline, else computed from the locations
+ * (360°: the viewer's own projection; flat: a pinhole model). `undefined` when a flat image does
+ * not show the target.
+ */
+export declare const mapillaryViewFor: (viewer: Viewer, image: Image, { lngLat, shape, outline }: MapillaryLookAt) => Promise<ViewTarget | undefined>;
+/**
+ * Turns the viewer to the target. Returns the outline it aimed at (given, or the image's own
+ * detection of `value`), or `null` when it aimed by location; `false` when the shown (flat) image
+ * does not show the target.
+ */
+export declare const turnMapillaryViewerTo: (viewer: Viewer, image: Image, lookAt: MapillaryLookAt) => Promise<MapillaryViewerOutline | null | false>;
+/** Replaces the outlines drawn in the viewer (needs the viewer's `tag` component). */
+export declare const setMapillaryViewerOutlines: (viewer: Viewer, outlines: readonly MapillaryViewerOutline[]) => void;

package/dist/panels/panoramaxDataProvider.d.ts

@@ -0,0 +1,44 @@
+import { DataProviderBase, type ClusterContract, type CoreImagesContract, type ImagesContract, type ImageTilesContract, type ImageTilesRequestContract, type MeshContract, type SequenceContract, type SpatialImagesContract } from 'mapillary-js';
+import { type PanoramaxItem } from './panoramaxItem';
+export type PanoramaxDataProviderOptions = {
+    /** The Panoramax API, e.g. `https://api.panoramax.xyz/api`. */
+    endpoint: string;
+};
+/**
+ * Lets a mapillary-js `Viewer` show Panoramax pictures: pass it as the viewer's `dataProvider`.
+ *
+ * A picture opens with its `sd` file (2048 px wide). The viewer then asks for tiles of the part in
+ * view; they are cut here, in the browser. Only when the view needs more detail than `sd` has is
+ * the original file loaded for that, once. (Panoramax has tiles of its own for 360° pictures only,
+ * in another layout.)
+ *
+ * Panoramax has no 3D reconstruction, so the viewer places each picture by its compass direction
+ * and offers the steps along the sequence only, not the arrows to pictures nearby.
+ *
+ * A Panoramax sequence can hold thousands of pictures and the API has no short list of them, so
+ * the viewer never gets the whole sequence. Every picture gets a short one of its own: the
+ * picture before, the picture, the picture after. `Image.sequenceId` of the viewer is therefore
+ * not the Panoramax sequence; use `getItem(id).collection`.
+ */
+export declare class PanoramaxDataProvider extends DataProviderBase {
+    private readonly endpoint;
+    private readonly items;
+    private readonly itemRequests;
+    private readonly imageBuffers;
+    private readonly pictures;
+    constructor({ endpoint }: PanoramaxDataProviderOptions);
+    /** The Panoramax data of a picture the viewer has loaded. */
+    getItem(imageId: string): PanoramaxItem | undefined;
+    getCoreImages(cellId: string): Promise<CoreImagesContract>;
+    getImages(imageIds: string[]): Promise<ImagesContract>;
+    getSpatialImages(imageIds: string[]): Promise<SpatialImagesContract>;
+    getSequence(sequenceId: string): Promise<SequenceContract>;
+    getImageBuffer(url: string): Promise<ArrayBuffer>;
+    getImageTiles({ imageId, z, }: ImageTilesRequestContract): Promise<ImageTilesContract>;
+    private cutTile;
+    private loadPicture;
+    getMesh(): Promise<MeshContract>;
+    getCluster(url: string): Promise<ClusterContract>;
+    private loadItems;
+    private toImageEnt;
+}

package/dist/panels/panoramaxItem.d.ts

@@ -0,0 +1,96 @@
+import type { NormalizedPhoto } from '@osm-editor-kit/street-imagery';
+/** The parts of a Panoramax picture (a STAC item of `/api/search`) the viewer reads. */
+export type PanoramaxItem = {
+    id: string;
+    collection?: string;
+    geometry: {
+        type: 'Point';
+        coordinates: [number, number];
+    };
+    links?: {
+        rel: string;
+        href?: string;
+        /** `prev` and `next` name the neighbour in the sequence. */
+        id?: string;
+        /** `via` names the server the picture is stored on. */
+        instance_name?: string;
+    }[];
+    assets?: Partial<Record<'hd' | 'sd' | 'thumb', {
+        href: string;
+    }>>;
+    providers?: {
+        name: string;
+        roles?: string[];
+    }[];
+    properties?: {
+        datetime?: string;
+        datetimetz?: string;
+        created?: string;
+        license?: string;
+        exif?: Record<string, unknown>;
+        'view:azimuth'?: number | null;
+        'geovisio:producer'?: string;
+        'geovisio:rank_in_collection'?: number;
+        'original_file:name'?: string;
+        'original_file:size'?: number;
+        'quality:horizontal_accuracy'?: number;
+        'pers:interior_orientation'?: {
+            camera_manufacturer?: string;
+            camera_model?: string;
+            focal_length?: number;
+            /** Horizontal field of view in degrees; 360 for a 360° picture. */
+            field_of_view?: number | null;
+            /** Width and height of the picture in pixels. */
+            sensor_array_dimensions?: [number, number];
+        };
+    };
+};
+export declare const isPanoramaxItemSpherical: (item: PanoramaxItem) => boolean;
+/** Width and height in pixels; a guess when the picture does not state them. */
+export declare const panoramaxItemSize: (item: PanoramaxItem) => [number, number];
+/** Neighbour in the sequence, from the item's `prev` / `next` link. */
+export declare const panoramaxItemNeighbour: (item: PanoramaxItem, rel: 'prev' | 'next') => string | null;
+/** The file a picture opens with: `sd`, 2048 px wide. */
+export declare const panoramaxItemImageUrl: (item: PanoramaxItem) => string;
+type PictureSize = [width: number, height: number];
+/**
+ * The size to tell mapillary-js: the real proportions, with the longer side raised to the next
+ * power of two. Its tile levels halve from that power of two, so a picture of 8704 px would get
+ * levels of 4352, 2176, 1088 px, the low ones coarser than the `sd` file. This way they are
+ * 8192, 4096, 2048 px.
+ */
+export declare const panoramaxViewerSize: (item: PanoramaxItem) => PictureSize;
+/** Whether level `z` shows more detail than the `sd` file; only then the original is needed. */
+export declare const panoramaxLevelNeedsOriginal: (size: PictureSize, z: number) => boolean;
+/** The tiles of a picture at level `z`. */
+export declare const panoramaxTilesOfLevel: (size: PictureSize, z: number) => {
+    x: number;
+    y: number;
+}[];
+/**
+ * Where to cut a tile from a file of the picture, and how large to draw it. `original` is the
+ * size of that file; the cut is scaled when it differs from the stated `size`.
+ */
+export declare const panoramaxTileRect: (size: PictureSize, tile: {
+    x: number;
+    y: number;
+    z: number;
+}, original: {
+    width: number;
+    height: number;
+}) => {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    outWidth: number;
+    outHeight: number;
+};
+/**
+ * Focal length of a flat picture as mapillary-js wants it: relative to the longer side. A
+ * picture without a field of view gets a common one.
+ */
+export declare const panoramaxItemFocal: (item: PanoramaxItem) => number;
+/** The picture as a photo with creator, licence, local capture time and camera. */
+export declare const panoramaxPhotoFromItem: (item: PanoramaxItem) => NormalizedPhoto;
+export {};

package/dist/panels/panoramaxLimitPanning.d.ts

@@ -0,0 +1,54 @@
+/** The parts of Photo Sphere Viewer (inside the Panoramax viewer) that limiting the view needs. */
+export type PsvForPanLimit = {
+    state: {
+        hFov: number;
+        vFov: number;
+        textureData?: {
+            panoData?: {
+                baseData?: {
+                    fullWidth: number;
+                    fullHeight: number;
+                    croppedWidth: number;
+                    croppedHeight: number;
+                    croppedX: number;
+                    croppedY: number;
+                };
+            };
+        };
+    };
+    dataHelper: {
+        fovToZoomLevel(fov: number): number;
+    };
+    getZoomLevel(): number;
+    zoom(level: number): void;
+    getPosition(): {
+        yaw: number;
+        pitch: number;
+    };
+    rotate(position: {
+        yaw: number;
+        pitch: number;
+    }): void;
+    addEventListener(type: string, listener: (event: Event) => void): void;
+    removeEventListener(type: string, listener: (event: Event) => void): void;
+};
+type ViewPosition = {
+    yaw: number;
+    pitch: number;
+};
+/**
+ * The view position moved back so the image stays in view. Flat photos are shown as a small
+ * patch of a sphere; outside the patch there is only black. 360° photos have no limit.
+ */
+export declare const limitToImage: (psv: PsvForPanLimit, position: ViewPosition) => ViewPosition;
+/**
+ * The widest zoom level for a flat photo: the image with a small margin around it (in the
+ * tighter direction). `null` when there is no limit.
+ */
+export declare const widestZoomLevel: (psv: PsvForPanLimit) => number | null;
+/**
+ * Keep the view inside the image while the user pans and zooms. Returns a function that removes
+ * the listeners again.
+ */
+export declare const limitPanningToImage: (psv: PsvForPanLimit) => (() => void);
+export {};

package/dist/panels/panoramaxPhotoFromMetadata.d.ts

@@ -0,0 +1,8 @@
+import type { NormalizedPhoto } from '@osm-editor-kit/street-imagery';
+import type { PnxPictureMetadata } from './panoramax-photo-viewer.d';
+/**
+ * The shown picture as a photo with everything the Panoramax viewer knows about it: creator,
+ * licence, local capture time, camera. The viewer's own legend holds the same; hosts show it in
+ * their own layout instead.
+ */
+export declare const panoramaxPhotoFromMetadata: (metadata: PnxPictureMetadata) => NormalizedPhoto;

package/dist/panoramax-web-viewer/index.d.ts

@@ -0,0 +1 @@
+export { PanoramaxWebViewerPanel } from '../panels/PanoramaxWebViewerPanel';