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](/home/ray/dev/linkong/planet/docs/technical/en/earth-frontend-context.md)
- [Backend Collectors](/home/ray/dev/linkong/planet/docs/technical/en/backend-collectors.md)
- [backend/app/services/collectors/celestrak.py](/home/ray/dev/linkong/planet/backend/app/services/collectors/celestrak.py)
- [frontend/public/earth/js/satellites.js](/home/ray/dev/linkong/planet/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](https://www.navcen.uscg.gov/sites/default/files/pdf/gps/GPS_ZIP/GPS_III_EC_Antenna_Patterns_SVN_74_75_76_77_78.pdf)
- [ESA Galileo satellites](https://www.esa.int/Applications/Satellite_navigation/Galileo/Galileo_satellites)
- [Navipedia Galileo General Introduction](https://gssc.esa.int/navipedia/index.php/Galileo_General_Introduction)
- [BeiDou official overview](https://www.beidou.gov.cn/xt/gfxz/201812/P020190117356387956569.pdf)
- [GPS.gov GNSS overview](https://www.gps.gov/systems/gnss/)

### 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](https://www.mathworks.com/help/phased/ug/iridium-satellite-spot-beam-coverage-on-the-us-1.html)

### 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](https://www.itu.int/dms_pub/itu-r/opb/hdb/R-HDB-42-2002-PDF-E.pdf)

### 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](/home/ray/dev/linkong/planet/backend/app/services/collectors/celestrak.py)
- [backend/app/api/v1/visualization.py](/home/ray/dev/linkong/planet/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](/home/ray/dev/linkong/planet/frontend/public/earth/js/satellites.js)
- [frontend/public/earth/js/iridium-footprint-adapter.js](/home/ray/dev/linkong/planet/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](/home/ray/dev/linkong/planet/frontend/public/earth/js/main.js)
- [frontend/public/earth/js/info-card.js](/home/ray/dev/linkong/planet/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