Nasal library/geo: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
(→‎Functions: Doc tile_index() and tile_path())
(→‎Functions: Doc viewer_position())
Line 427: Line 427:


=== viewer_position() ===
=== viewer_position() ===
{{Nasal doc
|syntax = geo.viewer_position();
|text = Returns the current viewer position in the form of a <code>geo.Coord</code> object. Note that the altitude will be in metres.
|example1 = var v_pos = geo.viewer_position();
v_pos.dump();
}}


== Variable ==
== Variable ==

Revision as of 16:22, 28 August 2016

WIP.png 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

Classes

Coord

Source

The main class, used widely for storing and managing positional data. Coordinates may be stored in either Earth-centered, Earth-fixed This is a link to a Wikipedia article coordinates (x, y and z) or geodetic coordinates This is a link to a Wikipedia article (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]);

Source

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

Source

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

Source

Sets the latitude This is a link to a Wikipedia article 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);

Source

Sets the longitude This is a link to a Wikipedia article 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);

Source

Sets the altitude This is a link to a Wikipedia article 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 This is a link to a Wikipedia article (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]);

Source

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 This is a link to a Wikipedia article (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);

Source

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

Source

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

Source

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

Source

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

Source

Returns the latitude coordinate.

Example

var coord = geo.Coord.new();
coord.set_latlon(98, 173);
print(coord.lat()); # prints "98"

lon()

geo.Coord.lon();

Source

Returns the longitude coordinate.

Example

var coord = geo.Coord.new();
coord.set_latlon(98, 173);
print(coord.lon()); # prints "173"

alt()

geo.Coord.alt();

Source

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

Source

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

Source

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

Source

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

Source

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

Source

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

Source

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

Source

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

Source

Returns the initial bearing (see here) to another geo.Coord instance. The bearing will be an absolute bearing This is a link to a Wikipedia article (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);

Source

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

Source

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

Missiles on a map.png
geo.Coord.apply_course_distance(course, dist);

Source

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

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