Rutas de migración de KmlLayer

Introducción

El objetivo de esta guía es abarcar los usos más comunes de KmlLayer y proporcionar las rutas de migración correspondientes a implementaciones alternativas. Esta información está dirigida a los desarrolladores que deben dejar de usar KmlLayer debido a su baja programada. La última versión que admite KmlLayer es la 3.65, que se retirará en mayo de 2027.

Tu ruta de migración depende de cómo uses KmlLayer:

Archivo KML para aplicar estilo a la información de límites, fronteras o áreas de interés

Para los desarrolladores que usan KmlLayer para mostrar o diseñar límites administrativos, como destacar un país, un estado o una localidad específicos, Google Maps Platform recomienda migrar al diseño basado en datos (DDS) para límites.

Recomendación de migración: Diseño basado en datos aplicable a límites

El diseño basado en datos para límites proporciona acceso directo a los polígonos de límites administrativos de Google, lo que te permite aplicar diseños personalizados (relleno y trazo) a estas regiones sin necesidad de alojar ni administrar archivos KML externos.

FeatureType disponible

Las áreas administrativas se clasifican por función y se organizan por niveles. Se admiten los siguientes tipos de componentes para el diseño:

  • COUNTRY: Es la entidad política nacional.
  • ADMINISTRATIVE_AREA_LEVEL_1: Es una entidad civil de primer orden por debajo del nivel de país (p. ej., estados en EE.UU.).
  • ADMINISTRATIVE_AREA_LEVEL_2: Es una entidad civil de segundo orden por debajo del nivel de país (p. ej., condados en EE.UU.).
  • LOCALITY: Ciudad o pueblo constituido.
  • POSTAL_CODE: Códigos postales que se usan para el correo.
  • SCHOOL_DISTRICT: Distritos escolares unificados, primarios o secundarios.

Consulta la cobertura de límites para conocer las regiones en las que están disponibles estos tipos de componentes.

Cómo destacar un área

Para aplicar un diseño a una región específica, debes segmentarla por su ID de lugar.

Cómo restringir el desplazamiento lateral a un área

Para evitar que los usuarios naveguen fuera del cuadro delimitador del área destacada, puedes usar la opción restriction dentro de MapOptions.

El objeto restriction define un latLngBounds que limita el área visible del mapa. Consulta la documentación para obtener más detalles sobre cómo funciona la restricción.

// Restrict panning to a specific bounding box
restriction: {
  latLngBounds: {
    north: 47.8,
    south: 45.8,
    east: 10.5,
    west: 5.9,
  },
  strictBounds: true,
},

Resumen de la implementación de la migración

A continuación, se muestra un ejemplo completo de cómo usar el diseño basado en datos para límites y una restricción de región para enfocar el mapa en un área específica.

const myTargetRegion = "ChIJYW1Zb-9kjEcRFXvLDxG1Vlw"; // Place ID for Switzerland

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 46.8, lng: 8.2 },
    zoom: 9,
    mapId: "YOUR_MAP_ID", // Required for DDS
    // Restrict panning to a specific bounding box
    restriction: {
    // Bounding box for Switzerland
      latLngBounds: {
        north: 47.8,
        south: 45.8,
        east: 10.5,
        west: 5.9,
      },
      strictBounds: true,
    },
  });

  // Access the Country layer and style a specific region by Place ID
  const countryLayer = map.getFeatureLayer("COUNTRY");
  countryLayer.style = (options) => {
    if (options.feature.placeId === myTargetRegion) {
      return {
        fillColor: "#FF0000",
        fillOpacity: 0.5,
        strokeColor: "#FF0000",
        strokeWeight: 2,
      };
    } else {
    // Style everything else whited out, to make the area of interest pop out more.
      return {
        fillColor: '#ffffff',
        fillOpacity: 0.8,
      };
    }
  };
}

Archivo KML con datos vectoriales (puntos, polilíneas, límites y polígonos)

Recomendación de migración: Diseño basado en datos aplicable a conjuntos de datos

Google recomienda la siguiente ruta para mostrar datos geográficos disponibles públicamente y, al mismo tiempo, obtener más control sobre el diseño y el rendimiento.

El diseño basado en datos aplicable a conjuntos de datos te permite subir tus propios datos geoespaciales (KML, GeoJSON o CSV), aplicar diseños personalizados según los atributos de los datos y mostrar componentes en mapas de vectores.

1. Configuración y carga

A diferencia de KmlLayer, que recupera una URL en el tiempo de ejecución, DDS requiere que alojes los datos como un conjunto de datos en la consola de Google Cloud.

2. Cómo configurar la vista del puerto en los datos

KmlLayer automáticamente se desplaza y acerca la ubicación de los datos de forma predeterminada. Con DDS para conjuntos de datos, este comportamiento no es automático y debe implementarse de forma manual.

  • Restricciones codificadas: Si el área de datos es estática, usa la opción restriction en MapOptions para bloquear la ventana gráfica en límites específicos.
  • Zoom dinámico: Para establecer el viewport de forma dinámica, puedes usar map.fitBounds() con el cuadro delimitador de tu conjunto de datos.

3. Diseño a partir de atributos de entidades

Los archivos KML suelen contener información de estilo (como colores) que DDS no aplica automáticamente. Debes crear una función de diseño del cliente que lea los atributos de los componentes del conjunto de datos para aplicar colores y opacidad. Consulta la documentación para desarrolladores sobre cómo definir el diseño de tus datos para obtener todos los detalles.

Ejemplo: Cómo aplicar diseño a una función con atributos

En el siguiente ejemplo, se muestra cómo crear una función de diseño que lee los atributos background_color y opacity directamente del conjunto de datos subido:

/**
 * Migration example: Styling features from dataset attributes.
 */
function styleDDSLayer(map, datasetId) {
  const datasetLayer = map.getDatasetFeatureLayer(datasetId);

  // Set the style function
  datasetLayer.style = (params) => {
    // Access attributes defined in your KML/Dataset
    const featureAttributes = params.feature.datasetAttributes;

    // Read style values from attributes, with fallback defaults
    const fillColor = featureAttributes['background_color'] || '#4285F4';
    const fillOpacity = parseFloat(featureAttributes['opacity']) || 0.5;
    const strokeColor = featureAttributes['border_color'] || '#34A853';

    return {
      fillColor: fillColor,
      fillOpacity: fillOpacity,
      strokeColor: strokeColor,
      strokeWeight: 2,
    };
  };
}

Para obtener más detalles sobre la implementación de interacciones y el diseño, consulta la Descripción general del diseño basado en datos para conjuntos de datos y la API de Datasets para datos dinámicos.

Recomendación de migración: Renderización del cliente con GeoJSON

Para los desarrolladores que migran de KmlLayer a la renderización del cliente con GeoJSON, Google Maps Platform recomienda una ruta de migración que implica convertir tu formato de datos y usar la capa de datos para renderizar y diseñar funciones directamente en el navegador.

La renderización del cliente con la capa de datos proporciona una forma muy flexible de mostrar datos geográficos. A diferencia de KmlLayer, que se renderiza en los servidores de Google, la capa de datos te permite interactuar con las funciones como objetos JavaScript estándar. Sin embargo, ten en cuenta que, para los conjuntos de datos grandes, es posible que prefieras el procesamiento y la renderización del servidor de tus datos, como con el Diseño basado en datos para conjuntos de datos.

1. Cómo convertir archivos KML a GeoJSON

El primer paso es convertir tus archivos KML a GeoJSON. Esto se puede hacer con varias herramientas populares de código abierto:

  • ogr2ogr: Esta potente utilidad de línea de comandos, que forma parte del paquete de GDAL, puede convertir entre muchos formatos vectoriales.
ogr2ogr -f GeoJSON output.json input.kml
  • togeojson: Una herramienta pequeña y bien probada diseñada específicamente para convertir KML y GPX a GeoJSON.
togeojson input.kml > output.json

2. Cómo configurar la vista del puerto en los datos

Si bien KmlLayer automáticamente se desplaza y acerca a la ubicación de los datos, la capa de datos no lo hace. Para establecer el viewport de modo que se ajuste a tus datos de GeoJSON, debes calcular manualmente el cuadro delimitador y llamar a map.fitBounds().

3. Diseño a partir de atributos de entidades

En la capa de datos, puedes definir una función style que lea los atributos (propiedades) directamente de cada elemento GeoJSON para determinar su apariencia.

Ejemplo: Ajuste de la función de diseño y la ventana gráfica

En el siguiente ejemplo, se muestra cómo cargar datos de GeoJSON, calcular sus límites para establecer la ventana gráfica y aplicar diseño a los componentes según sus atributos:

/**
 * Migration example: Loading GeoJSON, fitting viewport, and styling from attributes.
 */
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -28, lng: 137 },
  });

  // Load the GeoJSON data
  map.data.loadGeoJson('path/to/your/data.json', null, (features) => {
    // Adjust viewport to show all loaded features
    const bounds = new google.maps.LatLngBounds();
    features.forEach((feature) => {
      feature.getGeometry().forEachLatLng((latlng) => {
        bounds.extend(latlng);
      });
    });
    map.fitBounds(bounds);
  });

  // Set the style function to read from GeoJSON properties
  map.data.setStyle((feature) => {
    // Access attributes defined in your GeoJSON properties
    const fillColor = feature.getProperty('background_color') || '#4285F4';
    const opacity = parseFloat(feature.getProperty('opacity')) || 0.5;
    const strokeColor = feature.getProperty('border_color') || '#34A853';

    return {
      fillColor: fillColor,
      fillOpacity: opacity,
      strokeColor: strokeColor,
      strokeWeight: 2,
      visible: true
    };
  });
}

Para obtener más información sobre el uso de la capa de datos, consulta la documentación sobre la importación de GeoJSON en Maps.

Ruta de migración: Renderización del cliente con bibliotecas de terceros

Para los desarrolladores que buscan otras alternativas a KmlLayer, existen varias bibliotecas mantenidas por la comunidad que renderizan datos KML en la API de Google Maps JavaScript Platform.

1. deck.gl

deck.gl es un framework de visualización de alto rendimiento potenciado por WebGL. Se puede usar como reemplazo casi directo para la renderización de KML a través de sus GoogleMapsOverlay y GeoJsonLayer.

  • Requisito de Canvas: Para usar deck.gl de manera eficaz, debes convertir tu mapa para que use el tipo de mapa de vectores (que se renderiza en un elemento de lienzo) con sus capacidades de renderización de WebGL.
  • Compatibilidad con KML: El análisis de la geometría se controla con @loaders.gl/kml, que convierte KML en GeoJSON. Ten en cuenta que algunas funciones de KML, como los estilos complejos, los íconos y los NetworkLinks, pueden requerir una implementación manual adicional.
  • Documentación: Documentación de deck.gl | Cargador de KML de loaders.gl.
  • Ejemplos:
    • El ejemplo deckgl-kml-updated del repositorio de GitHub de Google Maps muestra cómo usar deck.gl para renderizar datos KML que se actualizan en tiempo real.
    • En el ejemplo de deckgl-kml, se muestra cómo usar deck.gl para renderizar datos de KML.

2. geoxml3

geoxml3 es un procesador de KML diseñado específicamente para la API de Google Maps JavaScript v3. Analiza KML de forma local en el navegador y renderiza los datos como objetos estándar de la API de Google Maps, como marcadores, polilíneas y polígonos.

  • Compatibilidad con mapas estándar: A diferencia de las soluciones basadas en WebGL, geoxml3 funciona en los mapas estándar de la API de Maps JavaScript v3 sin necesidad de un modo de renderización específico.
  • Advertencias:
    • Compatibilidad limitada con KMZ: La biblioteca no admite archivos KMZ por completo de forma nativa. Por lo general, para descomprimir archivos KMZ, se requiere la integración con secuencias de comandos de terceros adicionales, como ZipFile.complete.js.
    • Elementos no admitidos: No se admiten funciones como geometrías 3D, etiquetas complejas y ciertos elementos KML más nuevos.
  • Documentación: Repositorio de GitHub de geoxml3

Archivo KML con elementos interactivos

Recomendación de migración: Diseño basado en datos aplicable a conjuntos de datos

Para los desarrolladores que migran de KmlLayer al Diseño basado en datos (DDS) para conjuntos de datos, esta guía explica cómo realizar la transición de las interacciones automáticas de KML a interacciones personalizadas de alto rendimiento, como clics y desplazamientos del mouse.

Configuración inicial

Antes de implementar interacciones, asegúrate de haber seguido los pasos de configuración de la guía Migración de KML: datos vectoriales:

  • ID de mapa: Configura un ID de mapa para el tipo de mapa de vectores.
  • Carga: Sube tus datos KML a la consola de Google Cloud para obtener un ID de conjunto de datos.
  • Acceso a la capa: Usa map.getDatasetFeatureLayer(datasetId) para acceder a la capa interactiva.

1. Cómo controlar eventos de interacción

En KmlLayer, la API controla automáticamente los clics en las funciones para que aparezca una ventana de información. Con DDS para conjuntos de datos, debes registrar manualmente los objetos de escucha para los eventos del mouse en la capa del conjunto de datos.

  • click: Se activa cuando un usuario hace clic en una función.
  • mousemove: Se activa cuando el cursor se mueve sobre una entidad, lo que resulta útil para los efectos de desplazamiento.

2. Diseño dinámico (efecto de desplazamiento)

Dado que los estilos de DDS se aplican de forma global a la capa, debes mantener una variable de estado para hacer un seguimiento de la función con la que se interactúa y volver a aplicar el estilo.

let currentFeatureId = null;

function initInteraction(map, datasetId) {
  const datasetLayer = map.getDatasetFeatureLayer(datasetId);

  // Apply the style function
  datasetLayer.style = (params) => {
    const isHovered = params.feature.datasetAttributes['id'] === currentFeatureId;
    return {
      strokeColor: 'green',
      strokeWeight: isHovered ? 4.0 : 2.0, // Bold border on hover
      fillColor: 'green',
      fillOpacity: isHovered ? 0.5 : 0.3,
    };
  };

  // Add interaction listeners
  datasetLayer.addListener('mousemove', (event) => {
    if (event.features.length > 0) {
      currentFeatureId = event.features[0].datasetAttributes['id'];
      datasetLayer.style = datasetLayer.style; // Re-apply style to reflect changes
    }
  });

  // Clear hover state when the mouse leaves the features
  map.addListener('mousemove', () => {
    if (currentFeatureId !== null) {
      currentFeatureId = null;
      datasetLayer.style = datasetLayer.style;
    }
  });
}

3. Cómo mostrar HTML desde el atributo description

En KML, la etiqueta <description> suele contener HTML para la ventana de información predeterminada. Cuando estos datos se importan como un conjunto de datos, el description se convierte en un atributo de la característica. Para renderizarlo, pasa la cadena directamente a un google.maps.InfoWindow estándar.

const infoWindow = new google.maps.InfoWindow();

datasetLayer.addListener('click', (event) => {
  if (event.features.length > 0) {
    const feature = event.features[0];
    // Access the HTML description attribute
    const htmlContent = feature.datasetAttributes['description'];

    infoWindow.setContent(htmlContent);
    infoWindow.setPosition(event.latLng);
    infoWindow.open(map);
  }
});

4. Ventana de información personalizada con ExtendedData

Si tu KML usa <ExtendedData> para almacenar pares clave-valor personalizados, estos se asignan a datasetAttributes. Puedes iterar estos atributos para compilar una pantalla HTML personalizada.

function createCustomContent(feature) {
  const attributes = feature.datasetAttributes;
  const container = document.createElement("div");
  container.style.padding = "10px";
  container.innerHTML = "<h3>Feature Details</h3><dl></dl>";

  const dl = container.querySelector("dl");

  // Iterate through all data attributes imported from KML ExtendedData
  for (const key in attributes) {
    const dt = document.createElement("dt");
    dt.style.fontWeight = "bold";
    dt.textContent = key;

    const dd = document.createElement("dd");
    dd.textContent = attributes[key];

    dl.appendChild(dt);
    dl.appendChild(dd);
  }
  return container;
}

datasetLayer.addListener('click', (event) => {
  if (event.features.length > 0) {
    const content = createCustomContent(event.features[0]);
    infoWindow.setContent(content);
    infoWindow.setPosition(event.latLng);
    infoWindow.open(map);
  }
});

Para conocer técnicas de visualización más avanzadas, consulta la documentación para desarrolladores sobre cómo aplicar estilo a los datos.

Recomendación de migración: Renderización del cliente con GeoJSON

Para los desarrolladores que migran de KmlLayer a la renderización del cliente con GeoJSON y la capa de datos, esta guía explica cómo realizar la transición de las interacciones automáticas de KML a las interacciones personalizadas basadas en eventos y al diseño dinámico.

Configuración inicial

Antes de implementar interacciones, debes convertir tus datos de KML a GeoJSON y cargarlos en la capa de datos. Consulta la guía Recomendación de migración: Renderización del cliente con GeoJSON para obtener detalles sobre el uso de herramientas como ogr2ogr o togeojson y la inicialización del mapa con map.data.loadGeoJson().

1. Interacciones automáticas frente a interacciones manuales

Una diferencia clave entre estas capas es cómo controlan la entrada del usuario:

  • KmlLayer: Controla automáticamente los clics en los elementos y muestra un objeto InfoWindow que contiene los datos de y en formato KML.
  • Capa de datos: No muestra objetos InfoWindow automáticamente. Debes agregar manualmente agentes de escucha de eventos para capturar las interacciones del usuario y escribir código para mostrar los datos.

2. Cómo controlar eventos de interacción

Para que los componentes de GeoJSON sean interactivos, usa el método addListener() en el objeto map.data. Los eventos comunes incluyen los siguientes:

  • click: Se usa para activar ventanas de información o lógica de selección.
  • mouseover / mouseout: Se usa para efectos de desplazamiento y resaltado.

3. Cómo mostrar descripciones en HTML en una ventana de información

Cuando se convierte KML a GeoJSON, la etiqueta <description> (que suele contener HTML) se asigna a una propiedad llamada description. Puedes usar feature.getProperty('description') para recuperar esta cadena y renderizarla dentro de un google.maps.InfoWindow estándar.

const infoWindow = new google.maps.InfoWindow();

// Handle clicks to show the HTML description
map.data.addListener('click', (event) => {
  // Access the 'description' property from the GeoJSON feature
  const htmlContent = event.feature.getProperty('description');

  if (htmlContent) {
    infoWindow.setContent(htmlContent);
    infoWindow.setPosition(event.latLng);
    infoWindow.open(map);
  }
});

4. Ventanas de información personalizadas y ExtendedData

Si tu KML original utilizaba <ExtendedData>, estos pares nombre-valor se convierten en propiedades de GeoJSON. Como la capa de datos no tiene una IU predeterminada para estos elementos, debes implementar una ventana de información personalizada para iterar por ellos y mostrarlos.

Puedes acceder a estos atributos con event.feature.getProperty('attribute_name') y crear una cadena HTML personalizada o un elemento DOM para pasar al método infoWindow.setContent().

5. Diseño dinámico (efectos de desplazamiento)

La capa de datos te permite actualizar los diseños de las funciones de forma programática en respuesta a eventos. Usa overrideStyle() para cambiar temporalmente la apariencia de una función (p.ej., al colocar el cursor sobre ella) y revertStyle() para volver al diseño global.

// Set a base style for all features
map.data.setStyle({
  fillColor: 'blue',
  strokeWeight: 1
});

// Highlight feature on mouseover
map.data.addListener('mouseover', (event) => {
  map.data.revertStyle(); // Clear previous highlights
  map.data.overrideStyle(event.feature, {strokeWeight: 8});
});

// Revert style on mouseout
map.data.addListener('mouseout', (event) => {
  map.data.revertStyle();
});

Para obtener detalles de implementación más específicos, consulta la documentación sobre Capa de datos: Control de eventos y Capa de datos: Diseño dinámico.

Ruta de migración: Renderización del cliente con bibliotecas de terceros

Para los desarrolladores que migran de KmlLayer a soluciones de terceros, esta guía se enfoca en el manejo de datos interactivos, como los clics del mouse y los eventos dinámicos, con deck.gl y geoxml3.

Configuración inicial

Antes de implementar interacciones, asegúrate de haber seguido los pasos de configuración de la guía Ruta de migración: Renderización del cliente con bibliotecas de terceros. Esto incluye lo siguiente:

  • deck.gl: Convierte tu mapa para usar el tipo de mapa de vectores (requisito de lienzo).
  • geoxml3: Publica los secuencias de comandos de la biblioteca desde tu propio host y administra el uso compartido de recursos entre dominios (CORS).

1. Datos interactivos con deck.gl

deck.gl admite KML como formato de entrada directa y controla automáticamente las interacciones de funciones, como los clics, según los datos proporcionados en el archivo KML.

  • Controlador de KMLLoader: Con el módulo @loaders.gl/kml, la geometría y las propiedades se analizan en un formato que deck.gl usa para activar eventos de interacción de forma nativa.
  • Clics en funciones: Cuando se hace clic en una función, deck.gl puede capturar el evento y mostrar los metadatos asociados (como <name> o <description>).
  • Ejemplo: La muestra deckgl-kml-updated demuestra la renderización de KML en tiempo real, en la que, al colocar el cursor sobre los marcadores de terremotos, se muestra información detallada del evento.

2. Datos interactivos con geoxml3

geoxml3 analiza el KML de forma local en el navegador, extrae la información de estilo y genera objetos estándar de la API de Google Maps que conservan su interactividad.

  • Extracción de estilo nativo: La biblioteca toma los elementos <Style> y <StyleMap> del KML para aplicarlos a los marcadores, las polilíneas y los polígonos generados.
  • Controladores de clics: De forma predeterminada, geoxml3 proporciona controladores de clics para estos objetos. También puedes definir funciones de devolución de llamada personalizadas (createMarker, createOverlay) durante la creación de instancias del analizador para implementar tu propia lógica de selección o actualizaciones de la barra lateral.
  • Ejemplo: En este ejemplo, se muestra cómo usar geoxml3 para renderizar KML, con personalizaciones como marcadores de círculos con interacción, como hacer clic en los marcadores para mostrar información sobre terremotos.
  • Patrón de uso:
var myParser = new geoXML3.parser({
  map: map,
  processStyles: true, // Automatically handle KML styles
  afterParse: function(doc) {
    // Code to run after the KML is fully parsed
  }
});
myParser.parse('interactive_data.kml');

Archivo KML con imágenes

Para los desarrolladores que usan KmlLayer para mostrar imágenes, como mapas con datos derivados de satélites, patrones climáticos o planos históricos, esta guía describe las rutas de migración a GroundOverlays o analizadores de terceros.

Recomendación de migración: GroundOverlay de la API de Maps JavaScript

La ruta recomendada para migrar imágenes es usar la clase google.maps.GroundOverlay. Esto te permite colocar una imagen en el mapa en coordenadas geográficas específicas directamente en tu código.

1. Implementación

En lugar de depender de un archivo KML para definir los límites, debes especificar la URL de la imagen y un objeto LatLngBounds que represente el rectángulo en el mapa.

  • Documentación: Guía de superposiciones de suelo.
  • Preparación de la imagen: Si tu imagen está georreferenciada, pero no en la proyección correcta (EPSG:4326), puedes usar la herramienta de código abierto gdalwarp para deformar la imagen y usarla con la API de Maps JavaScript.
gdalwarp -t_srs EPSG:4326 image.jp2 image.jpg

Ruta de migración: Uso de bibliotecas de terceros

Si tu flujo de trabajo requiere que conserves tus datos en formato KML, puedes usar bibliotecas de terceros, como geoxml3 o deck.gl, para renderizar superposiciones de imágenes.

Renuncia de responsabilidad: Google no admite estas soluciones de terceros. Sin embargo, se probaron y deberían funcionar para la mayoría de los casos de uso.

1. geoxml3

geoxml3 es una buena opción para analizar elementos GroundOverlay simples de forma local en el navegador y convertirlos en objetos de la API de Google Maps.

Ejemplo de uso:

const geoXmlParser = new geoXML3.parser({
    map: map,
    afterParse: function(doc) {
        console.log("Parsing complete. Number of documents: " + doc.length);
        const bounds = doc[0].gbounds;
        if (bounds && !bounds.isEmpty()) {
           map.fitBounds(bounds);
        }
    },
    createOverlay: function(groundOverlayData) {
        // Extract bounds and URL from parsed KML data
        const imageUrl = groundOverlayData.icon.href;
        const imageBounds = {
            north: parseFloat(groundOverlayData.latLonBox.north),
            south: parseFloat(groundOverlayData.latLonBox.south),
            east: parseFloat(groundOverlayData.latLonBox.east),
            west: parseFloat(groundOverlayData.latLonBox.west)
        };

        // Create the Google Maps GroundOverlay
        const nativeOverlay = new google.maps.GroundOverlay(imageUrl, imageBounds);
        nativeOverlay.setMap(map);
    }
});
geoXmlParser.parse('your_file.kml');

2. deck.gl

Si bien el GeoJsonLayer estándar de deck.gl controla los datos vectoriales, también puede admitir GroundOverlays a través de una implementación manual con BitmapLayer.

Este enfoque implica aprovechar KMLLoader para analizar el archivo y, luego, definir de forma explícita un BitmapLayer con la URL y las coordenadas de la imagen extraídas de los datos de KML.

  • Requisito: Para usar deck.gl, se requiere un tipo de mapa de vectores.
  • Documentación: BitmapLayer de deck.gl

Caso avanzado: Pirámides de mosaicos con gdal2tiles

En el caso de los archivos KML complejos que contienen pirámides de mosaicos de imágenes, la migración es más difícil y requiere la extracción de los datos de imágenes.

  • Herramienta: gdal2tiles puede extraer datos de una pirámide KMZ y generar código estándar de la API de Maps JavaScript para mostrar las segmentaciones. Ten en cuenta que el resultado final puede requerir modificaciones manuales para incorporarse a un mapa existente.
gdal2tiles -z 10- -n -u https://yourhost.com/tiles/ -w google input.kmz

El manejo de archivos KML con vínculos de red requiere un cambio del proceso automático de recuperación de KmlLayer del lado de la nube a estrategias de administración de datos más explícitas.

Solución admitida: Diseño basado en datos (DDS) para conjuntos de datos

Dado que los conjuntos de datos de Google Maps Platform no analizan de forma nativa los elementos <NetworkLink>, debes elegir una estrategia de migración según la estructura de tus datos:

  • Estrategia A: Conjuntos de datos distintos (ideal para capas controladas por el usuario) Sube cada archivo KML que antes era una vinculación de red como su propio conjunto de datos individual en la consola de Google Cloud. Luego, puedes usar JavaScript para cargar y mostrar dinámicamente estas capas cuando sea necesario llamando a map.getDatasetFeatureLayer(datasetId) y ajustando su visibilidad o estilo.
  • Estrategia B: Archivo KML aplanado (ideal para una visualización de alto rendimiento) Combina todas las entidades de tus diversos archivos vinculados a la red en un solo archivo KML integral antes de subirlo como un conjunto de datos. Luego, puedes usar el diseño dinámico basado en atributos de entidades para filtrar y mostrar subconjuntos de datos específicos sobre la marcha.

Actualización de datos dinámicos: Para imitar el comportamiento de "actualización automática" de los vínculos de red, usa la API de Datasets para subir de forma programática una nueva versión de tu conjunto de datos cada vez que cambien los datos de origen.

Soluciones de código abierto: deck.gl y geoxml3

Ni deck.gl ni geoxml3 proporcionan una compatibilidad sólida para analizar y recuperar automáticamente los elementos <NetworkLink> de KML.

deck.gl

deck.gl utiliza KMLLoader (creado en togeojson), que no admite NetworkLinks de forma explícita.

  • Por qué no es una buena solución: El analizador está diseñado para ser un convertidor síncrono y "sin complicaciones" que evita realizar sus propias solicitudes de red para garantizar la confiabilidad y la simplicidad. Si tu aplicación depende de archivos KML que apuntan a varias URLs, deck.gl no las resolverá automáticamente.

geoxml3

Si bien geoxml3 se desarrolló para analizar KML para la API de Maps JS, su compatibilidad con los vínculos de red es experimental y no se mantiene.

  • Por qué no es una buena solución: La funcionalidad solo existe en una rama "network_link" específica que es antigua y no está bien probada. No se recomienda usar esta opción para la migración de datos de producción, ya que es posible que no pueda controlar estructuras de vínculos complejas o requisitos de seguridad modernos, como CORS.

Recomendación de resumen

Para una migración confiable, los desarrolladores deben evitar los analizadores de terceros para los archivos con vínculos de red y, en su lugar, reconstruir la lógica de recuperación de datos con la API de Datasets. Esto garantiza que tus datos se administren de forma segura dentro de la infraestructura de Google Maps Platform en lugar de depender de analizadores del cliente sin mantenimiento.

Cómo usar KML para mostrar superposiciones de pantalla

Para los desarrolladores que migran de KmlLayer a alternativas modernas, como el diseño basado en datos (DDS), es importante tener en cuenta que las superposiciones de pantalla no se admiten en los conjuntos de datos. Para lograr el mismo efecto de mostrar imágenes, logotipos o leyendas fijos sobre el mapa, debes crear controles personalizados con la API de Maps JavaScript.

1. Qué buscar en tu archivo KML

Para compilar un control personalizado equivalente, examina el elemento <ScreenOverlay> en tu archivo KML en busca de los siguientes atributos clave:

  • <Icon>&lt;href>: Es la URL de la imagen que deseas mostrar.
  • <screenXY>: Define dónde se posiciona la superposición en la pantalla.
    • x=0, y=1 (fracciones) corresponde a la esquina superior izquierda.
    • x=1, y=1 corresponde a la posición Superior derecha.
    • x=0, y=0 corresponde a la posición inferior izquierda.
    • x=1, y=0 corresponde a la posición Inferior derecha.
  • <size>: Define el ancho y la altura de la superposición.
  • <rotation>: Indica si se debe rotar la imagen.

2. Implementación: Cómo crear un control personalizado

Un control personalizado es, básicamente, un elemento HTML estándar (como <div> o <img>) que "insertas" en una de las posiciones predefinidas del mapa.

Cómo asignar posiciones de KML a ControlPosition

La API de Maps JavaScript usa la enumeración ControlPosition para anclar controles. Usa la siguiente tabla para asignar tu <screenXY> de KML a la constante de la API de JS adecuada:

Posición KML (screenXY) API de JS ControlPosition
Arriba a la izquierda (x:0, y:1) TOP_LEFT (heredado) o BLOCK_START_INLINE_START (lógico)
Esquina superior derecha (x:1, y:1) TOP_RIGHT o BLOCK_START_INLINE_END
Esquina inferior izquierda (x:0, y:0) BOTTOM_LEFT o BLOCK_END_INLINE_START
Inferior derecha (x:1, y:0) BOTTOM_RIGHT o BLOCK_END_INLINE_END

3. Ejemplo de migración: Superposición de logotipo fijo

En el siguiente ejemplo, se simula un logotipo de ScreenOverlay de KML ubicado en la esquina superior derecha del mapa.

Aplicación de estilos de CSS

Usa CSS para definir el tamaño y la apariencia de tu "superposición".

#logo-control {
  padding: 10px;
  background-color: rgba(255, 255, 255, 0.8);
  margin: 10px;
  border-radius: 2px;
  box-shadow: 0 1px 4px rgba(0,0,0,0.3);
}

#logo-control img {
  width: 150px; /* Equivalent to KML <size> */
  display: block;
}

Implementación de JavaScript

Agrega el elemento al array map.controls.

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 12,
    center: { lat: 41.85, lng: -87.65 },
  });

  // 1. Create the container for the overlay
  const logoControlDiv = document.createElement("div");
  logoControlDiv.id = "logo-control";

  // 2. Create the image (KML <Icon>)
  const logoImage = document.createElement("img");
  logoImage.src = "https://example.com/logo.png";
  logoImage.alt = "Company Logo";

  logoControlDiv.appendChild(logoImage);

  // 3. Position the control (KML <screenXY>)
  // In this case, we use TOP_RIGHT
  map.controls[google.maps.ControlPosition.TOP_RIGHT].push(logoControlDiv);
}

Más información