VFR Flight Plan Generator

• METARs: https://aviationweather.gov/api/data/metar?ids=KRHV,KKIC&format=raw (comma-separated ICAO codes)
• TAFs: https://aviationweather.gov/api/data/taf?ids=KRHV,KKIC&format=raw
• Winds & Temps Aloft (FD forecasts): https://aviationweather.gov/api/data/windtemp?region=sfo&level=low&fcst=06
  • Use the 6-hour forecast (fcst=06). The region parameter should match the area of flight (e.g., sfo for Northern California, lax for Southern California).
  • Winds aloft are reported at specific stations (e.g., SFO, SAC, SBA). Interpolate geographically between stations for winds at each checkpoint along the route.
• PIREPs: https://aviationweather.gov/api/data/pirep?id=KRHV&distance=100&format=raw
• AIRMETs/SIGMETs: https://aviationweather.gov/api/data/airsigmet

For terminal information (field elevation, runway lengths, frequencies), use airnav.com: https://www.airnav.com/airport/KRHV (replace ICAO code as needed). This provides elevation, runway dimensions, and radio frequencies.

Step 1: Gather Information from the User

Ask for the following (some may already be provided):

Aircraft:

• N-number (e.g., N2316T)
• Type (e.g., C172/G)
• True airspeed at cruise (KTAS)
• Fuel burn rate (GPH)
• Compass deviation (DEV) — usually 0 for most headings
• Fuel on board (hours + minutes)
• Color of aircraft

Route:

• Departure airport (ICAO)
• Destination airport (ICAO)
• Checkpoints along the route (visual landmarks, VORs, airports)
• Whether the user wants a specific intermediate airport as a checkpoint (e.g., for fuel or as an alternate)
• Checkpoint spacing rule: Checkpoints must be placed approximately every 15 nautical miles along the route. No cruise leg should exceed ~15 NM. When the user says "direct" or "you pick checkpoints," identify airports, VORs, or charted visual reporting points from the Sectional chart at roughly 15 NM intervals. Prefer airports (ICAO identifiers) as checkpoints since they are always charted and easy to identify visually. Climb and descent legs may be shorter (8-10 NM is typical).
• Pilot certificate level: Whether the pilot is a student pilot, private pilot, etc. Student pilots CANNOT enter Class B airspace and should avoid Class C airspace. This fundamentally affects route selection.

For each leg, you need:

• True course (TC) — measured from a sectional chart or computed
• Distance (NM)
• Planned altitude
• Wind direction and velocity at that altitude (from winds aloft forecast)
• Temperature at altitude (if available, otherwise "STD")

Terminal information:

• Field elevation, runway info, and radio frequencies for departure and destination

Page 2 (optional):

• Weather briefing notes (TAF airports, METAR airports, winds aloft station)
• FAA flight plan details (proposed departure time, cruising altitude, route description, remarks, passengers, alternate airport)

Airspace Considerations

When selecting a route, always consider airspace restrictions based on the pilot's certificate level:

Class B airspace (the "upside-down wedding cake" around major airports like SFO, LAX, JFK):

• Student pilots are PROHIBITED from entering Class B airspace unless they have a specific logbook endorsement for that specific Class B area, which is rare. Always assume a student pilot does NOT have Class B authorization unless they explicitly say otherwise.
• Class B shelves are shown on Sectional/TAC charts with notation like "100/60" meaning ceiling 10,000 ft MSL, floor 6,000 ft MSL. If your cruising altitude is BELOW the floor of a shelf, you are outside Class B and can fly under it.
• Example: At 4,500 MSL in the Bay Area, you can safely fly under the "100/60" shelf (floor 6,000) and "100/50" shelf (floor 5,000) but NOT under the "100/40" shelf (floor 4,000).

Class C airspace (around airports like OAK, SJC, SMF):

• Requires two-way radio communication with ATC and a transponder. Student pilots CAN enter Class C but it adds workload and may be intimidating. Avoid when practical.

Class D airspace (around smaller towered airports like KRHV, KLVK, KCCR, KAPC):

• Requires two-way radio communication with the tower. Fine for all pilots, including students.

Route planning for airspace avoidance:

• In the San Francisco Bay Area, the direct north-south route along the Bay shore (KRHV → KNUQ → KHWD → KOAK) goes through SFO Class B and Oakland Class C. Student pilots should instead use the east corridor through the Livermore Valley: KRHV → Sunol area → KLVK → Walnut Creek/Concord → northward. At 4,500 MSL, this corridor stays below the Class B shelves.
• Always check the TAC or Sectional chart for the specific shelf floors at your planned altitude before committing to a route.
• When in doubt, route further from the Class B core airport, even if it adds distance.

Step 2: Flight Planning Math

For each leg, compute these values in order:

1. Wind Correction Angle (WCA): Use the wind triangle. WCA = arcsin((wind_speed / TAS) * sin(wind_direction - true_course)). Positive WCA means crab right, negative means crab left. Display with sign (e.g., "+7", "-3").

2. True Heading (TH): TH = TC + WCA

3. Magnetic Heading (MH): MH = TH + VAR (where VAR is the local magnetic variation; negative in the western US, e.g., -13 for the San Francisco Bay Area). The variation is obtained from the sectional chart isogonic lines.

4. Compass Heading (CH): CH = MH + DEV (deviation from compass card, usually 0).

5. Groundspeed (GS): From the wind triangle. GS = TAS * cos(WCA) + wind_speed * cos(wind_direction - true_course). Or compute more precisely using the full wind triangle equations.

6. ETE: ETE = (distance / GS) * 60 (in minutes, then format as MM:SS).

7. Fuel Used: fuel = (ETE_hours) * GPH

8. Remaining Distance: Cumulative distance remaining from each checkpoint to destination.

9. Fuel Remaining: Starting fuel minus cumulative fuel used.

Important notes on the climb and descent legs:

• The first leg is typically a climb leg — use a reduced TAS (e.g., 74 kts for a C172) and higher fuel burn
• The last leg may be a descent leg — use a reduced TAS (e.g., 75 kts) with altitude shown as "Desc"
• Winds for climb/descent legs are typically interpolated from surface winds and winds at altitude

Step 3: Generate the PDF Overlay

Read and use the template script at scripts/build_overlay_template.py. This is a fully working Python script that generates the overlay. You will need to customize it for each flight plan by:

1. Updating the legs data array with the computed flight data
2. Updating terminal information (airports, elevations, runways, frequencies)
3. Updating notes
4. Updating Page 2 data (weather briefing labels, FAA flight plan fields)
5. Updating the header (N-number, GPH)

The template script contains all the precise grid coordinates for the ASA form, which were painstakingly measured at 600dpi. Do not change the coordinate constants unless the user reports alignment issues.

Key Technical Details

Coordinate system:

• The ASA form is scanned at 300dpi. Page 1 is landscape (766.56 x 593.28 points). Page 2 is portrait (599.52 x 766.56 points) with Rotation=270.
• Scale factor: S = 300/72 = 4.1667 pixels per PDF point
• px(pixel_x) = pixel_x / S converts 300dpi pixel x to PDF x coordinate
• py(pixel_y) = P1_H - pixel_y / S converts 300dpi pixel y to PDF y coordinate (reportlab y=0 at bottom)

Font: Caladea Bold (/usr/share/fonts/truetype/crosextra/Caladea-Bold.ttf). Install with apt-get install fonts-crosextra-caladea if not present.

Page 2 rotation: Page 2 has a 270-degree rotation in the PDF. The script handles this by applying rotate(-90) + translate(-P2_H, 0) to work in visual coordinates. FAA flight plan fields need an additional rotate(90) at each text position so text reads bottom-to-top.

The Blank Form

A copy of the blank ASA Flight Planner form is bundled at assets/Flight-Plan-Form-2004.pdf. Copy it to your working directory before running the build script. If the user provides a different version of the form, use that instead. The form has two pages:

• Page 1: Preflight planning grid (left) + En route section (right) + Terminal info + Notes (bottom)
• Page 2: Weather briefing (left) + FAA flight plan form (right)

Grid Reference

For the precise column and row boundaries of the ASA form, see references/asa-form-grid.md. This file documents every vertical and horizontal grid line measured at 600dpi, along with the computed column centers used in the template script.

Step 4: Build and Verify

1. Run the build script: python build_overlay.py
2. The script automatically renders verification images at 300dpi
3. Check the verification crops (preflight area, en route area, header, terminal info) to confirm text is properly positioned in cells
4. If the user reports misalignment, refer to references/asa-form-grid.md for the grid boundaries and adjust the relevant coordinate constants

Leg Data Structure

Each leg in the data array needs these fields:

{
  "tc": 145,          // True Course (degrees)
  "alt": "5,500",     // Altitude (string — can be "Climb", "Desc", or "5,500")
  "wd": 225,          // Wind Direction (degrees)
  "wv": 13,           // Wind Velocity (knots)
  "temp": "+10",      // Temperature (string — "+10", "STD", or "")
  "tas": 108,         // True Airspeed (knots)
  "wca": "+7",        // Wind Correction Angle (string with sign)
  "th": 152,          // True Heading (degrees)
  "mh": 139,          // Magnetic Heading (degrees)
  "var": -13,         // Magnetic Variation (negative = West)
  "dev": 0,           // Compass Deviation
  "cp": "GILROY",     // Checkpoint name
  "ch": 139,          // Compass Heading (degrees)
  "leg": 9.8,         // Leg distance (NM)
  "rem": 56.4,        // Remaining distance (NM)
  "gs": 100,          // Groundspeed (knots)
  "ete": "5:52",      // Estimated Time En Route (MM:SS)
  "fu": 1.0,          // Fuel used this leg (gallons)
  "fr": 49.3          // Fuel remaining (gallons)
}

Common Pitfalls

• TH vs MH columns: The TRUE HEADING and MAG HEADING are separate columns with a thick boundary at x=1372. TH goes in the left column (1206-1372), MH goes in the right column (1372-1552). These look close together and it's easy to put both values in the same column.
• Sub-rows: Each data row has a top sub-row (main values like TH, MH) and a bottom sub-row (VAR, DEV). The row_y() function handles this.
• Page 2 text orientation: FAA flight plan fields read bottom-to-top, requiring a 90-degree rotation at each text position. Weather briefing text reads normally (horizontal).
• Long checkpoint names: Names longer than 10 characters should use a smaller font to fit in the cell. The template handles this automatically.
• Altitude as string: The altitude field can contain text like "Climb" or "Desc" for the first and last legs, so it's stored as a string.
• Checkpoint spacing: Never create legs longer than ~15 NM. If two airports are 30+ NM apart, find an intermediate checkpoint (airport, VOR, or charted visual point) between them. The ASA form has 10 data rows, which is plenty for a well-spaced route.
• Checkpoint validity: Only use checkpoints that appear on the FAA Sectional or TAC chart. Valid checkpoint types: (1) airports with ICAO identifiers (e.g., KLVK, KCCR), (2) VOR stations with three-letter IDs (e.g., SJC, SGD), (3) charted VFR visual reporting points that have VP codes (e.g., VPDAM for Del Valle Dam, VPWAL for Walnut Creek). Do NOT use city names, generic landmark names, or any point that is not explicitly printed on the chart. If you cannot find a VP code for a landmark, it is not a valid charted VFR checkpoint.
• Airspace avoidance: For student pilots, Class B airspace is PROHIBITED. Plan routes that stay entirely outside Class B boundaries at the planned altitude. Check TAC/Sectional charts for shelf floor altitudes — notation like "100/60" means ceiling 10,000 ft, floor 6,000 ft. If your cruising altitude is below the floor, you are safely outside Class B. Class C airspace should also be avoided when practical for student pilots, as it adds ATC communication workload. Class D airspace (towered airports) is fine — it only requires radio contact with the tower.