MASINavigation - MOARdV/AvionicsSystems GitHub Wiki

MASINavigation.cs

Contents

MASINavigation encapsulates navigation functionality, including emulating radio navigation and GNSS navigation (by using stock waypoints). It provides methods to determine the distance from the vessel to a particular lat/lon location on the planet, and the distance between two arbitrary points on a planet.

All methods use the current vessel's parent body as the body for calculations.

Equations adapted from http://www.movable-type.co.uk/scripts/latlong.html.

General Navigation Category

The General Navigation section contains general-purpose navigational formulae that can be used for navigation near a planet's surface.

nav.Bearing(double latitude1, double longitude1, double latitude2, double longitude2)

  • latitude1: Latitude of position 1 in degrees. Negative values indicate south, positive is north.
  • longitude1: Longitude of position 1 in degrees. Negative values indicate west, positive is east.
  • latitude2: Latitude of position 2 in degrees. Negative values indicate south, positive is north.
  • longitude2: Longitude of position 2 in degrees. Negative values indicate west, positive is east.

Returns: Bearing (heading) in degrees, in the range [0, 360).

Returns the great-circle route bearing from (lat1, lon1) to (lat2, lon2).

nav.BearingFromVessel(double latitude, double longitude)

  • latitude: Latitude of the destination point in degrees. Negative values indicate south, positive is north.
  • longitude: Longitude of destination point in degrees. Negative values indicate west, positive is east.

Returns: Hearing in degrees from the vessel to the destination, in the range [0, 360).

Returns the great-circle bearing from the vessel to the specified lat/lon coordinates.

nav.CrossTrackDistance(double latitude1, double longitude1, double bearing1, double latitude2, double longitude2)

  • latitude1: Latitude of a point on the route to test.
  • longitude1: Longitude of a point on the route to test.
  • bearing1: Bearing from the lat/lon for the route to test.
  • latitude2: Latitude of the location of interest.
  • longitude2: Longitude of the location of interest.

Returns: Distance in meters from the current route to the location.

Returns the cross-track distance, in meters, of the specified location relative to the path specified by latitude1, longitude, and bearing1.

nav.CrossTrackDistanceFromVessel(double latitude, double longitude)

  • latitude: Latitude of the location of interest.
  • longitude: Longitude of the location of interest.

Returns: Distance in meters from the current route to the location.

Returns the cross-track distance, in meters, of the specified location relative to the vessel's current heading.

nav.DestinationLatitude(double latitude, double longitude, double range, double bearing)

  • latitude: Latitude of the point of origin. Negative values indicate south, positive is north.
  • longitude: Longitude of the point of origin. Negative values indicate west, positive is east.
  • range: Distance to travel along the bearing, in meters.
  • bearing: Bearing in degrees to travel.

Returns: Latitude in degrees.

Returns the latitude found at the given range along the given bearing.

nav.DestinationLatitudeFromVessel(double range, double bearing)

  • range: Distance to travel along the bearing, in meters.
  • bearing: Bearing in degrees to travel.

Returns: Latitude in degrees.

Returns the latitude found at the given range along the given bearing from the current vessel.

nav.DestinationLongitude(double latitude, double longitude, double range, double bearing)

  • latitude: Latitude of the point of origin. Negative values indicate south, positive is north.
  • longitude: Longitude of the point of origin. Negative values indicate west, positive is east.
  • range: Distance to travel along the bearing, in meters.
  • bearing: Bearing in degrees to travel.

Returns: Longitude in degrees.

Returns the longitude found at the given range along the given bearing from the point of origin.

nav.DestinationLongitudeFromVessel(double range, double bearing)

  • range: Distance to travel along the bearing, in meters.
  • bearing: Bearing in degrees to travel.

Returns: Longitude in degrees.

Returns the longitude found at the given range along the given bearing from the current vessel.

nav.GroundDistance(double latitude1, double longitude1, double latitude2, double longitude2)

  • latitude1: Latitude of position 1 in degrees. Negative values indicate south, positive is north.
  • longitude1: Longitude of position 1 in degrees. Negative values indicate west, positive is east.
  • latitude2: Latitude of position 2 in degrees. Negative values indicate south, positive is north.
  • longitude2: Longitude of position 2 in degrees. Negative values indicate west, positive is east.

Returns: Distance in meters between the two points, following the surface of the planet.

Return the ground distance between two coordinates on a planet.

Assumes the planet is the one the vessel is currently orbiting / flying over. Uses the sea-level altitude.

nav.GroundDistanceFromVessel(double latitude, double longitude)

  • latitude: Latitude of the destination point in degrees. Negative values indicate south, positive is north.
  • longitude: Longitude of destination point in degrees. Negative values indicate west, positive is east.

Returns: Distance in meters between the two points, following the surface of the planet.

Return the ground distance between the vessel and a location on the surface of the planet.

Uses the sea-level altitude.

nav.IntersectionOfTwoPathsLatitude(double latitude1, double longitude1, double bearing1, double latitude2, double longitude2, double bearing2)

  • latitude1: Latitude of the start of path 1.
  • longitude1: Longitude of the start of path 1.
  • bearing1: Initial bearing of path 1.
  • latitude2: Latitude of the start of path 2.
  • longitude2: Longitude of the start of path 2.
  • bearing2: Initial bearing of path 2.

Returns: The latitude where the two paths intersect.

Return the latitude where two great-circle paths intersect.

nav.IntersectionOfTwoPathsLongitude(double latitude1, double longitude1, double bearing1, double latitude2, double longitude2, double bearing2)

  • latitude1: Latitude of the start of path 1.
  • longitude1: Longitude of the start of path 1.
  • bearing1: Initial bearing of path 1.
  • latitude2: Latitude of the start of path 2.
  • longitude2: Longitude of the start of path 2.
  • bearing2: Initial bearing of path 2.

Returns: The latitude where the two paths intersect.

Return the longitude where two great-circle paths intersect.

nav.LineOfSight(double altitude)

  • altitude: Altitude above sea level, in meters.

Returns: Distance to the horizon, in meters.

Returns the distance to the horizon based on a given altitude ASL.

The horizon is assumed to be at sea level. Due to the small sizes of most stock KSP worlds, and the relatively large mountains, this number will not be reliable for estimating whether a given land position is within line-of-sight.

nav.SlantDistance(double latitude1, double longitude1, double altitude1, double latitude2, double longitude2, double altitude2)

  • latitude1: Latitude of the origin.
  • longitude1: Longitude of the origin.
  • altitude1: Altitude of the origin.
  • latitude2: Latitude of the destination.
  • longitude2: Longitude of the destination.
  • altitude2: Altitude of the destination.

Returns the slant distance (direct distance) between two locations on the current world.

nav.SlantDistanceFromVessel(double latitude, double longitude, double altitude)

  • latitude: Latitude of the destination.
  • longitude: Longitude of the destination.
  • altitude: Altitude of the destination.

Returns: Distance in meters from the vessel to the selected location.

Returns the slant distance (direct distance) between the vessel and a given location and altitude on the current planet.

nav.TargetBearing(bool relative)

  • relative: If true, bearing is relative to the vessel's current bearing; if false, it is absolute hearing.

Returns: Returns the bearing to the target in the range [0, 360), or 0.

Returns the bearing to the current active target. If no target is active, returns 0.

nav.TargetGroundDistance()

Returns: Distance in meters to the target, or 0.

Returns the ground distance in meters to the target, or 0 if there is no target.

nav.TerrainHeight(double range, double bearing)

  • range: Distance to travel along the bearing, in meters.
  • bearing: Bearing in degrees to travel.

Returns: Terrain height relative to the datum (sea-level) in meters.

Returns the terrain height (distance above or below the datum / sea-level) at the specified distance and bearing from the current vessel. This method is an optimized way of doing the following, without recomputing most of the same values twice in the nav.Destination methods, and paying the cost of looking up the current body in TerrainHeight.

local lat = nav.DestinationLatitudeFromVessel(range, bearing)
local lon = nav.DestinationLongitudeFromVessel(range, bearing)

return fc.BodyTerrainHeight(-1, lat, lon)

Launch Site Category

The Launch Site category contains information about the vessel's launch site.

nav.LaunchSiteLatitude()

The latitude of the vessel's launch site.

nav.LaunchSiteLongitude()

The longitude of the vessel's launch site.

nav.LaunchSiteName()

The name of the vessel's launch site.

Radio Navigation Category

The Radio Navigation section provides methods for emulating navigational radio on board aircraft (or ships, or whatever).

Most methods are centered around a selected radio (the radioId parameter, and they assume all computations in relation to the current active vessel. Because these methods emulate navigational radios, they account for limitations caused by the curvature of the planet as well as limited radio broadcasting distances.

Because of this, methods may return values indicating "no signal" even if the radio is tuned to a valid beacon.

The radioId parameter should be an integer (non-integer numbers are converted to integers). MAS does not place any restrictions on how many radios are used on a vessel, not does it place restrictions on what radio ids may be used. If the IVA creator wishes to use ids 2, 17, and 21, then MAS allows it.

Frequency is assumed to be in MHz, and MAS assumes radios have about a 10kHz minimum frequency separation (real-world VOR uses 50kHz), so setting a radio to 105.544 will select any navaids on a frequency between 105.499 and 105.599.

nav.GetDMESlantDistance(double radioId)

  • radioId: The id of the radio, any integer value.

Returns: Distance to DME in meters, or -1 if no DME equipment is in range on the given radio frequency.

Returns the slant distance in meters to a DME beacon selected on the given radio. If there is no DME equipment in range, returns -1.

nav.GetILSLocalizerError(double radioId)

  • radioId: The id of the radio, any integer value.

Returns: Localizer error, or 0.

Returns the horizontal error from the ILS localizer beam, up to the limit set by the ILS beacon's localizerSectorILS parameter. If there is no ILS localizer, or the vessel is outside the localizer's sector, returns 0.

A negative value indicates that the vessel is to the left of the localizer beam, while a positive value indicates that the vessel is to the right of the beam.

nav.GetILSLocalizerValid(double radioId)

  • radioId: The id of the radio, any integer value.

Returns: 1 if a valid ILS localizer is detected; 0 otherwise.

Returns 1 if the localizer signal is valid, 0 if it is not (or the beacon is not an ILS).

nav.GetILSGlideSlopeDefault(double radioId)

  • radioId: The id of the radio, any integer value.

Returns: Default glide slope, or 0.

Return the default glide slope for the given ILS beacon. Returns 0 if ILS out of glide slope range, or radio is not tuned to an ILS beacon.

nav.GetILSGlideSlopeError(double radioId, double glideSlope)

  • radioId: The id of the radio, any integer value.
  • glideSlope: The desired glide slope.

Returns: The deflection from the desired glide slope, or 0.

Returns the vertical deviation from the ILS glide path beam, up to the limit set by the ILS beacon's glidePathSectorILS. If there is no ILS beacon, or the vessel is outside the glide path's sector, returns 0.

nav.GetILSGlideSlopeValid(double radioId, double glideSlope)

  • radioId: The id of the radio, any integer value.
  • glideSlope: The desired glide slope.

Returns: 1 if the vessel is within the glide slope limits of a valid ILS glide path, 0 otherwise

Returns whether the glide slope error is valid.

nav.GetNavAidBearing(double radioId, bool relativeBearing)

  • radioId: The id of the radio, any integer value.
  • relativeBearing: If true, returns the bearing to the beacon relative to the vessel's front. If false, returns the absolute bearing to the beacon (relative to north).

Returns: Absolute or relative bearing to the navaid beacon, or 0.

Returns the bearing to the navaid selected by radioId. If no radio is in range, returns 0.

nav.GetNavAidCrossTrackDistance(double radioId)

  • radioId: The id of the radio, any integer value.

Returns: Cross-track distance in meters.

Returns the cross-track distance in meters, to the navaid specified by radioId. If no radio is in range, returns 0.

nav.GetNavAidDME(double radioId)

  • radioId: The id of the radio, any integer value.

Returns: As described in the summary.

Queries the radio beacon selected by radioId to determine if it includes DME equipment. Returns one of three values:

  • -1: No navaid beacons are in range on the current frequency.
  • 0: A navaid beacon is in range, but it does not support DME.
  • 1: A navaid beacon is in range, and it supports DME.

nav.GetNavAidIdentifier(double radioId)

  • radioId: The id of the radio, any integer value.

Returns: Beacon identifier, or an empty string if no beacon is in range on the current frequency.

Get the identifier for the beacon on the selected radio. The identifier is typically a three letter code, such as 'CST'. If no beacon is selected, or no beacon is in range, returns an empty string.

nav.GetNavAidLatitude(double radioId)

  • radioId: The id of the radio, any integer value.

Returns: Latitude, or 0

Returns the latitude of the active beacon. If no beacon is selected, or no beacon is in range, returns 0.

nav.GetNavAidLongitude(double radioId)

  • radioId: The id of the radio, any integer value.

Returns: Longitude, or 0

Returns the longitude of the active beacon. If no beacon is selected, or no beacon is in range, returns 0.

nav.GetNavAidName(double radioId)

  • radioId: The id of the radio, any integer value.

Returns: Beacon name, or an empty string if no beacon is in range on the current frequency.

Get the name for the beacon on the selected radio. If no beacon is selected, or no beacon is in range, returns an empty string.

nav.GetNavAidType(double radioId)

  • radioId: The id of the radio, any integer value.

Returns: As described in the summary.

Returns the type of radio beacon the radio currently is detecting. Returns one of three values:

  • 0: No navaid beacons are in range on the current frequency.
  • 1: Beacon is NDB.
  • 2: Beacon is VOR.
  • 3: Beacon is ILS.

nav.GetNDBBearing(double radioId)

  • radioId: The id of the radio, any integer value.

Returns: Vessel-relative bearing to the NDB beacon, in the range [0, 360). If the radio is not tuned to an NDB, or the NDB is out of range, returns -1.

Returns the NDB bearing for the given radio. This is bearing relative to the vessel's heading, not absolute heading to the NDB beacon.

nav.GetRadioFrequency(double radioId)

  • radioId: The id of the radio, any integer value.

Returns: 0 if the radio does not have a frequency set, otherwise, the frequency.

Returns the radio frequency setting for the specified radio.

nav.GetVORApproach(double radioId, double bearing)

  • radioId: The id of the radio, any integer value.
  • bearing: VOR bearing

Returns: -1, 0, or 1 as described in the summary.

Returns a number representing TO/FROM on the given VOR / bearing.

  • -1: FROM
  • 0: No VOR info
  • 1: TO

nav.GetVORDeviation(double radioId, double bearing)

  • radioId: The id of the radio, any integer value.
  • bearing: VOR bearing

Returns: Deviation in degrees, 0 if no in-range VOR.

Returns the deviation from the desired bearing line on the VOR in degrees.

nav.PlayNavAidIdentifier(double radioId, double volume, bool stopCurrent)

  • radioId: The id of the radio, any integer value.
  • volume: The volume to use for playback, between 0 and 1 (inclusive).
  • stopCurrent: If 'true', stops any current audio clip being played.

Returns: 1 if a Morse sequence is being played, 0 otherwise.

Plays the Morse code identifier for the selected radio. If radioId is not set to a valid frequency, or no radios are in range, no audio is played.

nav.SetRadioFrequency(double radioId, double frequency)

  • radioId: The id of the radio, any integer value.
  • frequency: The frequency of the radio, assumed in MHz.

Returns: 1 if the radio was switched off, or if any radios have a frequency within 10kHz of the requested frequency (regardless of range).

Sets the specified navigational radio to the frequency.

If frequency is less than or equal to 0.0, the radio is switched off.

Waypoint Navigation Category

The Waypoint Navigation section provides methods used to interact with stock and custom waypoints.

These methods differ from the Radio Nagivation section in that they do not include any gameplay simulation of radio navigation - these methods are more suited for Global Navigation Satellite Systems.

Most waypoint queries take a waypointIndex parameter. This parameter must be in the range of [0, nav.GetWaypointCount()-1] to select a custom waypoint, or -1 to select the current active waypoint.

nav.GetWaypointIndex()

Returns: Index of the active waypoint, or -1 if no waypoint is active or the waypoint is not a custom waypoint.

Get the custom waypoint index of the current waypoint. If there is no active waypoint, or the current waypoint is not in the custom waypoint database, return -1.

nav.SetWaypoint(double waypointIndex)

  • waypointIndex: The waypoint to select.

Returns: 1 if a waypoint was selected, 0 otherwise.

Set the stock waypoint system to the custom waypoint selected by waypointIndex.

A negative value, or a value equal to or greater than nav.GetWaypointCount() will clear the current waypoint.

nav.SetWaypointToGroundStation(double dsnIndex)

  • dsnIndex: A value between 0 and fc.GroundStationCount() - 1.

Returns: 1 if the waypoint was updated, 0 otherwise.

Select the ground station identified by dsnIndex as the current navigation waypoint.

If dsnIndex is not a valid ground station, the waypoint system is not updated.

nav.SetWaypointToLandingSite(double siteIndex)

  • siteIndex: A value between 0 and mechjeb.GetLandingSiteCount() - 1.

Returns: 1 if the waypoint was updated, 0 otherwise.

Select the MechJeb landing site identified by siteIndex as the current navigation waypoint.

If siteIndex is not a valid landing site, the waypoint system is not updated.

nav.SetWaypointToLaunchSite()

Returns: 1 if the launch site was selected, 0 if it could not be selected.

Sets the waypoint manager to target the vessel's launch site.

Requires the vessel to be in the sphere of influence of the launch site's world.

nav.WaypointActive()

Returns: 1 if a waypoint is active, 0 otherwise.

Returns 1 if there is a waypoint active. If the waypoint is a custom waypoint, its index can be queried using fc.GetWaypointIndex().

nav.WaypointAltitude(double waypointIndex)

  • waypointIndex: The waypoint to name, or -1 to select the current active waypoint.

Returns: Altitude of the selected waypoint, or 0.

Get the altitude of the waypoint selected by waypointIndex, or the current active waypoint if waypointIndex is -1.

nav.WaypointBearing(double waypointIndex)

  • waypointIndex: The waypoint index, or -1 to select the current active waypoint.

Returns: The bearing to the waypoint, in the range [0, 360), or -1 if there is no selected waypoint.

Get the absolute bearing to the selected waypoint (bearing relative to North).

nav.WaypointCount()

Returns: The number of waypoints.

Returns the number of waypoints in the custom waypoints table.

nav.WaypointCrossTrackDistance(double waypointIndex)

  • waypointIndex: The waypoint index, or -1 to select the current active waypoint.

Returns: Returns the cross-track distance in meters, or 0 if the selected waypoint is invalid.

Get the cross-track distance to the selected waypoint in meters.

nav.WaypointDistance(double waypointIndex)

  • waypointIndex: The waypoint index, or -1 to select the current active waypoint.

Returns: The distance to the waypoint in meters, or -1 if there is no selected waypoint.

Get the slant distance to the selected waypoint in meters.

nav.WaypointGroundDistance(double waypointIndex)

  • waypointIndex: The waypoint index, or -1 to select the current active waypoint.

Returns: The distance to the waypoint in meters, or -1 if there is no selected waypoint.

Returns the ground distance from the vessel to the selected waypoint in meters, assuming both are at sea level.

nav.WaypointLatitude(double waypointIndex)

  • waypointIndex: The waypoint index, or -1 to select the current active waypoint.

Returns: Latitude of the selected waypoint, or 0.

Get the latitude of the waypoint selected by waypointIndex, or the current active waypoint if waypointIndex is -1.

nav.WaypointLongitude(double waypointIndex)

  • waypointIndex: The waypoint index, or -1 to select the current active waypoint.

Returns: Longitude of the selected waypoint, or 0.

Get the longitude of the waypoint selected by waypointIndex, or the current active waypoint if waypointIndex is -1.

nav.WaypointName(double waypointIndex)

  • waypointIndex: The waypoint to name, or -1 to select the current active waypoint.

Returns: The name of the waypoint, or an empty string, or "Unknown".

Returns the name of waypoint identified by waypointIndex.

If waypointIndex is -1, returns the name of the active waypoint. If waypointIndex is between 0 and nav.GetWaypointCount(), returns that waypoint's name. Otherwise, returns an empty string.

If the waypoint was selected by another mod, and it is not in the stock waypoint database, this function may return "Unknown".

This documentation was automatically generated from source code at 12:52 UTC on 14/Jul/2020.