Documentación / Core / Cálculos en la Tierra

Cálculos en la Tierra (Spherical)

Proporcionamos cálculos geográficos como distancia, azimut, área e interpolación con los mismos nombres y resultados en 3 plataformas. Al no depender de utilidades de cada SDK de mapas, los valores no cambian al cambiar de proveedor. La detección de toques y el trazado de rutas de gran círculo dentro del SDK también utilizan este cálculo.

ELLIPSOID

WGS84

SEMI-MAJOR

6,378,137 m

FLATTENING

1 / 298.257…

UNIT

Metros / Grados

Ver demoPolígono geodésico · React ↗

Plataforma

01 · Cálculos básicos

Las funciones de uso común están agrupadas en Spherical. Las distancias se devuelven en metros, los azimuts en grados con el norte verdadero como 0, y las áreas en metros cuadrados. Los argumentos son las coordenadas mismas y no dependen de la proyección ni del zoom.

Función

Descripción

computeDistanceBetween

Distancia entre dos puntos (metros).

computeHeading

Azimut desde el punto de inicio hasta el punto final (-180 a 180 grados).

computeOffset

Coordenada especificada desde el punto de inicio con una distancia y un azimut. Se usa para generar círculos y anillos.

computeOffsetOrigin

Calcula el punto de inicio a partir del punto final, la distancia y el azimut.

computeLength

Longitud total a lo largo de una secuencia de coordenadas (metros). Para mostrar la distancia de una ruta.

computeArea / computeSignedArea

Área encerrada por una secuencia de coordenadas cerrada (metros cuadrados). Los valores con signo se pueden usar para determinar la dirección de rotación.

interpolate

Interpola linealmente entre dos puntos a lo largo de una ruta de gran círculo.

Planar.interpolate

Interpola proporcionalmente entre dos puntos en una línea recta de latitud/longitud (método del modelo Planar). También cruza por el lado más corto si cruza la línea de cambio de fecha.

com.mapconductor.core.spherical

val meters = Spherical.computeDistanceBetween(from, to)
val heading = Spherical.computeHeading(from, to)

// Coloca los marcadores del borde del círculo en ocho direcciones
val ring = (0 until 8).map { i ->
    Spherical.computeOffset(center, 3_000.0, i * 45.0)
}

val routeMeters = Spherical.computeLength(routePoints)
val areaSqMeters = Spherical.computeArea(polygonPoints)

MapConductorCore · spherical

let meters = Spherical.computeDistanceBetween(from: from, to: to)
let heading = Spherical.computeHeading(from: from, to: to)

let ring = (0..<8).map { i in
    Spherical.computeOffset(origin: center, distance: 3_000.0, heading: Double(i) * 45.0)
}

let routeMeters = Spherical.computeLength(routePoints)

@mapconductor/js-sdk-core

import { computeDistanceBetween, computeOffset, computeLength } from '@mapconductor/js-sdk-core';

const meters = computeDistanceBetween(from, to);

// Un anillo a 3 km del centro, cada 45 grados
const ring = Array.from({ length: 8 }, (_, i) =>
  computeOffset({ origin: center, distance: 3000, heading: i * 45 }));

const routeMeters = computeLength(routePoints);

02 · Modelo esférico y modelo elipsoidal

Para cálculos geográficos hay dos niveles de precisión: el modelo esférico que trata la Tierra como una esfera perfecta, y el modelo geodésico que la trata como el elipsoide WGS84. Se elige según el uso.

Las constantes de ambos se basan en WGS84 (radio ecuatorial 6,378,137 m, aplanamiento 1/298.257223563). Como las 3 plataformas usan las mismas constantes y fórmulas, la misma entrada devuelve el mismo valor.

Spherical

Modelo esférico (lo suficientemente rápido, lo suficientemente preciso)

Usos: visualización de distancia · azimut · generación de anillos · área · detección de toques

Distancia por haversine, azimut e interpolación por trigonometría esférica. Hasta unos cientos de km el error es prácticamente despreciable y el costo computacional es bajo.

WGS84Geodesic

Modelo elipsoidal (geodésica)

Usos: rutas de vuelo de larga distancia · distancia, azimut y área de alta precisión

Calcula la geodésica sobre el elipsoide WGS84 (solución iterativa tipo Vincenty). Dado que tiene la misma estructura de métodos que Spherical, se puede intercambiar sin cambiar la llamada: para esferas use Spherical, para WGS84 use WGS84Geodesic. El área se obtiene mediante authalic (elipsoide).

FALLBACK

Si no converge, vuelve al modelo esférico

La solución iterativa del elipsoide puede no converger, por ejemplo, para dos puntos casi antipodales. En esos casos cambia automáticamente al resultado del modelo esférico, por lo que nunca se devuelve 0 ni NaN. No es necesario escribir manejo de excepciones en el lado que invoca.

03 · Puente con la pantalla

Funciones que convierten cantidades basadas en pantalla como "un dedo" o "16px de margen" en distancias geográficas. Incluyen conversión según el zoom y la latitud, por lo que la sensación no cambia aunque cambie la ampliación o el lugar.

calculateMetersPerPixel

Metros por píxel en un zoom y latitud dados.

expandBounds

Expande un área rectangular hacia afuera en metros. Útil cuando se desean tomar datos un poco más amplios que el rango visible.

Figura · Flujo utilizado en la detección de toques

Convierte el valor de configuración «tamaño del dedo» (unidades lógicas) a píxeles de pantalla.

Con calculateMetersPerPixel, convierte a distancia de tolerancia (metros) con el zoom y la latitud actuales.

Usa esa distancia de tolerancia para determinar si se tocan líneas o formas, manteniendo las coordenadas geográficas.

Gracias a este flujo, la facilidad para pulsar líneas no cambia al hacer zoom y la detección es la misma en cualquier proveedor.

04 · Cálculos para líneas y formas

Funciones para que el dibujo y detección de polilíneas y polígonos arrojen los mismos resultados con cualquier proveedor. Se publican las mismas funciones que se usan internamente en el SDK.

Función

Descripción

WGS84Geodesic.createInterpolatePoints

Interpola coordenadas por tramo a lo largo de la línea geodésica. Crea una secuencia de coordenadas para motores que no pueden dibujar curvas directamente.

Planar.createInterpolatePoints

Interpola coordenadas a lo largo de una línea recta de latitud y longitud. El nombre es el mismo, solo difiere el espacio de nombres.

WGS84Geodesic.pointOnLineOrNull

Devuelve el punto más cercano dentro de la distancia especificada para un segmento de línea en la línea geodésica. Se usa para la detección de toques en curvas.

Planar.pointOnLineOrNull

Determina si está dentro de la distancia especificada para un segmento de línea recta.

splitByMeridian

Divide una secuencia de coordenadas que cruza el meridiano de 180 grados en el límite. Es una función de nivel superior que no pertenece a ningún espacio de nombres.

closestPointOnSegment

Encuentra el punto más cercano en un segmento de línea. Esta también es una función de nivel superior.

createInterpolatePoints y pointOnLineOrNull están disponibles con el mismo nombre tanto en WGS84Geodesic como en Planar. La persona que llama puede cambiar entre el modelo de línea geodésica y el modelo de línea recta simplemente reemplazando el espacio de nombres.

CONSISTENCY

La misma entrada da el mismo resultado

Las implementaciones en Kotlin, Swift y TypeScript están escritas con las mismas fórmulas y usan las mismas constantes. No hay discrepancias en las distancias o áreas que se muestran entre plataformas.

PUBLIC API

Utilizable también desde las apps

Las funciones de cálculo central no son internas: son API públicas. Se pueden usar directamente en la lógica de la app, como para mostrar distancias de ruta, calcular radios o hacer detección de toques personalizada. Todas las funciones listadas en esta página están disponibles en las 3 plataformas.