Migration

Diese Seite wurde aus der AirSimTech MediaWiki migriert.

Trajectory Module — Function Reference

This page documents every function and sub in the trajectory computation module. Each entry describes entry parameters, return values, purpose, algorithm, and callers.

TrajectoryActor.vb

TrajectoryActor Class

The main 4D trajectory computation actor. Runs on its own Akka.NET actor thread, receives ComputeTrajectory messages, and publishes TrajectoryResult via the EventStream.

Sub New (Constructor)

Entry Parameters	Type	Description
(none)		Actor constructor; Akka calls this via `Props.Create`

Outgoing	Description
(none)	Registers `Receive(Of ComputeTrajectory)` handler

Purpose: Initializes the actor with queue-latest-only concurrency (D-03 pattern). Registers the message handler that calls StartComputation.

How it works: Uses Akka ReceiveActor base class. The Receive(Of ComputeTrajectory) handler filters duplicate messages and delegates to StartComputation.

Called by: Akka actor system via Props.Create(Of TrajectoryActor)() in FmgcSupervisor.

Sub PreStart

Entry Parameters	Type	Description
(none — Overrides)		Akka lifecycle hook

Purpose: Preloads performance data from FMGCPERF1.MDB into the in-memory PerfDataStore (D-09, D-10). Falls back to formula-based model if MDB is unavailable.

How it works: Opens OleDb connection to performance database, reads all performance records into a tri-linear interpolation cache indexed by altitude, weight, and phase. Closes connection immediately after preload.

Called by: Akka actor lifecycle (automatically before first message).

Sub StartComputation

Entry Parameters	Type	Description
msg	ComputeTrajectory	Contains flight plan legs, cruise altitude, ZFW, FOB, cost index, winds, IAS targets, UTC offset

Outgoing	Description
TrajectoryResult	Published to EventStream; contains climb/cruise/descent profiles, T/C, T/D, fuel totals, timing, log entries

Purpose: Main orchestrator. Filters navigation legs, resolves computed-position legs (CA/VA/FA), computes all three profiles, stitches them together, and publishes the result.

How it works:

Filters legs to navigation-relevant types (Adep, Climb, Normal, Ades, EndOfFlight, EndOfAlt)
Resolves 0,0 lat/lon legs via LegGeometry.ComputeLegGeometry
Calls ComputeClimbProfile (forward from departure)
Calls ComputeDescentProfile (backward from destination)
If T/C ≥ T/D: activates short-route altitude capping via FindCrossoverAltitude
Calls ComputeCruiseProfile (T/C to T/D at cruise altitude)
Stitches all three profiles into allPoints list
Publishes TrajectoryResult to EventStream

Called by: Receive(Of ComputeTrajectory) handler in Sub New.

Calls: ComputeTotalRouteDistance, ComputeClimbProfile, ComputeDescentProfile, FindCrossoverAltitude, ComputeCruiseProfile, LegGeometry.ComputeLegGeometry

Function ComputeClimbProfile

Entry Parameters	Type	Description
msg	ComputeTrajectory	Full trajectory message with fuel, weight, speeds, winds
legs	IReadOnlyList(Of FlightPlanLeg)	Filtered navigation legs
totalRouteDistNm	Double	Total route distance in NM
crzAlt	Double	Target cruise altitude in feet
logEntries	List(Of TrajectoryLogEntry)	Diagnostic log accumulator (ByRef)
discAfter	Boolean()	Discontinuity-after flags per leg index

Outgoing	Description
List(Of ProfilePoint)	Ordered climb profile points from departure to T/C
ovfRolloutInfo (ByRef tuple)	Fly-over rollout state for cruise continuation

Purpose: Computes the climb profile from departure to top-of-climb (T/C) using forward 5 NM step iteration.

How it works:

Starts at ADEP altitude, initial fuel = FOB, weight = ZFW + FOB
Each 5 NM step: interpolates lat/lon via UpdatePositionAlongRoute, looks up wind, computes IAS (250 kt cap below FL100), TAS, GS, Mach
Queries PerfDataStore for fuel flow and vertical speed at current altitude/weight/phase
Applies energy modulation when IAS changes ≥ 10 kt between steps
At waypoint boundaries: suppresses Internal point, emits WaypointFix + CurvePoints via arc generators
For overfly waypoints: calls GenerateFlyOverArc; for fly-by: calls GenerateFlyByArc; for RF legs: calls GenerateRfArc
After OVFLY arc: projects distFromDep back onto straight-line route to prevent distance inflation
Terminates when cruise altitude reached or route exhausted

Called by: StartComputation

Calls: ComputeLegDistances, ComputeCumulativeLegDistances, UpdatePositionAlongRoute, EstimateOat, LookupWindByAltitude, GenerateFlyByArc, GenerateFlyOverArc, GenerateRfArc, SpeedCalculations.CalcTasFromIas, SpeedCalculations.CalcGsFromTas, SpeedCalculations.CalcMachFromIas

Function ComputeCruiseProfile

Entry Parameters	Type	Description
msg	ComputeTrajectory	Full trajectory message
legs	IReadOnlyList(Of FlightPlanLeg)	Filtered navigation legs
tcDistNm	Double	Top-of-climb distance from departure
tdDistNm	Double	Top-of-descent distance from departure
totalRouteDistNm	Double	Total route distance
startFuelRemaining	Double	Fuel at end of climb (kg)
startTime	TimeSpan	Elapsed time at end of climb
logEntries	List(Of TrajectoryLogEntry)	Diagnostic log accumulator
ovfRolloutInfo	Tuple	Fly-over rollout override from climb
discAfter	Boolean()	Discontinuity-after flags

Outgoing	Description
List(Of ProfilePoint)	Ordered cruise profile points from T/C to T/D

Purpose: Fills the cruise segment between T/C and T/D at constant altitude.

How it works:

Iterates forward from tcDistNm to tdDistNm in 5 NM steps
At each step: interpolates position via UpdatePositionAlongRoute, computes performance at cruise altitude
Applies fly-over rollout override if active (forwarded from climb)
At waypoint boundaries within cruise range: generates WaypointFix + CurvePoints
Fly-by arcs in cruise pass boundaryDistNm:=tdDistNm to enable Phase 29 phase-boundary arc split at T/D
After OVFLY arc: projects distFromDep back onto straight-line route (same fix as climb)

Called by: StartComputation

Calls: ComputeLegDistances, ComputeCumulativeLegDistances, UpdatePositionAlongRoute, EstimateOat, GenerateFlyByArc, GenerateFlyOverArc, GenerateRfArc, SpeedCalculations.*

Function ComputeDescentProfile

Entry Parameters	Type	Description
msg	ComputeTrajectory	Full trajectory message
legs	IReadOnlyList(Of FlightPlanLeg)	Filtered navigation legs
totalRouteDistNm	Double	Total route distance
logEntries	List(Of TrajectoryLogEntry)	Diagnostic log accumulator
discAfter	Boolean()	Discontinuity-after flags

Outgoing	Description
List(Of ProfilePoint)	Ordered descent profile points from T/D to destination (reversed at end)

Purpose: Computes the descent profile from destination backward to top-of-descent (T/D).

How it works:

Iterates backward from destination in 5 NM steps
Altitude increases (backward = climbing toward cruise) with deceleration zone near destination
Below FL100: 250 kt IAS cap; deceleration zone applies F-speed, S-speed, Green Dot transitions
At waypoint boundaries: generates arcs with descendingDistance:=False (backward iteration builds points in reverse)
After all steps: reverses the point list so points go from T/D toward destination
Strips any CurvePoint or WaypointFix that landed in the cruise zone (cruise builds its own arcs)

Called by: StartComputation

Calls: ComputeLegDistances, InterpolatePositionBackward, EstimateOat, LookupWindByAltitude, GenerateFlyByArc, GenerateFlyOverArc, GenerateRfArc, SpeedCalculations.*

Function GenerateFlyByArc

Entry Parameters	Type	Description
fixLat, fixLon	Double	Waypoint fix coordinates
inboundTrack	Double	Inbound track in degrees (0-360)
outboundTrack	Double	Outbound track in degrees (0-360)
tasKts	Double	True airspeed in knots (for turn radius computation)
lastPoint	ProfilePoint	Previous trajectory point (for altitude, speed, distance state)
descendingDistance	Boolean	Optional. If True, distances decrease (descent backward iteration)
waypointIdent	String	Optional. Ident string for CurvePoints (e.g., "KRH")
boundaryDistNm	Double	Optional. Phase boundary distance for T/C/T/D arc split (Double.MaxValue = no split)
newPhase	FlightPhase	Optional. Phase after boundary crossing (default Cruise)
newPhaseIasKts	Integer	Optional. IAS for new phase after boundary crossing
weightKg	Double	Optional. Aircraft weight for performance lookup at boundary
oatC	Double	Optional. OAT for TAS computation at boundary

Outgoing	Description
List(Of ProfilePoint)	CurvePoints along the fly-by turn arc at 5° intervals

Purpose: Generates CurvePoints for a standard fly-by turn at a waypoint transition.

How it works:

Computes bank angle from TAS via CalcMaxBankAngle
Computes turn radius from TAS and bank via CalcTurnRadius
Computes turn angle and direction via CalcTurnData
Skips turns < 1° or > 179° (no-turn / U-turn)
5 NM COT cap: If anticipation distance (radius * tan(turnAngle/2)) > 5 NM:
- Caps COT at 5 NM before fix
- Turns through the full turn angle with same radius (aircraft exits on outbound heading but offset)
- After arc: turns onto intercept heading (outbound +/- 30°), finds capture point via RadialRadialIntersection
- Flies straight to capture point, then capture fly-by turn to align with outbound track
- Running altitude (V/S) applied through all segments
Normal case (anticipation ≤ 5 NM): computes COT/EOT via CalcCot/CalcEot
Emits CurvePoints at 5° arc intervals from COT bearing around turn center
Running altitude: applies V/S per step (splitVs * stepTime * 60)
Phase-boundary arc split (Phase 29): if arc crosses T/C or T/D boundary, interpolates exact split point, re-parameterises remaining arc with new-phase performance

Called by: ComputeClimbProfile, ComputeCruiseProfile, ComputeDescentProfile, GenerateFlyOverArc (capture fly-by)

Calls: GeoCalculations.CalcMaxBankAngle, CalcTurnRadius, CalcTurnData, CalcCot, CalcEot, PointAtDistanceBearing, Bearing, NormalizeDegrees, RadialRadialIntersection, EstimateOat, PerfDataStore.GetPerformanceCached, SpeedCalculations.CalcTasFromIas, SpeedCalculations.CalcMachFromIas

Function GenerateFlyOverArc

Entry Parameters	Type	Description
fixLat, fixLon	Double	Overfly waypoint fix coordinates
inboundTrack	Double	Inbound track in degrees
outboundTrack	Double	Outbound track in degrees
tasKts	Double	True airspeed in knots
lastPoint	ProfilePoint	Previous trajectory point
descendingDistance	Boolean	Optional. Distance direction flag
waypointIdent	String	Optional. Ident for arc CurvePoints
nextWptLat, nextWptLon	Double	Optional. Next waypoint coordinates for direct mode (CA/VA/FA legs). NaN = use intercept mode

Outgoing	Description
List(Of ProfilePoint)	CurvePoints for the fly-over reintercept geometry

Purpose: Generates the fly-over turn geometry where the aircraft overflies the fix and then reintercepts the outbound track.

How it works:

Two modes:

Direct mode (CA/VA/FA legs — nextWptLat/nextWptLon provided):

Arc sweeps from inbound track until the tangent heading matches the outbound leg bearing
No intercept segment; arc connects directly to next leg

Full intercept mode (fixed-position waypoints):

Turn center placed perpendicular from fix along inbound track
Arc sweeps from inbound through interceptHeading = outboundTrack +/- 30°
Straight segment from arc exit on intercept heading to capture point on outbound track
Capture fly-by turn at capture point from intercept heading to outbound track via GenerateFlyByArc
Running altitude (V/S) applied continuously through arc, straight segment, and capture

Straight segment and capture fly-by CurvePoints: Use ident "INTCPT" (displayed as **INTCPT in Layer 2).

Called by: ComputeClimbProfile, ComputeCruiseProfile, ComputeDescentProfile

Calls: GeoCalculations.CalcMaxBankAngle, CalcTurnRadius, CalcTurnData, PointAtDistanceBearing, Bearing, NormalizeDegrees, RadialRadialIntersection, GenerateFlyByArc (capture turn)

Function GenerateRfArc (Shared)

Entry Parameters	Type	Description
startLat, startLon	Double	Arc start coordinates
endLat, endLon	Double	Arc end coordinates (fix)
centerLat, centerLon	Double	Arc center coordinates
radiusNm	Double	Arc radius in NM
turnDirection	String	"L" or "R"
lastPoint	ProfilePoint	Previous trajectory point for state
descendingDistance	Boolean	Optional. Distance direction flag

Outgoing	Description
List(Of ProfilePoint)	CurvePoints along the RF arc at 5° intervals

Purpose: Generates CurvePoints for an RF (Radius-to-Fix) arc leg with a fixed center and radius (ARINC 424 RF path terminator).

How it works:

Computes bearings from center to start and end points
Computes sweep angle based on turn direction
Emits CurvePoints at 5° intervals, capped at 72 steps (360°)
All points inherit altitude, speed, and performance from lastPoint

Called by: ComputeClimbProfile, ComputeCruiseProfile, ComputeDescentProfile

Calls: GeoCalculations.Bearing, NormalizeDegrees, PointAtDistanceBearing

Function EstimateOat (Shared)

Entry Parameters	Type	Description
altFt	Double	Altitude in feet

Outgoing	Description
Double	Outside air temperature in °C (ISA model)

Purpose: ISA standard atmosphere temperature estimation.

How it works: 15.0 - 0.00198 * altFt, capped at -56.5 °C above the tropopause (36,089 ft).

Called by: ComputeClimbProfile, ComputeCruiseProfile, ComputeDescentProfile, GenerateFlyByArc (phase-boundary split)

Function LookupWindByAltitude (Shared)

Entry Parameters	Type	Description
windTable	IReadOnlyList(Of WindEntry)	Altitude-indexed wind entries
altFt	Double	Current altitude in feet

Outgoing	Description
WindEntry	Closest wind entry by altitude (or zero-wind if table empty)

Purpose: Returns the wind entry closest to the current altitude from an altitude-indexed wind table.

Called by: ComputeClimbProfile, ComputeDescentProfile

Function ComputeTotalRouteDistance (Shared)

Entry Parameters	Type	Description
legs	IReadOnlyList(Of FlightPlanLeg)	All navigation legs

Outgoing	Description
Double	Total great-circle route distance in NM

Purpose: Sums the great-circle distance between all consecutive waypoints.

Called by: StartComputation

Calls: GeoCalculations.DistanceNm

Function ComputeLegDistances (Shared)

Entry Parameters	Type	Description
legs	IReadOnlyList(Of FlightPlanLeg)	Navigation legs

Outgoing	Description
Double()	Array of distances per leg segment (NM)

Purpose: Computes the great-circle distance for each leg (between consecutive waypoints).

Called by: ComputeClimbProfile, ComputeCruiseProfile, ComputeDescentProfile

Calls: GeoCalculations.DistanceNm

Function ComputeCumulativeLegDistances (Shared)

Entry Parameters	Type	Description
legDists	Double()	Per-leg distances from `ComputeLegDistances`

Outgoing	Description
Double()	Cumulative distance from departure for each leg start

Purpose: Running sum of leg distances. cumul(0) = 0, cumul(i) = cumul(i-1) + legDist(i-1).

Called by: ComputeClimbProfile, ComputeCruiseProfile

Sub UpdatePositionAlongRoute (Shared)

Entry Parameters	Type	Description
distFromDep	Double	Distance from departure in NM
legs	IReadOnlyList(Of FlightPlanLeg)	Navigation legs
legDists	Double()	Per-leg distances
cumulDists	Double()	Cumulative distances
currentLat	Double (ByRef)	Output: interpolated latitude
currentLon	Double (ByRef)	Output: interpolated longitude
currentLegIndex	Integer (ByRef)	Output: index of the leg containing this distance

Purpose: Given a distance from departure, finds the containing leg and interpolates lat/lon along the straight-line segment.

How it works: Walks the cumulative distance array to find which leg segment the distance falls in, then linearly interpolates between the leg's start and end waypoint coordinates.

Called by: ComputeClimbProfile, ComputeCruiseProfile

Sub InterpolatePositionBackward (Shared)

Entry Parameters	Type	Description
distFromDes	Double	Distance from destination in NM
legs	IReadOnlyList(Of FlightPlanLeg)	Navigation legs
legDists	Double()	Per-leg distances
lat	Double (ByRef)	Output: interpolated latitude
lon	Double (ByRef)	Output: interpolated longitude

Purpose: Interpolates position backward from the destination by a given distance. Used by the descent profile (backward iteration).

How it works: Walks backward through legs, accumulating distance until the target distance is reached, then linearly interpolates within the found segment.

Called by: ComputeDescentProfile

Function FindCrossoverAltitude (Shared)

Entry Parameters	Type	Description
climbPoints	List(Of ProfilePoint)	Climb profile
descentPoints	List(Of ProfilePoint)	Descent profile (in forward order)
totalRouteDistNm	Double	Total route distance

Outgoing	Description
Double	Crossover altitude in feet where climb meets descent

Purpose: Finds the altitude at which the climb profile meets the descent profile. Used for short-route altitude capping when T/C ≥ T/D.

How it works: Walks the climb profile forward. At each point, interpolates the descent altitude at the same distance. When the climb altitude exceeds the descent altitude, the crossover is found via interpolation.

Called by: StartComputation (only when T/C ≥ T/D)

Calls: InterpolateAltitudeAtDistance

Function InterpolateAltitudeAtDistance (Shared)

Entry Parameters	Type	Description
points	List(Of ProfilePoint)	Profile point list
dist	Double	Distance to interpolate at

Outgoing	Description
Double	Interpolated altitude at the given distance

Purpose: Linear interpolation of altitude at a given distance using adjacent profile points.

Called by: FindCrossoverAltitude

LegGeometry.vb

LegGeometry Module

ARINC 424 per-leg-type geometry computation. Routes each leg type to the appropriate handler. Ported from VB6 modKernel.bas.

Function ComputeLegGeometry

Entry Parameters	Type	Description
currentLat, currentLon	Double	Current aircraft position
currentAlt	Double	Current altitude in feet
currentTrack	Double	Current track in degrees
leg	FlightPlanLeg	The leg to compute geometry for
nextLeg	FlightPlanLeg	The following leg (needed for VI/CI intercept computation)

Outgoing	Description
LegGeometryResult	EndLat, EndLon, TrackDegrees, DistanceNm, TargetAltitudeFt

Purpose: Main dispatch function routing ARINC 424 leg types to their specific geometry handlers.

How it works: Select Case leg.ArinCCommand dispatches to:

TF/CF → ComputeTfCf
DF/DIRECT → ComputeDfDirect
FC → ComputeFc
CA → ComputeCa
VA → ComputeVa
FD → ComputeFd
CD → ComputeCd
CR → ComputeCr
VD → ComputeVd
VM → ComputeVm
FM → ComputeFm
FA → ComputeFa
VI → ComputeVi
CI → ComputeCi
RF → ComputeRf
Else → TF fallback

Called by: TrajectoryActor.StartComputation (position resolution for computed-endpoint legs)

Function ComputeTfCf

Purpose: Track to Fix / Course to Fix. Endpoint = stored fix lat/lon. Track = initial bearing from current position.