Nasal library/geo

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 new 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 z-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 (commit)

This class can be used to show differences between FGPositioned (namespace: positioned) 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.

new()

geo.PositionedSearch.new(searchCmd, onAdded, onRemoved[, obj]);

Constructor function. Returns a new geo.PositionedSearch instance.

searchCmd

A mandatory function that will actually do the searching. It must return a vector containing the elements from the search.

onAdded

A mandatory function that will be called if a element has been added to the search results. The element added will be passed to this function.

onRemoved

A mandatory function that will be called if a element has been removed from the search results. The element removed will be passed to this function.

obj

Optional me reference. This will be used as the me reference in each of the above fucntions.

Example

var searchCmd = func(){
    return positioned.findAirportsWithinRange(10);
};

# This function will be called whenever an item is added
var added = func(apt){
    print("Airport ", apt.id, " added");
}

# This function will be called whenever an item is removed
var removed = func(apt){
    print("Airport ", apt.id, " removed");
}

# Create a new object, passing to it the search function to be used and the callbacks
var searcher = geo.PositionedSearch.new(searchCmd, added, removed);

# Actually update the searcher object
searcher.update();

test()

geo.PositionedSearch.test([from[, to]]);

Performs a test of the class. It benchmark's the amount of time it switch between searches for fixes at certain ranges.

from

Optional distance parameter in nautical miles for the first search for fixes. Defaults to 640.

to

Optional distance parameter in nautical miles for the second search for fixes. Defaults to 320.

Examples

geo.PositionedSearch.test(); # prints the test results and changed elements

geo.PositionedSearch.test(10, 50); # prints the test results and changed elements

update()

geo.PositionedSearch.update([searchCmd]);

Performs an search. It executes the search function and analyses the results.

searchCmd

Optional search function to use instead of the one given in PositionedSearch.new().

Example

var searchCmd = func(){
    return positioned.findAirportsWithinRange(10);
};
var added = func(apt){
    print("Airport ", apt.id, " added");
}
var removed = func(apt){
    print("Airport ", apt.id, " removed");
}

var searcher = geo.PositionedSearch.new(searchCmd, added, removed);
searcher.update();

_equals

geo.PositionedSearch._equals;

Function that checks if two objects are equal. You must redefine this function to use geo.PositionedSearch for other uses.

Example

var searchCmd = func(){
    var vec = [];
    var max = rand() * 10;
    for(var i = 1; i <= max; i += 1){
        append(vec, i);
    }
    return vec;
};
var added = func(num){
    print(num, " added");
}
var removed = func(num){
    print(num, " removed");
}

var searcher = geo.PositionedSearch.new(searchCmd, added, removed);
searcher._equals = func(a, b){ return a == b; }
searcher.update();
print("====");
searcher.update(); # run again to see differences between both queries

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

If the terrain altitude has not yet been loaded in the area identified by the coordinates, the function returns the nil value.

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

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