Face do cubo S2 a partir de lat/lon: qual face contém o ponto
Descubra em qual das seis faces do cubo S2 um ponto cai: San Francisco, em (37,7749; -122,4194), fica na face 4, a -Y, com u -0,918061185048 e v -0,635094359374. É o primeiro passo antes de montar células S2. Grátis no seu navegador.
- Grátis
- Funciona no seu navegador
- Sem cadastro
- Seus dados não saem do seu aparelho
Executar grátis
Exemplo resolvido
- Latitude
- 37,7749
- Longitude
- -122,4194
- Face
- 4
- Nome da face
- -Y
- X
- -0,4237560025
- Y
- -0,6672331383
A biblioteca de geometria S2 da Google divide a Terra projetando a esfera unitária sobre um cubo e subdividindo de forma recursiva cada face em uma hierarquia de células. Esta capacidade aceita lat e lon WGS84, converte-as em um vetor de direção unitário e devolve o índice de face S2 (de 0 a 5), um nome legível como +X ou -Z, os componentes cartesianos unitários e as coordenadas UV do ponto nessa face no intervalo convencional de menos um a mais um. Use-a ao construir índices espaciais, ensinar geometria esférica ou validar que as suas próprias ligações S2 escolhem a mesma face que a biblioteca de referência nos casos limite junto às bordas das faces.
Como lat/lon se torna uma face do cubo S2
As seis faces do cubo S2 correspondem aos seis semi-espaços definidos pelo eixo cartesiano dominante: a face zero é a face mais X, a um mais Y, a dois mais Z, a três menos X, a quatro menos Y e a cinco menos Z.
A implementação segue a mesma regra do maior componente absoluto usada pela biblioteca S2 da Google: compare os valores absolutos de x, y e z; o eixo de maior magnitude decide o par de faces; o sinal desse componente decide qual das duas faces opostas é escolhida. Em empates exatos vence o índice de eixo maior, alinhado a LargestAbsComponent do S2, para que pontos nas junções entre faces se resolvam de forma determinística.
Quando a face é conhecida, as coordenadas UV nela são obtidas dividindo os dois componentes não dominantes pelo dominante com as inversões de sinal específicas de cada face publicadas em ValidFaceXYZToUV do S2, produzindo valores no intervalo fechado de menos um a mais um que localizam o ponto dentro da face quadrada antes de qualquer hierarquia de células adicional.
Onde a consulta de face S2 vale o investimento
Geradores educativos e de exames que ensinam grelhas globais discretas podem pedir aos alunos a face de uma cidade e classificar face a um oráculo determinístico em vez de cadernos docentes instáveis. Pipelines de análise de registos que agrupam amostras GPS por face S2 para encaminhamento grosseiro ou divisões geográficas A/B chamam uma vez por evento e guardam o inteiro da face junto das coordenadas brutas. Validação falhada não consome saldo.
Mantenha pedidos pequenos, fixe o inteiro da face e o UV arredondado nos testes e obtenha atribuição de face reproduzível para índices, lições e workers de borda sem montar uma pilha completa de geometria esférica própria.
Casos de uso
Preâmbulo de codificação de células S2
Resolva qual das seis faces do cubo contém um lat/lon antes de calcular ids de célula S2 hierárquicos ou coberturas de região num worker que não pode carregar a biblioteca S2 completa.
Ensino de grelhas globais discretas
Permita que os alunos enviem coordenadas de cidades e verifiquem o índice de face face a um oráculo que segue a regra do maior componente absoluto da Google, incluindo polos e junções entre faces.
Agrupamento geográfico grosseiro
Agrupe eventos GPS por face S2 para painéis de encaminhamento ou divisões geográficas A/B sem calcular ids de célula completos em cada amostra.
Perguntas frequentes
O que significam as faces de 0 a 5?
Seguem a convenção S2 da Google: 0=+X, 1=+Y, 2=+Z (norte), 3=-X, 4=-Y, 5=-Z (sul). A escolha é o maior componente cartesiano absoluto do vetor unitário.
O que são u e v na resposta?
As coordenadas UV localizam o ponto na face do cubo escolhida no intervalo [-1, 1], com as mesmas convenções de sinal ValidFaceXYZToUV do S2.
Como se descobre a face do cubo S2 de um ponto?
A latitude e a longitude viram um vetor unitário com três componentes. O componente de maior valor absoluto escolhe o eixo, e o sinal dele decide qual das duas faces opostas fica com o ponto.
Qual face recebe um ponto bem na aresta entre duas faces?
O empate é resolvido sempre do mesmo jeito: se dois componentes do vetor unitário têm o mesmo tamanho, vence o eixo de índice mais alto. Assim, pontos nas arestas não pulam de uma face para outra.
Isto calcula o identificador completo da célula S2?
Não. A ferramenta identifica só a face, o vetor unitário e a posição u e v nessa face. Para o identificador completo da célula, use esses valores num codificador de células S2.
Ferramentas relacionadas
Para desenvolvedores — acesso via API
Tudo nesta página está disponível via API. Esta seção é para equipes que querem integrar a ferramenta aos próprios sistemas; quem não precisa disso pode simplesmente usar a ferramenta acima.
Endpoint
Autenticação por token Bearer. Um único POST coloca a tarefa na fila; o resultado chega por webhook ou link assinado.
Chame do seu código
curl -X POST https://api.kit.forhosting.com/geo/s2-face-from-latlon \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"lat":37.7749,"lon":-122.4194}'const res = await fetch("https://api.kit.forhosting.com/geo/s2-face-from-latlon", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"lat": 37.7749,
"lon": -122.4194
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/geo/s2-face-from-latlon",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"lat": 37.7749,
"lon": -122.4194
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/geo/s2-face-from-latlon", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"lat":37.7749,"lon":-122.4194}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"lat":37.7749,"lon":-122.4194}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/geo/s2-face-from-latlon", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Exemplo de requisição
{
"lat": 37.7749,
"lon": -122.4194
}Exemplo de resposta
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "geo.s2_face_from_latlon",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}A API é assíncrona: cada chamada devolve um task_id na hora. Se preferir polling, consulte o status a até 1 requisição por segundo.
Preço
Preço publicado, sem tokens nem créditos escondidos. Tarefa que falha não é cobrada.
Erros
| HTTP | Código | O que significa |
|---|---|---|
401 | unauthorized | Token ausente ou inválido. Confira o header Authorization. |
402 | insufficient_balance | Saldo insuficiente para esta tarefa. Faça uma recarga e tente de novo. |
404 | unknown_type | Esse tipo de tarefa não existe. Confira o campo type no catálogo. |
429 | rate_limited | Muitas requisições em pouco tempo. Espere um instante e tente de novo. |
Notas técnicas
Antes de codificar um id de célula S2, calcular uma cobertura ou raciocinar sobre interseção de regiões, é preciso saber qual das seis faces desse cubo contém uma latitude e uma longitude dadas. O algoritmo é matemática analítica pura, sem chamadas de rede nem estado aleatório, de modo que o caminho gratuito do navegador e o caminho de API pago sempre coincidem.
Como lat/lon se torna uma face do cubo S2
Comece com latitude e longitude em graus decimais na esfera WGS84. Converta a latitude em um ângulo polar a partir do equador e a longitude em um azimute a partir do meridiano de Greenwich, ambos em radianos. O vetor de direção unitário é então x igual a cos(latitude) cos(longitude), y igual a cos(latitude) sin(longitude) e z igual a sin(latitude), com z positivo apontando para o polo norte e x positivo em direção a latitude zero e longitude zero.
Contrato de entrada, campos da resposta e erros de validação
Envie por POST um corpo JSON com dois números finitos obrigatórios: lat (ou o alias latitude) entre menos noventa e noventa inclusive, e lon (ou os aliases lng e longitude) entre menos cento e oitenta e cento e oitenta inclusive. Cadeias numéricas são aceites como números JSON. Campos em falta, cadeias vazias, valores não finitos como NaN ou Infinity e latitudes ou longitudes fora do intervalo falham com invalid_input e não são faturados. Em sucesso a resposta devolve lat e lon limpos, o inteiro face de zero a cinco, face_name como um de +X, +Y, +Z, -X, -Y ou -Z, os componentes do vetor unitário x, y e z, o par UV local da face u e v, e method igual a s2_face_from_unit_sphere para os clientes documentarem a projeção usada. Exemplo: São Francisco perto da latitude 37.7749 e longitude negativa 122.4194 cai na face quatro (menos Y) porque o maior componente absoluto do vetor unitário é um y negativo. O polo norte (latitude 90, longitude 0) cai na face dois (mais Z). Longitude zero equatorial (latitude 0, longitude 0) cai na face zero (mais X). Combine esta resposta com o seu próprio codificador de células S2 se precisar de ids de célula completos; este endpoint só identifica a face e a posição UV nela.
Onde a consulta de face S2 vale o investimento
Plataformas de mapas e SIG que expõem ids de célula S2 para coberturas de região precisam de um primeiro passo de verificação de face alinhado à biblioteca de produção; uma API parse pequena evita enviar um binding completo de C++ ou Java para cada worker de borda só para saber em que face do cubo um pin assenta. Como a implementação é parse pura de nível A, cada chamada bem-sucedida custa o preço base publicado US$ 0,002 sem tokens de modelo nem rede de saída.
Perguntas técnicas
Como se encontra a face do cubo S2 de uma latitude e longitude?
Envie lat finita em [-90, 90] e lon em [-180, 180]. A API devolve face 0–5, face_name (+X…-Z), o vetor unitário x/y/z e o UV nessa face.
O que acontece se a latitude ou a longitude estiverem fora do intervalo?
A tarefa falha com invalid_input. A latitude deve estar em [-90, 90] e a longitude em [-180, 180]; pedidos inválidos não são faturados.
Quanto custa a ferramenta de face do cubo S2 a partir de lat/lon?
A ferramenta do navegador é gratuita. Pedidos API usam saldo pré-pago do KIT a US$ 0,002 por chamada bem-sucedida; entrada inválida não é faturada.