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.geocoordSystem.cartesian

Constructor | Methods

Constructor

ICoordSystem()

Methods

Name

Returns

Description

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:

Parameter

Default value

Description

point1*

—

Type: Number[]

The first point.

point2*

—

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:

Parameter

Default value

Description

startPoint*

—

Type: Number[]

Point of departure.

direction*

—

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 dlon/dlat amount (in JavaScript - this is a standard function Math.atan2(dlon, dlat)). In order to calculate the direction of movement from the azimuth "a", put dlat = cos(a), dlon = sin(a).

distance*

—

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.
    var azimuth = Math.PI / 4;
    // Direction of movement.
    var direction = [Math.cos(azimuth), Math.sin(azimuth)];
    // Path function.
    var 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:

Parameter

Default value

Description

startPoint*

—

Type: Number[]

Point of departure.

endPoint*

—

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.
        var 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'
            }));
        }
    });
});