Funções para trabalhar com coordenadas geográficas

Documentação sobre coordenadas

​

greatCircleDistance

Calcula a distância entre dois pontos na superfície da Terra com base na fórmula do círculo máximo.

greatCircleDistance(lon1Deg, lat1Deg, lon2Deg, lat2Deg)

Parâmetros de entrada

• lon1Deg — Longitude do primeiro ponto em graus. Intervalo: [-180°, 180°].
• lat1Deg — Latitude do primeiro ponto em graus. Intervalo: [-90°, 90°].
• lon2Deg — Longitude do segundo ponto em graus. Intervalo: [-180°, 180°].
• lat2Deg — Latitude do segundo ponto em graus. Intervalo: [-90°, 90°].

Valores positivos correspondem à latitude norte e à longitude leste, e valores negativos correspondem à latitude sul e à longitude oeste.

Valor retornado

A distância entre dois pontos na superfície da Terra, em metros.

Gera uma exceção quando os valores dos parâmetros de entrada estão fora do intervalo.

Exemplo

SELECT greatCircleDistance(55.755831, 37.617673, -55.755831, -37.617673) AS greatCircleDistance

┌─greatCircleDistance─┐
│            14128352 │
└─────────────────────┘

​

geoDistance

Semelhante a greatCircleDistance, mas calcula a distância no elipsoide WGS-84 em vez de na esfera. Esta é uma aproximação mais precisa do geoide da Terra. O desempenho é o mesmo de greatCircleDistance (sem perda de desempenho). Recomenda-se usar geoDistance para calcular distâncias na Terra.

Nota técnica: para pontos suficientemente próximos, calculamos a distância usando uma aproximação planar com a métrica no plano tangente ao ponto médio das coordenadas.

geoDistance(lon1Deg, lat1Deg, lon2Deg, lat2Deg)

Parâmetros de entrada

• lon1Deg — Longitude do primeiro ponto em graus. Intervalo: [-180°, 180°].
• lat1Deg — Latitude do primeiro ponto em graus. Intervalo: [-90°, 90°].
• lon2Deg — Longitude do segundo ponto em graus. Intervalo: [-180°, 180°].
• lat2Deg — Latitude do segundo ponto em graus. Intervalo: [-90°, 90°].

Valores positivos correspondem à latitude norte e à longitude leste, e valores negativos correspondem à latitude sul e à longitude oeste.

Valor retornado

A distância entre dois pontos na superfície da Terra, em metros.

Gera uma exceção quando os valores dos parâmetros de entrada estão fora do intervalo.

Exemplo

SELECT geoDistance(38.8976, -77.0366, 39.9496, -75.1503) AS geoDistance

┌─geoDistance─┐
│   212458.73 │
└─────────────┘

​

greatCircleAngle

Calcula o ângulo central entre dois pontos na superfície terrestre usando a fórmula do círculo máximo.

greatCircleAngle(lon1Deg, lat1Deg, lon2Deg, lat2Deg)

Parâmetros de entrada

• lon1Deg — Longitude do primeiro ponto em graus.
• lat1Deg — Latitude do primeiro ponto em graus.
• lon2Deg — Longitude do segundo ponto em graus.
• lat2Deg — Latitude do segundo ponto em graus.

Valor retornado

O ângulo central entre dois pontos, em graus.

Exemplo

SELECT greatCircleAngle(0, 0, 45, 0) AS arc

┌─arc─┐
│  45 │
└─────┘

​

pointInEllipses

Verifica se o ponto pertence a pelo menos uma das elipses. As coordenadas são geométricas no sistema de coordenadas cartesiano.

pointInEllipses(x, y, x₀, y₀, a₀, b₀,...,xₙ, yₙ, aₙ, bₙ)

Parâmetros de entrada

• x, y — Coordenadas de um ponto no plano.
• xᵢ, yᵢ — Coordenadas do centro da i-ésima elipse.
• aᵢ, bᵢ — Eixos da i-ésima elipse nas unidades das coordenadas x e y.

O número de parâmetros de entrada deve ser 2+4⋅n, em que n é o número de elipses.

Valores retornados

1 se o ponto estiver dentro de pelo menos uma das elipses; 0 se não estiver.

Exemplo

SELECT pointInEllipses(10., 10., 10., 9.1, 1., 0.9999)

┌─pointInEllipses(10., 10., 10., 9.1, 1., 0.9999)─┐
│                                               1 │
└─────────────────────────────────────────────────┘

​

pointInPolygon

Verifica se o ponto está contido no polígono no plano.

pointInPolygon((x, y), [(a, b), (c, d) ...], ...)

Valores de entrada

• (x, y) — Coordenadas de um ponto no plano. Tipo de dado — Tuple — uma tupla de dois números.
• [(a, b), (c, d) ...] — Vértices do polígono. Tipo de dado — Array. Cada vértice é representado por um par de coordenadas (a, b). Os vértices devem ser especificados em sentido horário ou anti-horário. O número mínimo de vértices é 3. O polígono deve ser constante.
• A função oferece suporte a polígonos com furos (áreas vazadas). Tipo de dado — Polygon. Passe o Polygon inteiro como segundo argumento ou passe primeiro o anel externo e, em seguida, cada furo como argumento adicional separado.
• A função também oferece suporte a multipolígonos. Tipo de dado — MultiPolygon. Passe o MultiPolygon inteiro como segundo argumento ou liste cada polígono componente como um argumento separado.

Valores retornados

1 se o ponto estiver dentro do polígono, 0 se não estiver. Se o ponto estiver na borda do polígono, a função poderá retornar 0 ou 1.

Exemplo

SELECT pointInPolygon((3., 3.), [(6, 0), (8, 4), (5, 8), (0, 2)]) AS res

┌─res─┐
│   1 │
└─────┘

Nota • Você pode definir validate_polygons = 0 para ignorar a validação da geometria. • pointInPolygon pressupõe que todo polígono esteja bem formado. Se a entrada tiver auto-interseções, anéis em ordem incorreta ou arestas sobrepostas, os resultados se tornam pouco confiáveis — especialmente para pontos que ficam exatamente sobre uma aresta, um vértice ou dentro de uma auto-interseção, onde a noção de “dentro” vs. “fora” é indefinida. • Quando o argumento do polígono é constante e o ponto é expresso usando colunas-chave indexadas (por exemplo, pointInPolygon((x, y), constant_polygon) em uma tabela em que x, y fazem parte da PRIMARY KEY ou são cobertos por um índice minmax), o ClickHouse pode usar tanto a chave primária quanto os índices de data-skipping minmax para descartar grânulos irrelevantes.