geolib
v3.3.4
Biblioteca para fornecer operações geoespaciais básicas como cálculo de distância, conversão de coordenadas decimais em sexagesimal e vice -versa, etc. Esta biblioteca é atualmente em 2D , o que significa que a altitude/elevação ainda não é suportada por nenhuma de suas funções!
Um Changelog detalhado pode ser encontrado em Changelog.md
npm install geolibyarn add geolibHá uma compilação UMD e uma construção do módulo ES . Você pode usar a construção da UMD no nó como qualquer outra biblioteca:
const geolib = require ( 'geolib' ) ;ou no navegador usando um elemento de script simples:
< script src =" lib/geolib.js " > </ script > Se você o carregar no navegador, poderá acessar todas as funções via window.geolib .
Se você está trabalhando com um empacotador (como webpack ou parcela) ou possui um ambiente que suporta módulos ES, você pode importar determinadas funções do pacote diretamente:
import { getDistance } from 'geolib' ;ou carregar toda a biblioteca:
import * as geolib from 'geolib' ;Ou você pode importar funções únicas diretamente para fazer o uso de tresidores (recomendados):
import getDistance from 'geolib/es/getDistance' ; Esta biblioteca está escrita no TypeScript. Você não precisa conhecer o TypeScript para usar o geolib, mas as definições de tipo fornecem informações valiosas sobre o uso geral, os parâmetros de entrada etc.
Todos os métodos que estão trabalhando com coordenadas aceitam um objeto com uma propriedade lat / latitude e uma lon / lng / longitude , ou uma matriz de coordenadas de Geojson, como: [lon, lat] . Todos os valores podem estar em formato decimal ( 53.471 ) ou sexagesimal ( 53° 21' 16" ).
Os valores de distância são sempre flutuantes e representam a distância nos metros .
getDistance(start, end, accuracy = 1)Calcula a distância entre duas coordenadas GEO.
Esta função leva até 3 argumentos. Os primeiros 2 argumentos devem ser GeolibInputCoordinates válidas (por exemplo {latitude: 52.518611, longitude: 13.408056} ). As coordenadas podem estar em formato sexagesimal ou decimal. O terceiro argumento é a precisão (em metros). Por padrão, a precisão é de 1 metro. Se você precisar de um resultado mais preciso, poderá defini -lo com um valor mais baixo, por exemplo, para 0.01 para precisão do centímetro. Você pode definir mais alto para ter o resultado arredondado para o próximo valor divisível pela precisão escolhida (por exemplo, 25428 com uma precisão de 100 se torna 25400 ).
getDistance (
{ latitude : 51.5103 , longitude : 7.49347 } ,
{ latitude : "51° 31' N" , longitude : "7° 28' E" }
) ; // Working with W3C Geolocation API
navigator . geolocation . getCurrentPosition (
( position ) => {
console . log (
'You are ' ,
geolib . getDistance ( position . coords , {
latitude : 51.525 ,
longitude : 7.4575 ,
} ) ,
'meters away from 51.525, 7.4575'
) ;
} ,
( ) => {
alert ( 'Position could not be determined.' ) ;
}
) ;Retorna a distância nos medidores como um valor numérico.
getPreciseDistance(start, end, accuracy = 1) Calcula a distância entre duas coordenadas GEO. Esse método é mais preciso do que getDistance , especialmente para longas distâncias, mas também é mais lento. Está usando a fórmula inversa de Vincentos para elipsóides.
São necessários os mesmos argumentos (até 3) como getDistance .
geolib . getPreciseDistance (
{ latitude : 51.5103 , longitude : 7.49347 } ,
{ latitude : "51° 31' N" , longitude : "7° 28' E" }
) ;getCenter(coords)Calcula o centro geográfico de todos os pontos em uma coleção de coordenadas geográficas. Pega uma variedade de coordenadas e calcula o centro dela.
geolib . getCenter ( [
{ latitude : 52.516272 , longitude : 13.377722 } ,
{ latitude : 51.515 , longitude : 7.453619 } ,
{ latitude : 51.503333 , longitude : - 0.119722 } ,
] ) ;Retorna um objeto:
{
"latitude" : centerLat ,
"longitude" : centerLon
}getCenterOfBounds(coords)Calcula o centro dos limites das coordenadas geográficas.
Pega uma variedade de coordenadas, calcule a borda dessas e retribua o centro desse retângulo.
Em polígonos como fronteiras políticas (por exemplo, estados), isso pode dar um resultado mais próximo à expectativa humana do que getCenter , porque essa função pode ser perturbada pela distribuição desigual de pontos em lados diferentes.
Imagine o Estado dos EUA Oklahoma: getCenter , que dá um ponto do sul, porque a fronteira sul contém muito mais nós do que os outros.
geolib . getCenterOfBounds ( [
{ latitude : 51.513357512 , longitude : 7.45574331 } ,
{ latitude : 51.515400598 , longitude : 7.45518541 } ,
{ latitude : 51.516241842 , longitude : 7.456494328 } ,
{ latitude : 51.516722545 , longitude : 7.459863183 } ,
{ latitude : 51.517443592 , longitude : 7.463232037 } ,
] ) ;Retorna um objeto:
{
"latitude" : centerLat ,
"longitude" : centerLng
}getBounds(points)Calcula os limites das coordenadas geográficas.
geolib . getBounds ( [
{ latitude : 52.516272 , longitude : 13.377722 } ,
{ latitude : 51.515 , longitude : 7.453619 } ,
{ latitude : 51.503333 , longitude : - 0.119722 } ,
] ) ;Retorna a latitude mínima e máxima e a longitude mínima e máxima como objeto:
{
"minLat" : minimumLatitude ,
"maxLat" : maximumLatitude ,
"minLng" : minimumLongitude ,
"maxLng" : maximumLongitude ,
}isPointInPolygon(point, polygon)Verifica se um ponto está dentro de um polígono ou não.
geolib . isPointInPolygon ( { latitude : 51.5125 , longitude : 7.485 } , [
{ latitude : 51.5 , longitude : 7.4 } ,
{ latitude : 51.555 , longitude : 7.4 } ,
{ latitude : 51.555 , longitude : 7.625 } ,
{ latitude : 51.5125 , longitude : 7.625 } ,
] ) ; Retorna true ou false
isPointWithinRadius(point, centerPoint, radius)Verifica se um ponto está dentro de um círculo ou não.
// checks if 51.525/7.4575 is within a radius of 5 km from 51.5175/7.4678
geolib . isPointWithinRadius (
{ latitude : 51.525 , longitude : 7.4575 } ,
{ latitude : 51.5175 , longitude : 7.4678 } ,
5000
) ; Retorna true ou false
getRhumbLineBearing(origin, destination)Obtém rolamentos da linha rosa de dois pontos. Descubra a diferença entre a linha do rinquinho e o grande círculo rolando na Wikipedia. A linha de rumbinho deve estar bem na maioria dos casos:
http://en.wikipedia.org/wiki/rhumb_line#general_and_mathematical_description
A função é fortemente baseada na grande versão do PHP de Doug Vanderweide (licenciada no GPL 3.0) http://www.dougv.com/2009/07/13/calculating-the-bearing-and-compass-sose-direction-bet------mwo--latititude-------uply--bearing-compass-sose-direction-bet-wo--latitude-----longo---tear---compass--direction-between-two--latititude--longitude-coordinates-flos
geolib . getRhumbLineBearing (
{ latitude : 52.518611 , longitude : 13.408056 } ,
{ latitude : 51.519475 , longitude : 7.46694444 }
) ;Retornos rolamentos calculados como número.
getGreatCircleBearing(origin, destination)Recebe um grande rolamento de círculo de dois pontos. Isso é mais preciso que o rolamento da linha de rumbis, mas também mais lento.
geolib . getGreatCircleBearing (
{ latitude : 52.518611 , longitude : 13.408056 } ,
{ latitude : 51.519475 , longitude : 7.46694444 }
) ;Retornos rolamentos calculados como número.
getCompassDirection(origin, destination, bearingFunction = getRhumbLineBearing) Receba a direção da bússola de uma coordenada de origem para uma coordenada de destino. Opcionalmente, uma função para determinar o rolamento pode ser passada como terceiro parâmetro. O padrão é getRhumbLineBearing .
geolib . getCompassDirection (
{ latitude : 52.518611 , longitude : 13.408056 } ,
{ latitude : 51.519475 , longitude : 7.46694444 }
) ; Retorna a direção (por NNE , SW , E ,…) como string.
orderByDistance(point, arrayOfPoints)Classifica uma variedade de coordenados por distância de uma coordenada de referência.
geolib . orderByDistance ( { latitude : 51.515 , longitude : 7.453619 } , [
{ latitude : 52.516272 , longitude : 13.377722 } ,
{ latitude : 51.518 , longitude : 7.45425 } ,
{ latitude : 51.503333 , longitude : - 0.119722 } ,
] ) ;Retorna uma variedade de pontos ordenados pela distância ao ponto de referência.
findNearest(point, arrayOfPoints) Encontra o único ponto mais próximo de uma coordenada de referência. Na verdade, é apenas um método de conveniência que usa orderByDistance sob o capô e retorna o primeiro resultado.
geolib . findNearest ( { latitude : 52.456221 , longitude : 12.63128 } , [
{ latitude : 52.516272 , longitude : 13.377722 } ,
{ latitude : 51.515 , longitude : 7.453619 } ,
{ latitude : 51.503333 , longitude : - 0.119722 } ,
{ latitude : 55.751667 , longitude : 37.617778 } ,
{ latitude : 48.8583 , longitude : 2.2945 } ,
{ latitude : 59.3275 , longitude : 18.0675 } ,
{ latitude : 59.916911 , longitude : 10.727567 } ,
] ) ;Retorna o ponto mais próximo do ponto de referência.
getPathLength(points, distanceFunction = getDistance) Calcula o comprimento de uma coleção de coordenadas. Espera uma variedade de pontos como primeiro argumento e opcionalmente uma função para determinar a distância como segundo argumento. O padrão é getDistance .
geolib . getPathLength ( [
{ latitude : 52.516272 , longitude : 13.377722 } ,
{ latitude : 51.515 , longitude : 7.453619 } ,
{ latitude : 51.503333 , longitude : - 0.119722 } ,
] ) ;Retorna o comprimento do caminho nos medidores como número.
getDistanceFromLine(point, lineStart, lineEnd, accuracy = 1)Obtém a distância mínima de um ponto a uma linha de dois pontos.
geolib . getDistanceFromLine (
{ latitude : 51.516 , longitude : 7.456 } ,
{ latitude : 51.512 , longitude : 7.456 } ,
{ latitude : 51.516 , longitude : 7.459 }
) ;Retorna a distância mais curta da linha fornecida como número.
Nota: Se todos os pontos estiverem muito próximos, a função poderá retornar a NAN. Nesse caso, geralmente ajuda a aumentar levemente a precisão (por exemplo, 0.01 ).
getBoundsOfDistance(point, distance)Calcula as coordenadas delimitadoras de todos os pontos na superfície da Terra menos que ou igual à grande distância especificada do círculo.
geolib . getBoundsOfDistance (
{ latitude : 34.090166 , longitude : - 118.276736555556 } ,
1000
) ;Retorna uma variedade com as coordenadas do sudoeste e do nordeste.
isPointInLine(point, lineStart, lineEnd)Calcula se o ponto dado está em uma linha formada por início e fim.
geolib . isPointInLine (
{ latitude : 0 , longitude : 10 } ,
{ latitude : 0 , longitude : 0 } ,
{ latitude : 0 , longitude : 15 }
) ;sexagesimalToDecimal(value)Converte uma coordenada sexagesimal em formato decimal
geolib . sexagesimalToDecimal ( `51° 29' 46" N` ) ;Retorna o novo valor como número decimal.
decimalToSexagesimal(value)Converte uma coordenada decimal em formato sexagesimal
geolib . decimalToSexagesimal ( 51.49611111 ) ; // -> 51° 29' 46`Retorna o novo valor como string sexagesimal.
geolib.getLatitude(point, raw = false)geolib.getLongitude(point, raw = false)Retorna a latitude/longitude para um determinado ponto e o converte para decimal. Se o segundo argumento for definido como true, ele não converte o valor para decimal.
geolib . getLatitude ( { lat : 51.49611 , lng : 7.38896 } ) ; // -> 51.49611
geolib . getLongitude ( { lat : 51.49611 , lng : 7.38896 } ) ; // -> 7.38896Retorna o valor como decimal ou em seu formato original se o segundo argumento foi definido como true.
toDecimal(point) Verifica se uma coordenada já está em formato decimal e, se não, converte -o. Funciona com valores únicos (por exemplo 51° 32' 17" ) e coordenadas completas (por exemplo {lat: 1, lon: 1} ), desde que em um formato suportado.
geolib . toDecimal ( `51° 29' 46" N` ) ; // -> 51.59611111
geolib . toDecimal ( 51.59611111 ) ; // -> 51.59611111Retorna um valor decimal para o valor de entrada fornecido.
computeDestinationPoint(point, distance, bearing, radius = earthRadius)Calcula o ponto de destino dado um ponto inicial, uma distância (em metros) e um rolamento (em graus). Se nenhum raio for dado, ele padrão é o raio médio da Terra de 6.371.000 metros.
ATENÇÃO: Esta fórmula não é 100% precisa (mas muito próxima).
geolib . computeDestinationPoint (
{ latitude : 52.518611 , longitude : 13.408056 } ,
15000 ,
180
) ; geolib . computeDestinationPoint (
[ 13.408056 , 52.518611 ]
15000 ,
180
) ;Retorna o destino no mesmo formato que as coordenadas de entrada. Então, se você passar por um ponto Geojson, você receberá um ponto Geojson.
getAreaOfPolygon(points)Calcula a área da superfície de um polígono.
geolib . getAreaOfPolygon ( [
[ 7.453635617650258 , 51.49320556213869 ] ,
[ 7.454583481047989 , 51.49328893754685 ] ,
[ 7.454778172179346 , 51.49240881084831 ] ,
[ 7.453832678225655 , 51.49231619246726 ] ,
[ 7.453635617650258 , 51.49320556213869 ] ,
] ) ;Retorna o resultado como número em metros quadrados.
getCoordinateKeys(point)Obtém os nomes de propriedades deles usados no ponto de uma forma normalizada:
geolib . getCoordinateKeys ( { lat : 1 , lon : 1 } ) ;
// -> { latitude: 'lat', longitude: 'lon' } Retorna um objeto com uma latitude e uma propriedade longitude . Seus valores são os nomes de propriedades para latitude e longitude usadas no ponto passado. Provavelmente deve ser usado apenas internamente.
getCoordinateKey(point, keysToLookup) É usado por getCoordinateKeys sob o capô e retorna o nome da propriedade de uma lista de nomes possíveis.
geolib . getCoordinateKey ( { latitude : 1 , longitude : 2 } , [ 'lat' , 'latitude' ] ) ;
// -> latitude Retorna o nome da propriedade como string ou undefined se não houve correspondência.
isValidCoordinate(point)Verifica se um determinado ponto tem pelo menos uma latitude e uma longitude e está em um formato suportado.
// true:
geolib . isValidCoordinate ( { latitude : 1 , longitude : 2 } ) ;
// false, longitude is missing:
geolib . isValidCoordinate ( { latitude : 1 } ) ;
// true, GeoJSON format:
geolib . isValidCoordinate ( [ 2 , 1 ] ) ; Retorna true ou false .
getSpeed(startPointWithTime, endPointWithTime)Calcula a velocidade entre dois pontos dentro de um determinado período de tempo.
geolib . getSpeed (
{ latitude : 51.567294 , longitude : 7.38896 , time : 1360231200880 } ,
{ latitude : 52.54944 , longitude : 13.468509 , time : 1360245600880 }
) ;Retorne a velocidade em metros por segundo como número.
convertSpeed(value, unit) Converte o resultado do getSpeed em um formato mais amigável humano. As unidades atualmente disponíveis são mph e kmh .
unit pode ser uma de:
geolib . convertSpeed ( 29.8678 , 'kmh' ) ;Retorna o valor convertido como número.
convertDistance(value, unit)Converte uma determinada distância (em metros) em outra unidade.
unit pode ser uma de:
geolib . convertDistance ( 14200 , 'km' ) ; // 14.2
geolib . convertDistance ( 500 , 'km' ) ; // 0.5Retorna a distância convertida como número.
convertArea(value, unit) Converte o resultado do getAreaForPolygon em uma unidade diferente.
unit pode ser uma de:
geolib . convertArea ( 298678 , 'km2' ) ) ;Retorna a área convertida como número.
wktToPolygon(wkt)Converte o texto bem conhecido (também conhecido como WKT) em polígono que o geolib entende. https://en.wikipedia.org/wiki/well-known_text_representation_of_geometry#geometric_objects
geolib . wktToPolygon ( 'POLYGON ((30 10.54321, 40 40, 20 40, 10 20, 30 10))' ) ;
// [
// { latitude: 10.54321, longitude: 30 },
// { latitude: 40, longitude: 40 },
// { latitude: 40, longitude: 20 },
// { latitude: 20, longitude: 10 },
// { latitude: 10, longitude: 30 },}
// ]Retorna a variedade de coordenadas.
Na versão 3.0.0, estou tentando voltar um pouco às raízes . O Geolib já foi iniciado porque eu precisava de um punhado de métodos para executar tarefas muito específicas relacionadas ao GEO, como obter a distância ou a direção entre dois pontos. Como era uma das primeiras bibliotecas da NPM naquela época para fazer esse tipo de coisa de uma maneira muito simples, tornou -se muito popular (com mais de 300 mil downloads por mês a partir de abril de 2019!) E, como conseqüência, obteve muitas contribuições ao longo dos anos. Muitos dos quais eu apenas me fundi desde que tenham acompanhado testes, sem olhar para consistência, convenções, complexidade, estilo de codificação ou mesmo a qualidade geral das funções que às vezes nem mesmo entendi completamente.
Eu limpei completamente a base de código, reconstruí toda a biblioteca "do zero", unifiquei todos os argumentos da função, removi algumas funções em que eu não tinha certeza se elas deveriam estar aqui (sinta -se à vontade para adicioná -las de volta, você está usando -as!) Ou, se elas foram usadas (fizeram algumas pesquisas no Github para os nomes de funções, foram lançados lá em que não há zero).
O suporte de elevação foi descartado, bem como algumas funções que tornaram desnecessariamente a biblioteca realmente grande em tamanho (por exemplo, isPointInsideRobust sozinho tinha mais de 700 linhas de código e foi basicamente retirado de uma biblioteca diferente).
Eu removi o grunhido do processo de construção, adicionei ferramentas "modernas" como Eslint e mais bonito. Mudei do Travis CI para o Circle CI e estou no processo de automatização ainda mais do processo de liberação de novas versões usando compensações semantic-release e conventional-commits . Também mudei de JavaScript puro para o TypeScript porque acho que ele tem alguns benefícios.
getDistance padrão de ser a lenta e precisa para ser a rápida e ligeiramente imprecisa. A antiga função getDistance agora se chama getPreciseDistance , enquanto a função antiga getDistanceSimple agora é a função getDistance padrão. Você pode, no entanto, aprovar getPreciseDistance como argumento para qualquer função que use o cálculo da distância internamente.getBoundsOfDistance() agora retorna as coordenadas exatas devido à remoção da limitação artificial de 8 lugar decimalgetCompassDirection() não retorna mais um objeto com uma direção exata e uma aproximação , mas apenas a direção exata como stringgetCompassDirection() não é mais uma string ("círculo", "linha"), mas uma função para determinar o rolamento (você pode passar getRhumbLineBearing ou getGreatCircleBearing ). A função recebe a origem e o destino como primeiro e segundo argumento. Se nenhum argumento do terceiro foi dado, getRhumbLineBearing(origin, dest) é usado por padrão.roughCompassDirection(exact) se você realmente precisar apenas de uma direção muito difícil (e potencialmente imprecisa ou inadequada). Melhor não use.orderByDistance() não modifica mais sua entrada, portanto não adiciona uma propriedade distance e key às coordenadas retornadas.getSpeed() agora é sempre devolvido como medidores por segundo . Ele pode ser convertido usando a nova função de conveniência convertSpeed(mps, targetUnit)findNearest() não se offset mais e limit argumentos. É apenas um método de conveniência para obter o único ponto mais próximo de um conjunto de coordenadas. Se você precisar de mais de um, dê uma olhada na implementação e implemente sua própria lógica usando orderByDistance52° 46' 21.0004" em casos raros, mas também é mais preciso do que era antes.computeDestinationPointgetBoundsgetBoundsOfDistancegetCentergetCenterOfBoundsgetCompassDirectiongetDistanceFromLinegetPathLengthgetRhumbLineBearinggetSpeedisDecimalisPointInLineisPointNearLineisSexagesimalorderByDistancegetKeys renomeado para getCoordinateKeysvalidate renomeado para isValidCoordinategetLat renomeado para getLatitudegetLon renomeado para getLongitudelatitude -> renomeada para getLatitudelongitude -> renomeada para getLongitudeconvertUnit -> Remamed to convertDistance, porque o nome era muito ambíguouseDecimal renomeado para toDecimaldecimal2sexagesimal renomeado para decimalToSexagesimalsexagesimal2decimal renomeado para sexagesimalToDecimalgetDistance renomeado para getPreciseDistancegetDistanceSimple renomeado para getDistanceisPointInside renomeado para isPointInPolygonisPointInCircle renomeado para isPointWithinRadiusgetBearing renomeado para getGreatCircleBearing para ser mais explícitogetElev -> removidoelevation -> removidacoords -> removido (pode ser re -addido como GetCoordinate ou GetNormalized Coordinate)ll -> removido (porque WTF?)preparePolygonForIsPointInsideOptimized -> Removido devido à falta de documentação e aos testes ausentesisPointInsideWithPreparedPolygon -> Removido devido à falta de documentaçãoisInside Alias -> Removido (muito ambíguo) - Use isPointInPolygon ou isPointWithinRadiuswithinRadius -> removido, use isPointWithinRadiusgetDirection -> Removido (desordem desnecessária) - Use getCompassDirectiongetAreaOfPolygon para calcular a área de um polígonogetCoordinateKey para obter um nome de propriedade (por exemplo, lat ou lng de um objeto com base em uma matriz de nomes possíveis)
