3D models | 2GIS Documentation
MapGL JS API

3D models

The map supports rendering of 3D models of the GLTF/GLB format. These models allow you to improve the esthetics of the map view, highlight certain objects, and increase the level of details.

3D models

To add models to the map, you need to prepare data and configure a layer in the Style editor. Examples below show styling of city sights where each sight has a unique model.

  1. Open the Style editor.

  2. Add a new layer and select the 3D model layer type.

  3. On the Data tab, scroll down and select JSON - add manually.

  4. Copy and paste the following code snippet:

    [
    "match",
    [
        "get",
        "layerType"
    ],
    [
        "SightModels"
    ],
    true,
    false
    ]
    
  5. Switch to the Style tab and set the following parameters using JSON (click Edit JSON):

    Parameter Value
    Model source ["get", "url"]
    Scale ["get", "scale"]
    Rotation ["get", "rotation"]
    Offset ["get", "translate"]

    Because the URL and exact location of models will be defined in the geodata, you need to link parameters of a model with its attributes using get expressions in the style layer.

  6. Place the resulting style layer after layers with POI and before layers with 3D buildings so that models do not overlay captures and icons:

    Order of style layers

  7. In the editor toolbar, select Share and copy the style ID to be used later:

    Style ID

Set the location of each model and its positioning configuration in a GeoJSON file:

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "properties": {
                "url": 'https://disk.2gis.com/digital-twin/models_s3/docs/kingdomcentre.glb',
                "layerType": "SightModels",
                "scale": [1, 1, 1],
                "rotation": [0, 0, 0],
                "translate": [0, 0, 0],
            },
            "geometry": {
                "type": "Point",
                "coordinates": [61.284307, 55.177358]
            }
        }
    ]
}

Parameters:

  • "type": "Feature" - common Feature object of GeoJSON.

  • properties:

    • url - URL to load a model.
    • "layerType": "SightModels" - enables the map to match a data object to a created style layer.
    • scale - initial scale setting.
    • rotation - initial rotation setting.
    • translate - initial offset setting.

    You can edit transformation settings later, after checking the model position on the map.

  • geometry:

    • "type": "Point" - point object.
    • coordinates - object center coordinates. In the given example, the object will be displayed in the 61.284307, 55.177358 point.

When the model data and the style layer are ready, you can evaluate an intermediate result:

<!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="Quickstart with 2GIS Map API" />
        <style>
            html,
            body,
            #container {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
            }
        </style>
    </head>
    <body>
        <div id="container"></div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
        <script>
            const map = new mapgl.Map('container', {
                center: [46.674137, 24.711404],
                zoom: 17,
                rotation: 174,
                pitch: 45,
                key: 'Your API access key',
                style: '18d586c4-4c36-4455-a60f-a4366f1fb17f'
            });

            map.on('click', function (ev) {
                console.log(ev);
            });

            const modelSource = new mapgl.GeoJsonSource(map, {
                data: {
                    "type": "FeatureCollection",
                    "features": [
                        {
                            "type": "Feature",
                            "properties": {
                                "scale": [1, 1, 1],
                                "rotation": [0, 0, 0],
                                "translate": [0, 0, 0],
                                "layerType": "SightModels",
                                "url": "https://disk.2gis.com/digital-twin/models_s3/docs/kingdomcentre.glb",
                                "idsToHide": []
                            },
                            "geometry": {
                                "type": "Point",
                                "coordinates": [46.674137, 24.711404]
                            }
                        }
                    ]
                }    
            })
            </script>
    </body>
</html>

You can see that the model is displayed on the map but is shown incorrectly. You need to configure its rotation and offset and hide a 3D building currently located in the model place.

To correctly position the model, open the example with the intermediate result and edit values of the scale, rotation, and translate object parameters. To correctly display the model above, specify the following values:

"scale": [0.98, 0.98, 0.98],
"rotation": [0, 0, 23],
"translate": [22, -6, 0],

Details about 3D model positioning

3D models support transformations in three-dimensional space defined by x-, y-, and z-axes.

Coordinate system

Scale transformation is done in the local coordinate system (Local in the picture above). Other transformations are performed in the World Coordinate System (World), where the x-axis faces east, the y-axis faces north, and the z-axis points upwards.

The scale is set in relative units based on the initial model size.

In most cases, you should change the model scale in all three axes at once. Otherwise, a model will look stretched and distorted.

The rotation is set in degrees.

The most common case is rotating a model around the z-axis. Rotation around other axes may lead to model distortion.

The offset is set in meters relatively to the initial model location.

You should define the offset in x- and y-axes only to prevent a model from "hanging in the air".

To hide a 3D building overlaying the added model:

  1. Get the target building ID:

    1. Subscribe to the click event on the map and make it return to the console. Add the following snippet to your application source code:

      map.on('click', function (ev) {
          console.log(ev);
      });
      
    2. Open the browser DevTools and click the building to be hidden. The required ID is shown in the target.id field of the event. Event example:

      Click event in the console

  2. Specify the received ID in the idsToHide filed of the GeoJSON data:

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "properties": {
                "idsToHide": ["2111697998173735"],
                ...
            },
            ...
        }
    ]
}
  1. Specify this filed in the Linked ids parameter of the style layer:
Parameter Value
Linked ids ["get", "idsToHide"]

You can also check style layer settings in a prepared style. To access the settings, log into the Styles editor and select Create a copy.

<!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="Quickstart with 2GIS Map API" />
        <style>
            html,
            body,
            #container {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
            }
        </style>
    </head>
    <body>
        <div id="container"></div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
        <script>
            const map = new mapgl.Map('container', {
                center: [46.674137, 24.711404],
                zoom: 16.5,
                rotation: 174,
                pitch: 45,
                key: 'Your API access key',
                style: '18d586c4-4c36-4455-a60f-a4366f1fb17f',
                enableTrackResize: true
            });

            map.on('click', function (ev) {
                console.log(ev);
            });

            const modelSource = new mapgl.GeoJsonSource(map, {
                data: {
                    "type": "FeatureCollection",
                    "features": [
                        {
                            "type": "Feature",
                            "properties": {
                                "scale": [0.98, 0.98, 0.98],
                                "rotation": [0, 0, 23],
                                "translate": [22, -6, 0],
                                "layerType": "SightModels",
                                "url": "https://disk.2gis.com/digital-twin/models_s3/docs/kingdomcentre.glb",
                                "idsToHide": ["70030076256609771"]
                            },
                            "geometry": {
                                "type": "Point",
                                "coordinates": [46.674137, 24.711404]
                            }
                        }
                    ]
                }    
            })
            </script>
    </body>
</html>