Meratyn

Manual/Referencia

Primeros pasos

Meratyn es la plataforma SIG ligera y cloud-native de Meratyn. Actualmente se desarrolla y se despliega localmente; este repositorio no publica ninguna aplicación alojada oficial ni versión en un almacén de paquetes.

Esta página le ayuda a empezar a usar Meratyn. Si desea ejecutarlo desde el código fuente con fines de desarrollo, vaya directamente a Ejecutar desde el código fuente más abajo.

Uso de Meratyn

Elija la opción que mejor se ajuste a su forma de trabajar. La misma aplicación se distribuye en cada formato, de modo que los proyectos y los archivos .meratyn.json se mueven entre ellos.

En un navegador

Ejecute bun run dev y abra https://mappview.mapptech.com.co. La compilación para navegador conserva los datos locales en la sesión del navegador y procesa en el cliente los flujos de trabajo compatibles.

Instrucciones de compilación local{ .md-button .md-button—primary }

Puede cargar datos vectoriales seleccionados en el navegador y admitidos por DuckDB-WASM Spatial, arrastrar rásteres GeoTIFF/COG sobre el mapa, añadir servicios y conjuntos de datos basados en URL (XYZ, WMS, GeoJSON, teselas vectoriales, COG, ArcGIS, FlatGeobuf, PMTiles, Zarr, LiDAR y Gaussian splats), dar estilo a las capas, probar plugins y abrir o guardar proyectos con un selector o una descarga del navegador. Los diálogos nativos y las rutas recordadas, los MBTiles locales y la lectura local de archivos ráster necesitan la aplicación de escritorio.

En el escritorio

La aplicación de escritorio añade diálogos nativos con rutas recordadas, MBTiles locales y lectura local de archivos ráster. Abrir y guardar proyectos también funciona en el navegador mediante un selector y una descarga. Ejecute el escritorio localmente con bun run tauri:dev.

Descargar la aplicación de escritorio{ .md-button .md-button—primary }

En Jupyter

El paquete Python meratyn incrusta la aplicación completa de Meratyn en un notebook de Jupyter y controla el mapa mediante una API ampliada al estilo leafmap que se sincroniza en ambos sentidos, de modo que las ediciones hechas en la interfaz se pueden leer de vuelta desde Python.

pip install -e ./python

El paquete se instala desde este checkout; el repositorio no publica ningún paquete en PyPI ni en conda. Hay extras opcionales para las utilidades respaldadas por GeoPandas disponibles con pip install "meratyn[all]".

Consulte la referencia del Paquete Python para empezar.

En Android

Meratyn se distribuye también como aplicación Android nativa construida a partir del mismo código base, con una disposición táctil responsiva para teléfonos. Consulte Android para los detalles de instalación.

Ejecutar desde el código fuente

Esta sección está dirigida a desarrolladores que quieren clonar Meratyn y ejecutarlo desde el código fuente localmente con fines de desarrollo. La mayoría de los usuarios no la necesita. Meratyn es un monorepo de workspaces npm: la aplicación principal vive en apps/mappview y se compila con Tauri, React, TypeScript y MapLibre GL JS.

Requisitos previos

  • Bun 1.4.2 o más reciente
  • Cadena de herramientas de Rust para las compilaciones de escritorio
  • Dependencias de compilación de escritorio Linux de los requisitos previos de Tauri v2

Instalación

git clone <repository-url>
cd Meratyn
bun install

Los usuarios de Bun pueden ejecutar bun install. La lista trustedDependencies de la raíz permite los scripts de instalación conocidos de core-js, @google/genai, esbuild, protobufjs, sharp y workerd.

Actualización

Para actualizar un checkout existente del código fuente a la versión más reciente, extraiga los cambios, reinstale las dependencias (por si cambió package.json) y recompile:

cd /path/to/Meratyn   # your Meratyn checkout
git pull origin main
bun install

Si compila una versión de producción, recompile después con bun run build (web) o bun run tauri:build (escritorio). Si trabaja con los servidores de desarrollo (bun run dev o bun run tauri:dev), el git pull y el bun install anteriores bastan — solo reinicie el servidor de desarrollo para recoger los cambios.

Ejecutar la interfaz de navegador

bun run dev

Abra https://mappview.mapptech.com.co. El mapa y la importación vectorial del navegador admiten archivos vectoriales locales que DuckDB-WASM Spatial puede leer, con manejo directo de GeoJSON, Shapefiles comprimidos y archivos KMZ. Use Add Vector Layer o arrastre archivos sobre la aplicación; los rásteres GeoTIFF/COG también pueden arrastrarse al mapa para añadirlos como capas ráster. La interfaz de navegador también puede añadir servicios y conjuntos de datos basados en URL tales como XYZ, WMS, URLs de GeoJSON, teselas vectoriales, rásteres COG, servicios ArcGIS, FlatGeobuf, PMTiles, Zarr, LiDAR y Gaussian splats.

Los diálogos nativos y las rutas recordadas, los MBTiles locales, la lectura local de archivos ráster y otras operaciones del sistema de archivos de escritorio requieren Tauri. Abrir y guardar proyectos también funciona en el navegador mediante un selector y una descarga alternativa.

Ejecución con Docker

El repositorio incluye un Dockerfile para la versión de navegador de Meratyn. Compila la aplicación Vite y sirve los archivos de producción con nginx:

docker build -t mapptech/mappview:local .
docker run --rm -p 8080:80 mapptech/mappview:local

Abra https://mappview.mapptech.com.co. La interfaz de navegador contenerizada incluye abrir y guardar proyectos en el navegador; los diálogos nativos y las rutas recordadas, los MBTiles locales, la lectura local de archivos ráster y otras funciones exclusivas de Tauri requieren la aplicación de escritorio.

Sidecar de conversión incluido

La imagen también incluye el sidecar Python (uvicorn) y lo expone mediante proxy inverso en /sidecar, de modo que el navegador lo alcanza en el mismo origen sin CORS ni un proceso separado que gestionar. /conversion/status está accesible en https://mappview.mapptech.com.co/sidecar/conversion/status.

Para las entradas y herramientas compatibles, la compilación de navegador ejecuta Conversion y la caja de herramientas Whitebox en el cliente sobre DuckDB-WASM y @mappview/wasm. El sidecar incluido añade rutas a archivos nativos, conversiones y herramientas Whitebox fuera de los motores del navegador, además de:

  • Las Raster tools (rasterio), que tienen una alternativa en el cliente para las herramientas principales pero alcanzan el conjunto completo a través del sidecar.
  • El motor opcional GeoPandas para las Vector tools, que de otro modo se ejecutan en el cliente sobre Turf.js o Pyodide.

Los trabajos del sidecar leen y escriben rutas del propio sistema de archivos del sidecar — un navegador no puede entregarle al contenedor una ruta absoluta del host — y esas lecturas y escrituras están confinadas a MAPPVIEW_CONVERSION_ROOTS (por defecto /data en la imagen). Monte sus archivos ahí:

docker run --rm -p 8080:80 -v "$PWD/data:/data" mapptech/mappview:local

Las conexiones PostGIS del sidecar están deshabilitadas por separado en despliegues compartidos hasta que MAPPVIEW_POSTGIS_HOSTS liste los hosts de bases de datos permitidos (opcionalmente con puertos). La aplicación de escritorio sigue sin restricciones por defecto porque su sidecar está ligado a loopback y autenticado por token.

freestiler y whitebox-workflows no publican wheels linux/arm64, así que se instalan solo en amd64; en arm64 el sidecar reporta esas herramientas no disponibles. Esto no afecta a los motores propios de PMTiles y Whitebox del navegador, que son WebAssembly y se ejecutan en cualquier arquitectura.

Defina MAPPVIEW_DISABLE_SIDECAR=1 para ejecutar solo nginx (comportamiento solo web):

docker run --rm -p 8080:80 -e MAPPVIEW_DISABLE_SIDECAR=1 mapptech/mappview:local

Protección con contraseña (opcional)

Para exigir un usuario y una contraseña, defina MAPPVIEW_AUTH_USER y MAPPVIEW_AUTH_PASSWORD; nginx protege entonces la aplicación y la API /sidecar con HTTP Basic Auth (una credencial compartida única). Combínelo con un proxy inverso que termina TLS fuera de las redes de confianza:

docker run --rm -p 8080:80 \
  -e MAPPVIEW_AUTH_USER=admin \
  -e MAPPVIEW_AUTH_PASSWORD='change-me' \
  mapptech/mappview:local

Para permitir que los usuarios autenticados accedan al proxy de IA gestionado sin exponer su token de servidor, dirija las peticiones de IA a través de la misma instancia de nginx:

export MAPPVIEW_AI_PROXY_TOKEN="$(openssl rand -hex 32)"

# Run the edge service (@mappview/edge-service), which reads the token at boot
cd services/edge
MAPPVIEW_AI_PROXY_TOKEN="$MAPPVIEW_AI_PROXY_TOKEN" bun start
cd ../..

docker run --rm -p 8080:80 \
  -e MAPPVIEW_AUTH_USER=admin \
  -e MAPPVIEW_AUTH_PASSWORD='change-me' \
  -e MAPPVIEW_AI_URL=/ai \
  -e MAPPVIEW_AI_MODEL=openai/gpt-5.6-luna \
  -e MAPPVIEW_AI_PROXY_URL=http://host.docker.internal:8791 \
  -e MAPPVIEW_AI_PROXY_TOKEN="$MAPPVIEW_AI_PROXY_TOKEN" \
  mapptech/mappview:local

El token del proxy debe coincidir con la variable de entorno MAPPVIEW_AI_PROXY_TOKEN con la que se inició el servicio edge (services/edge/src/server.ts la lee al arrancar). nginx la inyecta en el lado del servidor y nunca aparece en la configuración del frontend. Las llamadas de inferencia directas al proxy configurado sin el token devuelven 401. Si MAPPVIEW_AI_URL no está definida, la imagen deja el proxy gestionado deshabilitado. Use HTTPS y prefiera un --env-file o un gestor de secretos.

Habilitar el proxy no restringe por sí solo quién puede usarlo: quien alcance /ai en el contenedor consume contra sus cuentas del proveedor de IA. Defina MAPPVIEW_AUTH_USER/MAPPVIEW_AUTH_PASSWORD como arriba, o ponga su propia autenticación delante, antes de exponer una instancia con IA habilitada. Si un proxy TLS está delante del contenedor, liste su dirección en MAPPVIEW_TRUSTED_PROXIES (una lista de IPs o CIDRs separados por comas) para que el límite de peticiones por cliente vea al cliente real en lugar de contar a cada usuario como el proxy.

El navegador solicita las credenciales en la primera visita. /healthz permanece sin autenticación para que la comprobación de salud del contenedor siga funcionando. Cuando las variables no están definidas (el valor por defecto), no se aplica ninguna autenticación.

Como con cualquier variable de entorno de Docker, una contraseña pasada con -e queda en el historial de su shell y es legible en el host vía docker inspect. Más allá de pruebas locales rápidas, prefiera --env-file con un archivo de permisos restringidos, o un gestor de secretos.

Basic Auth es una credencial compartida única, no cuentas por usuario, y envía credenciales con cada petición. Para necesidades multiusuario o de SSO, ponga delante de la imagen sin modificar un proxy de autenticación como oauth2-proxy o Authelia. Vea también la nota en docker/nginx.conf sobre retirar las excepciones CSP de localhost antes de exponer la imagen públicamente.

Argumentos de compilación de subruta y onboarding

Para despliegues bajo una subruta de URL, pase la base de la aplicación en tiempo de compilación:

docker build --build-arg MAPPVIEW_APP_BASE=/mappview/ -t mappview .

El contenedor siempre sirve la aplicación desde su ruta raíz. El argumento de compilación solo fija el prefijo de URL que la aplicación espera, de modo que los despliegues en subruta requieren además un proxy inverso delante del contenedor que retire el prefijo antes de reenviar las peticiones (por ejemplo, nginx proxy_pass http://mappview/; con barra final).

Para omitir el asistente de bienvenida del primer arranque para cada visitante (despliegues tipo kiosco o integrados), incluya VITE_WELCOME_DISABLED=1 de forma permanente en la compilación:

docker build --build-arg VITE_WELCOME_DISABLED=1 -t mappview .

Los enlaces individuales también pueden desactivarlo en tiempo de ejecución con ?welcome=0. Consulte Incrustación y uso compartido.

Controlar un mapa incrustado desde una página anfitriona

Para permitir que una página que enmarca la aplicación dialogue con el mapa vivo por postMessage (volar a un registro, resaltar un elemento, abrir una herramienta de procesamiento, y recibir eventos de selección, vista y herramienta), liste los orígenes de confianza:

docker run --rm -p 8080:80 \
  -e MAPPVIEW_EMBED_ORIGINS="https://portal.example.com" \
  mapptech/mappview:local

Sin definir (el valor por defecto) la API permanece apagada, de modo que un despliegue público jamás puede ser controlado por quien lo enmarque. Consulte Hablar con el mapa en tiempo de ejecución para la referencia de mensajes y un ejemplo de página anfitriona.

Ejecutar la aplicación de escritorio

bun run tauri:dev

Compilar

bun run build
bun run tauri:build

La compilación de escritorio por defecto mantiene pequeño el binario de Linux y usa DuckDB-WASM para las funciones respaldadas por DuckDB en el navegador. Para compilar un binario de escritorio mayor con el cargador vectorial nativo duckdb-rs habilitado, ejecute:

bun run tauri:build:native-duckdb

Dónde encontrar la salida:

  • Compilación web — archivos estáticos en apps/mappview/dist/. Sirva este directorio con cualquier servidor web estático (o con la imagen Docker anterior).
  • Instaladores de escritorio — apps/mappview/src-tauri/target/release/bundle/, con subcarpetas por plataforma: deb/, rpm/ y appimage/ en Linux; msi/ y nsis/ en Windows; dmg/ y macos/ en macOS. El ejecutable sin empaquetar está en apps/mappview/src-tauri/target/release/. En Linux, bun run tauri:build compila deb y rpm por defecto; pasar --bundles sustituye esa selección por defecto en lugar de añadirla, de modo que enumere todos los formatos que quiera, por ejemplo bun run tauri:build -- --bundles deb,rpm,appimage para los tres.

Credenciales opcionales de imágenes

El plugin Street View puede usar imágenes de Google Street View y Mapillary. El panel 3D Tiles también puede cargar Google Photorealistic 3D Tiles con la misma clave de Google Maps. Cree apps/mappview/.env.local y defina una o ambas credenciales de proveedor:

VITE_GOOGLE_MAPS_API_KEY=your_google_maps_api_key
VITE_MAPILLARY_ACCESS_TOKEN=your_mapillary_access_token

Para Google Street View, habilite la Maps Embed API para esa clave en Google Cloud. Para Google Photorealistic 3D Tiles, habilite la Map Tiles API. Para pruebas locales en shell, la compilación de escritorio con Vite también acepta GOOGLE_MAPS_API_KEY. Para Mapillary, cree una aplicación en el panel de desarrollador de Mapillary y use su token de acceso de cliente.

Reinicie bun run dev o bun run tauri:dev después de cambiar las variables de entorno.

Credenciales opcionales de mapas base

El diálogo New map ofrece mapas base de Protomaps (Light, Dark, White, Grayscale, Black) cuando hay configurada una clave de API de Protomaps. Sin clave estas opciones están ocultas, y puede seguir usando los mapas base de OpenFreeMap o una URL de estilo personalizada.

Use su propia clave — créela en el panel de Protomaps. Défela de dos maneras:

  • Para su propio despliegue — incorpórela a la compilación con la variable de entorno VITE_PROTOMAPS_API_KEY, por ejemplo en apps/mappview/.env.local:

    VITE_PROTOMAPS_API_KEY=your_protomaps_api_key

    Para una compilación gestionada, pásela como variable de entorno de tiempo de compilación. La URL de estilo resultante es https://api.protomaps.com/styles/v5/<flavor>/en.json?key=<your_key>.

  • En tiempo de ejecución, sin recompilar — añada una variable de entorno llamada VITE_PROTOMAPS_API_KEY en Settings → Environment Variables. Los mapas base de Protomaps aparecen tan pronto como se habilita la clave. Consulte Configuración.

Superposiciones de tráfico opcionales

El control Basemaps incluye una categoría Traffic con superposiciones de tráfico en tiempo real que se apilan sobre cualquier mapa base (active el conmutador de añadir/múltiple del panel). Cada proveedor se autentica con su propia clave de API, definida en Settings → Environment Variables (o incorporada a apps/mappview/.env.local):

VITE_GOOGLE_MAPS_API_KEY=your_google_maps_api_key   # Google Traffic (Map Tiles API)
VITE_TOMTOM_API_KEY=your_tomtom_api_key             # TomTom Traffic Flow
VITE_HERE_API_KEY=your_here_api_key                 # HERE Traffic Flow

Google Traffic y Google Photorealistic 3D Tiles reutilizan la misma VITE_GOOGLE_MAPS_API_KEY que Street View; habilite la Map Tiles API para esa clave en Google Cloud. Una clave recién introducida surte efecto de inmediato, sin reabrir el proyecto. Hasta que la clave de un proveedor esté definida, su superposición reporta un error de clave ausente en lugar de cargar teselas.

Estilos opcionales de Amazon Location

Las entradas Amazon Location del control Basemaps son mapas base de estilo (reemplazan todo el estilo del mapa, a diferencia de las superposiciones de tráfico anteriores). Se autentican con su propia clave de API de Amazon Location, definida en Settings → Environment Variables (o incorporada a apps/mappview/.env.local):

VITE_AMAZON_LOCATION_API_KEY=your_amazon_location_api_key   # Amazon Location styles
VITE_AMAZON_LOCATION_AWS_REGION=us-east-1                   # optional; omit to use the control's built-in default region

Mapas base opcionales de Protomaps y Stadia Maps

El control Basemaps también incluye mapas base de estilo Protomaps y Stadia Maps (incluido Stadia x Stamen). Ambos se autentican con su propia clave:

VITE_PROTOMAPS_API_KEY=your_protomaps_api_key   # same key as the New map dialog's Protomaps basemaps
VITE_STADIA_API_KEY=your_stadia_api_key         # https://client.stadiamaps.com

Protomaps reutiliza la clave descrita en Credenciales opcionales de mapas base más arriba — défila una vez y ambos lugares la recogen. Hasta que cada clave esté definida, el panel muestra un mensaje “Get a … API key” en lugar del mapa base, sin cargar teselas.

Las claves definidas vía Settings → Environment Variables, o tecleadas directamente en la vista API keys del panel (el botón de clave en la cabecera del panel), se aplican en tiempo de ejecución sin reabrir el proyecto. Una clave incorporada a apps/mappview/.env.local se lee en tiempo de compilación y necesita reiniciar el servidor de desarrollo. Cuando VITE_AMAZON_LOCATION_API_KEY está definida en el entorno tiene precedencia sobre una clave tecleada en el panel; quitarla del entorno la borra en la siguiente recarga de página.

Credenciales opcionales del globo 3D (Cesium Ion)

La vista opcional del globo 3D de Cesium — un globo en panel dividido renderizado con CesiumJS junto al mapa 2D de MapLibre — necesita un token de acceso de Cesium Ion para sus imágenes mundiales y su terreno. Cree una cuenta gratuita de Ion, copie su token de acceso por defecto y déselo a la compilación:

CESIUM_TOKEN=your_cesium_ion_access_token

CESIUM_TOKEN (o la variante con prefijo VITE_, VITE_CESIUM_TOKEN) la lee vite.config.ts y queda incorporada a la compilación. También puede definirla en tiempo de ejecución — sin recompilar — en la sección Environment Variables del diálogo de Settings, que tiene un campo dedicado y enmascarado Cesium Ion token. Ese token se guarda localmente en el dispositivo (en el almacenamiento del navegador en la compilación web), no en el archivo de proyecto compartido, y sobrescribe el valor de compilación; es la manera en que un usuario web aporta su propio token de Ion. (Una variable libre VITE_CESIUM_TOKEN en la misma sección también funciona y tiene precedencia, como anulación.) Sin token de ninguna fuente, el conmutador del globo 3D se oculta por completo (el mapa 2D no se ve afectado). Los tokens de acceso de Ion están diseñados para viajar dentro de los bundles del cliente. Consulte Arquitectura para saber cómo se integra el globo.

Espejos opcionales en tiempo de ejecución (sin conexión y aislados de la red)

El motor vectorial Python (Pyodide) carga su runtime del CDN público jsDelivr por defecto. Para alojarlo usted mismo para uso sin conexión o en producción, apúntelo a una copia espejo de la distribución de Pyodide:

VITE_PYODIDE_INDEX_URL=https://your-host/pyodide/v0.27.7/full/

De forma similar, la extensión Spatial de DuckDB se instala por defecto desde el repositorio remoto de extensiones de DuckDB. Para cargarla desde un espejo (de modo que INSTALL spatial se omita y la extensión se cargue directamente), defina la ruta o URL completa del archivo de extensión:

VITE_DUCKDB_SPATIAL_EXTENSION_PATH=https://your-host/duckdb/spatial.duckdb_extension.wasm

Ambas variables también pueden definirse en tiempo de ejecución a través de las variables de entorno del diálogo de Settings (sin necesidad de recompilar), de modo que los despliegues aislados de la red o corporativos pueden apuntar Pyodide y la extensión DuckDB Spatial a espejos internos sin recompilar.

Sidecar Python opcional

El sidecar FastAPI opcional está reservado para flujos de trabajo de procesamiento más pesados y no es necesario para la interfaz de escritorio.

cd services/server
python -m venv .venv
source .venv/bin/activate
pip install -e "."
uvicorn sidecar.app.main:app --host 127.0.0.1 --port 8765

El sidecar autoconfigura un runtime gestionado en el primer uso; defina MAPPVIEW_CONVERSION_PYTHON=$(which python) para reutilizar en su lugar el entorno actual. Consulte el README del sidecar (services/server/README.md) para más detalles.

Extras opcionales

La instalación base es deliberadamente pequeña. Cada grupo de herramientas tiene su propio extra; instale solo los que necesite y luego ejecute mappview-server (o el comando uvicorn anterior). Estos comandos continúan desde services/server, el directorio al que cambia el fragmento anterior:

# Conversion tools (DuckDB, rio-cogeo, freestiler)
pip install -e ".[conversion]"

# Vector tools — GeoPandas engine (GeoPandas, Shapely)
pip install -e ".[vector]"

# Raster tools (rasterio, numpy, contourpy)
pip install -e ".[raster]"

# Proxy de segmentación IA (cliente HTTP ligero; los modelos usan el runtime separado)
pip install -e ".[ml]"

# Runtime SamGeo/SAM3 gestionado por el operador (Python 3.12+, entorno separado)
pip install -e ".[samgeo-runtime]"

El extra [ml] mantiene ligero el sidecar y no instala PyTorch ni archivos de modelos. Ejecute samgeo-api desde el entorno Python 3.12 o posterior con una compilación compatible de PyTorch. El extra [samgeo-runtime] fija segment-geospatial[api,samgeo3]==1.4.2; defina luego MAPPVIEW_ML_SAMGEO_URL en el entorno del sidecar. Después de aportar los pesos y aceptar sus condiciones, defina MAPPVIEW_ML_SAMGEO_WEIGHTS_CONFIGURED=1 y MAPPVIEW_ML_SAMGEO_LICENSE_ACCEPTED=1. Meratyn nunca guarda esos pesos, credenciales ni confirmaciones en un archivo de proyecto. Consulte Segmentación IA para el límite completo.

Desde la raíz del repositorio, use en cambio la ruta completa — por ejemplo pip install -e "services/server[conversion]".

Para usar el sidecar desde la compilación web, inícielo y sirva la aplicación desde localhost:5173 — CORS está restringido a ese origen y a los orígenes de Tauri. Donde una herramienta tiene motor de navegador (todas las Vector tools y las conversiones GeoParquet/CSV), el diálogo retrocede a él automáticamente cuando el sidecar o su extra no está disponible. Consulte Herramientas de procesamiento para saber qué hace cada motor, y Segmentación IA para el servidor de modelos samgeo-api independiente.