The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.
JavaScript
"""Map-site URL parsers (engine/mapsites.py).
Server-side on purpose: URL formats race sites that change without notice and
the extension can't be updated remotely — so every rule is here, where an app
update fixes it. The contract: a recognized map site always returns its site
id (coordinates/title/imagery date when the URL carries them, None when it
doesn't), anything else returns None, and nothing ever raises.
"""
import json
import math
from pathlib import Path
import pytest
from azimut.engine.mapsites import _mercator_y, parse_map_url
_RECORDED = json.loads(
(Path(__file__).parent / "fixtures" / "map-sites.json").read_text(encoding="utf-8")
)
RECORDINGS = _RECORDED["recordings"]
ROUNDING = _RECORDED["rounding"]
LAT, LON, Z = 45.197652, 11.777344, 6
#: How closely the parse has to predict how far Earth's picture moved. Earth's
#: own drawing agrees with its formula to about a thousandth at a 35° field of
#: view, and a few thousandths at 60°, which nobody opens by hand.
EARTH_SCALE_TOLERANCE = 0.004
#: What Earth writes after ``/data=``: its 2D map, as an analyst's own URL had
#: it, and a view after pressing Earth's "3D" button.
EARTH_2D = "CgRCAggCMikKJwolCiExa01obVdjV2t6UmJfTFhSbDFjQ3JPZEJla1p4TWJGVksgAToDCgEwQgIIAEoICI7Vld4EEAE"
EARTH_3D = "CgRCAggBKAJCAggASg0I____________ARAA"
# Mirrors frontend/src/lib/maplinks.js exactly: whatever Azimut can send the
# user out to, the backend must be able to read back.
OPEN_IN_LINKS = [
(f"https://www.google.com/maps/@{LAT},{LON},{Z}z", "google-maps", Z),
(f"https://www.google.com/maps/@{LAT},{LON},{Z}z/data=!3m1!1e3", "google-maps", Z),
# a link has no ground in it, so Earth's scale waits for the map to move
(f"https://earth.google.com/web/@{LAT},{LON},0a,2733274d,35y,0h,0t,0r", "google-earth", None),
(f"https://maps.apple.com/?ll={LAT},{LON}&z={Z}&map=satellite", "apple-maps", Z),
(f"https://www.bing.com/maps?cp={LAT}~{LON}&lvl={Z}&style=h", "bing-maps", Z),
(f"https://yandex.com/maps/?ll={LON},{LAT}&z={Z}&l=sat", "yandex-maps", Z),
(f"https://browser.dataspace.copernicus.eu/?zoom={Z}&lat={LAT}&lng={LON}",
"copernicus-browser", Z),
(f"https://zoom.earth/maps/satellite/#view={LAT},{LON},{Z}z", "zoom-earth", Z),
(f"https://satellites.pro/#{LAT},{LON},{Z}", "satellites-pro", Z),
]
@pytest.mark.parametrize("url,site,zoom", OPEN_IN_LINKS)
def test_every_open_in_link_round_trips(url, site, zoom):
p = parse_map_url(url)
assert p["site"] == site
assert p["lat"] == LAT and p["lon"] == LON
assert p["zoom"] == zoom
def test_satellites_pro_redirects_to_a_country_path():
# the bare link is what the app sends; the site answers it with a country
# path of its own and keeps the fragment, which is where the view lives
for url in (
f"https://satellites.pro/#{LAT},{LON},{Z}",
f"https://satellites.pro/plan/France_map#{LAT},{LON},{Z}",
f"https://satellites.pro/France_map#{LAT},{LON},{Z}",
):
p = parse_map_url(url)
assert (p["site"], p["lat"], p["lon"], p["zoom"]) == ("satellites-pro", LAT, LON, Z)
def test_explicit_satellite_urls_are_classified():
urls = [
f"https://www.google.com/maps/@{LAT},{LON},2000m/data=!3m1!1e3",
f"https://earth.google.com/web/@{LAT},{LON},0a,1000d,35y,0h,0t,0r",
f"https://maps.apple.com/?ll={LAT},{LON}&z={Z}&t=k",
f"https://maps.apple.com/?ll={LAT},{LON}&z={Z}&map=satellite",
f"https://maps.apple.com/?ll={LAT},{LON}&z={Z}&map=hybrid",
f"https://www.bing.com/maps?cp={LAT}~{LON}&lvl={Z}&style=h",
f"https://yandex.com/maps/?ll={LON},{LAT}&z={Z}&l=sat",
f"https://zoom.earth/#view={LAT},{LON},{Z}z",
f"https://satellites.pro/#{LAT},{LON},{Z}",
f"https://browser.dataspace.copernicus.eu/?zoom={Z}&lat={LAT}&lng={LON}",
]
assert all(parse_map_url(url)["imagery_mode"] == "satellite" for url in urls)
def test_generic_map_urls_are_not_guessed_as_satellite():
urls = [
f"https://www.google.com/maps/@{LAT},{LON},{Z}z",
f"https://www.bing.com/maps?cp={LAT}~{LON}&lvl={Z}&style=r",
f"https://yandex.com/maps/?ll={LON},{LAT}&z={Z}&l=map",
f"https://maps.apple.com/?ll={LAT},{LON}&z={Z}&t=m",
f"https://maps.apple.com/?ll={LAT},{LON}&z={Z}&map=explore",
f"https://www.openstreetmap.org/#map={Z}/{LAT}/{LON}",
]
assert all(parse_map_url(url)["imagery_mode"] is None for url in urls)
def test_google_maps_forms():
p = parse_map_url(
"https://www.google.com/maps/place/Tour+Eiffel/@48.8583701,2.2944813,17z/data=!3m1!4b1"
)
assert (p["site"], p["lat"], p["zoom"], p["title"]) == (
"google-maps", 48.8583701, 17, "Tour Eiffel")
# a pinned place without an @ viewport — !3d/!4d
p = parse_map_url("https://www.google.com/maps/place/x/data=!8m2!3d48.85!4d2.29")
assert (p["lat"], p["lon"]) == (48.85, 2.29)
# a share short-link: recognized, no coordinates
assert parse_map_url("https://maps.app.goo.gl/AbCdEf123")["lat"] is None
# google search is not a map
assert parse_map_url("https://www.google.com/search?q=eiffel+tower") is None
def test_google_earth_heading_and_search_name():
p = parse_map_url(
"https://earth.google.com/web/search/Palais%20de%20l%27%C3%89lys%C3%A9e/"
"@48.8704156,2.3167542,79a,684d,35y,41.12345h,45.18471069t,0r"
)
assert p["title"] == "Palais de l'Élysée"
assert p["bearing"] == pytest.approx(41.12345)
assert p["zoom"] is None # Earth encodes camera distance, not web zoom
@pytest.mark.parametrize("url,title", [
("https://www.bing.com/maps?q=tour+eiffel&cp=48.85~2.29&lvl=17", "tour eiffel"),
("https://yandex.com/maps/?text=tour%20eiffel&ll=2.29,48.85&z=17", "tour eiffel"),
("https://maps.apple.com/?q=Tour+Eiffel&ll=48.85,2.29&z=17", "Tour Eiffel"),
("https://www.openstreetmap.org/search?query=tour+eiffel#map=17/48.85/2.29", "tour eiffel"),
# nothing named in the URL → the app titles by coordinates instead
("https://www.google.com/maps/@48.85,2.29,17z", None),
("https://satellites.pro/#48.85,2.29,17", None),
])
def test_place_names_become_the_suggested_title(url, title):
assert parse_map_url(url)["title"] == title
def test_imagery_dates_only_where_urls_honestly_carry_them():
p = parse_map_url(
"https://browser.dataspace.copernicus.eu/?zoom=12&lat=45.19&lng=11.77"
"&fromTime=2024-07-01T00%3A00%3A00.000Z&toTime=2024-07-01T23%3A59%3A59.999Z"
)
assert p["imagery_date"] == "2024-07-01"
# zoom earth daily date, single-digit parts normalized
p = parse_map_url("https://zoom.earth/maps/daily/#view=45.19,11.77,8z/date=2025-7-4")
assert p["imagery_date"] == "2025-07-04"
# junk dates are dropped, not passed through
assert parse_map_url("https://zoom.earth/#view=45.19,11.77,8z/date=2025-99-99")[
"imagery_date"] is None
# sites whose URLs carry no date — never invented
assert parse_map_url("https://www.google.com/maps/@48.85,2.29,17z")["imagery_date"] is None
def test_refusals_and_malformed_input():
# non-map sites: the extension stays out
assert parse_map_url("https://twitter.com/somebody/status/1") is None
assert parse_map_url("https://en.wikipedia.org/wiki/Eiffel_Tower") is None
# non-web protocols
assert parse_map_url("chrome://settings") is None
assert parse_map_url("about:blank") is None
assert parse_map_url("file:///home/user/map.html") is None
# garbage never raises
for junk in ("", "not a url", "https://", "https://www.google.com/maps/@nope",
"https://www.google.com/maps/place/%E0%A4%A/@48.85,2.29,17z"):
parse_map_url(junk)
# out-of-world coordinates are rejected, not filed
assert parse_map_url("https://www.openstreetmap.org/#map=17/98.0/2.29")["lat"] is None
# malformed bing cp degrades to "known site, nothing parsed"
assert parse_map_url("https://www.bing.com/maps?cp=garbage&lvl=9")["lat"] is None
# -- what kind of camera the URL describes --------------------------------------
#
# The rule the overlay hangs on: geometry the app *computes* (a search grid, a
# sun arc, a measured line) is Web Mercator arithmetic, so it is only honest on
# a straight-down 2D view. A media pin the analyst places by hand is computed
# from nothing and stays allowed everywhere — which is why this field says what
# the camera *is*, and never what may be drawn.
@pytest.mark.parametrize(
"url,kind",
[
# Street View: the 3a camera block, whatever else rides on it
(f"https://www.google.com/maps/@{LAT},{LON},3a,75y,90h,90t", "streetview"),
(
f"https://www.google.com/maps/place/Tour+Eiffel/@{LAT},{LON},3a,15y,180h,80t/data=x",
"streetview",
),
# a pitched 3D camera on Google Maps
(f"https://www.google.com/maps/@{LAT},{LON},1000m,45t", "tilted"),
# …and 0t is not pitched at all
(f"https://www.google.com/maps/@{LAT},{LON},{Z}z,0t", "map"),
(f"https://www.google.com/maps/@{LAT},{LON},{Z}z", "map"),
# Earth's 2D map is a map, and pitched (its 3D button) it is not
(f"https://earth.google.com/web/@{LAT},{LON},0a,1000d,35y,0h,0t,0r", "map"),
(f"https://earth.google.com/web/@{LAT},{LON},0a,600d,35y,20h,60t,0r", "tilted"),
# flat-map renderers with no other mode to be in
(f"https://www.openstreetmap.org/#map={Z}/{LAT}/{LON}", "map"),
(f"https://zoom.earth/#view={LAT},{LON},{Z}z", "map"),
(f"https://www.bing.com/maps?cp={LAT}~{LON}&lvl={Z}", "map"),
(f"https://maps.apple.com/?ll={LAT},{LON}&z={Z}", "map"),
],
)
def test_view_kind_reads_the_camera_out_of_the_url(url, kind):
assert parse_map_url(url)["view_kind"] == kind
def test_satellite_is_still_a_straight_down_map():
"""Google drops the zoom in satellite view and quotes a viewport height in
metres instead. The camera did not move — only the way the URL describes it
— so the view is a map, and the overlay's tools are not thrown off a whole
imagery mode by a change of notation.
The camera and the flattening are both fine, so ``geometry`` says yes. What
is missing without a window height is the *scale*: no zoom, no
``scale_source``, and the drawing waits for one (`maptools.js`'s verdict).
"""
parsed = parse_map_url(f"https://www.google.com/maps/@{LAT},{LON},1053m/data=!3m1!1e3")
assert parsed["view_kind"] == "map"
assert (parsed["lat"], parsed["lon"]) == (LAT, LON)
assert parsed["zoom"] is None
assert parsed["scale_source"] is None
assert parsed["geometry"] is True
def test_earths_2d_map_is_web_mercator_with_its_scale_in_the_url():
"""Earth, and Maps in Earth mode, with the camera level.
Earth's 2D map was registered screenshot against screenshot
(``tests/fixtures/earth-scale.json``): Web Mercator, drawn about the middle
of the window, ``2·d·tan(y/2)`` metres from top to bottom. So it is a map
like any other, with a projection and a scale read out of its URL.
Maps in Earth mode keeps its flattening and states no scale: Maps rewrites a
level ``a`` camera into ``,3231m`` as soon as it lands, so the view waits
for that instead.
"""
earth = parse_map_url(
f"https://earth.google.com/web/@{LAT},{LON},146.5a,666.25d,35y,0h,0t,0r", height_px=1000
)
assert earth["view_kind"] == "map"
assert earth["projection"] == "webmercator"
assert earth["geometry"] is True
assert earth["scale_source"] == "distance"
assert earth["far"] is False
maps = parse_map_url(f"https://www.google.com/maps/@{LAT},{LON},336a,35y,0t/data=!3m1!1e3")
assert maps["view_kind"] == "map"
assert maps["geometry"] is True
assert maps["scale_source"] is None
assert (maps["lat"], maps["lon"]) == (LAT, LON)
def test_only_earths_3d_camera_turns_into_a_globe_far_out():
"""Earth's 2D map stays a flat Mercator however far out it goes (all of
Europe on screen, and 400 km out measured). Its 3D mode is a perspective
camera on a sphere, and past ``LEVEL_CEILING_M`` that is a globe. The address
bar says which one it is in its ``data=`` blob."""
far = f"https://earth.google.com/web/@{LAT},{LON},-0a,202330.09623202d,35y,0h,0t,0r"
flat = parse_map_url(f"{far}/data={EARTH_2D}?authuser=0", height_px=934)
assert (flat["view_kind"], flat["geometry"], flat["far"]) == ("map", True, False)
assert flat["scale_source"] == "distance"
globe = parse_map_url(f"{far}/data={EARTH_3D}", height_px=934)
assert (globe["view_kind"], globe["geometry"], globe["far"]) == ("globe", False, True)
# in close, the 3D camera is still a map
near = f"https://earth.google.com/web/@{LAT},{LON},146.5a,666.25d,35y,0h,0t,0r/data={EARTH_3D}"
assert parse_map_url(near)["view_kind"] == "map"
# a bare link opens the 2D map, and a blob nobody can read is taken as 3D,
# whose rules are the stricter ones
assert parse_map_url(far)["view_kind"] == "map"
assert parse_map_url(f"{far}/data=AAAA")["view_kind"] == "globe"
def test_earth_states_no_scale_for_a_camera_it_has_not_placed():
"""``d`` is a distance to the ground only once Earth has put the camera
there, which it does by writing the ground's height into ``a``."""
def scale(camera: str) -> str | None:
url = f"https://earth.google.com/web/@{LAT},{LON},{camera}"
return parse_map_url(url, height_px=1000)["scale_source"]
# Earth's own writing, over land and over the sea
assert scale("198.8634048a,2196.68868628d,35y,0h,0t,0r") == "distance"
assert scale("-0a,202330.09623202d,35y,0h,0t,0r") == "distance"
# a link, written as 0a with a whole d: over 200 m of ground it is drawn 7%
# nearer than it says, so it waits for the map to move
assert scale("0a,3000d,35y,0h,0t,0r") is None
# closer than Earth's map lets a camera come: loading a link, Earth once
# wrote this for a camera 1528 m up, where a was not the ground at all
assert scale("1518.44008742a,10.0137594d,35y,0h,0t,0r") is None
# a height no ground has, and a field of view that is missing or not one
assert scale("-7546.56236661a,8346.46045906d,35y,0h,0t,0r") is None
assert scale("198.86a,2196.69d,0y,0h,0t,0r") is None
assert scale("198.86a,2196.69d,0h,0t,0r") is None
def _earth_cases() -> list[dict]:
path = Path(__file__).parent / "fixtures" / "earth-scale.json"
return json.loads(path.read_text(encoding="utf-8"))["cases"]
def test_earths_scale_is_what_its_screenshots_measured():
"""Every case in ``tests/fixtures/earth-scale.json``, predicted from its URL.
Each one is a camera Earth placed, opened again a known step east and north,
and the screenshots registered to a hundredth of a pixel. The parse of the
base URL, through Web Mercator, has to say how far the picture moved — at
three window shapes, two fields of view, three latitudes, over mountains and
400 km out.
"""
cases = _earth_cases()
assert len(cases) >= 6
for case in cases:
parsed = parse_map_url(case["base"], height_px=case["window"]["h"])
assert parsed["scale_source"] == "distance", case["id"]
world = 256 * 2 ** parsed["zoom"]
east = -case["east"]["d_lon"] / 360 * world
step = case["north"]["d_lat"]
north = (_mercator_y(parsed["lat"]) - _mercator_y(parsed["lat"] + step)) / 256 * world
tolerance = EARTH_SCALE_TOLERANCE
assert case["east"]["moved_px"] == pytest.approx(east, rel=tolerance), case["id"]
assert case["north"]["moved_px"] == pytest.approx(north, rel=tolerance), case["id"]
assert abs(case["east"]["across_px"]) < 0.5, case["id"]
assert abs(case["north"]["across_px"]) < 0.5, case["id"]
def test_earth_draws_its_camera_at_the_middle_of_the_window():
"""No table entry for Earth, and this is why: halving the distance draws the
ground twice as big about the camera's own pixel, and in every window that
pixel was the middle."""
for case in _earth_cases():
offset = case["camera_offset_px"]
assert abs(offset["x"]) < 1.5 and abs(offset["y"]) < 1.5, case["id"]
def test_a_level_3d_camera_far_enough_out_is_a_globe():
"""Level is not enough on its own for a 3D camera: past ``LEVEL_CEILING_M``
the ground under it is visibly round, and a flat scale would be wrong by
more than the tools are worth."""
high = f"https://earth.google.com/web/@{LAT},{LON},146a,900000d,35y,0h,0t,0r/data={EARTH_3D}"
assert parse_map_url(high)["view_kind"] == "globe"
# …and a 3D camera whose height the URL never states is not assumed to be low
bare = f"https://earth.google.com/web/@{LAT},{LON}/data={EARTH_3D}"
assert parse_map_url(bare)["view_kind"] == "globe"
def test_a_pitched_camera_is_not_a_map_however_it_is_written():
"""The metres are a red herring on their own: the same block carries the
tilt, and a tilt is what decides."""
assert parse_map_url(f"https://www.google.com/maps/@{LAT},{LON},1000m,45t")["view_kind"] == "tilted"
assert (
parse_map_url(f"https://www.google.com/maps/@{LAT},{LON},336a,35y,45.5t/data=!3m1!1e3")[
"view_kind"
]
== "tilted"
)
# roll counts as well: a level camera turned on its axis is still level, but
# one that is not is not a map
assert (
parse_map_url(f"https://earth.google.com/web/@{LAT},{LON},1a,600d,35y,0h,0t,30r")[
"view_kind"
]
== "tilted"
)
def test_only_a_documented_tile_zoom_is_named_as_one():
"""Which sites' ``zoom`` can be turned into a scale without asking the map.
OpenStreetMap's slippy-map spec and Bing's tile system state the same thing
— 256-pixel tiles, one tile of the world at zoom 0 — Google's matches both,
and Copernicus Browser draws on Leaflet, which is that spec with a library
round it. Apple's documentation says only that ``z`` "defines the area
around the center point", but a browser dragged and zoomed at two window
sizes drew tile level 15 both times, so it is recorded on the measurement.
Earth quotes a camera distance and no level at all.
"""
for url, site in (
(f"https://www.google.com/maps/@{LAT},{LON},{Z}z", "google-maps"),
(f"https://www.bing.com/maps?cp={LAT}~{LON}&lvl={Z}", "bing-maps"),
(f"https://www.openstreetmap.org/#map={Z}/{LAT}/{LON}", "openstreetmap"),
(f"https://maps.apple.com/?ll={LAT},{LON}&z={Z}", "apple-maps"),
(f"https://browser.dataspace.copernicus.eu/?zoom={Z}&lat={LAT}&lng={LON}",
"copernicus-browser"),
):
parsed = parse_map_url(url)
assert parsed["site"] == site
assert parsed["scale_source"] == "zoom", site
assert parsed["zoom"] == Z, site
earth = parse_map_url(f"https://earth.google.com/web/@{LAT},{LON},1a,600d,35y,0h,0t,0r")
assert earth["site"] == "google-earth"
assert earth["scale_source"] is None
assert earth["zoom"] is None
def test_apples_stale_zoom_is_dropped_once_it_states_a_span():
"""Apple carries the ``z`` its opening link had and never rewrites it.
Measured: opened at 15, zoomed twice, the address bar still said 15 while
the span had quartered. A view that states a span therefore states no zoom
at all here, and the span is what a caller reads.
"""
opened = parse_map_url(f"https://maps.apple.com/?ll={LAT},{LON}&z=15&map=satellite")
assert opened["zoom"] == 15 and opened["scale_source"] == "zoom"
assert opened["span_lat"] is None
moved = parse_map_url(
"https://maps.apple.com/frame?z=15&map=satellite"
"¢er=47.388462%2C2.352785&span=0.029055%2C0.056434"
)
assert (moved["lat"], moved["lon"]) == (47.388462, 2.352785)
assert (moved["span_lat"], moved["span_lon"]) == (0.029055, 0.056434)
assert moved["zoom"] is None and moved["scale_source"] is None
def test_a_stated_size_becomes_a_zoom_once_the_window_height_is_known():
"""The two views that state a size rather than a level.
Both numbers are the map's own, and both were checked against a browser:
a 1000 px window opened at 15z came back as ``,3231m`` from Google and as
``span=0.029055,…`` from Apple. Fed those back with the height they were
drawn at, this returns the level they were drawn at.
"""
satellite = parse_map_url(
"https://www.google.com/maps/@47.388462,2.352785,3231m/data=!3m1!1e3", height_px=1000
)
assert satellite["scale_source"] == "height_m"
assert satellite["zoom"] == pytest.approx(15, abs=0.01)
# Earth's view covers the same ground in a shorter window, so it is further out
earth = (
"https://earth.google.com/web/@47.38914743,2.35481038,"
"198.8634048a,2196.68868628d,35y,0h,0t,0r"
)
tall = parse_map_url(earth, height_px=1000)
assert tall["scale_source"] == "distance"
assert tall["zoom"] == pytest.approx(16.2234, abs=0.001) # registered: 16.22341
shorter = parse_map_url(earth, height_px=760)["zoom"]
assert shorter == pytest.approx(tall["zoom"] + math.log2(0.76))
apple = parse_map_url(
"https://maps.apple.com/frame?map=satellite"
"¢er=47.388462%2C2.352785&span=0.029055%2C0.056434",
height_px=1000,
)
assert apple["scale_source"] == "span"
assert apple["zoom"] == pytest.approx(15, abs=0.01)
# the same view in a shorter window is the same map drawn smaller: Apple
# states the span it actually covers, so the level comes back unchanged
shorter = parse_map_url(
"https://maps.apple.com/frame?map=satellite"
"¢er=47.388462%2C2.352785&span=0.022082%2C0.039268",
height_px=760,
)
assert shorter["zoom"] == pytest.approx(15, abs=0.01)
def test_without_a_window_height_a_stated_size_is_left_alone():
"""No height, no zoom — never a guessed one."""
satellite = parse_map_url("https://www.google.com/maps/@47.388462,2.352785,3231m/data=!3m1!1e3")
assert satellite["zoom"] is None and satellite["scale_source"] is None
earth = parse_map_url("https://earth.google.com/web/@47.38,2.35,198.86a,2196.69d,35y,0h,0t,0r")
assert earth["zoom"] is None and earth["scale_source"] is None
def test_every_recognized_site_answers_the_scale_question():
for url, _site, _zoom in OPEN_IN_LINKS:
assert parse_map_url(url)["scale_source"] in {"zoom", "height_m", "span", "distance", None}
def test_view_kind_is_unclassified_rather_than_guessed():
"""A Google Maps URL with no camera block says nothing about its camera, and
saying nothing is the answer — the same rule imagery_mode follows."""
parsed = parse_map_url("https://www.google.com/maps/place/Tour+Eiffel")
assert parsed["site"] == "google-maps"
assert parsed["view_kind"] is None
def test_a_street_view_url_carries_its_point_but_no_zoom():
"""Which is the second, independent reason the overlay declines geometry
there: the projection needs a zoom, and a pano camera has none."""
parsed = parse_map_url(f"https://www.google.com/maps/@{LAT},{LON},3a,75y,90h,90t")
assert (parsed["lat"], parsed["lon"]) == (LAT, LON)
assert parsed["zoom"] is None
# the point is still real, read from the address bar — a pin can be filed on it
assert parsed["view_kind"] == "streetview"
def test_every_recognized_site_answers_the_question():
"""Every parse carries the key, so a caller never has to tell "no camera in
this URL" from "this build predates the field"."""
for url, _site, _zoom in OPEN_IN_LINKS:
assert "view_kind" in parse_map_url(url)
# -- what may be drawn over the view --------------------------------------------
#
# Three independent ways the projection can be wrong, and the overlay has to
# decline on any one of them: a camera Mercator says nothing about, a
# flattening we cannot invert, and a zoom where the site draws a globe while
# its URL goes on quoting a zoom.
def test_geometry_needs_a_flat_camera_a_known_projection_and_a_flat_zoom():
ok = parse_map_url(f"https://www.google.com/maps/@{LAT},{LON},17z")
assert ok["geometry"] is True
assert ok["projection"] == "webmercator"
def test_copernicus_2d_map_is_leaflet_and_drawable():
"""Its flat map is Leaflet's default CRS, which is EPSG:3857.
Two ways round: the browser's own package.json depends on leaflet, and two
zooms about two different pixels solved for the same camera centre through
spherical Mercator to half a pixel (tests/fixtures/map-sites.json).
"""
flat = parse_map_url(f"https://browser.dataspace.copernicus.eu/?zoom=15&lat={LAT}&lng={LON}")
assert flat["projection"] == "webmercator"
assert flat["view_kind"] == "map"
assert flat["geometry"] is True
@pytest.mark.parametrize(
"url,why",
[
# a pano camera
(f"https://www.google.com/maps/@{LAT},{LON},3a,75y,90h,90t", "streetview"),
# a pitched one
(f"https://www.google.com/maps/@{LAT},{LON},1000m,45t", "tilted"),
# Earth's 3D camera far enough out to be a globe
(f"https://earth.google.com/web/@{LAT},{LON},0a,900000d,35y,0h,0t,0r/data={EARTH_3D}", "globe"),
# Copernicus Browser in its 3D terrain viewer, which it says in the URL
(f"https://browser.dataspace.copernicus.eu/?zoom=17&lat={LAT}&lng={LON}"
'&terrainViewerSettings=%7B%22settings%22%3A%7B%22x%22%3A1%7D%7D', "terrain viewer"),
],
)
def test_geometry_declines_wherever_the_projection_would_be_a_guess(url, why):
assert parse_map_url(url)["geometry"] is False, why
def test_yandex_is_elliptical_and_says_so():
"""EPSG:3395, not 3857. Drawing it as spherical Mercator is wrong by
kilometres at Moscow's latitude — and wrong with total confidence."""
parsed = parse_map_url(f"https://yandex.com/maps/?ll={LON},{LAT}&z={Z}&l=sat")
assert parsed["projection"] == "ellipsoidal"
assert parsed["geometry"] is True # known, therefore drawable
def test_the_globe_floor_is_a_warning_rather_than_a_floor():
"""A *flat map drawn far out* is warned about, not refused.
A site becoming a globe on the way out does not change its URL shape, so the
zoom is the only warning there is — and out there the drawing still appears:
the middle of the screen is right and the edges drift, which is the trade for
seeing a whole region's worth of work at once. ``far`` is what says so, and
the panel dims what it draws.
The other globe is refused outright — see the test below, and the two are
not the same thing.
"""
low = parse_map_url(f"https://www.google.com/maps/@{LAT},{LON},7z")
high = parse_map_url(f"https://www.google.com/maps/@{LAT},{LON},8z")
assert (low["geometry"], high["geometry"]) == (True, True)
assert (low["far"], high["far"]) == (True, False)
assert low["globe_below"] == 8
# Earth's own 3D globe is the same verdict reached from a camera height
earth = parse_map_url(
f"https://earth.google.com/web/@{LAT},{LON},0a,900000d,35y,0h,0t,0r/data={EARTH_3D}"
)
assert earth["view_kind"] == "globe" and earth["far"] is True
# OpenStreetMap has no globe to fall into, so it has no floor
flat = parse_map_url(f"https://www.openstreetmap.org/#map=3/{LAT}/{LON}")
assert flat["globe_below"] is None
assert (flat["geometry"], flat["far"]) == (True, False)
def test_a_globe_camera_is_refused_where_a_flat_map_drawn_far_out_is_not():
"""The other globe: a perspective camera on a sphere, which is not a map.
Google's Earth mode is the case that separates the two, because it is the
one view that is a globe camera *and* has a named flattening. Mercator is
not approximately right out there, it is wrong — so ``geometry`` declines
even though the projection is known, and the extension says to zoom in
rather than dimming a drawing nobody can judge (`maptools.js`, ``REFUSALS``).
"""
globe = parse_map_url(f"https://www.google.com/maps/@{LAT},{LON},900000a,35y,0h,0t,0r")
assert globe["view_kind"] == "globe"
assert globe["projection"] == "webmercator" # known, and still not enough
assert globe["geometry"] is False
# `far` stays true out there, because it has a second job: it is what stops
# the extension measuring a site's layout off a view that far out
assert globe["far"] is True
# …and the same camera in close is a map, which is the whole point of
# measuring the height rather than refusing the site
near = parse_map_url(f"https://www.google.com/maps/@{LAT},{LON},1000a,35y,0h,0t,0r")
assert (near["view_kind"], near["geometry"], near["far"]) == ("map", True, False)
def test_a_pin_is_never_gated_by_any_of_this():
"""Whatever the camera is, the URL still names a point — which is the one a
pin files on. The verdict only says the *pixel* clicked cannot be trusted."""
for url in (
f"https://www.google.com/maps/@{LAT},{LON},3a,75y,90h,90t",
f"https://earth.google.com/web/@{LAT},{LON},0a,600d,35y,20h,60t,0r",
):
parsed = parse_map_url(url)
assert parsed["geometry"] is False
assert (parsed["lat"], parsed["lon"]) == (LAT, LON)
# --- against the real thing ----------------------------------------------------
#
# `tests/fixtures/map-sites.json` is nine map sites driven in a browser: opened
# at a known level, dragged a known number of pixels, zoomed about a known
# pixel, and read back out of the address bar after every step. Fifty-odd URLs
# that sites wrote about themselves, rather than a table written to suit this
# parser.
#
# The frontend suite replays the same file through the extension's arithmetic
# (`extensionMapFrame.test.js`) and checks that it puts each view back where the
# browser had it. What is checked here is the other half: that the parse still
# hands it those views.
@pytest.mark.parametrize(
"recording", RECORDINGS, ids=[r["label"] for r in RECORDINGS]
)
def test_recorded_browser_sessions_still_parse_the_same_way(recording):
# The map's height, not the window's. A site with a header above its map
# draws it in fewer pixels than the window has, and the two views that state
# a size rather than a level — Apple's span, Google satellite's metres — are
# only a scale next to the number of pixels they were drawn in. The
# extension hands over the same number (`mapoverlay.js`, `mapHeight`).
height = recording["map_height"]
for step in recording["steps"]:
parsed = parse_map_url(step["url"], height_px=height)
assert parsed is not None, step["url"]
assert parsed["site"] == step["site"]
assert parsed["scale_source"] == step["scale_source"]
for key, want in step["view"].items():
got = parsed[key] if key != "bearing" else (parsed["bearing"] or 0)
if isinstance(want, float) and isinstance(got, float):
assert got == pytest.approx(want, abs=1e-9), (key, step["url"])
else:
assert got == want, (key, step["url"])
def test_every_site_this_parser_knows_has_been_driven_in_a_browser():
"""A site nobody has driven a browser through is a site we are guessing at.
Keyed on this module's own table rather than on the links the app hands out,
because the extension draws on every site here — OpenStreetMap included,
which the app never links to because it is already a tile provider inside it.
`frontend/calibration/protocol.mjs` drives exactly this list.
"""
from azimut.engine.mapsites import SITES
recorded = {r["site"] for r in RECORDINGS}
known = {site_id for site_id, *_rest in SITES}
assert known == recorded
assert {site for _url, site, _zoom in OPEN_IN_LINKS} <= known
def test_the_recordings_cover_more_than_one_window():
"""A fixed side panel keeps its pixel offset when the window changes and a
proportional one does not, which is the whole reason for a second size.
Stated as a floor rather than as a list: `npm run calibrate:maps` records a
matrix of windows, browsers and browser zooms, and a re-run that covers more
of it must not have to come and edit this. What it may not do is cover less.
"""
sizes = {(r["window"]["w"], r["window"]["h"]) for r in RECORDINGS}
assert len(sizes) >= 2, sizes
assert min(w for w, _h in sizes) <= 1200, "a window no narrower than 1200 px is one window"
# every site is recorded at the widest window, whatever else was recorded
widest = max(sizes)
at_widest = {r["site"] for r in RECORDINGS if (r["window"]["w"], r["window"]["h"]) == widest}
assert at_widest == {r["site"] for r in RECORDINGS}
def test_the_map_is_the_window_minus_whatever_the_site_puts_above_it():
"""How tall the map was drawn, and where that number comes from.
A map centred in what its chrome leaves is centred by exactly half of what
the chrome took, so the camera offset the recording solved for *is* the
measurement of the header. `extension/mapoverlay.js` reads it the same way
and hands the result to this parser; the fixture is where the two meet.
"""
for recording in RECORDINGS:
window = recording["window"]["h"]
chrome = 2 * abs(recording["centre"]["y"] - window / 2)
# under a couple of pixels is the solve's own noise, not a header
want = round(window - chrome) if chrome >= 4 else window
assert recording["map_height"] == want, recording["label"]
assert 0 < recording["map_height"] <= window
def test_bings_rounded_zoom_is_reported_as_written():
"""The one site that rounds the zoom it writes.
Bing's wheel moves a third of a level and its URL carries one decimal, so
a view at 15.334 is written 15.3 — recorded in the fixture, six notches of
it. Nothing here tries to undo that: this side reports what the address bar
says, and the extension works the difference out from the pixel the zoom
held still, which is the only place the answer exists.
"""
written = [parse_map_url(step["url"])["zoom"] for step in ROUNDING["steps"]]
assert written == [15, 15.3, 15.7, 16, 16.3, 16.7, 17]
assert all(round(zoom, 1) == zoom for zoom in written), "one decimal, as Bing writes it"
for step in ROUNDING["steps"]:
parsed = parse_map_url(step["url"])
assert parsed["site"] == ROUNDING["site"]
assert parsed["scale_source"] == "zoom"
assert (parsed["lat"], parsed["lon"]) == (step["view"]["lat"], step["view"]["lon"])
# --- a camera that never quite comes back to zero -------------------------------
def test_a_camera_a_hair_off_level_is_still_a_map():
"""The bug that turned the tools off on Google Earth.
These viewers write the camera they are holding, at full precision, and a
turn of the compass leaves a fraction of a degree of pitch behind it. Read as
"tilted", that is a tool which stops working the moment the view is turned —
and the analyst is told to level a view that looks level to them.
"""
for angle in ("0.0001", "0.4", "1.9"):
url = f"https://earth.google.com/web/@{LAT},{LON},146a,666d,35y,12h,{angle}t,0r"
assert parse_map_url(url)["view_kind"] == "map", angle
# the same forgiveness on the other viewer with a free camera
assert (
parse_map_url(f"https://www.google.com/maps/@{LAT},{LON},336a,35y,0.5t/data=!3m1!1e3")[
"view_kind"
]
== "map"
)
def test_a_camera_anyone_pitched_is_still_refused():
for angle in ("2.1", "15", "45.5"):
url = f"https://earth.google.com/web/@{LAT},{LON},146a,666d,35y,12h,{angle}t,0r"
assert parse_map_url(url)["view_kind"] == "tilted", angle
def test_the_pitch_is_reported_so_a_refusal_can_name_it():
""""Tilted" is a verdict; "tilted 40°" is the thing to go and undo — and on a
viewer that leaves half a degree behind, the number is how an analyst tells a
camera they pitched from one they did not."""
tilted = parse_map_url(f"https://earth.google.com/web/@{LAT},{LON},146a,666d,35y,0h,40t,0r")
assert tilted["tilt"] == 40
# roll answers on the same field: whichever tips the ground plane most
rolled = parse_map_url(f"https://earth.google.com/web/@{LAT},{LON},146a,666d,35y,0h,3t,30r")
assert rolled["tilt"] == 30
level = parse_map_url(f"https://earth.google.com/web/@{LAT},{LON},146a,666d,35y,0h,0t,0r")
assert level["tilt"] == 0
# a site whose URL states no camera angle says nothing rather than zero
assert parse_map_url(f"https://www.openstreetmap.org/#map=17/{LAT}/{LON}")["tilt"] is None
#: Sites the extension starts unplaced on, and why each is left out of
#: ``_CAMERA_CENTRE`` rather than measured into it.
UNHINTED_ON_PURPOSE = {
"apple-maps": "its sidebar folds away below a width the URL never states, so"
" its offset is 67 px in a wide window and nothing in a narrow one",
}
def test_the_starting_offset_matches_what_the_browser_measured():
"""The offset the extension starts drawing from, against the recording.
``_CAMERA_CENTRE`` is the one place this parser states a number about pixels
rather than about a URL, and it exists because the alternative — starting at
the middle of the window — is a number too, and the wrong one on four of
these sites. So it is held to the recording the same way everything else
here is: every entry within a pixel and a half of where a browser drew the
camera, in every window the site was recorded in.
The other half is the drift gate. A site with no entry starts at the middle
of the window, which is a claim that the middle is right — so a recording
that says otherwise has to be either measured into the table or named in
``UNHINTED_ON_PURPOSE`` with the reason it cannot be.
"""
from azimut.engine.mapsites import _CAMERA_CENTRE, _centre_hint
for recording in RECORDINGS:
offset = (
recording["centre"]["x"] - recording["window"]["w"] / 2,
recording["centre"]["y"] - recording["window"]["h"] / 2,
)
hint = _centre_hint(recording["site"])
if hint:
assert hint["x"] == pytest.approx(offset[0], abs=1.5), recording["label"]
assert hint["y"] == pytest.approx(offset[1], abs=1.5), recording["label"]
# and a sideways offset is never claimed below a window it has been
# measured in, because that is where a side panel folds away
if hint["x"]:
assert hint["min_w"] <= recording["window"]["w"], recording["label"]
assert hint["min_w"] >= min(
r["window"]["w"] for r in RECORDINGS if r["site"] == recording["site"]
), recording["label"]
# under a couple of pixels is the solve's own noise, not a layout
elif max(abs(o) for o in offset) >= 4:
assert recording["site"] in UNHINTED_ON_PURPOSE, (
f"{recording['label']} draws its camera {offset} from the middle of the"
" window and nothing says so: add it to _CAMERA_CENTRE or say why not"
)
# and nothing in the table that no browser was ever driven through
assert set(_CAMERA_CENTRE) <= {r["site"] for r in RECORDINGS}
assert set(UNHINTED_ON_PURPOSE) <= {r["site"] for r in RECORDINGS}
assert not set(UNHINTED_ON_PURPOSE) & set(_CAMERA_CENTRE)
def test_the_starting_offset_reaches_the_extension_with_the_view():
"""It travels the one channel the extension reads: the parse of its URL."""
hinted = parse_map_url("https://www.bing.com/maps?cp=47.388462~2.352785&lvl=15")
# a header, claimed at any width: its height does not change with one
assert hinted["centre_hint"] == {"x": 0.0, "y": 40.5, "min_w": 0}
# and a site that draws dead centre says nothing rather than saying zero
assert parse_map_url("https://www.google.com/maps/@47.388462,2.352785,15z")["centre_hint"] is None
# a side panel says how narrow a window it has been seen in, because that is
# the thing that folds away (`_CAMERA_CENTRE`)
panelled = parse_map_url("https://yandex.com/maps/?ll=2.352785%2C47.388462&z=15")
assert panelled["centre_hint"] == {"x": 210.0, "y": 10.0, "min_w": 1200}
narrowest = {
r["window"]["w"] for r in RECORDINGS if r["site"] == "yandex-maps"
}
assert panelled["centre_hint"]["min_w"] == min(narrowest)