Skip to main content

Geo functions

waypoints

Commentary

added in 0.3.11

stateful function

Generates a map of data about how to travel between waypoints, a series of coordinates. On each invocation, the map's keys latitude, longitude, and heading will update.

Inputs

  • waypoints: A series of coordinates to travel to.
  • speed: The speed to travel, in km/hr.
  • scale: Controls the granularity of points to travel through the waypoints. A value of 1, the default, yields one point per kilometer. Higher values yield coarser points, lower yield finer.
  • unit: Specify values in degrees or radians. Default is radians.
  • loop: Optional parameter. When set to true, causes an infinite series of coordinates to be generated in a loop around waypoints. In other words, when the last waypoint is encountered, a final segment is automatically drawn back to the first. Defaults to false.

Outputs

  • latitude: The current latitude.
  • longitude: The current longitude.
  • heading: The current heading between this geoposition and the next.
  • duration: The number of milliseconds between each point. Use this value to throttle the generator for speed-realism.
  • points: The total number of iterations it will take to travel between the first and last waypoint. Use this to stop the generator after completing the route. If loop is set to true, this indicates the number of points needed to travel through one complete loop.
  • distance: The total number of kilometers between the waypoints.
  • time: The total time, in hours, it will take to travel between waypoints for the given speed.

Examples

Generating coordinates

It's a good idea to place calls to waypoints in a var so you can pick apart it's output with function modifiers. This example uses selectKeys to obtain just the coordinates for output. It also uses points to stop the generator on completion and duration to throttle according to the real-world speed.

{
"topic": "sandbox",
"vars": {
"location": {
"_gen": "waypoints",
"waypoints": [
{
"coordinates": [
19.784437,
-94.723348
]
},
{
"coordinates": [
20,
-92
]
},
{
"coordinates": [
18,
-97
]
}
],
"speed": 500,
"scale": 1,
"unit": "degrees"
}
},
"value": {
"_gen": "var",
"var": "location",
"selectKeys": [
"latitude",
"longitude"
]
},
"localConfigs": {
"maxEvents": {
"_gen": "var",
"var": "location",
"path": [
"points"
]
},
"throttleMs": {
"_gen": "var",
"var": "location",
"path": [
"duration"
]
}
}
}
[
{
"latitude": 19.784437,
"longitude": -94.723348
},
{
"latitude": 19.785193361403508,
"longitude": -94.71379239298246
},
{
"latitude": 19.78594972280702,
"longitude": -94.70423678596491
},
{
"latitude": 19.786706084210525,
"longitude": -94.69468117894736
},
{
"latitude": 19.787462445614036,
"longitude": -94.68512557192983
},
{
"latitude": 19.788218807017543,
"longitude": -94.67556996491228
},
{
"latitude": 19.788975168421054,
"longitude": -94.66601435789474
},
{
"latitude": 19.78973152982456,
"longitude": -94.65645875087719
},
{
"latitude": 19.79048789122807,
"longitude": -94.64690314385965
},
{
"latitude": 19.79124425263158,
"longitude": -94.6373475368421
}
]

Specification

JSON schema

{
"type": "object",
"properties": {
"waypoints": {
"oneOf": [
{
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"coordinates": {
"oneOf": [
{
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
},
{
"type": "object",
"properties": {
"_gen": {
"type": "string"
}
},
"required": [
"_gen"
]
}
]
}
},
"required": [
"coordinates"
]
},
{
"type": "object",
"properties": {
"_gen": {
"type": "string"
}
},
"required": [
"_gen"
]
}
]
},
"minItems": 2
},
{
"type": "object",
"properties": {
"_gen": {
"type": "string"
}
},
"required": [
"_gen"
]
}
]
},
"speed": {
"oneOf": [
{
"type": "number",
"minimum": 0
},
{
"type": "object",
"properties": {
"_gen": {
"type": "string"
}
},
"required": [
"_gen"
]
}
]
},
"scale": {
"type": "number",
"minimum": 0.000001
},
"unit": {
"type": "string",
"enum": [
"degrees",
"radians"
]
},
"loop": {
"type": "boolean"
}
},
"required": [
"waypoints",
"speed"
]
}