Ajusta automáticamente la cámara a los elementos del mapa

Puedes encuadrar automáticamente marcadores, polilíneas, polígonos y rutas en 3D dentro de un viewport de <gmp-map-3d> configurando el atributo HTML autofits-camera o la propiedad autofitsCamera en los elementos secundarios compatibles. Cuando uno o más elementos secundarios habilitan la función, el mapa calcula una posición de la cámara que mantiene todos los elementos habilitados a la vista.

El ajuste automático de la cámara está disponible en el canal v=beta de la API de Maps JavaScript. Para obtener instrucciones sobre cómo cargar el canal Beta, consulta Control de versiones.

Elementos admitidos

En la siguiente tabla, se enumeran los elementos secundarios de Map3DElement que admiten autofits-camera (autofitsCamera):

Elemento HTML Clase de JavaScript Biblioteca Notas
<gmp-marker-3d>, <gmp-marker-3d-interactive> Marker3DElement, Marker3DInteractiveElement maps3d Enmarca el position del marcador.
<gmp-marker>, <gmp-marker-interactive> MarkerElement, MarkerInteractiveElement maps3d Enmarca el position del marcador.
<gmp-polyline-3d>, <gmp-polyline-3d-interactive> Polyline3DElement, Polyline3DInteractiveElement maps3d Enmarca todas las coordenadas en el path de la polilínea.
<gmp-polygon-3d>, <gmp-polygon-3d-interactive> Polygon3DElement, Polygon3DInteractiveElement maps3d Enmarca todas las coordenadas en el path del polígono.
<gmp-route-3d> Route3DElement routes Espera a que se resuelva la solicitud de ruta y, luego, enmarca la ruta de acceso.

Elementos no admitidos

Model3DElement, PopoverElement y FlattenerElement no admiten autofitsCamera. Para enmarcar esos elementos, establece center y range en <gmp-map-3d> o llama a flyCameraTo.

Ajusta la cámara en la carga inicial

Para enmarcar elementos cuando se carga el mapa, agrega el atributo autofits-camera a cada elemento secundario que desees dentro del viewport inicial. No es necesario que calcules center ni range en <gmp-map-3d>:

<gmp-map-3d
  style="height: 400px; width: 100%;"
  mode="hybrid">
  <gmp-marker-3d
    position="47.6205,-122.3493"
    title="Space Needle"
    autofits-camera>
  </gmp-marker-3d>
  <gmp-marker-3d
    position="47.6097,-122.3425"
    title="Pike Place Market"
    autofits-camera>
  </gmp-marker-3d>
  <gmp-polyline-3d
    path="47.6205,-122.3493,0 47.6097,-122.3425,0"
    stroke-color="#4285F4"
    stroke-width="8"
    altitude-mode="clamp-to-ground"
    autofits-camera>
  </gmp-polyline-3d>
</gmp-map-3d>

<script async
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&v=beta&libraries=maps3d">
</script>

Reemplaza YOUR_API_KEY por tu clave de API de Google Maps Platform.

Cómo ajustar y animar las actualizaciones dinámicas

Cuando agregas un elemento habilitado después de la carga inicial, actualizas sus coordenadas o extremos de ruta, o estableces autofitsCamera en true, el mapa vuelve a calcular la cámara para encuadrar todos los elementos habilitados. Si quitas un elemento o estableces autofitsCamera en false, la cámara se mantendrá en su posición y se excluirá ese elemento de las actualizaciones futuras.

Para controlar si las actualizaciones dinámicas se ajustan o se animan, establece autofitsCameraAnimation (autofits-camera-animation) en Map3DElement en un valor AutofitsCameraAnimation:

  • AutofitsCameraAnimation.NONE ("none", predeterminado): Se ajusta a la posición actualizada sin animación.
  • AutofitsCameraAnimation.FLY_TO ("fly-to"): Vuela sin problemas a la posición actualizada. La carga inicial del mapa se ajusta sin animación, y FLY_TO recurre a un ajuste cuando el sistema operativo del usuario solicita un movimiento reducido.

Para configurar autofitsCamera y AutofitsCameraAnimation.FLY_TO de forma programática, consulta el siguiente ejemplo:

<div id="map-container" style="height: 400px; width: 100%;"></div>

<script>
  async function initMap() {
    const {
      AutofitsCameraAnimation,
      Map3DElement,
      Marker3DElement,
      MapMode,
    } = await google.maps.importLibrary('maps3d');

    const map = new Map3DElement({
      mode: MapMode.HYBRID,
      autofitsCameraAnimation: AutofitsCameraAnimation.FLY_TO,
    });
    document.getElementById('map-container').append(map);

    const originMarker = new Marker3DElement({
      position: { lat: 37.7955, lng: -122.3937 },
      autofitsCamera: true,
    });
    map.append(originMarker);

    /* Adding a second opted-in marker flies the camera to frame both. */
    const destinationMarker = new Marker3DElement({
      position: { lat: 37.8080, lng: -122.4177 },
      autofitsCamera: true,
    });
    map.append(destinationMarker);
  }
</script>
<script async
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&v=beta&loading=async&callback=initMap">
</script>

Reemplaza YOUR_API_KEY por tu clave de API de Google Maps Platform.

Cómo interactúan las propiedades y las restricciones de la cámara

Cuando al menos un elemento secundario se habilita con autofits-camera, Map3DElement combina la configuración de tu mapa con los límites calculados según las siguientes reglas:

  • center y range: Se anulan por el encuadre calculado, que agrega un 20% de relleno de rango y aplica un rango mínimo de 80 m. Si no hay elementos secundarios habilitados que proporcionen coordenadas, el mapa usará los valores de center y range configurados como resguardo.
  • tilt y heading: Se tratan como valores sugeridos durante el encuadre. Cuando se omiten, ambos se establecen de forma predeterminada en 0° para una vista de arriba hacia abajo y con el norte hacia arriba.
  • roll y fov: Se conservan como se configuraron en Map3DElement.
  • Elementos secundarios asíncronos: Antes de renderizar la vista inicial, Map3DElement espera a que los elementos secundarios asíncronos habilitados, como <gmp-route-3d>, terminen de cargar la geometría de la ruta.
  • Restricciones de mapa y cámara: Los límites geográficos (bounds) y de cámara (minAltitude, maxAltitude, minTilt, maxTilt, minHeading y maxHeading) siguen restringiendo la vista ajustada automáticamente. Para obtener más información, consulta Cómo restringir la vista y los límites de la cámara.

Próximos pasos