FlightPlot/REQUIREMENTS.md

# Flight Map Requirements

## Purpose

Create a Python program that generates an SVG map of a rectangular geographic
area with recorded aircraft flight tracks overlaid, suitable for drawing with
a physical pen plotter.

## Separate collection and plotting workflow

- Provide separate command-line commands for flight-data collection and SVG
  generation. Run collection first; generate maps later from the saved database.
- The collection command accepts optional opposite map corners and the SQLite
  database destination. If corners are omitted, use the default map area
  including Uithoorn in the Netherlands. It records flight data without
  generating an SVG or requiring map or terrain downloads.
- Store a recording-session record containing a session identifier, the
  normalized requested map bounds, the expanded collection bounds, the flight
  data source, the collection interval, and the recording start and end times.
  Preserve this metadata across interruption or restart.
- Associate every stored flight observation with its recording session so its
  map area and collection context remain identifiable.
- The plotting command accepts the database, a recording-session selection,
  an optional time interval within that recording, and output settings.
  Use the selected session's stored map bounds rather than requiring the user
  to enter the map area again.
- Plotting must not contact OpenSky or start flight-data collection. It may
  obtain OpenStreetMap-derived vector data and terrain elevation data
  separately as needed.
- Allow multiple maps with different time selections and output settings to be
  generated from the same recording without modifying the recorded flight
  observations or session metadata.
- Report missing sessions, invalid time selections, and absence of usable
  observations explicitly.
- Provide a purge command requiring an exact session identifier and explicit
  confirmation to permanently delete that session's observations and metadata
  in one transaction. Preserve all other sessions and their observations.
- Purging a missing session or database must report an error without creating
  a database. Stop collection for the selected session before purging it.

## Map input and output

- At collection time, accept the longitude and latitude of two opposite corners
  of the map, validate coordinates, and normalize their order.
- Provide a predefined default rectangular map area that includes the city of
  Uithoorn in the Netherlands. Explicitly supplied corners override this default.
- Default southwest corner: latitude 52.232, longitude 4.784.
  Default northeast corner: latitude 52.258, longitude 4.864.
  Command-line bounds use longitude first: 4.784 52.232 4.864 52.258.
- Store the actual bounds used, including when the default is selected, in the
  recording session. Later plotting must use those stored bounds rather than
  a potentially changed application default.
- At plotting time, load the map bounds from the selected recording session.
- Obtain OpenStreetMap-derived vector map data, either as vector tiles or
  geographic feature data, following the source's usage policy and including
  the required attribution. Standard raster map tiles are not suitable for
  the pen-plotter output.
- Cache downloaded vector map data persistently by source, geographic bounds,
  and feature query. Reuse it across plotting runs without downloading it
  again. Provide a configurable cache directory and an explicit refresh option.
- Write cache entries atomically so interrupted downloads or writes do not
  replace a previously usable entry. Report damaged cache entries explicitly.
- Generate an SVG using a consistent geographic projection for the map and
  flight tracks.
- Handle invalid input and download failures with clear error messages.

## Pen-plotter output

- Render map features and flight tracks as vector paths or line geometry,
  without embedded raster images or reliance on filled areas, shading, or
  other screen-only effects.
- Render all labels and attribution as paths, using single-line stroke
  lettering suitable for pen plotting rather than relying on installed fonts
  or tracing filled glyph outlines.
- Resolve clipping into the exported geometry so map features stop at the map
  boundary and flight-track extensions remain within the output page. Do not
  rely on SVG clipping masks being supported by the plotter software.
- Specify physical page dimensions and a matching SVG viewBox so the intended
  drawing size is preserved when imported into plotter software.
- Keep map geometry, flight tracks, and lettering in separate named SVG groups
  for independent selection and plotting.
- Select and simplify map features to keep the drawing legible at its physical
  output size. Omit minor pedestrian and cycle paths and suppress building
  outlines whose shorter dimension is smaller than three pen widths.

## Flight data and local recording

- Use OpenSky Network as the initial flight-data source.
- Retrieve live aircraft state vectors for the selected geographic area.
- Query an area slightly larger than the map so recorded flight paths can
  extend beyond the map boundary.
- Collect positions periodically, respecting OpenSky's current authentication
  requirements, rate limits, and usage terms.
- Store observations locally in SQLite so maps can be generated later without
  fetching those observations again.
- Store the aircraft's ICAO identifier, callsign when available, position
  timestamp, longitude, latitude, and available altitude measurements.
- Support generating a map from locally recorded observations for a selected
  time interval.
- Do not require historical data from before local recording began. Unrestricted
  historical access is not assumed.
- Report recording failures explicitly and handle missing fields and gaps in
  coverage without inventing observations.
- Initial use is non-commercial, subject to OpenSky's applicable terms and
  attribution requirements.

## Flight-track rendering

- Overlay recorded flight paths that cross the requested map area.
- Fit smooth interpolating curves through recorded flight positions rather
  than drawing angular polylines. Export flight paths as cubic Bezier geometry
  suitable for a pen plotter. Two-point tracks may remain straight.
- Do not smooth across track gaps, on-ground interruptions, or flight changes.
  Handle repeated positions without generating invalid curve coordinates.
- Clip the actual curves to the output bounds, not just their sample points,
  and use the same curved in-map portions for time and average-altitude selection.
- Extend the visible tracks a little beyond the map boundary using actual
  recorded positions from the surrounding area, not fabricated extrapolation.
- Keep the map background within its requested bounds and provide space in the
  SVG for the extended tracks and their labels.
- Identify each flight track with its date, time, callsign or flight number when
  available, and average reported barometric (pressure) altitude in metres.
- Do not present an OpenSky callsign as a verified passenger-facing flight
  number. Callsign-to-flight-number lookup is not required for the initial
  version.
- Calculate the map's average ground elevation from terrain elevation data
  for landmass within the requested map bounds, excluding mapped water and the
  surrounding collection area. Preserve islands in water multipolygon relations.
  Use an area-weighted mean or an equivalent equal-area sampling method.
- Average valid land samples only. Report the percentage and counts of sampled
  land with valid elevations, warn about missing land samples, and never classify
  missing terrain as water. Show land coverage in the SVG legend and metadata.
- Obtain AHN DTM height maps automatically through PDOK during plotting for the
  Netherlands. Cache validated GeoTIFF subsets persistently and atomically,
  record source and NAP reference, and support explicit refresh and disabling
  of automatic terrain retrieval. Explicit local terrain inputs take precedence.
- If AHN height maps are unavailable or the area is outside coverage, warn
  explicitly and continue rendering with the land-elevation summary unavailable.
  Reported aircraft altitude must remain independent of terrain availability.
- Calculate each track's time-weighted average reported barometric altitude
  over the portion inside the requested map bounds. Outside-map extensions
  must not affect this calculation.
- Do not subtract ground elevation or apply geoid, pressure, or vertical-reference
  corrections to aircraft altitude. The average land elevation is a separate,
  informational summary only.
- Label aircraft values explicitly as reported barometric altitude with units,
  not height above ground, terrain clearance, or verified altitude above sea level.
- Missing barometric altitude on a contributing segment makes that track's
  average unavailable, with an explicit warning. Do not fall back to geometric
  altitude. Zero and negative reported values are valid.
- Make labels readable and indicate unavailable metadata explicitly.

## Implementation and validation

- Implement the program in Python with a command-line interface.
- Document installation, the separate collection and plotting commands,
  session selection, map generation, configuration, data-source limitations,
  and attribution.
- Test coordinate handling, projection, local recording, track selection,
  average land elevation, average reported barometric altitude, missing altitude
  and elevation data, terrain-independent flight labels, and SVG generation.
- Test persistence of session bounds and observation associations, plotting
  after collection has stopped, and repeated plotting without changing the
  recorded flight data. Verify that collection does not require map or terrain
  services and plotting makes no OpenSky requests.
- Test that omitting map corners selects the Uithoorn default, explicit corners
  override it, and the selected bounds are persisted for later plotting.
- Validate that the exported SVG contains drawable vector geometry, path-based
  lettering, correct physical dimensions, and geometry clipped to its intended
  bounds, with no raster images or dependence on text rendering or clipping
  masks.
- Include an end-to-end test using fixed sample data without requiring live
  network access.
- Test cache reuse, separate entries for different map areas, explicit refresh,
  and preservation of cached data when refresh fails.

## Initial implementation defaults and limitations

- Use Overpass to obtain OpenStreetMap roads, waterways, building outlines, and
  water outlines, with local Overpass JSON also accepted for offline plotting.
- Default to A4 landscape (297 by 210 mm), 12 mm page margins, a 0.3 mm pen,
  and track extensions of up to 4 mm beyond the map border.
- Collect every 30 seconds within a 2,000 m margin around the saved map area.
- Display timestamps in UTC using date and 24-hour time, and altitudes in metres.
- Use PDOK AHN DTM `dtm_05m` via WCS for Dutch areas, requesting a 512 by 512
  nearest-neighbour subset in EPSG:28992, with elevations in metres relative
  to NAP. Accept local terrain GeoTIFFs with a declared vertical reference for
  the separate land-elevation summary. No geoid or aircraft datum conversion
  inputs are required or used.
- Estimate average land elevation using a 64 by 64 equal-area sampling grid.
  Exclude mapped water, average available land elevations, and warn about missing
  land coverage. No valid land samples makes the average unavailable.
- Use time-weighted reported barometric altitude with linear interpolation between recorded
  timestamps, restricted to the smoothed path's portion inside the map. Use
  centripetal Catmull-Rom interpolation converted to cubic Bezier curves for
  flight paths. Split tracks at changes
  in callsign, on-ground observations, or gaps exceeding 120 seconds by default.
- Reject antimeridian-crossing bounds and latitudes outside [-85, 85] explicitly.