Skip to content

The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.

JavaScript
56.6 KB
Raw Blame

Keyed imagery providers

Azimut offers optional Mapbox, Google and Sentinel Hub providers alongside the keyless defaults. Their legal and technical constraints define the implementation.

Implemented in engine/tiles.py, engine/google_tiles.py, engine/tilecache.py and api/settings.py.

Legal rules

Rule Why
Keys are user-supplied, stored locally, never bundled into a shared case/zip. Principle 7; keys are the user's own billing identity.
Core features never require a key. Key-less providers (Esri, OSM, OpenTopoMap) stay the default. Principle 7.
Never ship/suggest/document unofficial endpoints (mt1.google.com, khms*, …). Only official APIs. Legal-only policy.
Google tiles must NOT be cached to disk. Google's Map Tiles API forbids pre-fetch/store/cache/offline use of tiles (policies).
A Google capture is a flattened, attributed PNG, never stored raw tiles. Google permits attributed screenshots in reports and periodicals up to 5,000 copies; its anti-cache rule still forbids tile storage.
Every capture keeps provider attribution (Google/Mapbox + data providers, e.g. Maxar) unmodified. For Google it is burned into the image footer. Attribution is a condition of the allowed use, not a courtesy.

Per-provider capability matrix

Provider needs_key auth style capturable cacheable (tile disk cache) attribution source
Esri World Imagery no — yes yes static string
Esri Wayback no — yes yes (a release never changes) static string, release in provenance
OpenStreetMap no — yes yes static string
OpenTopoMap no — yes yes static string (CC-BY-SA² )
Sentinel-2 cloudless (EOX) no — no (a year's mosaic, no single date) yes EOX's words for the year shown, with its licence
Mapbox Satellite yes access token in URL yes yes¹ © Mapbox © OpenStreetMap (+ Maxar)
Google Satellite yes session token yes (flattened+attributed only) NO dynamic copyright from viewport endpoint
Google Satellite (Maps JS) yes key in script URL⁴ screen crops only (user-initiated grab, attribution burned) n/a (widget) Map data © Google + the widget's own credits
Sentinel-2 (Sentinel Hub) yes instance ID in URL³ yes yes © Copernicus Sentinel data {year}
Sentinel-1 radar (Sentinel Hub) yes, plus a radar layer instance ID in URL³ yes yes © Copernicus Sentinel data {year}

¹ Display + static-image capture with attribution is permitted; plan-level caching/redistribution limits vary, so the cache stays modest (30-day TTL) and attribution always on.

² Free for any use, commercial included, provided the attribution line stays visible. CC-BY-SA makes it a licence condition. The tile policy's only real limit is "no mass downloads", which a single-user workbench never approaches. Topographic, so imagery=false (the labels overlay would double its own labels). Its tile server stops at z17 and answers deeper zooms with a constant "max zoom layer = 17" placard. It is registered in PLACEHOLDER_TILE_SHA256, and the live map caps its zoom at the provider max so it is never requested. Verified 2026-07.

³ Open data under the Copernicus free, full and open licence. It requires attribution, so no capture or cache restriction. The constraint is quota, not law. The instance ID is the whole credential: OGC needs no OAuth token on top of it (verified 2026-07: a wrong id answers 400 Invalid instance id, never a 401). It is still the user's quota identity, so it lives in api_keys like any other key.

⁴ A Maps JS key is client-side by design (referrer-restricted, not secret), so shipping it to the browser in the loader URL is intended. Every other key is a tile key, and stays server-side behind the proxy.

Google in the EEA since 2025-07-08

Google stopped serving satellite tiles (Map Tiles API and Static Maps API) to projects with an EEA billing address: 403 PERMISSION_DENIED with the explanation in the error body (Map Tiles notice, Static notice). This applies to projects created after that date or that later left "Unmodified State". Non-EEA accounts keep the tile pipeline.

The Maps JavaScript API widget remains the official Google satellite route in the EEA, so Azimut supports both products:

Google Satellite (tiles) Google Satellite (Maps JS)
Works in the EEA no (403) yes
Rendering XYZ tiles through our proxy a real google.maps.Map under our own map, which is transparent where nothing is drawn
Captures stitched crop, attribution burned screen pixels only from one tab screenshot taken by the capture extension; attribution burned, method:"screenshot", framed:true
Capture frame any size (tiles are fetched) limited to the map view; no resolution multiplier
Rotation / oversample / marquee yes rotation + marquee yes, oversample no
Meter tiles map loads (~10k free/month); one widget instance per page life, reused across tabs and basemap switches; eco mode disabled because a replacement instance bills another load
Key test createSession server-side a real map in the browser, failed by any refusal Google names (below); a changed key requires reload; an accepted key test bills and records one map load

Both keys can be saved at once: each lights its own basemap, and the EEA failure path benches the tiles one automatically (below) leaving the widget on offer. Our own map keeps all interaction, so measure tools, places, reference windows and the labels overlay work unchanged over the widget.

Maps JS widget behavior

Google's own map renders in its own element under ours, and ours is transparent where nothing is drawn (lib/map/gmaps.js, "under glass"). It takes no pointer events: every gesture and every control is ours, and Google's camera is moved to follow ours on each frame.

  • Rotation works. Google has no bearing of its own on a raster satellite map, so its element is turned by CSS. A turned rectangle would expose blank corners, so the element is a square of the container's diagonal, centred, which covers every bearing at once — a rotated W×H rectangle always fits inside the circle of its own diagonal. Extra tile renders inside one map load are free; the billing is per google.maps.Map.
  • The credit line is moved upright. Google renders it inside that oversized, turned element, where a bearing would rotate it off screen. It is re-homed into a fixed holder at the bottom right, which is the one part of the layer that does take the pointer, so the terms link stays clickable. If Google's markup ever stops offering that node, the same credit and a terms link are stated by us instead — the imagery is never shown bare.
  • Cloned tiles remain off-limits. Reading them through canvas, html2canvas or their URLs is programmatic extraction forbidden by Google's terms. The capture path therefore goes through the capture extension (extension/, installed from Settings): one tabs.captureVisibleTab behind the user's click. This avoids the share prompt and preserves fullscreen, unlike the earlier getDisplayMedia route. Without the extension, Capture directs the user to Settings and does not offer a fallback.

What the screen-pixel route still forces, whatever supplies the frame:

Trap Rule
The tab frame covers the whole viewport, including Azimut chrome .map-wrap.grabbing hides the HUD, controls and child reference windows through :global. The marker stays because tile captures burn one into their output too.
Browser zoom or resize can make a frame belong to the wrong surface Validate every frame with lib/screenCrop.js isRegistered and the viewport aspect; refuse mismatches.
captureVisibleTab needs activeTab or <all_urls>; host permission is insufficient One extension click grants activeTab for the SPA tab's life. The app explains this once. Never request <all_urls>.

Provenance: framed:true means lat/lon is the registered crop centre. framed:false means lat/lon records only the map view used while filing a pasted or dropped image.

A frame that fails registration is refused and nothing is filed. Importing a pasted screenshot remains a separate capture-menu action so it cannot inherit registered-frame provenance.

The capture extension (extension/, api/ingest.py)

One MV3 extension (Chrome/Edge + Firefox), two flows:

Azimut's Maps JS basemap External map sites
Trigger the app's own Capture button (bridge content script relays) toolbar click / Alt+Shift+A → popup → drag an area
Sites localhost only Google Maps/Earth, Bing, Yandex, OSM, Apple Maps, Zoom Earth, Satellites.pro and Copernicus Browser; endpoint also refuses non-map sites
Metadata app view (framed:true) parsed only from the URL: coordinates, zoom, bearing, place name and any encoded imagery date; correctable in the popup; may be empty
Filing same-origin, no pairing token-gated POST /api/ingest/screenshot, CORS limited to extension origins; /api/events refreshes open app tabs
Attribution burned by the app burned server-side per site (api/ingest.py ATTRIBUTIONS), source URL + site + timestamp always in provenance

The extension only screenshots and sends the URL. Every URL format rule lives in engine/mapsites.py; the popup prefill is GET /api/ingest/parse, and the POST re-derives site/attribution/metadata from the URL itself, trusting the client for nothing but its own corrections. The unpacked extension cannot update remotely, while the app can. Keep site knowledge in the app so format changes do not require reinstalling the extension.

Legal rails, encoded in both the extension and the endpoint: one screenshot per explicit user action (nothing schedulable), URL-only metadata, on-screen credits ride along inside the pixels, attribution burned on top.

Dead keys bench their basemap

settings.json → provider_status holds each credential's last verdict. Written by: the Settings key test (every provider), a createSession refusal or a tile 401/403 that survives the re-mint retry (with Google's own sentence as the reason), and a refusal of the JS map in the browser. Never by plain network errors; a timeout says nothing about the key.

Google calls gm_authFailure for a bad key only. Billing switched off, the API not enabled, a spent quota or a blocked referrer are named in a console error alone (BillingNotEnabledMapError…), while the map keeps drawing dimmed tiles under "For development purposes only". lib/map/gmaps.js reads those lines as they pass, so each refusal benches the basemap with what to do about it, and the key test waits a few seconds past tilesloaded for one. A key marked bad is withheld from all_providers(), so the basemap vanishes from the selector (the live map falls back to Esri) until the key changes (verdict cleared) or a test passes. Settings shows the stored reason inline.

Tile retries and failure messages

Three rules, shared by the live proxy and fetch_crop so a provider that is slow on the map is not quietly fast on the evidence.

A ceiling per provider. TILE_TIMEOUT is 20s; Provider.timeout overrides it, and only Sentinel-1 does (45s). Radar is drawn from the GRD through our evalscript at request time where the optical layer is served already baked, so a cold 512px tile regularly outran the shared ceiling.

One more try, twice. MAX_TILE_TRIES is 3, for a transport error or a 502 /503/504, never for a 4xx (a verdict about the request) and never for a 500 (the service's verdict on this render — on 2026-10-07 every Sentinel-1 tile answered 500 for hours, identically). Retries cost nothing on the meter, which only ever counts a 2xx. Before this, one slow tile left a hole in the live map and took a whole capture down with it.

The provider's own sentence reaches the panel. Sentinel Hub answers a render it could not do with an OGC ExceptionReport; upstream_reason() unwraps it from its Java trace, strips addresses and credentials, caps it at 240 characters and the proxy returns that as the failed tile's body, as text/plain. The engine hands it to the map as a Blob, so the reason arrives a tick after the trouble. Without it, a Copernicus outage is indistinguishable from a bug in Azimut — the DEM outage above read as "try again" for an hour. Our own sentences still win for 401/403 and 429, which name what to go and do.

Per-provider eco thresholds

eco_max_zooms in settings.json lets each tile basemap carry its own eco threshold (blank = provider default, else the global one; 0 = eco off for it). Needed because one global value can't fit both a z22 basemap and Sentinel-2's z14 ceiling. The JS widget is excluded because replacing it bills another load.

Sentinel-2 is a dated mosaic, not a basemap

Use the OGC WMTS endpoint for pictures. Catalog provides STAC metadata but no pixels. Band math goes through WMS GetMap with an EVALSCRIPT parameter rather than the Process API, which wants a POST and a separate token; see "Detect reads band products" below.

https://sh.dataspace.copernicus.eu/ogc/wmts/{key}?SERVICE=WMTS&REQUEST=GetTile
  &VERSION=1.0.0&LAYER=TRUE_COLOR&TILEMATRIXSET=PopularWebMercator512
  &TILEMATRIX={z}&TILECOL={x}&TILEROW={y}&FORMAT=image/jpeg&MAXCC=100

{key} is a configuration-instance UUID from Dashboard → Configuration Utility. Use the Simple Sentinel-2 L2A template, which defines TRUE_COLOR. L2A provides corrected bottom-of-atmosphere colour; the 120 m mosaic and 20 m Europe-only templates are unsuitable as basemaps. Turn off Show logo and Show warnings because the server burns both into every tile.

TIME is a mosaicking window, so this layer is "mosaic over range X", not "the imagery". Omitting it is not "the most recent pass": the mosaicking order is applied per pixel over the whole archive, so wherever the newest scene has nodata — a swath edge, a granule gap — the pixel comes from an older one and the tile is a blend of dates that cannot be dated. Azimut therefore resolves the newest pass over the crosshair and sends it as TIME=day/day, which leaves holes where that pass has no pixels. A hole can be read; a blend cannot. The undated template is kept for one case only: no pass could be resolved at all (deep polar winter, a persistent gap), and then the map says "several dates" and the capture files no date rather than naming the newest pass it mostly is not showing. The radar basemap follows the same rule, where a blend would mix looks from opposite sides of the track. A map plate's Sentinel-2 ground holds the same rule with no fallback: its map is drawn on one pass picked from the dates over its middle (TIME=day/day), and draws nothing until one is.

MAXCC is always sent, and defaults to 100. A configuration instance carries a cloud-coverage data filter of its own — the standard template ships 20% — and a scene above it is dropped before rendering, so the tile comes back empty rather than cloudy. Left implicit that reads as the app hiding cloudy days: a date the calendar offered renders black, and the dataMask probe calls it a coverage gap. Stating the ceiling on every request (tiles, the probe, the WFS date list) means what filters a date is our number, not the instance's. Detect reads a day it has settled on at 100 whatever its ceiling, because the ceiling's job there is to pick the newest pass: sent as MAXCC it dropped the whole tile of a day chosen over it (26/09/2026 over Lyman, 51% cloud, came back without a pixel at 30).

The provider id carries the layer, the window and the ceiling: sentinel2~SWIR~2026-05-01~2026-05-31~CC20 (engine/sentinel.py, mirrored in frontend/src/lib/sentinel.js). That is what solves the cache trap this section used to warn about: the disk cache keys on provider.id, so a window in the id is a window in the cache key and two dates can never collide. It also means the tile proxy, fetch_crop and a capture's provenance all inherit the choice. None can render from one window and file under another. tiles.get_provider() parses the variant; parse_variant is the validation boundary (the id becomes a URL path segment and a cache directory, so the shape is an allowlist).

Choice UI Notes
Layer picker populated from GetCapabilities on a user request LAYERS in engine/sentinel.py is a four-entry catalogue; the instance is authoritative. Analyzer checks keep missing products visible but disabled and use actual IDs such as VEGETATION_INDEX. An unverified catalogue cannot start check imagery.
Date a calendar: candidate pass days are coloured by cloud, then checked at the crosshair one day, not a range. Sent as TIME=day/day. "Most recent" is a WFS lookup that resolves to a day and sends it the same way, never an open window
Cloud a slider, 0–100%, default 100 (no filter) lower it and cloudier passes leave the tiles, the calendar and "most recent" together. Commits on release, so a drag is not a tile per step

Layers written in Azimut

A layer is a name the whole app already carries — the provider id, the tile cache, a capture's provenance — plus a rendering. Normally the rendering is a layer in the Copernicus dashboard; it can also be a script saved here (settings.json → sentinel_layers, engine/sentinel.py). Nothing downstream learns a new idea: resolve_layer turns the name into the request.

Stored {"id", "label", "base", "script", "hint", "form"?}, up to 40, script ≤ 4000 chars
id the allowlisted layer-name shape, because it is a URL path segment and a directory name
base a layer the instance serves, which supplies the data collection — an evalscript replaces a layer's style, never its source (the same arrangement the radar basemap uses). Never the Sentinel-1 layer: Sentinel-2 bands read through it render nothing
script sent as EVALSCRIPT=, base64 then URL-escaped, with LAYER=<base>
form how a form wrote it (composite/index), a memo and not the truth — the script renders. Unreadable, it is dropped and the layer reopens as its script
Offered merged into /api/satellite/sentinel/layers, marked custom, so every map tab gets them: Satellite, both Compare sides, Detect and the analyzer builder all read that one route
Enabled always, unlike a configured layer: a script on this machine needs no confirmation from GetCapabilities
Collision a name written here wins over a configured one, so a layer later added to the dashboard cannot quietly change what a saved capture renders
Backup carried in the settings bundle (the analyst's own work, and no credential)

A preview is a layer too. A script is judged on pixels, so the picker renders one before it is saved, under AZIMUT_DRAFT_<digest of the script>. The digest is in the name because the name is what the disk cache keys on: change two numbers, press Preview again, and the tiles have to be fetched rather than served from the last attempt. Only one draft is kept, it is never offered in a picker, and it is left out of the settings backup (this machine's scratch work).

A layer that paints one quantity is also a Detect rule. (A − B) / (A + B) is measure="nd" and one band painted into all three channels — grey, not colour — is measure="band" (analysis_models.Rule), so the builder offers each as the rule it already is, an index with its threshold and a band on the line a band rule starts at (lib/customLayers.layerAsRule). A colour composite does not come over — three channels are not one number — and neither does a hand-written script. The menu lists those too, greyed, with the reason (lib/customLayers.whyNotARule): a layer silently missing from it reads as "rules cannot be built from my layers at all".

A rule's line moves on the readings, not on new imagery. POST /compare/analyzers/check/values sends what one rule read over the whole ground a check was tested on (detect_rules.rule_values), quantised to sixteen bits across the span actually measured and split over a PNG's red and green channels — a canvas hands back eight-bit RGBA whatever the file held, so a 16-bit greyscale would be truncated and the line would land in the wrong place. The browser applies the same comparison the engine applies (analyzerRules.passesValue mirrors detect_rules._passes), and tests/test_detect_rules.py proves the two agree pixel for pixel at several lines. One rule at a time, only once its slider is touched, and never a fetch: every rule of every tile would be tens of megabytes on a press nobody made.

A rule can be drawn as a layer, too. The reverse direction (lib/map/ruleLayer.js): a rule names the bands it reads, so the same generators write the script that paints what it measures — nd and the two-band published indices as indexScript, a band rule as a grey composite, brightness as the visible bands averaged. It renders through the ordinary draft-preview path, so it caches and resolves exactly as a hand-written layer does. No threshold is baked in: the script's digest is the draft's name and so the tile cache's key, and a threshold in it would refetch the frame at every nudge of the slider.

Figures: one place, one day, several renderings

POST /api/cases/{case}/satellite/figure renders the same ground through several layers and lays the panels out as a Geo Proof (engine/figures.py, api/figures.py). Each panel goes through the ordinary provider variant, so a layer written here resolves and caches exactly as it does on the map, and is filed as a real capture with its own provenance. The composer already lays panels out, captions them, draws the footer and takes annotations, so a figure opens as a composition that can be arrowed rather than a picture to accept or redo.

One day for every panel, by design: a figure is one acquisition seen several ways. Panels of different dates would compare two things at once, which is Compare's job. Up to 8 panels, 1–4 per row, each layer once. The footer states the day, the point and Copernicus Sentinel-2 L2A.

Dates come from WFS, and cost one request

GET /ogc/wfs/{instance}?TYPENAMES=DSS2&TIME=…&BBOX=…&OUTPUTFORMAT=application/json uses the same instance credential and no OAuth. DSS2 is L2A; a date list from L1C would be a plausible lie about a different collection. SRSNAME=EPSG:4326 puts latitude first in the BBOX.

Billed at 0.01 PU but one whole request, so record_usage counts it as 1: both quotas are 30k. The meter tracks requests exactly and slightly overstates PU, so its unit is "request", not "tile" (meterUnit).

Granule footprints are checked against the query (_covered). A granule's bounding box is a square; its data is the slice of orbit swath inside it. WFS answers on the box, so without the check a listed day can render black. The footprint is tested under both axis orders: read backwards, every granule on Earth would be rejected.

Over a drawn area, a date also has a coverage share

sentinel.acquisitions(rings, …) runs the same WFS query over the union box of the areas a Detect sweep would cover, and keeps the footprints instead of reducing them to a yes/no. Each date comes back with coverage: the share of those areas that day's granules actually reach, measured by sampling a few hundred points inside the rings and testing each against the footprints — the geometry already in the module, so no polygon clipper joins the dependency list. Sampling puts the answer within a percent, which is what a "62% of the areas" badge can honestly claim; FULL_COVER = 0.98 is what counts as whole, because a ring's own edge lands a point or two outside a granule that in truth reaches it.

This is the question a crosshair lookup cannot answer. Sentinel-2 flies 290 km swaths, so an area wider than one has no single day covering it, and a date picked on its centre sweeps nodata over the rest. The automatic date rules (resolve_dates) take the newest pass that is both under the cloud ceiling and at full cover, and name the best partial share when there is none.

Still one lookup for the whole set of areas, not one per area, read in pages of 100 granules (FEATURE_OFFSET), newest first (checked 2026-09), up to five. Each page is one request on the meter. truncated says the fifth page was full, so the oldest passes in the window are missing.

WFS dates are still candidates. Before changing the map, the picker sends an 8×8 WMS dataMask check for the selected layer and day. A failed check leaves the current map in place and marks the date unavailable at that location. The result is cached by layer, date and rounded coordinates. Moving the map disables the old dates until the list refreshes. A successful check counts as one more Sentinel Hub request.

Its levels are numbered by resolution, not by grid width. TILEMATRIX=14 is 9.55 m/px on an 8192-wide grid, equivalent to Mapbox z13. Tile indices stay at the repo's tile_z either way, so only the level's name differs: Provider.zoom_offset=1 re-adds what z_shift took off. A wrong offset returns 400 Invalid TILECOL.

Eco mode needs its own threshold here (Provider.eco_max_zoom=7). The global default (z15) is tuned for basemaps that run to z22; Sentinel-2's imagery stops at z14, so sharing it would replace the layer at most supported zooms. At z7 and out the view spans a whole region and free Esri imagery serves it just as well. The swap is limited to those overview zooms.

Limit Value Consequence
Native resolution 10 m/px ≈ 9.55 m/px at TILEMATRIX=14 max_native_zoom=14; deeper requests only buy server-side upsampling
Useful zoom z18 max_zoom=18 on magnified native tiles
Coarsest pixel 1500 m/px, so z7 for a 512 px tile min_zoom=7; shallower tiles answer 404 unasked, and the 3D view draws that ground from Esri
Free quota 30 000 requests + 30 000 PU/month (Copernicus General) meter="sentinelhub"; per-account and editable in Settings
Rate 300 req/min, 300 PU/min why tiles stay 512
PU cost 512×512, 3 bands, 8-bit = exactly 1 PU one tile = 1 request = 1 PU, so the counter is faithful

PU scales with area, so tile size is cost-neutral (1024 → 4 PU, 256 → 0.25 PU): Google's big-tile trick buys nothing here. 512 wins on the requests/min limit alone.

Detect reads band products, not pictures

A Detect sweep fetches, for each tile and date, the WMTS picture the analyst reviews and one WMS band product the detector measures (sentinel.DETECT_PRODUCTS: vessel, fire, surface, index-*). Each product is four bytes a pixel, so one metered request carries everything a detector reads:

  • The box is padded by 32 px (analyzers.PAD, 306 m) on every side, so a ship's background ring, a coastline and a cloud's edge do not stop at the tile border. Checked against raw bands, the padded frame lands on the tile's grid exactly.
  • Reflectance is stretched by a gain of 2 (1.6 for short-wave infrared in surface). Glint puts open sea near 9% in the near-infrared; the old gain of 8 saturated at 12.5%, where hulls and wave crests read the same.
  • The fourth byte is the sky: the scene class in the low four bits and a flag for near-infrared under 15%, which is what the engine casts cloud shadows onto.
  • CLP/CLM are not used. On Copernicus Data Space they come back as zeros for some acquisitions, a thick cloud included, and over bright desert they flag dark irrigated fields as cloud when they are there.
  • Input bands cost processing units, output bands do not: each product asks for only the bands its detector reads, plus SCL.

Products are cached beside their picture under <variant>~<product>~v<N> (analyzers.product_cache_id), so a rerun over the same dates spends nothing, and PRODUCT_VERSION keeps a frame from an older layout from being decoded as a newer one.

An analyzer of your own reads raw bands instead: bands-B04-B08, up to three Level-2A bands a product, named in the collection's order and checked against sentinel.L2A_BANDS before a script is built, so no free expression reaches an evalscript. Its channels are 16 bits, reflectance in ten-thousandths (Sentinel-2's own scale), because an index computed on the server from two dark bands loses its meaning at a byte's 0.2% step; the fourth channel is the same sky. Pillow cannot hold 16 bits across four channels, so the engine decodes these with OpenCV and keeps a run's copy as the PNG that arrived. A recipe reads every three distinct bands as one more request per date and tile, which the wizard counts. A check in the builder reads the same products from the tile cache, on the tiles under its pins and across an edge from a pin within 48 pixels of it, at most twelve (detect_rules.check_tiles). What it still lacks is counted by check/plan before anything is fetched, and Test fetches it, one metered request each. The shipped examples were calibrated on Planetary Computer's key-less Level-2A, laid out as this evalscript returns it (the 1000 offset taken off from processing baseline 04.00, the way Sentinel Hub harmonises), so their marks cost no Copernicus request until a user runs them.

Difference asks for the same bands over the view on screen (sentinel.CHANGE_PRODUCTS: change-<index>, and change-sky for the sky alone). Those frames are decoded in the browser, which draws them into a canvas, so alpha has to stay the data mask — a canvas premultiplies it — and the sky byte rides in green instead. Nothing is cached: the view is whatever the camera is on.

The view goes deeper than the pixels

max_native_zoom (14) and max_zoom (18) are different questions: where the imagery stops, and where looking at it stops being useful. You cannot read a ship at 10 m/px from three levels out, so the view runs to z18 while requests stop at 14 and magnify the last native tile without extra requests. Asking Sentinel Hub for z18 would bill 16 times as many tiles for server-side upsampling.

The live map stops its tile requests at that level and scales the last one up; fetch_crop mirrors it so a capture matches the screen, and records native_zoom + native_meters_per_pixel next to zoom. This records that the native resolution is lower than the display zoom implies. The tile proxy refuses to fetch past the ceiling at all (_native_grid_zoom), for anything that isn't the live map.

Free tiers are facts about the account, not about us

Copernicus documents 10 000 PU/month and provisions 30 000 (observed 2026-07, copernicus-general-quota). So config.FREE_TIER is a default, and free_tiers in settings.json overrides any meter (config.free_tier(), editable per provider under Settings → Usage). A hardcoded number makes the gauge and 90% soft block can match the user's account rather than a global assumption. Quotas · PU definition

Sentinel-1 comes through a layer the user adds

Radar is the same account, the same quota and the same configuration instance, but an instance serves no Sentinel-1 until one of its layers reads it: the WFS answers TYPENAME=DSS3 not found! for an instance built from the Sentinel-2 template (verified 2026-09). The user adds a layer in the Configuration Utility with Sentinel-1 GRD as its source, IW mode, VV+VH polarisation, High resolution, any orbit direction, orthorectification on, gamma0 and no speckle filter; the form refuses to save until Data processing names a predefined product or a script, which Azimut replaces anyway. The app shows that form field by field (lib/copernicusSetup.js). Orthorectification doubles a request's processing units and a speckle filter doubles them again; terrain gamma0 multiplies them by 2.5 (Copernicus PU rules, 2026-09). The processing a layer sets (backscatter coefficient, orthorectification, DEM) cannot be overridden from an OGC request; only the evalscript can, and ours replaces the layer's.

Nothing in GetCapabilities says which layer reads which collection. WFS GetCapabilities does list one feature type per collection the layers use, free, which says whether any radar layer exists. Find (POST /api/satellite/sentinel1/layer) then asks each layer the Sentinel-2 templates do not ship, at most six, with an 8 × 8 render that reads VV and VH over the North Sea off Rotterdam: a Sentinel-2 layer answers 400 and the service's sentence says why. One request per probe, on the meter. The first layer that answers is kept as sentinel1_layer in settings.json, carried by the backup, and forgotten when the instance id changes. It can also be named and checked by hand.

Once it is known, it leaves the display list. The same silence in GetCapabilities that makes Find necessary means the instance hands the radar layer back among the optical ones, often first, so /api/satellite/sentinel/layers drops sentinel1_layer from what it offers — picked as a Sentinel-2 display it would render radar dated and cloud-filtered by a calendar that is not its own. Radar is reached through sentinel1_layer alone; nothing of its road reads that list.

  • A pass is a day and a time. Sentinel-1 passes a place at dawn flying south and at dusk flying north, so one day can hold two looks from opposite sides. Radar lookups (collection=sentinel1) group granules by pass rather than by day, name a pass by the UTC time of its first slice (the WFS time field, or the sensing start in the product name), and derive the direction from the local solar hour. Requests carry TIME as twenty minutes either side of that time (sentinel.pass_window), which holds one pass and nothing else.
  • One track compares with itself. A relative orbit repeats to the second every twelve days, whichever satellite flies it; the neighbouring track that also sees a place passes about eight minutes off (Dover 2025: orbits 132 and 59 at 17:49 and 17:41). Two passes within four minutes of each other in the day are one track (sentinel.same_track), and Detect, Difference and the pickers hold a pair to it.
  • The basemap is sentinel1, offered once sentinel1_layer is set. A pass rides on the id as sentinel1~2026-05-14~054210 (no colons: the id is a cache folder), a day alone as sentinel1~2026-05-14, and the plain id is the most recent pass. It is drawn in the review composite: VV red from -22 to 2 dB, VH green from -30 to -6 dB, their difference blue from 0 to 15 dB.
  • Detect's radar product (sar) carries VV and VH in decibels, a fifth of one per step from -35 dB, the first byte never zero where the radar saw something. The review picture (sar-picture) is rendered by WMS like a product, since there is no true colour to borrow.
  • The water mask (water) is a Sentinel-2 product read beside a radar vessel sweep: the scene class of the least cloudy pass of the year before the pass's month (PRIORITY=leastCC), water, land, or unknown where that pass saw cloud, shadow or snow. Dry desert is as radar-dark as calm sea in both polarisations, and without it the radar alone put 72 candidates on Port Sudan's town and sand.

Calibration used no quota: the scenes were read key-less from Microsoft Planetary Computer's sentinel-1-rtc and sentinel-2-l2a collections and encoded in the products' byte layout. Those are terrain-flattened gamma0; a layer left at the Sentinel Hub default reads ellipsoid gamma0, which differs little over sea and flat ground and more on slopes, which is one more reason to ask for orthorectification.

Google is not a static {key} URL

It needs a session token, minted and refreshed transparently before the rest of the pipeline sees a normal XYZ template:

  1. POST https://tile.googleapis.com/v1/createSession?key={API_KEY} → {"session":"<token>","expiry":"<unix>",…}. Session params (mapType) are part of the token identity.
  2. Tiles: GET https://tile.googleapis.com/v1/2dtiles/{z}/{x}/{y}?session={token}&key={API_KEY}
  3. Refresh on expiry or on 401/403.
  4. Attribution: GET https://tile.googleapis.com/tile/v1/viewport?session={token}&key={API_KEY}&zoom={z}&north=&south=&east=&west= → copyright (e.g. "Map data ©2026 Google, Maxar Technologies"). Never reduced to just "Google".

The token may be cached; tiles may not.

Measured findings (2026-07)

Tile sizes. Mapbox serves 512px tiles: it bills 256px tiles 4× vs 512px for the same ground area at the same m/px. Google serves 1024px hi-DPI tiles (scale=scaleFactor4x, highDpi=true): it bills per request regardless of tile size, so one request covers sixteen 256px tiles' worth of ground at the same m/px; the output was verified pixel-identical. Mapbox's @2x equivalent is upsampled, so is why Mapbox stays at 512.

Oversampling. The live map oversamples Google 2× (1024px tiles in 512px cells, one zoom deeper) because Google's mid-zoom mosaics are verifiably softer than its deep ones, at one quarter the request cost of plain 256px tiles. The z17 view boosts to 4× (z19 detail): the z18 mosaic it would otherwise show is often an older/hazier collection than the z19+ aerial. Captures retain provider pixels without resampling in evidence imagery.

Billing units. Both bill per tile served. Google's 2D Map Tiles SKU is "Request that returns a 2D map tile" (session and viewport requests are free); Mapbox Static Tiles bills per tile request on a live map. Free tiers: Google 100k/month then $0.60/1k (plus hard limits of 15k tiles/day and 6k/min per project), Mapbox 200k/month then $0.50/1k (alerts only, no hard cap). Metered tiles are proxied through the backend so the counter matches billing exactly; browser cache hits never re-count.

NASA FIRMS is a keyed layer, not a basemap

Active fire detections (engine/firms.py) are the one keyed thing here that is not a picture of the ground: they are laid over whichever basemap is showing, so the key buys a layer and the card in Settings → Imagery carries no meter, no free-allowance box and no eco threshold. Nothing about it is billed.

Credential one MAP_KEY, from the FIRMS page; it serves the global and the US/Canada services alike
Where it goes in the path of every request, which is why the browser never builds one: /api/firms/points/{z}/{x}/{y} for the app, /api/ingest/firms for the extension
Asking the app gets vector tiles (/api/firms/points/{z}/{x}/{y}, z0 to z13) and draws every square itself. Far out, and for a dated range at every zoom, a tile is one WMS GetMap in EPSG:3857 — the projection the tile grid is already in, so nothing is reprojected — drawn with squares of 1 px, which the backend reads back into marks, one per 3 px (firmspoints.picture_tile). From z8 in, a rolling window comes from the area API's points: one request per satellite, 4° cell and five days, held in memory, and every tile of every zoom over that cell is cut from them (firmspoints.tile)
Drawing squares sized to the footprint (375 m VIIRS, 1 km MODIS, never under 7 px) with a dark ring, and for a window longer than a day FIRMS's "24 h" in red over the rest in amber. The map draws them (lib/map/firePoints.js), so a square keeps its size through a zoom and stays where it is while the next level loads, where a picture's squares grew with its pixels until the next picture landed. From z11.5 to z12 a rolling window's squares give way to the footprints, scan by track, each with its own ring and edge and the ground showing inside, so a square under another keeps its outline. A square read off a picture has no footprint and stays a square. The extension's one picture is FIRMS's own far out, asked in the path after the key and dressed with the ring, and drawn from the points close in
Windows FIRMS counts whole UTC days, not hours: "24 h" is yesterday and today, "48 h" and "72 h" reach two and three days back, "7 days" seven (matched pixel for pixel against the WMS layers, 2026-09-27). The points are filtered the same way, or the day's main pass would drop out of "24 h" at the zoom where the points take over
Live fires_viirs_24 / _48 / _72 / _7, and the same for fires_viirs_snpp, fires_viirs_noaa20 and fires_modis. The combined fires_viirs is S-NPP, NOAA-20 and NOAA-21 (checked pixel for pixel, 2026-09)
History the same layer names without the suffix, dated with TIME=from/to, up to 31 days per request
Zoom ceiling tiles are 512 px and stop at z13, where a VIIRS square is already 20 px or more. Deeper views draw the z13 tile's squares bigger, so a square stays the size of its footprint without another NASA request
Allowance 5,000 transactions per 10 minutes, counted per day covered and per satellite: a WMS tile of the last 24 hours on the combined VIIRS layer is 3, a tile of 31 days 93, and an area request 2 per day and satellite whatever its box, so a week of one cell is 48 and every zoom under it is then free (measured 2026-09). The count fell back to zero in one go after ten quiet minutes. Nothing polls, and a layer that is off asks for nothing
Area API api/area/csv/{key}/{source}/{west,south,east,north}/{days}/{first day}, days 1 to 5 counted forward. The near-real-time files (VIIRS_SNPP_NRT, VIIRS_NOAA20_NRT, VIIRS_NOAA21_NRT, MODIS_NRT) hold about the last three months, the archive files before. A wrong key answers 400 Invalid MAP_KEY.
Refusal a spent allowance and a key FIRMS does not know answer the same 28 KB placard. The key-status endpoint costs nothing and tells them apart: it gives a key it knows its count, and a key it does not a 403. A spent allowance pauses the layer a minute at a time and leaves the key alone; only the 403 benches it. Any area answer that is not the table is read through the same endpoint
Caching none on disk. The live layers are what is burning now (upstream refreshes every 15 minutes) and a cached fire is a lie with a timestamp; the browser holds one for 5 minutes, and a range that ended before yesterday for 6 hours. The points are held in memory, today and yesterday for 5 minutes and older days for 6 hours, a million rows at most (about 24 MB), least recently drawn out first

NOAA-21 is not offered on its own: FIRMS gives it the rolling layers and no dated one, and a sensor that could answer "now" but not "that day" is a trap in a tool whose second question is always the date. It is inside the combined VIIRS layer, which is why that one counts three transactions a day.

The extension asks differently for the same reason it draws differently: it has no tile grid to hang tiles on, so it asks for one picture of the ground it can see per settled view and lays it under its own drawing, rotated with the map. That is also one request where tiles would be a dozen. Close in, that picture is drawn from the same points as the map's vector tiles, so both show the same squares.

Esri Wayback is one release at a time

Every published release of World Imagery stays online under its own number (engine/wayback.py). Same imagery, same terms and same attribution as the default basemap, and no key. Three services, all asked only after the analyst picks the basemap or opens its picker — and the walk follows the map from that first open, so an analyst reading a place through time never reads the history of where they were before:

Service What it answers Notes
waybackconfig.json (S3) every release: number, title with its date, metadata service read once per 6 h; numbers are not in date order, so the date sorts. Only metadata services on metadata.maptiles.arcgis.com are followed
MapServer/tilemap/{release}/{z}/{row}/{col} select: the release that tile was really published in walking it backwards from the newest shortlists a point's changes, one small request per candidate
WMTS/.../tile/{release}/{z}/{y}/{x} the pixels themselves one tile per candidate, read 8 at a time, to settle the shortlist
World_Imagery_Metadata_*/MapServer/{layer}/query SRC_DATE2 (epoch ms), provider, satellite layer = 23 − zoom, capped at 13. Slow, a couple of seconds each, so a walk asks up to 12 at once

What the tilemap calls a change is a change of bytes, and Esri republishes a picture far more often than the ground under it moves. So the pixels settle it: each candidate's tile is reduced to a 32×32 grey thumbnail and standardised, so a re-encoding or a new colour balance over one acquisition compares equal to it, and two releases are one picture when under 0.5% of the thumbnail differs by more than 0.7 of the tile's own spread. Measured against re-encoding, sharpening and a hard gamma, none of which reaches half of that, and a roof an eighth of the tile across, which passes it three times over. The metadata then merges what is left: neighbours stating the same acquisition day and satellite are one picture (observed 2026-09 in Mariupol: three releases over one GE01 acquisition of 2023-10-04, re-coloured). Both filters keep the older release, and a tile or a metadata answer that cannot be read is an unknown that never merges anything.

The walk runs at the view zoom, so what counts as a change scales with it: at z19 a tile is some 75 m across and the smallest change seen is a few metres.

A tile asked of a release it did not change answers 301 to the release that did; the proxy follows it and caches under the release asked for. The variant id esri-wayback~{release} is digits only, since it becomes a path segment and a cache directory; the plain esri-wayback resolves to the newest release, so its id and its cache always name one.

Sentinel-2 cloudless is a year, not a day

EOX's Sentinel-2 cloudless (engine/cloudless.py) is one cloud-free picture of the world a year, assembled pixel by pixel from many passes of that year (and of the one before, for 2016 and 2018). It is the opposite of what the imagery dating rule asks of evidence, so it is a basemap to show and never to capture: capturable is off, and wherever it is printed it says a year's mosaic, never a day. Map plates use it for the wide map a reader needs to see a country without clouds or seams.

Tiles tiles.maps.eox.at/wmts/1.0.0/{layer}/default/GoogleMapsCompatible/{z}/{y}/{x}.jpg, key-less, asked only once the analyst picks this ground
Layers s2cloudless_3857 (2016), s2cloudless-{year}_3857 (2018–2025); 2017 has no licence of its own and is not offered
Pixels 10 m, native to level 14; the view magnifies past it up to 17
Variant id s2cloudless~{year}, digits only; the plain s2cloudless is the newest year
Licence 2016: CC BY 4.0, free for any use. 2018 on: CC BY-NC-SA 4.0, non-commercial use only, and online publications carry the link (EOX)
Credit EOxCloudless https://cloudless.eox.at by EOX IT Services GmbH (Contains modified Copernicus Sentinel data {years}), then the licence; /api/satellite/cloudless/years hands the plate each year's, so the credits print the year shown

The inspector says the licence of the year picked under its picker, so an analyst publishing for a commercial outlet sees before exporting that only 2016 is theirs to use.

Key-less overlays

Drawn over any basemap, fetched by the browser straight from their own servers (all answer cross-origin), never through the proxy, never cached on disk and never in a capture. Borders and Place names are the layers the map opens with; every other is asked for only once its switch is on (frontend/src/lib/map/basemap.js). Checked 2026-09-13.

Layer Source Licence / terms Notes
Borders OpenFreeMap planet vector tiles (OpenMapTiles schema), the same TileJSON as Place names data ODbL © OSM contributors, © OpenMapTiles, OpenFreeMap credited; no key and no quota boundary lines (country, region, district) and the names of countries, regions and cities from place, in English else name:latin; drawn as lines on every map, the 3D one included. Checked 2026-10-21
Place names OpenFreeMap planet vector tiles (OpenMapTiles schema), found through its TileJSON since the tile paths change with each weekly build data ODbL © OSM contributors, © OpenMapTiles, OpenFreeMap credited; no key and no quota place layer only, towns down to hamlets, in name:latin; imagery only; the browser draws the text, so no glyphs are fetched. Checked 2026-09-27
Roads Esri Reference/World_Transportation Esri terms, as World Imagery imagery only
Railways OpenRailwayMap standard © OSM contributors, style © OpenRailwayMap
Power lines Open Infrastructure Map vector tiles (/map/power, /telecoms, /petroleum) data ODbL, analysis CC-BY 4.0, credit and link required no published tile usage policy, so the style is ours, requests only follow the view, and nothing is prefetched
Sea marks OpenSeaMap seamark © OpenSeaMap contributors (CC-BY-SA)
GPS traces gps.tile.openstreetmap.org/lines OSMF tile policy
Active fires NASA FIRMS, keyed, through the app see above
Night lights NASA GIBS WMTS, VIIRS_NOAA20_DayNightBand_At_Sensor_Radiance (from 2024-03-25), VIIRS_SNPP_… (from 2020-11-18, with gaps), VIIRS_Black_Marble 2016 public domain Level 8 (750 m); opaque, drawn lowest at 85%

Relief, summit names and the turn read ahead

The 3D map and the Horizon tab add three sources, all key-less, all asked only once a view needs them. Checked 2026-10-08.

Need Source Licence / terms Notes
Terrain heights Mapterhorn tiles.mapterhorn.com/{z}/{x}/{y}.webp (terrarium, 512 px, planet to z12, surveys deeper) open data sources, © Mapterhorn, attribution page linked through the app (api/terrain.py), disk cache cache/terrain/ bounded at 1 GiB with an LRU sweep at start, absences kept 30 days
Terrain fallback AWS Terrain Tiles s3.amazonaws.com/elevation-tiles-prod/terrarium (Mapzen, 256 px) open data, Mapzen and AWS credited asked only when Mapterhorn cannot be reached; four of its tiles one level deeper make one of ours, served with status 203 so the map knows, and a tilted capture of that map credits it
Summit names OpenFreeMap planet vector tiles, the mountain_peak layer (named natural=peak and volcano), found through the same TileJSON as place names data ODbL © OSM contributors, © OpenMapTiles, OpenFreeMap credited; no key, no quota Horizon only, once Summit names is switched on (engine/peaks.py). Zoom 12 within 15 km of the eye, 11 to 40 km, 10 to 100 km, 9 beyond: a 150 km view in the Alps is about 160 tiles and 15 MB, once. Each tile's summits are cached 90 days, nearest first, six at a time; a tile that fails waits 30 s, doubling to 10 min. Overpass was dropped on 2026-10-09: its public servers were busy, and overpass-api.de refused this address outright after a view's burst of cells
Sea and lakes OpenFreeMap planet vector tiles, the water layer (ocean, and lake with the reservoirs; rivers left out), found through the same TileJSON as place names data ODbL © OSM contributors, © OpenMapTiles, OpenFreeMap credited; no key, no quota Horizon's Find only, once the photo is said to show the sea or a lake, or a line along the sea's horizon is traced (engine/water.py): the tiles at z10 over the reach (the sea down to z6 for a far one), at most 64, each kept as a 256-pixel mask 90 days. Without them, the terrain's flat ground stands in. Checked 2026-10-25

The Horizon view's ground is a mesh the browser draws on the GPU. It reads terrain tiles (to z14) and free imagery tiles itself, in batches of up to 64 (/api/horizon/tiles/terrain, /api/horizon/tiles/imagery), through the same disk caches and proxy function as the map, so the native ceiling, the overzoom over gaps and the meter are the map's. Imagery is Esri World Imagery or a Wayback release; a billed provider is refused. Shadows of the sun or the moon are computed in the browser from that terrain, with nothing more to download, and there is no Horizon cache folder.

The one billed exception is Sentinel-2 near the eye, on the analyst's own Copernicus key and quota: switched on under the view's imagery button ("Sentinel-2 nearer than 5 km", up to 30 km; the button then reads "S2 · 5 km"), it is laid only on the ground nearer than that, Esri beyond, as Satellite's 3D view keeps billed tiles off the far ground. Tiles are read at the provider's native level and never beyond it, so nothing is billed for upsampling. Before it is switched on the view says how many requests it would cost (/api/horizon/tiles/estimate: the tiles touching the disc round the eye, nothing fetched, tiles already on disk not counted); switching it on asks the catalogue once for the newest pass under 30 % cloud in the last 90 days (one request, /api/satellite/sentinel/dates), again only when the eye moves farther than 10 km. The meter counts every tile, and a paused quota refuses the batch.

Map tiles come in batches (/api/tiles/batch/{provider}, /api/terrain/batch, api/tile_batch.py; lib/map/tileBatch.js). A browser keeps six connections to the app, and a view tilted toward the horizon asks for a hundred tiles at once. The tiles the globe (Satellite's 3D, a plate's 3D map) asks for in one go travel as one request per source, up to 32 of them, at most four requests at a time so the app's other calls keep a connection. The app fetches them side by side and writes each as it is done, so a slow tile holds up none of the others. Each tile is served exactly as its own route serves it: same cache, same meter, same overzoom, same status when it fails. A flat map asks a free provider the app keeps on disk (Esri, Wayback, OpenStreetMap, OpenTopoMap) the same way: asked one by one, its tiles waited two to three times longer for a connection than the app took to answer them. A billed provider's tile, and one the app does not keep, is asked at its own address, so the browser's own cache still spares it a second request.

GeoConfirmed is a query, not a feed

An added layer (engine/geoconfirmed.py), not an overlay: the backend reads it and the case keeps the copy. GeoConfirmed's public read-only API needs no key, calls itself free to use, and asks for a User-Agent that names the integration and for its cache headers to be respected. It states no licence, so every layer is credited to geoconfirmed.org on the map and on each card. Checked 2026-09-19.

Call When What it gives
GET /api/Conflict the GeoConfirmed dialog opens the public conflicts; the export is addressed by shortName
GET /api/Conflict/{shortName} add, Refresh, first switch-on of a session factions and their colours; 204 for a name it does not know
POST /api/Map/export/{shortName} add, Refresh, first switch-on of a session a KMZ of approved placemarks, filtered by start, end and GeoJSON polygons; both null for the whole history, which skips the switch-on read
  • The KMZ over the site's own JSON. /api/Placemark/{c}/geojson is 16 MB for Ukraine and holds no descriptions; the export is filtered server-side, and bundles every icon it uses (api/icons/<colour>/<invert>/template/<n>.png, 56 px discs), so one request dresses the layer.
  • What the export leaves out. No faction field: the icon path's colour is matched against the conflict's factions, and factions sharing a colour (Israel and the US on the Iran map) are one legend row. No date field: the placemark name is 13 SEP 2026. Placemarks with no name are reference sites (bases, plants) sent whatever the dates asked for: 512 of 530 on the Iran map for six weeks of August and September 2026.
  • Folders are relative ages ("B. Last 7 days"), true only on the day of the export, so they are dropped for the factions.
  • The hotspot is 16,16 px, the middle of a 32 px icon, on 56 px discs. It is dropped and the disc centred on its point.
  • Sizes seen. A month of Ukraine is ~800 placemarks, 83 icons and 330 kB. The whole Ukraine map is 60,000 placemarks and 333 icons, under both MAX_FEATURES and MAX_ICONS: 6.4 MB on the wire, about 4 s to read, 1.6 s to compose the icons and 38 MB of GeoJSON handed to the browser.

Deliberately not basemaps

Street View and Google Photorealistic 3D Tiles are not basemap providers. They remain separate ground-imagery and 3D-scene roadmap items.