DEV Community

Cover image for Cómo desplegar QuickMapServices, el catálogo abierto de geoservicios, en una aplicación personal
claudio matko
claudio matko

Posted on Edited on

Cómo desplegar QuickMapServices, el catálogo abierto de geoservicios, en una aplicación personal

#qms #gis #nextgis #webmap

QuickMapServices (QMS) es un catálogo abierto y colaborativo de geoservicios. Este recurso vino a resolver nada más ni nada menos que la búsqueda de geoservicios.

Entre sus principales beneficios, se puede destacar la exploración de servicios disponibles, la visualización de capas de vista previa, la posibilidad de verificar metadatos y licencias de los servicios, la posibilidad de aportar nuevos servicios y la integración con aplicaciones personalizadas.

Este recurso, que ya cuenta con entidad propia, es el alma del conocido plugin de QGIS que lleva el mismo nombre. Es el plugin más popular de QGIS, superando las 12 millones de descargas.

Pero por qué es tan importante QMS?, se puede decir que su valor yace en que los mapas base dan rápidamente contexto geográfico a cualquier proyecto GIS. El uso de estos servicios conlleva un valor agregado muy importante. Por tanto, contar con un mecanismo apoyado en un inventario que instantáneamente lleve al contexto de QGIS un catálogo inmenso de estos servicios, presupone ya mismo una gran ventaja. Aunque, como veremos a continuación, no es la única.

Con más de 11 años de edad, este catálogo concentra hoy +1000 servicios y en su evolución cuenta con importantes actualizaciones que facilitan la búsqueda y la contribución de geoservicios.

Una nueva vista del catálogo basada en mapas, que integra búsqueda directa, filtrado por tipo de servicio (TMS, Vector Tiles, WMS, WFS o GeoJSON) y previsualización en tiempo real en una única interfaz para comparar capas con OpenStreetMap y la compatibilidad con servicios de teselas vectoriales, que ofrecen información más nítida en todos los niveles de zoom y apariencia personalizable.

Además, los usuarios ya pueden añadir sus propios servicios de teselas vectoriales a este catálogo colaborativo, cuyo valor reside en las contribuciones de la comunidad geoespacial y cuya API pública permite integrarlo en aplicaciones GIS de escritorio, web y móviles.

Si no lo conocías ya, ahora sabés de qué se trata QMS, conocés algo de su historia y por qué se transformó en el plugin más popular de QGIS. Pero este artículo trata sobre algo más.

A continuación repasaremos los pasos para ensayar el despliegue de QMS en una aplicación personal, con el objetivo de tener una experiencia interactiva de integración. Siguiendo estos pasos podrás replicar lo necesario para empezar a integrar QMS en tus aplicaciones.

Todas las indicaciones están preparadas para ser ejecutadas en la distribución Ubuntu de GNU/Linux. Es el sistema operativo que se ha sabido ganar, no solo su espacio entre usuarios de escritorio, sino también, un lugar muy especial entre usuarios de servidores.

En este punto es oportuno destacar también que, este artículo se basa en la documentación oficial de NextGIS, creadores de QMS. En code.nextgis.com, podés hallar todo lo necesario para programar, dentro del ecosistema de software. Para el caso de QMS, existe una API y tres bibliotecas: Leaflet, MapLibre, OpenLayers. Para el caso específico del ejemplo la podés hallar haciendo clic acá.

QMS integración en cualquier lugar

En 5 pasos:

Comencemos!

1. Instalar Node.js

Node.js es un entorno de ejecución de JavaScript de código abierto y multiplataforma. Es una herramienta popular para casi cualquier tipo de proyecto. Con esta herramienta se ejecuta el motor JavaScript V8, fuera del navegador. Esto permite que Node.js tenga un rendimiento muy alto. A continuación copia el código para instalar Node 18 o superior.

sudo apt update
sudo apt install -y curl
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
Enter fullscreen mode Exit fullscreen mode

Cerrá y abrí la terminal y después:

nvm install 20
node -v    # debe mostrar v20.x
Enter fullscreen mode Exit fullscreen mode

2. Crear un proyecto (versión Leaflet)

Para este ejemplo decidí utilizar Leaflet, pero podés incursionar con OpenLayers o MapLibre también. Hacia el final te doy las indicaciones.

A continuación, lo que vas a hacer es crear la carpeta ~/qms-demo, los tres archivos, instalar las dependencias y arrancar el servidor.

Prepara un directorio de trabajo limpio, una carpeta vacía como directorio actual.

rm -rf ~/qms-demo && mkdir -p ~/qms-demo && cd ~/qms-demo
Enter fullscreen mode Exit fullscreen mode

Crea el archivo index.html, es el esqueleto de la demo. El archivo generado es una página HTML mínima, carga un script de módulo main.js donde irá la lógica del mapa con QMS.

cat > index.html <<'EOF'
<!doctype html>
<html lang="es">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Demo QMS</title>
    <style>
      html, body { margin: 0; height: 100%; }
      #map { width: 100%; height: 100vh; }
    </style>
  </head>
  <body>
    <div id="map"></div>
    <script type="module" src="/main.js"></script>
  </body>
</html>
EOF
Enter fullscreen mode Exit fullscreen mode

Crea un archivo main.js que inicializa un mapa Leaflet con una capa del catálogo QuickMapServices y un control para cambiar entre mapas base del catálogo QMS. En .setView([-34.6, -58.4], 11), podés configurar la vista de la zona de interés que querés que se visualice al iniciar. Para este ejemplo utilicé la localidad de Buenos Aires [-34.6, -58.4]. Si no sabés cuál es exactamente la posición de la localidad de interés, existen muchos recursos para hallarla, uno de ellos es epsg.io

cat > main.js <<'EOF'
import { map as createMap } from 'leaflet';
import 'leaflet/dist/leaflet.css';
import '@nextgis/qms-leaflet/lib/qms-leaflet.css';
import { addQmsLayer, createQmsControl } from '@nextgis/qms-leaflet';

async function init() {
  const map = createMap('map').setView([-34.6, -58.4], 11);
  await addQmsLayer(map, 448);
  map.addControl(createQmsControl({ initialLayer: 448, position: 'topright' }));
}

init().catch(console.error);
EOF
Enter fullscreen mode Exit fullscreen mode

Crea el archivo package.json en el directorio actual. Define el proyecto qms-demo e incluye: scripts, dependencias, Vite como servidor de desarrollo y empaquetador.

cat > package.json <<'EOF'
{
  "name": "qms-demo",
  "private": true,
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite --host",
    "build": "vite build"
  },
  "dependencies": {
    "@nextgis/qms-leaflet": "latest",
    "leaflet": "latest"
  },
  "devDependencies": {
    "vite": "latest"
  }
}
EOF
Enter fullscreen mode Exit fullscreen mode

Instala todas las dependencias declaradas en package.json. Si la instalación tiene éxito (&&), arranca el servidor de desarrollo de Vite (npm run dev), que sirve la demo con recarga en caliente para poder verla en el navegador.

npm install && npm run dev
Enter fullscreen mode Exit fullscreen mode

3. Despliegue y visualización

Abrí la URL que figura en tu terminal, en este ejemplo http://localhost:5174/ ó http://192.168.0.3:5174/

  VITE v8.3.7  ready in 195 ms

  ➜  Local:   http://localhost:5174/
  ➜  Network: http://192.168.0.3:5174/  wlp4s0
  ➜  press h + enter to show help
Enter fullscreen mode Exit fullscreen mode

Verás localmente en el entorno de tu red, el mapa de tu zona de interés con el control de búsqueda de QMS arriba a la derecha.

pc

Ya tenés en tu propia aplicación QMS integrado!

Ahora podés desplegar el menú de QMS y buscar cualquiera de los servicios integrados al catálogo para visualizar en la aplicación.

gif

Para volver a ejecutarlo, después de cerrar la terminal, no te olvides de ejecutar:

cd ~/qms-demo && npm run dev
Enter fullscreen mode Exit fullscreen mode

Si querés compartir la visualización rápidamente, con un colega fuera de tu red, existen varios caminos. A continuación te propongo uno de ellos.

Para evitar riesgos lógicos de seguridad de tu red, lo que te propongo a continuación es construir un túnel, para que por él salga la visualización de tu aplicación fuera de tu red.

Es importante destacar que esto es temporal, por lo tanto, solo tendrá efecto en el momento en que lo ejecutes y perderá validez cuando termines la sesión de la terminal.

4. Compartir el mapa con QMS integrado por Cloudflare Tunnel

En solo 3 pasos:

Instalá Cloudflared

Cloudflare actúa como intermediario entre los usuarios e internet para acelerar y proteger servicios web.

cd /tmp
curl -L -o cloudflared.deb https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared.deb
Enter fullscreen mode Exit fullscreen mode

Configurar Vite para aceptar el túnel

Vite es una herramienta de compilación para proyectos web modernos, diseñada para ofrecer una experiencia de desarrollo mucho más rápida y ágil.

Genera un archivo de configuración de Vite listo para servir la aplicación en red y a través de un túnel de Cloudflare. Ejecutá lo siguiente en la terminal:

cd ~/qms-demo
cat > vite.config.js <<'EOF'
export default {
  server: {
    host: true,
    port: 5174,
    strictPort: true,
    allowedHosts: ['.trycloudflare.com'],
  },
};
EOF
Enter fullscreen mode Exit fullscreen mode

Recordá verificar que el puerto al que estás apuntando sea el correcto. Para este ejemplo es 5174. En caso de tener inconvenientes con esto, verificá con:

curl -I http://localhost:5174
Enter fullscreen mode Exit fullscreen mode

Si devuelve HTTP/1.1 200 OK, Vite está en orden, si por el contrario dice Failed to connect, Vite no está corriendo o está en otro puerto. Para remediarlo levantá el túnel apuntando al puerto correcto, para saber cuál es el puerto donde está escuchando Vite ejecutá:

ss -ltnp | grep node
Enter fullscreen mode Exit fullscreen mode

Levantá el visualizador y el túnel

Inicia el servidor de desarrollo del proyecto en ~/qms-demo, que sirve el visualizador en tu máquina. Es decir, pone la aplicación a correr localmente. Debido a que el túnel será temporal, vas a necesitar para este caso, correr dos terminales simultáneamente: una para la aplicación local, Terminal 1 y otra para el túnel, Terminal 2, que te permitirá compartir la aplicación fuera de tu red.

Terminal 1

cd ~/qms-demo
npm run dev
Enter fullscreen mode Exit fullscreen mode

Crea un túnel de Cloudflare que expone ese servidor local a Internet mediante una URL pública temporal. Así, personas fuera de tu red pueden acceder a tu visualizador sin necesidad de configurar puertos, firewall ni DNS.

Terminal 2

cloudflared tunnel --url http://localhost:5174
Enter fullscreen mode Exit fullscreen mode

Importante, reemplazá http://localhost:5174, por tu dirección, la que obtuviste anteriormente

Al ejecutar Cloudflared, vas a recibir en unos instantes una URL en tu terminal. Esa es la URL que podés compartir con quien quieras dar acceso al túnel. El aspecto de la URL será semejante a https://algo-como-esto.trycloudflare.com

Ahora podés pedir a tus colegas, fuera de tu red, que te den su opinión respecto a tu trabajo, podés verificar cómo se visualiza tu aplicación y si requiere de algún ajuste adicional.

También podés probar cómo se ve desde tu teléfono móvil:

movil

Buscá el servicio que más te guste.

5. Cambiar a OpenLayers o MapLibre

Como lo adelanté al principio, esta guía cuenta con un ejemplo basado en Leaflet, aunque si querés probar con Openlayers o MapLibre, te dejo a continuación, las instrucciones para que sigas adelante. Es importante destacar que el index.html no cambia, solo hay que reemplazar el contenido de main.js y las dependencias del package.json:

OpenLayers:

Info oficial de NextGIS, clic acá

cd ~/qms-demo
npm uninstall leaflet @nextgis/qms-leaflet
npm install ol @nextgis/qms-ol
Enter fullscreen mode Exit fullscreen mode 
// main.js
import Map from 'ol/Map';
import View from 'ol/View';
import { fromLonLat } from 'ol/proj';
import 'ol/ol.css';
import '@nextgis/qms-ol/lib/qms-ol.css';
import { addQmsLayer, createQmsControl } from '@nextgis/qms-ol';

async function init() {
  const map = new Map({
    target: 'map',
    view: new View({ center: fromLonLat([-58.4, -34.6]), zoom: 11 }),
  });
  await addQmsLayer(map, 448);
  map.addControl(createQmsControl({ initialLayer: 448 }));
}

init().catch(console.error);
Enter fullscreen mode Exit fullscreen mode

MapLibre GL:

Info oficial de NextGIS, clic acá


cd ~/qms-demo
npm uninstall leaflet @nextgis/qms-leaflet
npm install maplibre-gl @nextgis/qms-maplibre-gl
Enter fullscreen mode Exit fullscreen mode 
// main.js
import { Map, NavigationControl } from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
import '@nextgis/qms-maplibre-gl/lib/qms-maplibre-gl.css';
import { addQmsLayer, createQmsControl } from '@nextgis/qms-maplibre-gl';

const map = new Map({
  container: 'map',
  style: { version: 8, sources: {}, layers: [] },
  center: [-58.4, -34.6],
  zoom: 10,
});

map.addControl(new NavigationControl(), 'top-right');

map.once('load', () => {
  addQmsLayer(map, 448).catch(console.error);
  map.addControl(createQmsControl({ initialLayer: 448 }), 'top-left');
});
Enter fullscreen mode Exit fullscreen mode

Pensamientos finales

A lo largo de este artículo exploramos cómo QuickMapServices puede trascender su rol como plugin de QGIS para convertirse en una pieza clave dentro de aplicaciones geoespaciales personalizadas.

Partiendo de la documentación oficial de NextGIS, recorrimos un camino que va desde la instalación de Node.js hasta el despliegue de un visor interactivo con Leaflet, presentando la posibilidad de compartir nuestro desarrollo mediante un túnel temporal con Cloudflare y culminando con la posibilidad de continuar la integración con OpenLayers y MapLibre GL.

Este recorrido demuestra que QMS no es solo un catálogo de servicios, sino una puerta de entrada para que desarrolladores y usuarios avanzados puedan incorporar capas base y servicios WMS/WMTS de manera sencilla y estandarizada en sus propios proyectos.

La versatilidad de las tres bibliotecas presentadas (Leaflet, OpenLayers y MapLibre GL) permite adaptar la solución a distintos contextos, desde prototipos rápidos hasta aplicaciones de alto rendimiento con renderizado vectorial.

El ejemplo práctico evidencia que con pocas líneas de código y una estructura mínima de archivos es posible tener un mapa funcional con el control de búsqueda de QMS integrado, sin necesidad de infraestructura compleja.

Este artículo buscó no solo mostrar cómo hacerlo, sino también inspirar a explorar las posibilidades que se abren al integrar QMS en aplicaciones propias. La invitación queda hecha: experimentar, adaptar los ejemplos a otras regiones o necesidades y aprovechar el ecosistema abierto que QMS y las bibliotecas, nos ofrecen. La geoinformación al alcance de todos.

Top comments (0)

⌂ 换网址