Introducing a new way to review your PRs.

Read the announcement

koala73 / worldmonitor

Real-time global intelligence dashboard. AI-powered news aggregation, geopolitical monitoring, and infrastructure tracking in a unified situational awareness interface

View on GitHub

29 documents · Updated Nov 20, 2026

docs / orbital-imagery-intelligence

Orbital imagery intelligence

Orbital Watch turns satellite pass forecasts and open imagery into place-based intelligence. It lets a reader inspect past and future coverage at a point, follow a set of watched sites, compare scenes, and act on imaging windows through the map, APIs, MCP tools, and alerts.

This page is a child of Intelligence products. Related products include Intelligence briefs and analysis, Forecasting, scenarios, and resilience, Company monitoring intelligence, and Travel-risk assessment workflows.

Product scope

Orbital Watch answers two linked questions: what satellites could image a place, and what imagery supports that answer. It joins predicted passes with scenes from open archives so a predicted pass is not treated as an image without archive evidence.

Product areaDecision support
Point lookupShows past passes, future opportunities, archive scenes, daylight, and sensor evidence for a selected point.
Watched sitesTracks imagery and future passes for curated hotspots, conflict zones, bases, facilities, ports, chokepoints, and reservoirs.
Change signalsScores comparable radar scenes for land sites and promotes only reviewed confirmed changes to product surfaces.
Scene reviewShows the newest scene, scene history, before-and-after comparison, and archive attribution.
AlertsNotifies opted-in users about suitable imaging windows and, when released, confirmed site changes.
DeliveryServes the product through the dashboard, REST RPCs, paid MCP tools, and notification events.

Data supply and watched-site coverage

The product starts with two data sets. The imaging catalog supplies sensor profiles and orbit elements. The watched-site registry supplies the places that receive scheduled evidence checks. Both are prepared before a reader or external client asks for data.

Imaging catalog

The imaging catalog represents satellites that match known sensor profiles. It combines current orbit elements with a short history of earlier elements so past passes use orbit data close to the time of each pass. This improves the match between a predicted pass and a scene acquired in the past. (scripts/seed-orbital-catalog.mjs, server/…/list-imaging-satellites.ts)

The catalog is a shared input for browser lookup, point queries, watched-site evaluation, and map track display. A missing or old catalog is marked stale rather than presented as a fresh view.

References: scripts/seed-orbital-catalog.mjs• L1-25 server/…/list-imaging-satellites.ts• L118-156 src/…/catalog.ts• L5-21

Watched-site registry

The watched-site registry turns existing map places into a common monitoring set. Entries at the same 0.01-degree cell merge into one site and retain their source lists. Each site has a country, a surface type, and a stable registry ID.

The surface type controls the evidence that can be produced. Land sites can receive radar change scoring. Maritime sites receive imagery and pass coverage but not land change scoring. Reservoir sites receive imagery and a radar water-extent reading.

References: shared/watched-sites.ts• L1-43 shared/watched-sites.ts• L125-160 scripts/_orbital-sites.mjs• L12-24

Site evidence rollups

The site seeder checks a bounded set of archive scenes for each registry site. It records the newest image, recent and upcoming passes, and the operators whose satellites cover the site. It also publishes country rollups so country views and external tools can read many sites without running a browser lookup.

The run keeps the last accepted record when a source is unavailable. It publishes site records before the index that names them. Readers reject records that are missing, mismatched, or too old. A refusal from the archive now also places the site run in backoff. During that window the run makes no archive request and publishes no partial index. (scripts/seed-orbital-sites.mjs• L264-337)

References: scripts/seed-orbital-sites.mjs• L264-337 scripts/seed-orbital-sites.mjs• L351-365 scripts/_orbital-sites.mjs• L147-219 scripts/_orbital-sites.mjs• L323-408 server/…/get-country-imagery-evidence.ts• L58-92

Imagery change detection

Change detection looks for a repeatable change in radar statistics over a small land-site footprint. It is an evidence signal, not an explanation of the event: a confirmed result means that comparable radar measurements changed, not that the system knows what caused the change.

When a site is evaluated, the change stage uses radar scenes grouped by acquisition geometry. It builds a baseline from older scenes, folds new observations into per-geometry tracks, and moves a flag through raised, confirmed, or retracted states. Water-heavy sites and overlapping duplicate footprints are excluded so the same pixels do not create several signals.

The change stage currently runs in shadow mode. Shadow means the system stores and reviews the signal without placing it in normal site and country responses. The alert path also suppresses site-change alerts during this period. Imaging-window alerts remain active.

References: scripts/_orbital-change.mjs• L16-45 scripts/_orbital-change.mjs• L168-277 scripts/_orbital-change.mjs• L280-333 server/…/get-country-imagery-evidence.ts• L1-5

Pass and scene retrieval

Point retrieval combines orbit geometry with archive search. The system computes a seven-day past window and a 72-hour future window, then assigns each pass an evidence tier. It matches scenes from open archives to passes that could have produced them and keeps unmatched acquisitions visible when they still help the reader.

The point API rounds coordinates to a 0.01-degree cell before it computes or caches a result. It searches both configured open archives for the past part of the window. A complete response can be cached for ten minutes. A stale catalog or incomplete archive answer is returned without cache storage so an outage does not become fresh-looking evidence. (server/…/get-point-passes.ts• L28-36, server/…/get-point-passes.ts• L102-141, server/…/get-point-passes.ts• L156-173)

The main evidence tiers describe increasing strength of support:

  • Confirmed image: an archive scene matches the pass.
  • Likely imaged: geometry and mission behavior make an image likely, but the archive has not confirmed it.
  • Within reach: the pass is in a useful footprint but does not yet support a stronger claim.
  • Capability overhead: a relevant capability passed over the point, without claiming that it produced an image.
  • Opportunity: a future pass that may image the point.

Optical scenes include point-level cloud and daylight context. Radar scenes do not use cloud as a limit. When an archive is incomplete, the response reports the missing source and keeps affected passes as unanswered instead of treating them as no-image results.

References: server/…/get-point-passes.ts• L28-36 server/…/get-point-passes.ts• L102-141 server/…/get-point-passes.ts• L156-173 src/…/pass-client.ts• L17-37 src/…/pass-job.ts• L118-180 src/…/match.ts• L179-227

Scene history and comparison

Scene review gives the reader a visual way to inspect evidence. The viewer shows a selected scene with its time, sensor, resolution, cloud context, and credit. For a north-up crop, it can search up to 60 days of earlier scenes from the same mission and place a selected before scene beside the current one.

The comparison is limited to aligned scenes from one collection. Cloudy optical scenes are hidden by default, while radar scenes remain usable because radar is not blocked by cloud. A scene that is listed before its crop is ready is shown as processing rather than as a false permanent failure.

References: src/…/scene-history.ts• L9-16 src/…/scene-history.ts• L61-101 src/…/OrbitalImageViewer.ts• L203-235 src/…/OrbitalImageViewer.ts• L303-361 src/…/OrbitalWatchPage.ts• L988-1027

Delivery interfaces

Orbital Watch exposes one domain service to the dashboard and external clients. REST RPCs and MCP tools use the same server evidence and preserve stale, partial, and access states instead of hiding them behind a generic empty result.

REST API

The versioned REST surface provides four reads:

  • The imaging catalog.
  • Point passes and matched acquisitions.
  • Country watched-site evidence.
  • A watched-site summary keyed by registry ID.

The watched-site summary is the privacy-safe map-popup path. The browser resolves a point to a known site locally, then sends only the site ID. The server returns the latest image and next pass, with reservoir water extent when relevant. It does not accept a user point on this free summary path.

References: proto/…/service.proto• L11-33 server/…/handler.ts• L7-12 server/…/get-point-passes.ts• L158-173 server/…/get-watched-site-imagery.ts• L81-101 src/…/watched-site-at.ts• L1-31

MCP tools

Paid MCP tools make the orbital evidence available to AI agents in bounded, structured responses. One tool returns passes and archive acquisitions for a point. Another returns watched-site imagery and confirmed change evidence for a country, with an optional site-name filter and image attribution.

MCP validates coordinates and country input before it calls the downstream REST path. Tool descriptions state that future passes are opportunities, military overhead is not an image, archive failures produce partial evidence, and confirmed change means changed radar statistics rather than a known cause.

References: api/…/_orbital.ts• L11-19 api/…/_orbital.ts• L113-190 api/…/_orbital-site-imagery.ts• L41-94

Access and product gates

Orbital Watch has separate access levels for browser lookup, alerts and MCP, and premium REST access. The free lookup supports browser point passes and the latest image and date for watched sites. Pro access adds imaging-window alerts and paid MCP tools. API plans add the premium REST paths.

The browser and server use launch gates independently. The client gate controls whether lookup entry points are shown. The server gate returns an uncached 404 while the product is dark. Paid REST and MCP calls still pass through shared account, entitlement, authentication, and usage controls.

Access levelMain capability
Free lookupBrowser pass lookup and public latest watched-site image summary.
Pro and Pro BusinessImaging-window alerts and orbital MCP tools.
API, API Business, and EnterprisePremium orbital MCP tools and REST API paths.

References: shared/orbital-watch-pricing.ts• L9-36 src/…/orbital-watch-flag.ts• L1-5 server/…/dark-launch.ts• L1-11 api/…/_orbital.ts• L97-111

Alerts and notification delivery

Alerts are opt-in and scoped to watched sites. After a successful site publish, the alert producer checks for suitable open optical or radar windows in the next 24 hours. It emits one coalesced event when a new window enters that lead period. It tracks pending and fired state so retries do not create duplicate notifications.

Confirmed site-change alerts use the same state machine but remain suppressed while change scoring is in shadow. When enabled, they describe a confirmed radar-statistics change and carry the site, scene, and trigger time. The notification relay then applies the user's site rules and channel settings.

References: scripts/…/orbital-site-alerts.cjs• L10-36 scripts/…/orbital-site-alerts.cjs• L61-107 scripts/…/orbital-site-alerts.cjs• L155-199 scripts/seed-orbital-sites.mjs• L230-346

Interactive map experience

The map is the main place where a reader explores orbital evidence. A user can open a point from the map, search for a place, use device location, follow a shared link, or open evidence from another map event. The sheet combines pass evidence, archive scenes, watched-site status, nearby event context, and live context around the point.

The evidence sheet keeps one selected pass across the sheet, timeline, and map. Selecting a pass can draw its ground track, footprint, and satellite position on the map. The timeline places images, events, daylight, and pass tiers on one time axis. The sheet also groups capability passes by operator type and shows future open optical and radar collection windows. (src/…/OrbitalWatchPage.ts• L424-460, src/…/OrbitalWatchPage.ts• L925-945, src/…/OrbitalWatchPage.ts• L1109-1177)

The experience keeps image loading distinct from evidence status. Thumbnails load near the viewport, failed or empty archive frames can fall back to earlier frames, and a crop that is not ready is shown as processing. The reader can open the newest scene, inspect source credits, and compare compatible history without treating a missing preview as a missing acquisition. (src/…/OrbitalWatchPage.ts• L204-289, src/…/OrbitalWatchPage.ts• L331-402, src/…/OrbitalWatchPage.ts• L988-1027)

The map protects location privacy in two ways. Share links round points to a 0.01-degree grid. A device-location lookup does not read a watched-site record or reservoir card that could reveal the user's location. When the sheet closes, the map restores its earlier camera instead of publishing the temporary evidence point as the map center.

References: src/…/orbital-watch.ts• L163-212 src/…/orbital-watch.ts• L313-417 src/…/OrbitalWatchPage.ts• L764-910 src/…/OrbitalWatchPage.ts• L925-1177 src/…/OrbitalTimeline.ts• L116-119 src/…/OrbitalPlaceTools.ts• L8-16 src/…/orbital-map-focus.ts• L100-132

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the sensor catalog, coordinate cell, pass tiers, archive matching, and REST/MCP response descriptions aligned.
  • Keep the watched-site cell match, share-link precision, site-ID lookup, and located-user privacy rule aligned.
  • Keep site record publication order, country-rollup freshness, archive backoff, stale responses, and cache headers aligned.
  • Keep change shadow state, flag projection, alert suppression, and pricing copy aligned until change review releases the signal.
  • Keep the browser lookup window and the point-pass API and MCP window contract aligned.
  • Keep image crop sources, processing states, north-up comparison rules, archive credits, and allowed preview hosts aligned.

Important failure modes

TriggerConsequenceGuard
Orbit catalog is missing or too oldPasses can be absent or based on stale orbit data.Mark the catalog stale and do not cache an empty fallback.
An archive refuses during site evaluationA partial run can erase current site evidence or issue repeated requests during an outage.Preserve the last record, publish only accepted work, and back off before the next archive request.
Country index and rollup revisions do not matchA country response can mix site data from different publications.Read the named rollup through the index freshness and schema gate.
A point archive source fails or the answer is incompleteThe reader can mistake missing evidence for no image.Return source failures and unanswered profiles, and do not cache the partial answer.
A scene crop is not ready after it is listedThe viewer can show a false failed image.Treat a recent Sentinel-1 crop 404 as processing for its readiness window.
A device-location point is sent as a watched-site queryA user's location can be linked to a public registry site.Match sites in the browser and send only a registry ID; skip site reads for located points.
Change scoring emits during shadow reviewUnreviewed radar signals can reach users or create alerts.Keep shadow flags separate and suppress change flags and change alerts.
Alert state is lost after publishThe same imaging window or change can notify users again.Persist pending state before publish and use stable coalesce keys.
Orbital launch flags disagreeThe UI can advertise a product that the API returns as unavailable.Gate client entry points and server RPCs separately, with shared launch review.

Key files

FileWhy to read it
shared/watched-sites.tsDefines the monitored place model, source lists, country attribution, and surface rules.
scripts/seed-orbital-catalog.mjsShows how the satellite catalog and historical orbit ring enter the product.
scripts/seed-orbital-sites.mjsShows the scheduled site-evidence lifecycle, publication order, archive backoff, change stage, and alert handoff.
scripts/_orbital-sites.mjsDefines site records, archive acquisitions, pass coverage, and country rollups.
scripts/_orbital-change.mjsDefines radar change scoring, flag states, exclusions, and shadow review.
server/…/get-point-passes.tsShows the rounded point contract, past and future lookup window, archive matching, and cache safety.
server/…/get-country-imagery-evidence.tsShows the country-level watched-site evidence boundary.
api/…/_orbital.tsDefines the paid orbital MCP pass and country-evidence tools.
src/…/orbital-watch.tsCoordinates point lookup, archive evidence, site records, map selection, and track display.
src/…/OrbitalWatchPage.tsDefines the evidence sheet, pass groups, site summary, image states, and user-facing recovery paths.
src/…/OrbitalTimeline.tsDefines the time view for imagery, events, daylight, and passes.
src/…/OrbitalImageViewer.tsDefines scene metadata, archive image review, and before-and-after comparison.
scripts/…/orbital-site-alerts.cjsDefines imaging-window and confirmed-change notification behavior.