Adición de una capa de WebGL personalizada a un mapa

2024-08-29

El SDK web de Azure Maps admite la creación de capas personalizadas mediante WebGL. WebGL se basa en OpenGL ES y permite representar gráficos 2D y 3D en exploradores web.

Con WebGL, puede crear gráficos interactivos de alto rendimiento que se representan en el explorador en tiempo real y que admiten escenarios como simulaciones, visualización de datos, animaciones y modelado 3D.

Los desarrolladores pueden acceder al contexto de WebGL del mapa durante la representación y usar capas de WebGL personalizadas para realizar una integración con otras bibliotecas, como three.js y deck.gl, con el fin de proporcionar contenido enriquecido e interactivo en el mapa.

Adición de una capa de WebGL

Para poder agregar una capa de WebGL a un mapa, necesita tener un objeto que implemente la interfaz WebGLRenderer. En primer lugar, proporcione un objeto id y renderer al constructor para crear una capa de WebGL y, luego, agregue la capa al mapa para que se represente.

En el código de ejemplo siguiente se muestra cómo agregar una capa de WebGL a un mapa:

var myRenderer = {
    /**
     * Either "2d" or "3d". Defaults to "2d".
     * - "3d" to use the depth buffer and share it with other layers
     * - "2d" to add a layer with no depth. If you need to use the depth buffer for a "2d"
     *   layer you must use an offscreen framebuffer and the prerender method.
     */
    renderingMode: "2d",

    /**
     * Optional method called when the layer has been added to the Map.
     * This gives the layer a chance to initialize gl resources and register event listeners.
     * @param map The Map this custom layer was just added to.
     * @param gl The gl context for the map.
     */
    onAdd: function (map, gl) {},

    /**
     * Optional method called when the layer has been removed from the Map.
     * This gives the layer a chance to clean up gl resources and event listeners.
     * @param map The Map this custom layer was just added to.
     * @param gl The gl context for the map.
     */
    onRemove: function (map, gl) {},

    /**
     * Optional method called during a render frame to allow a layer to prepare resources
     * or render into a texture.
     *
     * The layer cannot make any assumptions about the current GL state and must bind a framebuffer before rendering.
     *
     * @param gl The map's gl context.
     * @param matrix The map's camera matrix.
     */
    prerender: function (gl, matrix) {},

    /**
     * Required. Called during a render frame allowing the layer to draw into the GL context.
     *
     * The layer can assume blending and depth state is set to allow the layer to
     * properly blend and clip other layers. The layer cannot make any other 
     * assumptions about the current GL state.
     *
     * If the layer needs to render to a texture, it should implement the prerender
     * method to do this and only use the render method for drawing directly into the
     * main framebuffer.
     *
     * The blend function is set to gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA).
     * This expects colors to be provided in premultiplied alpha form where the r, g and b
     * values are already multiplied by the a value. If you are unable to provide colors in
     * premultiplied form you may want to change the blend function to
     * gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA).
     *
     * @param gl The map's gl context.
     * @param matrix The map's camera matrix.
     */
    render: function (gl, matrix) {}
};
 
//Add the layer to the map.
map.layers.add(new atlas.layer.WebGLLayer("layerId", { renderer: myRenderer }));

Nota

La clase WebGLLayer admite las opciones de capa minZoom, maxZoom y visible.

//Add the layer to the map with layer options. 
map.layers.add(new atlas.layer.WebGLLayer("layerId", 
    { 
        renderer: myRenderer, 
        minZoom: 10, 
        maxZoom: 22, 
        visible: true
    }
));

En este ejemplo se representa un triángulo en el mapa mediante una capa de WebGL.

Para obtener un ejemplo totalmente funcional con código fuente, consulte Capa simple de WebGL 2D en los ejemplos de Azure Maps.

La matriz de la cámara del mapa se usa para proyectar el punto de Mercator esférico en las coordenadas de gl. El punto de Mercator [0, 0] representa la esquina superior izquierda del mundo según Mercator y [1, 1] representa la esquina inferior derecha. Cuando renderingMode es "3d", la coordenada "z" es conforme. Un cuadro con longitudes "x", "y" y "z" idénticas en unidades de Mercator se representaría como un cubo.

La clase MercatorPoint tiene métodos estáticos fromPosition, fromPositions y toFloat32Array que se pueden usar para convertir una posición geoespacial en un punto de Mercator. Del mismo modo, los métodos toPosition y toPositions se pueden usar para proyectar un punto de Mercator en una posición.

Representar un modelo 3D.

Use una capa de WebGL para representar modelos 3D. En el ejemplo siguiente se muestra cómo cargar un archivo glTF y representarlo en el mapa mediante three.js.

Debe agregar los siguientes archivos de script.

<script src="https://unpkg.com/three@latest/build/three.min.js"></script>
<script src="https://unpkg.com/three@latest/examples/js/loaders/GLTFLoader.js"></script>

En este ejemplo se representa un loro en 3D animado en el mapa.

A screenshot showing an animated 3D parrot on the map.

Para obtener un ejemplo totalmente funcional con código fuente, consulte Tres capas personalizadas de WebGL en los ejemplos de Azure Maps.

La función onAdd carga un archivo .glb en memoria y crea instancias de objetos three.js, como la cámara, la escena, la luz y THREE.WebGLRenderer.

La función render calcula la matriz de proyección de la cámara y representa el modelo en la escena.

Sugerencia

Para tener una animación continua y fluida, puede desencadenar que se vuelva a pintar un solo fotograma mediante una llamada a map.triggerRepaint() en la función render.
Para habilitar el suavizado de contorno, basta con que establezca antialias en true como una de las opciones de estilo al crear el mapa.

Representación de un modelo 3D mediante babylon.js

Babylon.js es uno de los principales motores gráficos basados en WebGL del mundo. En el ejemplo siguiente se muestra cómo cargar un archivo GLTF y representarlo en el mapa mediante babylon.js.

Debe agregar los siguientes archivos de script.

<script src="https://cdn.babylonjs.com/babylon.js"></script> 
<script src="https://cdn.babylonjs.com/loaders/babylonjs.loaders.min.js"></script>

En este ejemplo se representa una torre satélite en el mapa.

La función onAdd crea una instancia de un motor BABYLON y una escena. A continuación, carga un archivo .gltf mediante BABYLON.SceneLoader.

La función render calcula la matriz de proyección de la cámara y representa el modelo en la escena.

Para obtener un ejemplo totalmente funcional con código fuente, consulte Capa webGL personalizada de Babylon en los ejemplos de Azure Maps.

Representación de una capa de deck.gl

Se puede usar una capa de WebGL para representar capas de la biblioteca de deck.gl. En el ejemplo siguiente se muestra la visualización de datos del flujo de migración de personas en Estados Unidos de un condado a otro en un intervalo de tiempo determinado.

Debe agregar el siguiente archivo de script.

<script src="https://unpkg.com/deck.gl@latest/dist.min.js"></script>

Defina una clase de capa que extienda atlas.layer.WebGLLayer.

class DeckGLLayer extends atlas.layer.WebGLLayer { 

    constructor(options) { 
        super(options.id); 

        //Create an instance of deck.gl layer 
        this._mbLayer = new deck.MapboxLayer(options); 

        //Create a renderer 
        const deckGLRenderer = { 
            renderingMode: "3d", 
            onAdd: (map, gl) => { 
               this._mbLayer.onAdd?.(map["map"], gl); 
            }, 
            onRemove: (map, gl) => { 
                this._mbLayer.onRemove?.(map["map"], gl); 
            }, 
            prerender: (gl, matrix) => { 
                this._mbLayer.prerender?.(gl, matrix); 
            }, 
            render: (gl, matrix) => { 
                this._mbLayer.render(gl, matrix); 
            } 
        }; 
        this.setOptions({ renderer: deckGLRenderer }); 
    } 
}

En este ejemplo se representa una capa de arco de la biblioteca de deck.gl.