planet/docs/technical/en/earth-satellite-footprint-policy.md

Earth Satellite Footprint Policy

This document records the current product boundary, data rationale, and implemented behavior for footprint in the Earth satellite layer. The goal is to prevent the Starlink-specific ground coverage model from being misapplied to other constellations.

Related context:

• Earth Frontend Context
• Backend Collectors
• backend/app/services/collectors/celestrak.py
• frontend/public/earth/js/satellites.js

Current Goal

• Define which non-Starlink satellites should not show a ground footprint
• Define which constellations may have their own footprint in the future but cannot reuse the Starlink bowtie / GSO-gap model
• Solidify this policy as an executable implementation boundary, not leave it scattered across visual parameters

Current Local Categories

The CelesTrak collector now prefers the complete active satellite catalog from GROUP=active&FORMAT=json. This prevents one failed CelesTrak group request from being saved as a successful but incomplete batch. The collector only proceeds when the downloaded JSON is a parseable array and records include NORAD_CAT_ID; network, resume, or parsing failures are retried, and final failure preserves the previous current dataset.

CelesTrak applies a repeat-download window to large groups such as active. To make database resets recoverable, Planet stores raw downloads under $PLANET_CACHE_DIR/downloads. When active returns the CelesTrak "GP data has not updated" HTTP 403:

• If an active cache exists, the collector reuses it to repopulate the database.
• If no active cache exists, the collector switches to fallback group mode and downloads starlink, gps-ops, galileo, glonass, beidou, leo, geo, and iridium-next.
• Fallback group mode requires every group to succeed or have a reusable cache; if any group is missing, the whole collection fails and no partial dataset is saved.

The collector still provides metadata.constellation_group to the frontend, but the value now comes from executable inference:

• OBJECT_NAME starting with STARLINK is marked as starlink
• OBJECT_NAME starting with IRIDIUM is marked as iridium-next
• Other active satellites are not forced into the old CelesTrak small-group labels, because a broad source group is not an exact constellation

The product policy therefore still discusses GNSS/RNSS, GEO, generic LEO, and Iridium NEXT semantics. However, only fallback group mode stores the old gps-ops, galileo, glonass, beidou, leo, or geo labels; the active primary path does not force every satellite into those labels.

Research Conclusions

1. GNSS / RNSS: gps-ops, galileo, glonass, beidou

Do not draw a localized ground footprint by default.

Reason:

• Public sources emphasize Earth-pointing, Earth coverage, continuous global coverage
• The public semantic of these systems is global navigation / timing coverage, not the localized spot footprint associated with Starlink's end-user service

More appropriate representation:

• Default: show only the satellite body and orbit
• If future needs require showing "service reachability," only a weak global coverage semantic is appropriate — do not draw a localized ground spot

References:

• GPS III EC Antenna Patterns
• ESA Galileo satellites
• Navipedia Galileo General Introduction
• BeiDou official overview
• GPS.gov GNSS overview

2. iridium-next

Can have a footprint, but cannot reuse Starlink's single bowtie footprint.

Reason:

• Iridium NEXT public documentation emphasizes a fixed multi-spot beam system
• Public examples commonly show 48 fixed spot beams in 4 tiers
• This is not the same problem as Starlink's "single satellite, single primary footprint, with GSO gap" business visualization

More appropriate representation:

• Default: still do not draw a Starlink-style ground footprint
• Future implementation: connect an independent Iridium multi-beam adapter layer
• Visually closer to multi-beam clusters / honeycomb / layered beams, not a single bowtie spot

Reference:

• Iridium Satellite Spot Beam Coverage on the US

3. geo

Do not draw a unified footprint by default.

Reason:

• GEO communication satellites may use global beam, zone beam, spot beam, or steerable spot beam
• Without operator / payload / beam contour metadata, drawing a unified footprint is very likely incorrect

More appropriate representation:

• Default: show only the GEO belt and satellite parking position semantics
• Only allow footprint drawing when beam contour / operator metadata is available

Reference:

• ITU Handbook on Satellite

4. leo (generic)

Do not draw a footprint by default.

Reason:

• The leo group is too mixed — it may include communication, remote sensing, experimental, and observation satellites
• Without mission / payload / antenna pattern metadata, there is no basis for a service-coverage visualization

More appropriate representation:

• Default: show only the satellite and orbit
• Future: if subdivided by operator / mission subtype, decide then whether to introduce an independent coverage mode

Product Policy

Current unified policy:

• Starlink
  • Keep the current dedicated ground_footprint logic
• Iridium NEXT
  • Reserve an independent adapter layer
  • Do not reuse Starlink footprint currently
• GPS / Galileo / GLONASS / BeiDou
  • No ground footprint
• GEO
  • No footprint without beam metadata
• Generic LEO
  • No footprint without mission metadata

Implemented Behavior

This implementation only does the minimum executable version and does not change existing Starlink visual parameters:

1. Backend passes constellation group and footprint policy hint to the frontend

• CelesTrak collector stores the source query in metadata.celestrak_query_group = active
• metadata.constellation_group only stores inferred business constellations such as starlink and iridium-next
• Visualization API outputs:
  • properties.constellation_group
  • properties.footprint_policy

Current policy values:

• starlink_ground_footprint
• iridium_coverage_ring
• none

Relevant code:

• backend/app/services/collectors/celestrak.py
• backend/app/api/v1/visualization.py

2. Frontend makes footprint a capability-gated renderer

• ground_footprint is only actually enabled when footprint_policy === starlink_ground_footprint
• iridium-next no longer falls back to a placeholder branch; it goes through an independent Iridium coverage ring adapter
• Other non-Starlink satellites automatically fall back to self_glow even if the user globally selects ground_footprint

Relevant code:

• frontend/public/earth/js/satellites.js
• frontend/public/earth/js/iridium-footprint-adapter.js

3. Satellite info card shows capability, not just orbital parameters

• Satellite details now clearly display:
  • Constellation / Group
  • Coverage Capability
  • Current Display
  • Coverage Model
• Users can directly see:
  • Whether the current satellite supports footprint
  • Whether the current display has been fallen back due to capability gating
  • That Iridium and Starlink use different models

Relevant code:

• frontend/public/earth/js/main.js
• frontend/public/earth/js/info-card.js

Current Implementation Boundary

This boundary must be maintained:

• Starlink's footprint parameters and shader logic serve Starlink only
• Non-Starlink capability decisions belong to the "policy layer / adapter layer"
• Do not re-mix different constellations' coverage models into the same parameter set
• iridium-next has been separated into an independent adapter and should continue along this boundary rather than adding more if/else to the existing Starlink bowtie

Recommended Next Steps

If continuing forward, the recommended order is:

1. Create a dedicated footprint adapter for iridium-next
2. Add a read-only indicator in the UI to tell users whether the current satellite supports footprint
3. If GEO beam contour / operator metadata becomes available, enable operator-specific footprint for GEO