Ruler | MapGL | 2GIS Documentation
MapGL JS API

Ruler plugin

Ruler has two usage modes: polyline and polygon.

The polyline mode allows you to measure a distance, and the polygon mode is used when you need to measure an area and a perimeter of a polygon on the map.

To append ruler on the map, first you need to instantiate Ruler:

const ruler = new mapgl.Ruler(map, { mode: 'polyline' });

Or if you use npm:

// Import either as an ES module...
import { Ruler } from '@2gis/mapgl-ruler';
// ...or as a CommonJS module
const { Ruler } = require('@2gis/mapgl-ruler');

const ruler = new Ruler(map, { mode: 'polyline' });

Try clicking on any place on the map to display a ruler.

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>2GIS Map API</title>
        <meta name="description" content="MapGL API ruler example" />
        <style>
            html,
            body,
            #container {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
            }
            .button {
                padding: 4px 10px;
                background: #00a81f;
                border-radius: 4px;
                box-shadow: 0 1px 3px 0 rgba(38, 38, 38, 0.5);
                border: none;
                color: #fff;
                font-size: 12px;
                cursor: pointer;
            }
        </style>
    </head>
    <body>
        <div id="container"></div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
        <script src="https://unpkg.com/@2gis/mapgl-ruler@^2/dist/ruler.js"></script>
        <script>
            const map = new mapgl.Map('container', {
                center: [55.31878, 25.23584],
                zoom: 13,
                key: 'Your API access key',
            });

            const ruler = new mapgl.Ruler(map, {
                mode: 'polyline',
                points: [
                    [55.31878, 25.23584],
                    [55.31878, 25.25584],
                    [55.33878, 25.23584],
                ],
            });

            const resetControl = new mapgl.Control(
                map,
                '<button class="button">Reset points</button>',
                {
                    position: 'topLeft',
                },
            );

            resetControl
                .getContainer()
                .querySelector('button')
                .addEventListener('click', function () {
                    ruler.destroy();
                    ruler.enable();
                });
        </script>
    </body>
</html>

Try clicking on any place on the map to display a ruler.

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>2GIS Map API</title>
        <meta name="description" content="MapGL API ruler example" />
        <style>
            html,
            body,
            #container {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
            }
            .button {
                padding: 4px 10px;
                background: #00a81f;
                border-radius: 4px;
                box-shadow: 0 1px 3px 0 rgba(38, 38, 38, 0.5);
                border: none;
                color: #fff;
                font-size: 12px;
                cursor: pointer;
            }
        </style>
    </head>
    <body>
        <div id="container"></div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
        <script src="https://unpkg.com/@2gis/mapgl-ruler@^2/dist/ruler.js"></script>
        <script>
            const map = new mapgl.Map('container', {
                center: [55.31878, 25.23584],
                zoom: 13,
                key: 'Your API access key',
            });

            const ruler = new mapgl.Ruler(map, {
                mode: 'polygon',
                points: [
                    [55.31878, 25.23584],
                    [55.31878, 25.25584],
                    [55.33878, 25.23584],
                ],
            });

            const resetControl = new mapgl.Control(
                map,
                '<button class="button">Reset points</button>',
                {
                    position: 'topLeft',
                },
            );

            resetControl
                .getContainer()
                .querySelector('button')
                .addEventListener('click', function () {
                    ruler.destroy();
                    ruler.enable();
                });
        </script>
    </body>
</html>

A RulerControl instance is a wrapper of a Ruler instance and it extends Control functionality.

It provides a control for enabling or disabling a ruler.

const rulerControl = new RulerControl(map, { position: 'centerRight', mode: 'polyline' });

You can get the Ruler instance via getRuler() method.

rulerControl.getRuler().setPoints([
    [55.31878, 25.23584],
    [55.31878, 25.25584],
    [55.33878, 25.23584],
]);

Try clicking on the ruler button to enable or disable ruler.

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>2GIS Map API</title>
        <meta name="description" content="MapGL API ruler control example" />
        <style>
            html,
            body,
            #container {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
            }
            .button {
                padding: 4px 10px;
                background: #00a81f;
                border-radius: 4px;
                box-shadow: 0 1px 3px 0 rgba(38, 38, 38, 0.5);
                border: none;
                color: #fff;
                font-size: 12px;
                cursor: pointer;
            }
        </style>
    </head>
    <body>
        <div id="container"></div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
        <script src="https://unpkg.com/@2gis/mapgl-ruler@^2/dist/ruler.js"></script>
        <script>
            const map = new mapgl.Map('container', {
                center: [55.31878, 25.23584],
                zoom: 13,
                key: 'Your API access key',
            });

            let mode = 'polyline';
            let control = new mapgl.RulerControl(map, { position: 'centerRight', mode });
            control.getRuler().setPoints([
                [55.31878, 25.23584],
                [55.31878, 25.25584],
                [55.33878, 25.23584],
            ]);

            const resetControl = new mapgl.Control(
                map,
                '<button class="button">Switch mode</button>',
                {
                    position: 'topLeft',
                },
            );

            resetControl
                .getContainer()
                .querySelector('button')
                .addEventListener('click', function () {
                    const data = control.getRuler().getData();
                    control.destroy();

                    let points = [];
                    switch (data.type) {
                        case 'polyline':
                            points = data.coordinates;
                            break;
                        case 'polygon':
                            points = data.coordinates[0];
                            break;
                    }

                    mode = mode === 'polyline' ? 'polygon' : 'polyline';
                    control = new mapgl.RulerControl(map, { position: 'centerRight', mode });
                    control.getRuler().setPoints(points);
                });
        </script>
    </body>
</html>