Documentation
Reference
2.1.55 (current version)
collection
interactivityModel
Interfaces

ICoordSystem

Interface for the map's coordinate system. This interface must be implemented if non-standard coordinates are used (such as cylindrical coordinates). To solve tasks with searching for the trajectory of movement on the earth's surface, use the coordSystem.geo object; on a Cartesian surface, use coordSystem.cartesian.

See coordSystem.geo coordSystem.cartesian

Constructor | Methods

Constructor

ICoordSystem()

Methods

NameReturnsDescription
getDistance(point1, point2)

Number

Returns the shortest distance (along a geodetic line) between the two set points (in meters).

solveDirectProblem(startPoint, direction, distance)

Object

Solves the first (direct) geodesic problem: where we will end up, if we start from a specified point and move in the specified direction for the specified distance, without turning. The following data is a solution for the direct geodetic problem:

  • The end point.
  • The final direction.
  • The path function.
  • A function that allows to specify, for any given moment in time, which point we will be at and which direction we will be moving in.

solveInverseProblem(startPoint, endPoint[, reverseDirection])

Object

Solves the second (inverse) geodetic problem: construct the shortest route between two points on the mapped surface and determine the distance and direction of movement. Note that on the map of the Earth's surface, the shortest routes are shown as crooked lines. For geo objects in the API, you can enable the mode for displaying shortest distances between points using the "geodesic" option.

Methods details

getDistance

{Number} getDistance(point1, point2)

Returns the shortest distance (along a geodetic line) between the two set points (in meters).

Parameters:

ParameterDefault valueDescription
point1*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Number[]

The first point.

point2*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Number[]

The second point.

* Mandatory parameter/option.

Example:

// Calculating the distance between Moscow and New York
// Coordinates of Moscow
ymaps.geocode('Moscow').then(function (res) {
    var moscowCoords = res.geoObjects.get(0).geometry.getCoordinates();
    // Coordinates of New York
    ymaps.geocode('New York').then(function (res) {
        var newYorkCoords = res.geoObjects.get(0).geometry.getCoordinates();
        // Distance
        alert(ymaps.formatter.distance(
            ymaps.coordSystem.geo.getDistance(moscowCoords, newYorkCoords)
        ));
    });
});

solveDirectProblem

{Object} solveDirectProblem(startPoint, direction, distance)

Solves the first (direct) geodesic problem: where we will end up, if we start from a specified point and move in the specified direction for the specified distance, without turning. The following data is a solution for the direct geodetic problem:

  • The end point.
  • The final direction.
  • The path function.
  • A function that allows to specify, for any given moment in time, which point we will be at and which direction we will be moving in.

Returns object with following fields:

  • startPoint - The starting point in geocoordinates.
  • startDirection - The starting direction of movement.
  • endPoint - The end point in geocoordinates.
  • endDirection - The final direction of movement.
  • distance - The distance in meters.
  • pathFunction - A function that accepts a number from 0 to 1 (the portion of the path completed) and returns a structure with the fields "point" and "direction".
.

Parameters:

ParameterDefault valueDescription
startPoint*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Number[]

Point of departure.

direction*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Number[]

Direction. Set as a vector (an increment of coordinates) - either [dlat, dlon] or [dlon, dlat], depending on the "coordorder" parameter. In order to get the azimuth from a direction specified like this (the azimuth is the angle between the direction of movement and North), we need to calculate the arctangent of the dlat/dlon amount (in JavaScript - this is a standard function Math.atan2(dlat, dlon)). In order to calculate the direction of movement from the azimuth "a", put dlat = cos(a), dlon = sin(a).

distance*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Number

The distance walked, in meters.

* Mandatory parameter/option.

Example:

// Let's assume that we took off from Domodedovo airport (Moscow) going 
// northeast and flew straight for 200 kilometers. We'll use placemarks to show our path
// on the map.

// Finding the coordinates of the starting point, using geocoding.
ymaps.geocode('Domodedovo airport').then(function (res) {
    var startPoint = res.geoObjects.get(0).geometry.getCoordinates(),
    // Moving northeast, azimuth of 45 degrees
    // or radian pi/4.
        azimuth = Math.PI / 4,
    // Direction of movement.
        direction = [Math.cos(azimuth), Math.sin(azimuth)],
    // Path function
        path = ymaps.coordSystem.geo
            .solveDirectProblem(startPoint, direction, 2e5).pathFunction;

    // Showing the path on the map using placemarks set every 10 km
    for (var i = 0; i <= 20; i++) {
        map.geoObjects.add(new ymaps.Placemark(path(i/20).point));
    }
});

solveInverseProblem

{Object} solveInverseProblem(startPoint, endPoint[, reverseDirection])

Solves the second (inverse) geodetic problem: construct the shortest route between two points on the mapped surface and determine the distance and direction of movement. Note that on the map of the Earth's surface, the shortest routes are shown as crooked lines. For geo objects in the API, you can enable the mode for displaying shortest distances between points using the "geodesic" option.

Returns object with following fields:

  • startPoint - The starting point in geocoordinates.
  • startDirection - The starting direction of movement.
  • endPoint - The end point in geocoordinates.
  • endDirection - The final direction of movement.
  • distance - The distance in meters.
  • pathFunction - A path function that accepts a number from 0 to 1 (the portion of the path completed) and returns a structure with the fields "point" and "direction".
.

Parameters:

ParameterDefault valueDescription
startPoint*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Number[]

Point of departure.

endPoint*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Number[]

Point of arrival.

reverseDirection false

Type: Boolean

Direction of movement. "false" - select the shortest arc; "true" - select the opposite of the shortest arc.

* Mandatory parameter/option.

Example:

// Constructing the shortest route from Kaliningrad to Vladivostok
// Finding the coordinates of Kaliningrad
ymaps.geocode('Kaliningrad').then(function (res) {
    var startPoint = res.geoObjects.get(0).geometry.getCoordinates();
    // Finding the coordinates of Vladivostok
    ymaps.geocode('Vladivostok').then(function (res) {
        var endPoint = res.geoObjects.get(0).geometry.getCoordinates(),
        // Finding the function of the path between two points
        path = ymaps.coordSystem.geo
            .solveInverseProblem(startPoint, endPoint).pathFunction;
        // Showing the path with 20 points
        for (var i = 0; i <= 20; i++) {
            // Finding an intermediate point
            var position = path(i/20).point;
            // Adding a placemark to an intermediate point
            map.geoObjects.add(new ymaps.Placemark(
                position, {
                    // Showing the distance covered in the placemark content
                    iconContent: ymaps.formatter.distance(
                        ymaps.coordSystem.geo.getDistance(startPoint, position)
                    )
                }, {
                    preset: 'isladns#redStretchyIcon'
                }
            ));
        }
    });
});