Nasal library/geo
Work in progress This article or section will be worked on in the upcoming hours or days. See history for the latest developments. |
The FlightGear forum has a subforum related to: Nasal Scripting |
Nasal scripting |
---|
Nasal internals |
---|
Memory Management (GC) |
This page contains documentation for the geo
namespace in Nasal. This namespace provides various geography/position-related functions, as well the main class. Everything in the geo
namespace is sourced from fgdata/Nasal/geo.nas
Classes
Coord
The main class, used widely for storing and managing positional data. Coordinates may be stored in either Earth-centered, Earth-fixed coordinates (x, y and z) or geodetic coordinates (latitude, longitude, and altitude). In addition, it will convert coordinates as necessary. However, note that for the conversion to work, set_latlon() and set_xyz() must be used.
new()
geo.Coord.new([coord]);
Constructor function. Returns a geo.Coord
instance.
- coord
- An optional
geo.Coord
instance. If given, the returned instance will contain the values from this argument.
Examples
var coord = geo.Coord.new();
var ac_pos = geo.aircraft_position();
var coord = geo.Coord.new(ac_pos);
coord.dump();
set()
geo.Coord.set(coord);
Sets the coordinates. Returns the geo.Coord
instance.
- coord
- Sets the coordinates from another
geo.Coord
instance.
Example
var ac_pos = geo.aircraft_position();
var coord = geo.Coord.new();
coord.set(ac_pos);
coord.dump();
set_lat()
geo.Coord.set_lat(lat);
Sets the latitude coordinate. Returns the geo.Coord
instance.
- lat
- The latitude coordinate, in degrees.
Example
var coord = geo.Coord.new();
coord.set_latlon(0, 0, 0);
coord.set_lat(45);
coord.dump();
set_lon()
geo.Coord.set_lon(lon);
Sets the longitude coordinate. Returns the geo.Coord
instance.
- lon
- The longitude coordinate, in degrees.
Example
var coord = geo.Coord.new();
coord.set_latlon(0, 0, 0);
coord.set_lon(90);
coord.dump();
set_alt()
geo.Coord.set_alt(alt);
Sets the altitude coordinate. Returns the geo.Coord
instance.
- alt
- The altitude coordinate. Note that this can be in either feet or metres, so make sure you convert correctly. Also note that in conversion, this coordinate will be assumed to be metres above equatorial radius of earth used is that defined by the WGS 84 (6,378,137 metres).
Example
var coord = geo.Coord.new();
coord.set_latlon(0, 0, 0);
coord.set_alt(1000);
coord.dump();
set_latlon()
geo.Coord.set_latlon(lat, lon[, alt]);
Sets the latitude and longitude coordinates, and optionally the altitude coordinate. Returns the geo.Coord
instance.
- lat
- The latitude coordinate, in degrees.
- lon
- The longitude coordinate, in degrees.
- alt
- The altitude coordinate. Note that this can be in either feet or metres, so make sure you convert correctly. Also note that in conversion, this coordinate will be assumed to be metres above equatorial radius of earth used is that defined by the WGS 84 (6,378,137 metres). Defaults to 0.
Examples
var coord = geo.Coord.new();
coord.set_latlon(45, 90);
coord.dump();
var coord = geo.Coord.new();
coord.set_latlon(45, 90, 1000);
coord.dump();
set_x()
geo.Coord.set_x(x);
Sets the x-axis coordinate coordinate. Returns the geo.Coord
instance.
- x
- The mandatory x-axis coordinate, in metres.
Example
var coord = geo.Coord.new();
coord.set_xyz(0, 0, 0);
coord.set_x(10);
coord.dump();
set_y()
geo.Coord.set_y(y);
Sets the y-axis coordinate coordinate. Returns the geo.Coord
instance.
- y
- The mandatory y-axis coordinate, in metres.
Example
var coord = geo.Coord.new();
coord.set_xyz(0,0,0);
coord.set_y(10);
coord.dump();
set_z()
geo.Coord.set_z(z);
Sets the y-axis coordinate coordinate. Returns the geo.Coord
instance.
- z
- The mandatory z-axis coordinate, in metres.
Example
var coord = geo.Coord.new();
coord.set_xyz(0, 0, 0);
coord.set_y(10);
coord.dump();
set_xyz()
geo.Coord.set_xyz(x, y, z);
Sets all three Cartesian coordinates. Returns the geo.Coord
instance. All arguments are mandatory.
- x
- The x-axis coordinate, in metres.
- y
- The y-axis coordinate, in metres.
- z
- The z-axis coordinate, in metres.
Example
var coord = geo.Coord.new();
coord.set_xyz(10, 10, 10);
coord.dump();
lat()
geo.Coord.lat();
Returns the latitude coordinate.
Example
var coord = geo.Coord.new();
coord.set_latlon(98, 173);
print(coord.lat()); # prints "98"
lon()
geo.Coord.lon();
Returns the longitude coordinate.
Example
var coord = geo.Coord.new();
coord.set_latlon(98, 173);
print(coord.lon()); # prints "173"
alt()
geo.Coord.alt();
Returns the altitude coordinate.
Example
var coord = geo.Coord.new();
coord.set_latlon(98, 173, 10);
print(coord.alt()); # prints "10"
latlon()
geo.Coord.latlon();
Returns a vector containing the latitude, longitude, and altitude, in that order.
Example
var coord = geo.Coord.new();
coord.set_latlon(98, 173, 10);
debug.dump(coord.latlon()); # prints "[98, 173, 10]"
x()
geo.Coord.x();
Returns the x-axis coordinate.
Example
var coord = geo.Coord.new();
coord.set_xyz(10, 10, 10);
print(coord.x()); # prints "10"
y()
geo.Coord.y();
Returns the y-axis coordinate.
Example
var coord = geo.Coord.new();
coord.set_xyz(10, 10, 10);
print(coord.y()); # prints "10"
z()
geo.Coord.z();
Returns the z-axis coordinate.
Example
var coord = geo.Coord.new();
coord.set_xyz(10, 10, 10);
print(coord.z()); # prints "10"
xyz()
geo.Coord.xyz();
Returns a vector containing the x, y, and z coordinates, in that order.
Example
var coord = geo.Coord.new();
coord.set_xyz(20, 10, 30);
debug.dump(coord.xyz()); # prints "[20, 10, 30]"
is_defined()
geo.Coord.is_defined();
Returns 1 (true) if all three coordinates (either x/y/z or /lat/lon/alt) are defined. Note that set_latlon() or set_xyz() must be used for this function to work correctly.
Examples
var coord = geo.Coord.new();
coord.set_xyz(10, 10, 10);
print(coord.is_defined()); # prints "1"
var coord = geo.Coord.new();
print(coord.is_defined()); # prints "0"
dump()
geo.Coord.dump();
Dumps all six coordinates into the console. It requires all three coordinates (either x/y/z or /lat/lon/alt) to be defined. Note that set_latlon() or set_xyz() must be used for this function to work correctly.
Examples
var coord = geo.Coord.new();
coord.set_xyz(10, 10, 10);
coord.dump(); # prints "x=10.000000 y=10.000000 z=10.000000 lat=89.981086 lon=44.999998 alt=-6356742.309706"
var coord = geo.Coord.new();
coord.set_latlon(90, 45, 10);
coord.dump(); # prints "x=0.055063 y=0.055063 z=6356762.314245 lat=90.000000 lon=45.000000 alt=10.000000"
course_to()
geo.Coord.course_to(coord);
Returns the initial bearing (see here) to another geo.Coord
instance. The bearing will be an absolute bearing (in the range 0–360).
- coord
- Mandatory
geo.Coord
instance to calculate bearing to.
Example
var c1 = geo.Coord.new();
c1.set_latlon(0, 0);
var c2 = geo.Coord.new();
c2.set_latlon(1, 1);
printf("%.5f", c1.course_to(c2)); # prints "44.99564"
distance_to()
geo.Coord.distance_to(coord);
Returns the great circle distance in metres to another geo.Coord
instance. Note that this function ignores altitude.
- coord
- Mandatory
geo.Coord
instance to calculate distance to.
Example
var c1 = geo.Coord.new();
c1.set_latlon(0, 0);
var c2 = geo.Coord.new();
c2.set_latlon(1, 1);
printf("%i", c1.distance_to(c2)); # prints "157425"
direct_distance_to()
geo.Coord.direct_distance_to(coord);
Returns the direct distance (cutting through the earth) in metres to another geo.Coord
instance.
- coord
- Mandatory
geo.Coord
instance to calculate distance to.
Example
var c1 = geo.Coord.new();
c1.set_latlon(0, 0);
var c2 = geo.Coord.new();
c2.set_latlon(45, 90);
printf("%i", c1.direct_distance_to(c2)); # prints "9012522"
apply_course_distance()
geo.Coord.apply_course_distance(course, dist);
Calculates a new coordinate from a given course and distancce, and then updates the coordinates to the new set. Returns the geo.Coord
instance.
- course
- Mandatory absolute bearing (0–360) to use in calculation.
- dist
- Mandatory distance in metres to use in calculation.
Examples
var coord = geo.Coord.new();
coord.set_latlon(0, 0);
coord.dump();
coord.apply_course_distance(245, 10000);
coord.dump(); # lat=-0.037964 lon=-0.081415
# WIP:
# get current aircraft position:
var centerPosition = geo.aircraft_position();
# set up a for-loop
# apply a bearing offset
# and distance 10 nm in front of the current position
# foreach position, add an AI model using put_model
PositionedSearch
Note This is currently only used by the MapStructure code to run more efficient searches (i.e. the delta-search stuff for map-canvas.xml) |
Functions
aircraft_position()
geo.aircraft_position();
Returns the main aircraft's current position in the form of a geo.Coord
object. Note that the altitude will be in metres.
Example
var ac_pos = geo.aircraft_position();
ac_pos.dump();
click_position()
geo.click_position();
Returns the position of the last mouse click on the landscape. Note that the altitude will be in metres.
Example
var click_pos = geo.click_position();
click_pos.dump();
elevation()
geo.elevation(lat, lon[, max_alt]);
Returns the elevation in metres of a certain point on the scenery. See also geodinfo
(which is used internally).
- lat
- Mandatory latitude coordinate.
- lon
- Mandatory longitude coordinate.
- max_alt
- Optional altitude in metres from which to begin searching. Defaults to 10,000 m.
Example
var ac_pos = geo.aircraft_position();
var elev = geo.elevation(ac_pos.lat(), ac_pos.lon());
printf("Terrain elevation: %i m", elev);
format()
geo.format(lat, lon);
Returns the coordinate formatted as a string. The format will be the same as used for scenery tiles, e.g., w010n50
(10 degrees West, 50 degrees North).
- lat
- Mandatory latitude coordinate.
- lon
- Mandatory longitude coordinate.
Example
var ac_pos = geo.aircraft_position();
print(geo.format(ac_pos.lat(), ac_pos.lon()));
normdeg()
geo.normdeg(angle);
Normalizes an angle to be in the range 0–360.
- angle
- Mandatory angle to normalize.
Examples
print(geo.normdeg(45)); # print "45"
print(geo.normdeg(-90)); # print "270"
print(geo.normdeg(-653)); # print "67"
normdeg180()
geo.normdeg180(angle);
Normalizes an angle to be in the range -180–180.
- angle
- Mandatory angle to normalize.
Examples
print(geo.normdeg180(96)); # print "96"
print(geo.normdeg180(-96)); # print "-96"
print(geo.normdeg180(256)); # print "-104"
print(geo.normdeg180(-209)); # print "151"
put_model()
tile_index()
tile_path()
viewer_position()
Variable
ERAD
geo.ERAD;
Radius of Earth in metres. This is almost equivalent to Earth's equatorial radius (6,378,137 m). Value: 6,378,138.12