Skip to content

Commit 005b706

Browse files
Sam-BollingSam-Bolling
committed
Add publisher thumbnail remediation plan
1 parent 9be220a commit 005b706

1 file changed

Lines changed: 190 additions & 0 deletions

File tree

‎docs/research/new-publisher-source-planning/Publisher_Thumbnail_Remediation_Plan_2026-05-29.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# Publisher Thumbnail Remediation Plan
2+
3+
Date: 2026-05-29
4+
Status: Planning
5+
6+
## Purpose
7+
8+
This plan closes the remaining deployed-system card thumbnail gaps for publisher systems that either lack media metadata or currently resolve to a misleading representative image. The goal is to improve card clarity without destabilizing publisher behavior, CSAPI resource identity, or Explorer map defaults.
9+
10+
## Current Thumbnail Coverage
11+
12+
Most station-style publishers already have acceptable thumbnail coverage through either SensorML `documents` media links or Explorer fallback logic:
13+
14+
| Publisher | Current state |
15+
| --- | --- |
16+
| `nws` | Representative ASOS station image in bootstrap SensorML. |
17+
| `aviation_wx` | Representative ASOS/AWOS station image in bootstrap SensorML. |
18+
| `ndbc` | NDBC station hardware photo path and BuoyCAM image observations. |
19+
| `coops` | NOAA CO-OPS station photo path. |
20+
| `iss` | NASA ISS photograph. |
21+
| `usgs_water` | NIMS camera thumbnail lookup where available. |
22+
| `usgs_nims` | Image observations are the core product. |
23+
| `environment_agency_hydrology` | Representative hydrometric gauge photo. |
24+
| `uk_air` | Representative air-quality station imagery. |
25+
| `bgs_sensorthings` | UKGEOS borehole infrastructure illustration. |
26+
| `met_office_datahub` | Explorer fallback for Met Office land-observation station imagery. |
27+
28+
Remaining gaps:
29+
30+
1. `opensky`
31+
2. `usgs_eq`
32+
3. `met_office_global_spot`
33+
34+
## Gap 1: OpenSky Feed Adapter
35+
36+
### Problem
37+
38+
`publishers/opensky/bootstrap_opensky.py` includes an `image` object in a properties-like structure, but the Explorer deployed-system card extracts thumbnails from SensorML `documents`/`documentation` entries whose link MIME type starts with `image/` or whose role/name includes photo/thumbnail/preview. The current OpenSky image is also a relative path:
39+
40+
`./metadata_enrichment_pack/assets/opensky_feed_adapter_generic.svg`
41+
42+
That relative path is not suitable for production Explorer rendering.
43+
44+
### Desired outcome
45+
46+
OpenSky deployed-system cards should render a representative aviation/feed-adapter thumbnail that communicates aircraft tracking or ADS-B coverage, without implying the system is a single physical aircraft sensor.
47+
48+
### Preferred fix
49+
50+
Update `publishers/opensky/bootstrap_opensky.py` so `_system_sml()` includes a production-resolvable image document in the `documents` list:
51+
52+
```json
53+
{
54+
"role": "http://dbpedia.org/resource/Photograph",
55+
"name": "Representative ADS-B Aircraft Tracking Image",
56+
"description": "Representative image for the OpenSky ADS-B feed-adapter coverage system; not a station-specific photograph.",
57+
"link": {"href": "<hosted image URL>", "type": "image/jpeg"}
58+
}
59+
```
60+
61+
Candidate image requirements:
62+
63+
- stable HTTPS URL,
64+
- permissive license or official source terms that allow reuse,
65+
- aviation / ADS-B / air traffic control / receiver-network visual language,
66+
- not misleading as a specific aircraft observation.
67+
68+
### Fallback option
69+
70+
If no clean external image is selected quickly, add an Explorer-side fallback in `demo/src/composables/useDeployedSystemCard.ts` for text matching `opensky`, `ads-b`, or `aircraft tracking`. This is faster but less portable than SensorML metadata because other CSAPI clients will not benefit.
71+
72+
### Verification
73+
74+
- Re-run OpenSky bootstrap idempotently against a safe target server.
75+
- Confirm the system SensorML contains an image document with an absolute HTTPS URL.
76+
- Open the production Explorer card and verify the image loads with nonzero natural dimensions.
77+
- Confirm OpenSky aircraft observations and map styling are unchanged.
78+
79+
## Gap 2: USGS Earthquake Feed
80+
81+
### Problem
82+
83+
`publishers/usgs_eq/bootstrap_usgs_eq.py` has strong documentation links but no image/thumbnail document. The deployed-system card therefore has no visual signal for the earthquake feed-adapter system.
84+
85+
### Desired outcome
86+
87+
USGS EQ deployed-system cards should render a representative seismic/earthquake thumbnail that clearly identifies the system as an event feed, not a physical fixed station.
88+
89+
### Preferred fix
90+
91+
Add an image document to `_system_sml()` in `publishers/usgs_eq/bootstrap_usgs_eq.py`.
92+
93+
Candidate image requirements:
94+
95+
- official USGS or public-domain seismic/earthquake visual preferred,
96+
- stable HTTPS URL,
97+
- either `image/jpeg`, `image/png`, or `image/svg+xml`,
98+
- description should state that it is representative feed imagery, not an event-specific image.
99+
100+
Suggested document shape:
101+
102+
```json
103+
{
104+
"name": "Representative Earthquake Feed Image",
105+
"description": "Representative visual for the USGS Earthquake Hazards feed adapter; event observations carry their own locations and metadata.",
106+
"link": {"href": "<hosted image URL>", "type": "image/jpeg"}
107+
}
108+
```
109+
110+
### Fallback option
111+
112+
Add an Explorer-side representative thumbnail fallback for text matching `usgs earthquake`, `earthquake hazards`, `seismic event`, or `earthquake feed`. This should remain secondary to a real SensorML media document.
113+
114+
### Verification
115+
116+
- Re-run `python -m publishers.usgs_eq.bootstrap_usgs_eq` idempotently on a safe target.
117+
- Verify the `USGS Earthquake Feed` card renders the selected thumbnail.
118+
- Verify event observations still display magnitude, place, depth, status, and USGS detail links.
119+
- Confirm publisher dedup behavior is unchanged.
120+
121+
## Gap 3: Met Office Global Spot Forecast
122+
123+
### Problem
124+
125+
`met_office_global_spot` systems are virtual forecast points, not physical deployed sensors. Explorer's current broad Met Office fallback can assign a land-observation station photograph to Global Spot forecast cards, which is visually polished but semantically misleading.
126+
127+
### Desired outcome
128+
129+
Met Office Global Spot cards should use forecast-appropriate imagery or no physical station image. The thumbnail should communicate forecast/model/data service semantics rather than implying an instrumented station exists at the forecast point.
130+
131+
### Preferred fix
132+
133+
Add a more specific Explorer fallback before the generic Met Office land-observation fallback in `demo/src/composables/useDeployedSystemCard.ts`:
134+
135+
1. Match `global spot`, `site-specific forecast`, or `forecast point` first.
136+
2. Return a forecast/model/data-service image, not a station photo.
137+
3. Keep `met_office_datahub` land observations using the existing weather-station fallback.
138+
139+
If a clean hosted image is found, also add a SensorML image document in `publishers/met_office_global_spot/bootstrap_met_office_global_spot.py` so the metadata is portable.
140+
141+
### Candidate image requirements
142+
143+
- official Met Office brand/data-service page image if reuse terms permit, or a neutral forecast/map visualization with permissive licensing,
144+
- stable HTTPS URL,
145+
- no suggestion of a physical station or observation mast,
146+
- description should explicitly say `forecast point` and `not a physical sensor`.
147+
148+
### Verification
149+
150+
- Rebuild Explorer and inspect the Global Spot deployed-system card.
151+
- Confirm `met_office_datahub` land-observation cards still use the station photo fallback.
152+
- Confirm forecast summaries remain visible and labeled as forecasts.
153+
154+
## Implementation Order
155+
156+
1. Research and select image sources for OpenSky, USGS EQ, and Met Office Global Spot.
157+
2. Prefer publisher SensorML document fixes for OpenSky and USGS EQ.
158+
3. Add Explorer-specific fallback only where metadata propagation is blocked or a virtual-system distinction is needed.
159+
4. Re-run targeted bootstraps idempotently on the target CSAPI server.
160+
5. Rebuild Explorer if fallback logic changes.
161+
6. Smoke test deployed-system cards in production or staging.
162+
7. Document the completion result in `docs/research/new-publisher-source-planning/`.
163+
164+
## Acceptance Criteria
165+
166+
- OpenSky card has a visible aviation/feed-adapter thumbnail.
167+
- USGS EQ card has a visible seismic/event-feed thumbnail.
168+
- Met Office Global Spot no longer uses a physical land-observation station photo unless source metadata explicitly provides one.
169+
- No existing station-style publisher loses its current thumbnail.
170+
- No publisher UID, datastream output name, or deployment hierarchy changes.
171+
- No map default, layer toggle, OpenSky icon, or latest-reading behavior changes.
172+
173+
## Files Likely To Change
174+
175+
Publisher repo:
176+
177+
- `publishers/opensky/bootstrap_opensky.py`
178+
- `publishers/usgs_eq/bootstrap_usgs_eq.py`
179+
- `publishers/met_office_global_spot/bootstrap_met_office_global_spot.py` if a portable SensorML image is selected
180+
181+
Explorer repo, only if fallback logic is needed:
182+
183+
- `demo/src/composables/useDeployedSystemCard.ts`
184+
185+
## Safety Notes
186+
187+
- Do not rerun destructive bootstrap cleanup flags.
188+
- Do not modify publisher observation schemas for this work.
189+
- Avoid broad Explorer text matching that accidentally changes unrelated Met Office land-observation thumbnails.
190+
- If live OSH still rejects some system SensorML updates, use Explorer fallback as a pragmatic production bridge and record the server behavior in the completion report.

0 commit comments

Comments
 (0)