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.

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

Tip  Copy & paste the examples into your Nasal Console and execute them to see what they do.

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

Version added: FG 3.0

This class can be used to show differences between search queries. Although it is only used for MapStructure and the Nasal Browser as of 09/2016, it can also be used for other applications.

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(1060)); # print "340"

print(geo.normdeg(-653)); # print "67"

normdeg180()

geo.normdeg180(angle);

Version added: FG 2.12

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()

geo.put_model(path, lat, lon[, elev[, hdg[, pitch[, roll]]]]);
geo.put_model(path, coord[, hdg[, pitch[, roll]]]]);

Places a model in the simulation at a given location and orientation. If successful, returns the model's root property as a props.Node object.

path

Path to the model as a string.

lat

Latitude coordinate.

lon

Longitude coordinate.

elev

Optional altitude. Defaults to nil, in which case the model will be placed on the terrain. Note that an error will be thrown if the terrain's elevation cannot be found, e.g., if there is no scenery tile loaded at the location.

coord

A geo.Coord instance, which, if given, replaces lat, lon and elev.

hdg

Optional model heading. Defaults to 0.

pitch

Optional model pitch. Defaults to 0.

roll

Optional model roll. Defaults to 0.

Examples

var path = 'Models/Geometry/glider.ac';
var coord = geo.aircraft_position();
var course = getprop("/orientation/heading-deg");
coord.apply_course_distance(course, 100); # Model to be added 100 m ahead
var model = geo.put_model(path, coord, course); # Place the default glider

var path = 'Models/Geometry/glider.ac';
var coord = geo.aircraft_position();
coord.apply_course_distance(getprop("/orientation/heading-deg"), 100); # model to be added 100 m ahead
var model = geo.put_model(path, coord.lat(), coord.lon(), coord.alt(), 0, 45, 50); # Place the default glider

tile_index()

geo.tile_index(lat, lon);

Returns the current tile's index. Effectively a wrapper for tileIndex .

lat

Mandatory latitude coordinate.

lon

Mandatory longitude coordinate.

Example

var ac_pos = geo.aircraft_position();
print(geo.tile_index(ac_pos.lat(), ac_pos.lon())); # prints the index of the current tile

tile_path()

geo.tile_path(lat, lon);

Returns the current tile's path under $FG_SCENERY/Terrain.

lat

Mandatory latitude coordinate.

lon

Mandatory longitude coordinate.

Example

var ac_pos = geo.aircraft_position();
printfinddata(geo.tile_path(ac_pos.lat(), ac_pos.lon())); # prints the path of the current

viewer_position()

geo.viewer_position();

Returns the current viewer position in the form of a geo.Coord object. Note that the altitude will be in metres.

Example

var v_pos = geo.viewer_position();
v_pos.dump();

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