Nasal library/geo: Difference between revisions
Red Leader (talk | contribs) (→aircraft_position(): Doc) |
(→set_z(): Correct a typo) |
||
(42 intermediate revisions by 4 users not shown) | |||
Line 1: | Line 1: | ||
{{Nasal Navigation|nocat=1}} | |||
{{Nasal Navigation}} | This page contains documentation for the '''<code>geo</code> namespace''' in [[Nasal]]. This namespace provides various geography/position-related [[#Functions|functions]], as well the [[#Coord|main class]]. Everything in the <code>geo</code> namespace is sourced from {{fgdata file|Nasal/geo.nas}} | ||
This page contains documentation for the '''<code>geo</code> namespace''' in [[Nasal]]. This namespace provides various geography/position-related [[#Functions|functions]], as well the [[#Coord|main class]]. | |||
{{tip|Copy & paste the examples into your [[Nasal Console]] and execute them to see what they do.|width=70%}} | |||
== Classes == | == Classes == | ||
Line 7: | Line 8: | ||
{{Nasal doc | {{Nasal doc | ||
|mode = class | |mode = class | ||
|text = The main class, used widely for storing and managing positional data. Coordinates may be stored in either {{wikipedia|ECEF|Earth-centered, Earth-fixed}} coordinates (x, y and z) or {{wikipedia|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. | |text = The main class, used widely for storing and managing positional data. Coordinates may be stored in either {{wikipedia|ECEF|Earth-centered, Earth-fixed}} coordinates (x, y and z) or {{wikipedia|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. | ||
}} | }} | ||
Line 13: | Line 13: | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = geo.Coord.new([coord]); | |syntax = geo.Coord.new([coord]); | ||
|text = Constructor function. Returns a new <code>geo.Coord</code> instance. | |||
|text = Constructor function. Returns a <code>geo.Coord</code> instance. | |||
|param1 = coord | |param1 = coord | ||
|param1text = An optional <code>geo.Coord</code> instance. If given, the returned instance will contain the values from this argument. | |param1text = An optional <code>geo.Coord</code> instance. If given, the returned instance will contain the values from this argument. | ||
Line 25: | Line 24: | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = geo.Coord.set(coord); | |syntax = geo.Coord.set(coord); | ||
|text = Sets the coordinates. Returns the <code>geo.Coord</code> instance. | |text = Sets the coordinates. Returns the <code>geo.Coord</code> instance. | ||
|param1 = coord | |param1 = coord | ||
Line 37: | Line 35: | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = geo.Coord.set_lat(lat); | |syntax = geo.Coord.set_lat(lat); | ||
|text = Sets the {{wikipedia|latitude}} coordinate. Returns the <code>geo.Coord</code> instance. | |text = Sets the {{wikipedia|latitude}} coordinate. Returns the <code>geo.Coord</code> instance. | ||
|param1 = lat | |param1 = lat | ||
Line 49: | Line 46: | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = geo.Coord.set_lon(lon); | |syntax = geo.Coord.set_lon(lon); | ||
|text = Sets the {{wikipedia|longitude}} coordinate. Returns the <code>geo.Coord</code> instance. | |text = Sets the {{wikipedia|longitude}} coordinate. Returns the <code>geo.Coord</code> instance. | ||
|param1 = lon | |param1 = lon | ||
Line 61: | Line 57: | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = geo.Coord.set_alt(alt); | |syntax = geo.Coord.set_alt(alt); | ||
|text = Sets the {{wikipedia|altitude}} coordinate. Returns the <code>geo.Coord</code> instance. | |text = Sets the {{wikipedia|altitude}} coordinate. Returns the <code>geo.Coord</code> instance. | ||
|param1 = alt | |param1 = alt | ||
Line 73: | Line 68: | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = geo.Coord.set_latlon(lat, lon[, alt]); | |syntax = geo.Coord.set_latlon(lat, lon[, alt]); | ||
|text = Sets the latitude and longitude coordinates, and optionally the altitude coordinate. Returns the <code>geo.Coord</code> instance. | |text = Sets the latitude and longitude coordinates, and optionally the altitude coordinate. Returns the <code>geo.Coord</code> instance. | ||
|param1 = lat | |param1 = lat | ||
Line 91: | Line 85: | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = geo.Coord.set_x(x); | |syntax = geo.Coord.set_x(x); | ||
|text = Sets the x-axis coordinate coordinate. Returns the <code>geo.Coord</code> instance. | |text = Sets the x-axis coordinate coordinate. Returns the <code>geo.Coord</code> instance. | ||
|param1 = x | |param1 = x | ||
Line 103: | Line 96: | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = geo.Coord.set_y(y); | |syntax = geo.Coord.set_y(y); | ||
|text = Sets the y-axis coordinate coordinate. Returns the <code>geo.Coord</code> instance. | |text = Sets the y-axis coordinate coordinate. Returns the <code>geo.Coord</code> instance. | ||
|param1 = y | |param1 = y | ||
Line 115: | Line 107: | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = geo.Coord.set_z(z); | |syntax = geo.Coord.set_z(z); | ||
|text = Sets the z-axis coordinate coordinate. Returns the <code>geo.Coord</code> instance. | |||
|text = Sets the | |||
|param1 = z | |param1 = z | ||
|param1text = The mandatory z-axis coordinate, in metres. | |param1text = The mandatory z-axis coordinate, in metres. | ||
Line 124: | Line 115: | ||
coord.dump(); | coord.dump(); | ||
}} | }} | ||
==== set_xyz() ==== | ==== set_xyz() ==== | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = geo.Coord.set_xyz(x, y, z); | |syntax = geo.Coord.set_xyz(x, y, z); | ||
|text = Sets all three Cartesian coordinates. Returns the <code>geo.Coord</code> instance. All arguments are mandatory. | |text = Sets all three Cartesian coordinates. Returns the <code>geo.Coord</code> instance. All arguments are mandatory. | ||
|param1 = x | |param1 = x | ||
Line 142: | Line 133: | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = geo.Coord.lat(); | |syntax = geo.Coord.lat(); | ||
|text = Returns the latitude coordinate. | |text = Returns the latitude coordinate. | ||
|example1 = var coord = geo.Coord.new(); | |example1 = var coord = geo.Coord.new(); | ||
Line 151: | Line 141: | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = geo.Coord.lon(); | |syntax = geo.Coord.lon(); | ||
|text = Returns the longitude coordinate. | |text = Returns the longitude coordinate. | ||
|example1 = var coord = geo.Coord.new(); | |example1 = var coord = geo.Coord.new(); | ||
Line 160: | Line 149: | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = geo.Coord.alt(); | |syntax = geo.Coord.alt(); | ||
|text = Returns the altitude coordinate. | |text = Returns the altitude coordinate. | ||
|example1 = var coord = geo.Coord.new(); | |example1 = var coord = geo.Coord.new(); | ||
Line 169: | Line 157: | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = geo.Coord.latlon(); | |syntax = geo.Coord.latlon(); | ||
|text = Returns a vector containing the latitude, longitude, and altitude, in that order. | |text = Returns a vector containing the latitude, longitude, and altitude, in that order. | ||
|example1 = var coord = geo.Coord.new(); | |example1 = var coord = geo.Coord.new(); | ||
Line 178: | Line 165: | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = geo.Coord.x(); | |syntax = geo.Coord.x(); | ||
|text = Returns the x-axis coordinate. | |text = Returns the x-axis coordinate. | ||
|example1 = var coord = geo.Coord.new(); | |example1 = var coord = geo.Coord.new(); | ||
Line 187: | Line 173: | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = geo.Coord.y(); | |syntax = geo.Coord.y(); | ||
|text = Returns the y-axis coordinate. | |text = Returns the y-axis coordinate. | ||
|example1 = var coord = geo.Coord.new(); | |example1 = var coord = geo.Coord.new(); | ||
Line 196: | Line 181: | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = geo.Coord.z(); | |syntax = geo.Coord.z(); | ||
|text = Returns the z-axis coordinate. | |text = Returns the z-axis coordinate. | ||
|example1 = var coord = geo.Coord.new(); | |example1 = var coord = geo.Coord.new(); | ||
Line 205: | Line 189: | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = geo.Coord.xyz(); | |syntax = geo.Coord.xyz(); | ||
|text = Returns a vector containing the x, y, and z coordinates, in that order. | |text = Returns a vector containing the x, y, and z coordinates, in that order. | ||
|example1 = var coord = geo.Coord.new(); | |example1 = var coord = geo.Coord.new(); | ||
Line 214: | Line 197: | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = geo.Coord.is_defined(); | |syntax = geo.Coord.is_defined(); | ||
|text = 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. | |text = 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. | ||
|example1 = var coord = geo.Coord.new(); | |example1 = var coord = geo.Coord.new(); | ||
Line 225: | Line 207: | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = geo.Coord.dump(); | |syntax = geo.Coord.dump(); | ||
|text = 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. | |text = 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. | ||
|example1 = var coord = geo.Coord.new(); | |example1 = var coord = geo.Coord.new(); | ||
Line 237: | Line 218: | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = geo.Coord.course_to(coord); | |syntax = geo.Coord.course_to(coord); | ||
|text = Returns the initial bearing (see [http://www.movable-type.co.uk/scripts/latlong.html#bearing here]) to another <code>geo.Coord</code> instance. The bearing will be an {{wikipedia|absolute bearing}} (in the range 0–360). | |||
|text = Returns the initial bearing (see [http://www.movable-type.co.uk/scripts/latlong.html#bearing here]) to another <code>geo.Coord</code> instance. The bearing will be in the range 0–360. | |||
|param1 = coord | |param1 = coord | ||
|param1text = Mandatory <code>geo.Coord</code> instance to calculate bearing to. | |param1text = Mandatory <code>geo.Coord</code> instance to calculate bearing to. | ||
Line 247: | Line 227: | ||
printf("%.5f", c1.course_to(c2)); # prints "44.99564" | printf("%.5f", c1.course_to(c2)); # prints "44.99564" | ||
}} | }} | ||
==== distance_to() ==== | ==== distance_to() ==== | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = geo.Coord.distance_to(coord); | |syntax = geo.Coord.distance_to(coord); | ||
|text = Returns the great circle distance in metres to another <code>geo.Coord</code> instance. Note that this function ignores altitude. | |text = Returns the great circle distance in metres to another <code>geo.Coord</code> instance. Note that this function ignores altitude. | ||
|param1 = coord | |param1 = coord | ||
Line 263: | Line 243: | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = geo.Coord.direct_distance_to(coord); | |syntax = geo.Coord.direct_distance_to(coord); | ||
|text = Returns the direct distance (cutting through the earth) in metres to another <code>geo.Coord</code> instance. | |text = Returns the direct distance (cutting through the earth) in metres to another <code>geo.Coord</code> instance. | ||
|param1 = coord | |param1 = coord | ||
Line 274: | Line 253: | ||
}} | }} | ||
==== apply_course_distance() ==== | ==== apply_course_distance() ==== | ||
[[File:Missiles on a map.png|thumb]] | |||
{{Nasal doc | {{Nasal doc | ||
|syntax = geo.Coord. | |syntax = geo.Coord.apply_course_distance(course, dist); | ||
|text = Calculates a new coordinate from a given course and distancce, and then updates the coordinates to the new set. Returns the <code>geo.Coord</code> instance. | |text = Calculates a new coordinate from a given course and distancce, and then updates the coordinates to the new set. Returns the <code>geo.Coord</code> instance. | ||
|param1 = course | |param1 = course | ||
|param1text = Mandatory | |param1text = Mandatory absolute bearing (0–360) to use in calculation. | ||
|param2 = dist | |param2 = dist | ||
|param2text = Mandatory distance in metres to use in calculation. | |param2text = Mandatory distance in metres to use in calculation. | ||
Line 287: | Line 266: | ||
coord.apply_course_distance(245, 10000); | coord.apply_course_distance(245, 10000); | ||
coord.dump(); # lat=-0.037964 lon=-0.081415 | coord.dump(); # lat=-0.037964 lon=-0.081415 | ||
|example2 = | |||
# 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 === | === PositionedSearch === | ||
{{Nasal doc | |||
|mode = class | |||
|version = 3.0 | |||
|commit = {{fgdata commit|a9576e|t=commit}} | |||
|text = This class can be used to show differences between FGPositioned (namespace: <code>positioned</code>) 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() ==== | |||
{{Nasal doc | |||
|syntax = geo.PositionedSearch.new(searchCmd, onAdded, onRemoved[, obj]); | |||
|text = Constructor function. Returns a new <code>geo.PositionedSearch</code> instance. | |||
|param1 = searchCmd | |||
|param1text = A mandatory function that will actually do the searching. It must return a vector containing the elements from the search. | |||
|param2 = onAdded | |||
|param2text = 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. | |||
|param3 = onRemoved | |||
|param3text = 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. | |||
|param4 = obj | |||
|param4text = Optional <code>'''me'''</code> reference. This will be used as the <code>'''me'''</code> reference in each of the above fucntions. | |||
|example1 = 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() ==== | |||
{{Nasal doc | |||
|syntax = geo.PositionedSearch.test([from[, to]]); | |||
|text = Performs a test of the class. It benchmark's the amount of time it switch between searches for fixes at certain ranges. | |||
|param1 = from | |||
|param1text = Optional distance parameter in nautical miles for the first search for fixes. Defaults to 640. | |||
|param2 = to | |||
|param2text = Optional distance parameter in nautical miles for the second search for fixes. Defaults to 320. | |||
|example1 = geo.PositionedSearch.test(); # prints the test results and changed elements | |||
|example2 = geo.PositionedSearch.test(10, 50); # prints the test results and changed elements | |||
}} | |||
==== update() ==== | |||
{{Nasal doc | |||
|syntax = geo.PositionedSearch.update([searchCmd]); | |||
|text = Performs an search. It executes the search function and analyses the results. | |||
|param1 = searchCmd | |||
|param1text = Optional search function to use instead of the one given in <code>[[#new()_2|PositionedSearch.new()]]</code>. | |||
|example1 = 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 ==== | |||
{{Nasal doc | |||
|syntax = geo.PositionedSearch._equals; | |||
|text = Function that checks if two objects are equal. You must redefine this function to use <code>geo.PositionedSearch</code> for other uses. | |||
|example1 = 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 == | == Functions == | ||
Line 300: | Line 381: | ||
=== click_position() === | === click_position() === | ||
{{Nasal doc | |||
|syntax = geo.click_position(); | |||
|text = Returns the position of the last mouse click on the landscape. Note that the altitude will be in metres. | |||
|example1 = var click_pos = geo.click_position(); | |||
click_pos.dump(); | |||
}} | |||
=== elevation() === | === elevation() === | ||
{{Nasal doc | |||
|syntax = geo.elevation(lat, lon[, max_alt]); | |||
|text = Returns the elevation in metres of a certain point on the scenery. See also {{func link|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. | |||
|param1 = lat | |||
|param1text = Mandatory latitude coordinate. | |||
|param2 = lon | |||
|param2text = Mandatory longitude coordinate. | |||
|param3 = max_alt | |||
|param3text = Optional altitude in metres from which to begin searching. Defaults to 10,000 m. | |||
|example1 = var ac_pos = geo.aircraft_position(); | |||
var elev = geo.elevation(ac_pos.lat(), ac_pos.lon()); | |||
printf("Terrain elevation: %i m", elev); | |||
}} | |||
=== format() === | === format() === | ||
{{Nasal doc | |||
|syntax = geo.format(lat, lon); | |||
|text = Returns the coordinate formatted as a string. The format will be the same as used for scenery tiles, e.g., <code>w010n50</code> (10 degrees West, 50 degrees North). | |||
|param1 = lat | |||
|param1text = Mandatory latitude coordinate. | |||
|param2 = lon | |||
|param2text = Mandatory longitude coordinate. | |||
|example1 = var ac_pos = geo.aircraft_position(); | |||
print(geo.format(ac_pos.lat(), ac_pos.lon())); | |||
}} | |||
=== normdeg() === | === normdeg() === | ||
{{Nasal doc | |||
|syntax = geo.normdeg(angle); | |||
|text = Normalizes an angle to be in the range 0–360. | |||
|param1 = angle | |||
|param1text = Mandatory angle to normalize. | |||
|example1 = print(geo.normdeg(45)); # print "45" | |||
|example2 = print(geo.normdeg(-90)); # print "270" | |||
|example3 = print(geo.normdeg(1060)); # print "340" | |||
|example4 = print(geo.normdeg(-653)); # print "67" | |||
}} | |||
=== normdeg180() === | === normdeg180() === | ||
{{Nasal doc | |||
|syntax = geo.normdeg180(angle); | |||
|version = 2.12 | |||
|commit = {{fgdata commit|8c23d0|t=commit}} | |||
|text = Normalizes an angle to be in the range -180–180. | |||
|param1 = angle | |||
|param1text = Mandatory angle to normalize. | |||
|example1 = print(geo.normdeg180(96)); # print "96" | |||
|example2 = print(geo.normdeg180(-96)); # print "-96" | |||
|example3 = print(geo.normdeg180(256)); # print "-104" | |||
|example4 = print(geo.normdeg180(-209)); # print "151" | |||
}} | |||
=== put_model() === | === put_model() === | ||
{{Nasal doc | |||
|syntax = geo.put_model(path, lat, lon[, elev[, hdg[, pitch[, roll]]]]); | |||
geo.put_model(path, coord[, hdg[, pitch[, roll]]]]); | |||
|text = Places a model in the simulation at a given location and orientation. If successful, returns the model's root property as a <code>props.Node</code> object. | |||
|param1 = path | |||
|param1text = Path to the model as a string. | |||
|param2 = lat | |||
|param2text = Latitude coordinate. | |||
|param3 = lon | |||
|param3text = Longitude coordinate. | |||
|param4 = elev | |||
|param4text = Optional altitude. Defaults to <code>'''nil'''</code>, 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. | |||
|param5 = coord | |||
|param5text = A <code>geo.Coord</code> instance, which, if given, replaces '''lat''', '''lon''' and '''elev'''. | |||
|param6 = hdg | |||
|param6text = Optional model heading. Defaults to 0. | |||
|param7 = pitch | |||
|param7text = Optional model pitch. Defaults to 0. | |||
|param8 = roll | |||
|param8text = Optional model roll. Defaults to 0. | |||
|example1 = 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 | |||
|example2 = 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() === | === tile_index() === | ||
{{Nasal doc | |||
|syntax = geo.tile_index(lat, lon); | |||
|text = Returns the current tile's index. Effectively a wrapper for {{func link|tileIndex()}}. | |||
|param1 = lat | |||
|param1text = Mandatory latitude coordinate. | |||
|param2 = lon | |||
|param2text = Mandatory longitude coordinate. | |||
|example1 = 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() === | === tile_path() === | ||
{{Nasal doc | |||
|syntax = geo.tile_path(lat, lon); | |||
|text = Returns the current tile's path under <tt>''[[$FG_SCENERY]]/Terrain''</tt>. | |||
|param1 = lat | |||
|param1text = Mandatory latitude coordinate. | |||
|param2 = lon | |||
|param2text = Mandatory longitude coordinate. | |||
|example1 = var ac_pos = geo.aircraft_position(); | |||
printfinddata(geo.tile_path(ac_pos.lat(), ac_pos.lon())); # prints the path of the current | |||
}} | |||
=== 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 == | ||
Line 315: | Line 513: | ||
|text = Radius of Earth in metres. This is almost equivalent to Earth's equatorial radius (6,378,137 m). Value: 6,378,138.12 | |text = Radius of Earth in metres. This is almost equivalent to Earth's equatorial radius (6,378,137 m). Value: 6,378,138.12 | ||
}} | }} | ||
{{Nasal namespaces}} |
Latest revision as of 16:51, 16 October 2019
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
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 theme
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