feat(street-level): "show me X on Street View" action, street_level view field and sl= links

show_street_level (voice and typed) flies to a place and opens its nearest
street-level photo from Google Street View, Mapillary, KartaView or
Panoramax; Street View switches to Google 3D first. The view model gains a
street_level field, share links carry sl=<source>,<lat>,<lon>, and
show_in_gods_eye_view can open a photo. A plain sl=google link only arms the
point and waits for OPEN, so it never bills a key without a click.

Embed pages show an open photo in an overlay that Esc closes. On-screen
strings are translated into es, ru, zh-CN and zh-Hant. Covered by unit tests
and three new steps in the Street Level browser suite.
This commit is contained in:
Said Turksever committed 2026-11-03 14:32:02 +00:00
1 parent f3adccd01a
commit 98de41c94a
64 files changed
+4147 -66

No files matched your search

+164 -7
View File
@@ -11,6 +11,7 @@ import {
decodeLayerStateParams,
encodeLayerStateParams,
} from '../data/layerState.js';
import { encodeIdSwitches } from '../data/idSwitches.js';
import { RETIRED_STYLES } from '../visualStylePolicy.js';
/** Visual styles by internal name, with the name share links use. */
@@ -65,6 +66,63 @@ const FOLLOWABLE = Object.freeze({
export const VIEW_FOLLOW_KINDS = Object.freeze(Object.keys(FOLLOWABLE));
/**
* Street-level imagery sources a view can open, the layer that shows them and
* the map a source needs (Google's terms allow Street View beside Google maps
* only). Literal here: this module stays portable.
*/
const STREET_LEVEL_LAYER = 'street-level';
export const VIEW_STREET_LEVEL_PROVIDERS = Object.freeze([
'google',
'mapillary',
'kartaview',
'panoramax',
]);
const STREET_LEVEL_MAP = Object.freeze({ google: 'photoreal' });
const STREET_LEVEL_PARAM = 'sl';
const EARTH_RADIUS_M = 6_371_000;
/** Above this a camera frames a region, not a street: photos open under it. */
const LOOK_AT_MAX_ALTITUDE_M = 20_000;
/** Flatter than this the look-at point is at the horizon: use the camera's. */
const LOOK_AT_MIN_PITCH_DEG = -5;
/** Further ahead than this the camera frames a region: use its own point. */
const LOOK_AT_MAX_DISTANCE_M = 10_000;
/**
* The ground point a street-scale camera looks at: straight below it when it
* looks down, else ahead along its heading by altitude / tan(pitch). A camera
* with no altitude, above street scale, aimed at the horizon, or looking
* further than 10 km ahead gives its own point. Longitude wraps at the
* antimeridian.
*/
function lookAtPoint(camera) {
const pitch = Number(camera.pitch_deg ?? -90);
const altitude = Number(camera.altitude_m);
if (
!(altitude > 0) ||
altitude > LOOK_AT_MAX_ALTITUDE_M ||
!(pitch > -89) ||
pitch > LOOK_AT_MIN_PITCH_DEG
)
return { lat: camera.lat, lon: camera.lon };
const ground = altitude / Math.tan((-pitch * Math.PI) / 180);
if (ground > LOOK_AT_MAX_DISTANCE_M)
return { lat: camera.lat, lon: camera.lon };
const heading = ((Number(camera.heading_deg) || 0) * Math.PI) / 180;
const dLat =
((ground * Math.cos(heading)) / EARTH_RADIUS_M) * (180 / Math.PI);
const cosLat = Math.cos((camera.lat * Math.PI) / 180) || 1e-6;
const dLon =
((ground * Math.sin(heading)) / (EARTH_RADIUS_M * cosLat)) *
(180 / Math.PI);
const lon = camera.lon + dLon;
return {
lat: clamp(camera.lat + dLat, -90, 90),
lon: lon > 180 ? lon - 360 : lon < -180 ? lon + 360 : lon,
};
}
/** Annotation kinds the app draws, as in its annotate_map action. */
export const VIEW_ANNOTATION_TYPES = Object.freeze([
'pin',
@@ -162,6 +220,21 @@ export const VIEW_PROPERTIES = Object.freeze({
additionalProperties: false,
},
}),
street_level: Object.freeze({
type: 'object',
description:
'Open street-level photos at a point: Google Street View (google; the ' +
'map becomes Google 3D), Mapillary, KartaView or Panoramax. lat/lon ' +
'default to the spot the camera looks at. The app flies there and ' +
'opens the nearest photo; a plain link with google only arms it, ' +
'leaving the billed load to a click. Not with follow.',
properties: {
provider: { type: 'string', enum: [...VIEW_STREET_LEVEL_PROVIDERS] },
lat: { type: 'number', minimum: -90, maximum: 90 },
lon: { type: 'number', minimum: -180, maximum: 180 },
},
additionalProperties: false,
}),
follow: Object.freeze({
type: 'object',
description:
@@ -251,6 +324,7 @@ export function createView({
map = null,
follow = null,
annotations = [],
street_level: streetLevel = null,
} = {}) {
if (!Number.isFinite(camera?.lat) || !Number.isFinite(camera?.lon))
throw new TypeError('A view needs a camera lat and lon');
@@ -264,10 +338,37 @@ export function createView({
throw new TypeError(`Cannot follow a ${follow.kind}`);
if (follow?.cockpit === true && !followed.cockpit)
throw new TypeError(`A ${follow.kind} has no cockpit view`);
let street = null;
if (streetLevel) {
if (follow)
throw new TypeError(
'A view cannot both follow an entity and open street-level photos',
);
const provider = streetLevel.provider ?? null;
if (provider !== null && !VIEW_STREET_LEVEL_PROVIDERS.includes(provider))
throw new TypeError(`Unknown street-level source: ${provider}`);
const needs = provider ? STREET_LEVEL_MAP[provider] || null : null;
if (needs && map !== null && map !== needs)
throw new TypeError(
`${provider} street-level imagery shows only on the ${needs} map`,
);
if (needs) map = needs;
// The point defaults to where the camera looks: a view "of X" opens
// photos at X, also when the camera sits behind it.
const seen = lookAtPoint(camera);
const lat = latitude(streetLevel.lat) ?? seen.lat;
const lon = longitude(streetLevel.lon) ?? seen.lon;
street = Object.freeze({
...(provider ? { provider } : {}),
lat: round(clamp(lat, -90, 90), 5),
lon: round(clamp(lon, -180, 180), 5),
});
}
const enabled = new Set(
layers.filter((layer) => REGISTERED_LAYER_IDS.includes(layer)),
);
if (followed) enabled.add(followed.layer);
if (street) enabled.add(STREET_LEVEL_LAYER);
return Object.freeze({
camera: Object.freeze({
lat: round(clamp(camera.lat, -90, 90), 4),
@@ -296,6 +397,7 @@ export function createView({
.map(annotationOf)
.filter(Boolean),
),
street_level: street,
});
}
@@ -321,8 +423,29 @@ export function viewToParams(view) {
...state.options[followed.owner],
[followed.key]: view.follow.id,
};
// The restored layer lights the source the photos come from.
const provider = view.street_level?.provider;
if (provider)
state.options[STREET_LEVEL_LAYER] = {
...state.options[STREET_LEVEL_LAYER],
mapillary: provider === 'mapillary',
providerSwitches: encodeIdSwitches(
VIEW_STREET_LEVEL_PROVIDERS.filter((id) => id !== 'mapillary').map(
(id) => [id, id === provider],
),
),
};
encodeLayerStateParams(params, state);
}
if (view.street_level)
params.set(
STREET_LEVEL_PARAM,
[
view.street_level.provider ?? '',
view.street_level.lat.toFixed(5),
view.street_level.lon.toFixed(5),
].join(','),
);
if (view.annotations.length) {
const encoded = JSON.stringify(view.annotations);
if (encoded.length <= MAX_ANNOTATION_PARAM_CHARS)
@@ -345,6 +468,40 @@ export function annotationsFromParams(params) {
}
}
/**
* The street-level photos a share link opens (`sl=<source>,<lat>,<lon>`, the
* source optional), or null.
*/
export function streetLevelFromParams(params) {
const raw = params.get(STREET_LEVEL_PARAM);
if (!raw) return null;
// Three fields, plain decimal degrees: that alone bounds the value.
const parts = raw.split(',');
if (parts.length !== 3) return null;
const [provider, lat, lon] = parts;
if (provider && !VIEW_STREET_LEVEL_PROVIDERS.includes(provider)) return null;
// Plain decimal degrees only: no exponents, hex or blanks.
const DECIMAL = /^-?\d{1,3}(\.\d{1,8})?$/;
if (!DECIMAL.test(lat) || !DECIMAL.test(lon)) return null;
const point = { lat: latitude(Number(lat)), lon: longitude(Number(lon)) };
if (point.lat === undefined || point.lon === undefined) return null;
return { ...(provider ? { provider } : {}), ...point };
}
/** The entity a decoded layer state follows, or null. */
function followFromState(state) {
for (const [kind, followed] of Object.entries(FOLLOWABLE)) {
const id = state?.options?.[followed.owner]?.[followed.key];
if (id !== null && id !== undefined) return { kind, id: String(id) };
}
return null;
}
/** The entity a share link follows, or null. */
export function followFromParams(params) {
return followFromState(decodeLayerStateParams(params));
}
/** The view a set of share-link hash parameters restores, or null. */
export function viewFromParams(params) {
const lat = Number.parseFloat(params.get('lat'));
@@ -355,13 +512,12 @@ export function viewFromParams(params) {
return Number.isFinite(value) ? value : undefined;
};
const state = decodeLayerStateParams(params);
let follow = null;
for (const [kind, followed] of Object.entries(FOLLOWABLE)) {
const id = state?.options?.[followed.owner]?.[followed.key];
if (id !== null && id !== undefined && !follow)
follow = { kind, id: String(id) };
}
const follow = followFromState(state);
const map = params.get('map');
// A link is untrusted input: its photos win over a map their source cannot
// show on, and a followed entity keeps the camera.
const street = follow ? null : streetLevelFromParams(params);
const needs = street?.provider ? STREET_LEVEL_MAP[street.provider] : null;
return createView({
camera: {
lat,
@@ -376,9 +532,10 @@ export function viewFromParams(params) {
: Object.hasOwn(STYLES_BY_URL_NAME, params.get('style'))
? STYLES_BY_URL_NAME[params.get('style')]
: null,
map: VIEW_MAPS.includes(map) ? map : null,
map: needs ? needs : VIEW_MAPS.includes(map) ? map : null,
follow,
annotations: annotationsFromParams(params),
street_level: street,
});
}
+373
View File
@@ -127,6 +127,379 @@ test('annotations travel in the link, keeping only what the app draws', async ()
assert.equal(viewToParams(many).has('an'), false);
});
test('street-level photos travel in the link, light their source and bring their map', async () => {
const { streetLevelFromParams, VIEW_STREET_LEVEL_PROVIDERS } =
await import('./index.js');
const { decodeLayerStateParams } = await import('../data/layerState.js');
assert.deepEqual(VIEW_STREET_LEVEL_PROVIDERS, [
'google',
'mapillary',
'kartaview',
'panoramax',
]);
const view = createView({
camera: { lat: 38.5799, lon: -121.4937, altitude_m: 400 },
street_level: { provider: 'google' },
});
assert.equal(view.map, 'photoreal', 'Street View brings Google 3D');
assert.deepEqual(view.layers, ['street-level']);
assert.deepEqual(view.street_level, {
provider: 'google',
lat: 38.5799,
lon: -121.4937,
});
const params = viewToParams(view);
assert.equal(params.get('sl'), 'google,38.57990,-121.49370');
assert.deepEqual(viewFromParams(params), view);
const state = decodeLayerStateParams(params);
assert.deepEqual(state.enabledLayerIds, ['street-level']);
assert.equal(state.options['street-level'].mapillary, false);
assert.equal(
state.options['street-level'].providerSwitches,
'google-1*kartaview-0*panoramax-0',
'Street View on, KartaView off',
);
const mapillary = createView({
camera: { lat: 1, lon: 2 },
map: 'osm',
street_level: { provider: 'mapillary', lat: 1.00001, lon: 2.00001 },
});
assert.equal(mapillary.map, 'osm', 'Mapillary shows on any map');
assert.deepEqual(viewFromParams(viewToParams(mapillary)), mapillary);
const lit = decodeLayerStateParams(viewToParams(mapillary)).options[
'street-level'
];
assert.equal(lit.mapillary, true);
assert.equal(
lit.providerSwitches,
'google-0*kartaview-0*panoramax-0',
'a Mapillary link lights Mapillary only',
);
const anySource = createView({
camera: { lat: 1, lon: 2 },
street_level: {},
});
assert.deepEqual(anySource.street_level, { lat: 1, lon: 2 });
assert.equal(viewToParams(anySource).get('sl'), ',1.00000,2.00000');
assert.deepEqual(viewFromParams(viewToParams(anySource)), anySource);
assert.throws(
() =>
createView({
camera: { lat: 1, lon: 2 },
map: 'osm',
street_level: { provider: 'google' },
}),
/photoreal/,
);
assert.throws(
() =>
createView({
camera: { lat: 1, lon: 2 },
street_level: { provider: 'openstreetcam' },
}),
/Unknown street-level source/,
);
assert.equal(
streetLevelFromParams(new URLSearchParams('sl=google,x,y')),
null,
);
assert.equal(streetLevelFromParams(new URLSearchParams('sl=bing,1,2')), null);
assert.equal(streetLevelFromParams(new URLSearchParams('lat=1')), null);
assert.equal(createView({ camera: { lat: 1, lon: 2 } }).street_level, null);
});
test('street-level photos: a tilted camera opens them where it looks, a link cannot pair them with the wrong map, and follow is refused', async () => {
const { streetLevelFromParams } = await import('./index.js');
// Looking north from 1,000 m at 45°: the ground point is ~1 km north.
const tilted = createView({
camera: {
lat: 48.8494,
lon: 2.2945,
altitude_m: 1000,
heading_deg: 0,
pitch_deg: -45,
},
street_level: { provider: 'google' },
});
assert.ok(
tilted.street_level.lat > 48.858 && tilted.street_level.lat < 48.859,
String(tilted.street_level.lat),
);
assert.equal(tilted.street_level.lon, 2.2945);
const down = createView({
camera: { lat: 1, lon: 2, altitude_m: 1000 },
street_level: {},
});
assert.deepEqual(down.street_level, { lat: 1, lon: 2 });
// A hand-edited link: the photos win over the map.
const link = viewFromParams(
new URLSearchParams('v=2&lat=1&lon=2&map=osm&sl=google,1,2'),
);
assert.equal(link.map, 'photoreal');
assert.deepEqual(link.street_level, { provider: 'google', lat: 1, lon: 2 });
assert.throws(
() =>
createView({
camera: { lat: 1, lon: 2 },
follow: { kind: 'aircraft', id: 'a1' },
street_level: {},
}),
/cannot both follow/,
);
// A followed link drops its photos rather than fight over the camera.
const followed = viewFromParams(
viewToParams(
createView({
camera: { lat: 1, lon: 2 },
follow: { kind: 'satellite', id: '25544' },
}),
),
);
assert.equal(followed.street_level, null);
// Strict parsing: three fields, real numbers, in range, bounded length.
for (const bad of [
'google,1',
'google,1,2,3',
'google,1abc,2',
'google,91,0',
'google,,2',
'google,1,2'.padEnd(65, '0'),
])
assert.equal(
streetLevelFromParams(new URLSearchParams({ sl: bad })),
null,
bad,
);
});
test('the look-at default is street-scale only, follows the heading, and wraps at the antimeridian', async () => {
const { followFromParams, streetLevelFromParams } =
await import('./index.js');
const at = (camera) =>
createView({ camera, street_level: { provider: 'mapillary' } })
.street_level;
// Looking east from 1,000 m at 45° in Paris: ~1 km east is ~0.0137° of longitude.
const east = at({
lat: 48.85,
lon: 2.2945,
altitude_m: 1000,
heading_deg: 90,
pitch_deg: -45,
});
assert.ok(Math.abs(east.lon - (2.2945 + 0.01365)) < 0.0005, String(east.lon));
assert.ok(Math.abs(east.lat - 48.85) < 0.0002, String(east.lat));
// Looking west from the same place lands west.
assert.ok(
at({
lat: 48.85,
lon: 2.2945,
altitude_m: 1000,
heading_deg: 270,
pitch_deg: -45,
}).lon < 2.2945,
);
// At the horizon, with no altitude, or above street scale: the camera's own point.
assert.deepEqual(at({ lat: 1, lon: 2, altitude_m: 1000, pitch_deg: 0 }), {
provider: 'mapillary',
lat: 1,
lon: 2,
});
assert.deepEqual(at({ lat: 1, lon: 2, pitch_deg: -30 }), {
provider: 'mapillary',
lat: 1,
lon: 2,
});
assert.deepEqual(at({ lat: 1, lon: 2, altitude_m: 50_000, pitch_deg: -30 }), {
provider: 'mapillary',
lat: 1,
lon: 2,
});
// Across the antimeridian the longitude wraps instead of clamping.
const wrapped = at({
lat: 0,
lon: 179.999,
altitude_m: 1000,
heading_deg: 90,
pitch_deg: -45,
});
assert.ok(wrapped.lon < -179.9, String(wrapped.lon));
// A followed link keeps its camera: the photos are dropped even when both are in the hash.
const followed = viewToParams(
createView({
camera: { lat: 1, lon: 2 },
follow: { kind: 'satellite', id: '25544' },
}),
);
followed.set('sl', 'google,1.00000,2.00000');
assert.deepEqual(followFromParams(followed), {
kind: 'satellite',
id: '25544',
});
assert.equal(viewFromParams(followed).street_level, null);
assert.equal(followFromParams(new URLSearchParams('v=2&lat=1&lon=2')), null);
// Strict decimal degrees: no exponents, hex, blanks or over-long values.
for (const bad of [
'google,1e1,2',
'google,0x10,2',
'google, 1,2',
'google,1.,2',
`google,${'1.0000000'.padEnd(60, '0')},2`,
])
assert.equal(
streetLevelFromParams(new URLSearchParams({ sl: bad })),
null,
bad,
);
assert.deepEqual(
streetLevelFromParams(new URLSearchParams({ sl: ',-1.5,2' })),
{ lat: -1.5, lon: 2 },
);
});
test('the look-at thresholds are pinned: 20 km up, -5° of pitch, 10 km ahead', () => {
const at = (camera) => createView({ camera, street_level: {} }).street_level;
const own = { lat: 1, lon: 2 };
const moved = (point) => point.lat !== own.lat || point.lon !== own.lon;
// Altitude ceiling, at a steep pitch that keeps the distance under 10 km.
assert.ok(
moved(at({ ...own, altitude_m: 19_999, pitch_deg: -70 })),
'19,999 m applies',
);
assert.ok(
!moved(at({ ...own, altitude_m: 20_001, pitch_deg: -70 })),
'20,001 m does not',
);
// Pitch cutoff, at 100 m so the distance cap cannot decide it (1.4 km ahead).
assert.ok(
moved(at({ ...own, altitude_m: 100, pitch_deg: -6 })),
'-6° applies',
);
assert.ok(
!moved(at({ ...own, altitude_m: 100, pitch_deg: -4 })),
'-4° does not',
);
// Distance cap, pinned either side of 10 km at 1,000 m: -5.8° looks 9.84 km
// ahead, -5.6° 10.2 km.
assert.ok(
moved(at({ ...own, altitude_m: 1000, pitch_deg: -5.8 })),
'9.84 km ahead applies',
);
assert.ok(
!moved(at({ ...own, altitude_m: 1000, pitch_deg: -5.6 })),
'10.2 km ahead does not',
);
assert.ok(
!moved(at({ ...own, altitude_m: 10_000, pitch_deg: -30 })),
'17 km ahead does not',
);
assert.ok(
moved(at({ ...own, altitude_m: 5_000, pitch_deg: -30 })),
'8.7 km ahead applies',
);
// Near-vertical stays put (no tan blow-up).
assert.ok(!moved(at({ ...own, altitude_m: 1000, pitch_deg: -89.5 })));
// Western wrap and the pole clamp.
const west = at({
lat: 0,
lon: -179.999,
altitude_m: 1000,
heading_deg: 270,
pitch_deg: -45,
});
assert.ok(west.lon > 179.9, String(west.lon));
const pole = at({
lat: 89.9995,
lon: 0,
altitude_m: 1000,
heading_deg: 0,
pitch_deg: -45,
});
assert.ok(pole.lat <= 90, String(pole.lat));
});
test('sl rejects a bad longitude slot and over-precise values, and no length bound hides the regex', async () => {
const { streetLevelFromParams } = await import('./index.js');
for (const bad of [
'google,1,1e1',
'google,1,0x10',
'google,1, 2',
'google,1,2.',
'google,1.123456789,2',
'google,1,2.123456789',
])
assert.equal(
streetLevelFromParams(new URLSearchParams({ sl: bad })),
null,
bad,
);
assert.deepEqual(
streetLevelFromParams(
new URLSearchParams({ sl: 'google,-89.12345678,179.12345678' }),
),
{ provider: 'google', lat: -89.12345678, lon: 179.12345678 },
);
});
test('KartaView photos travel in a link and light KartaView alone, on any map', async () => {
const { streetLevelFromParams } = await import('./index.js');
const { decodeLayerStateParams } = await import('../data/layerState.js');
const view = createView({
camera: { lat: 52.52, lon: 13.405, altitude_m: 400 },
map: 'osm',
street_level: { provider: 'kartaview' },
});
assert.equal(view.map, 'osm', 'KartaView needs no particular map');
assert.deepEqual(view.layers, ['street-level']);
const params = viewToParams(view);
assert.equal(params.get('sl'), 'kartaview,52.52000,13.40500');
assert.deepEqual(viewFromParams(params), view);
const lit = decodeLayerStateParams(params).options['street-level'];
assert.equal(lit.mapillary, false);
assert.equal(
lit.providerSwitches,
'google-0*kartaview-1*panoramax-0',
'KartaView on, the others off',
);
assert.deepEqual(
streetLevelFromParams(new URLSearchParams({ sl: 'kartaview,1,2' })),
{
provider: 'kartaview',
lat: 1,
lon: 2,
},
);
});
test('Panoramax photos travel in a link and light Panoramax alone, on any map', async () => {
const { streetLevelFromParams } = await import('./index.js');
const { decodeLayerStateParams } = await import('../data/layerState.js');
const view = createView({
camera: { lat: 48.8874, lon: 2.3495, altitude_m: 400 },
map: 'osm',
street_level: { provider: 'panoramax' },
});
assert.equal(view.map, 'osm', 'Panoramax needs no particular map');
assert.deepEqual(view.layers, ['street-level']);
const params = viewToParams(view);
assert.equal(params.get('sl'), 'panoramax,48.88740,2.34950');
assert.deepEqual(viewFromParams(params), view);
const lit = decodeLayerStateParams(params).options['street-level'];
assert.equal(lit.mapillary, false);
assert.equal(
lit.providerSwitches,
'google-0*kartaview-0*panoramax-1',
'Panoramax on, the others off',
);
assert.deepEqual(
streetLevelFromParams(new URLSearchParams({ sl: 'panoramax,1,2' })),
{ provider: 'panoramax', lat: 1, lon: 2 },
);
});
test('a view naming the retired Snow style opens on Normal', () => {
const camera = { lat: 1, lon: 2 };
assert.equal(createView({ camera, style: 'snow' }).style, 'normal');