﻿LunaLab - Logica cientifica do sistema de identificacao lunar
Versao: 2026-07-06

Objetivo
--------
O sistema nao deve depender apenas da aparencia da foto. A fase real da Lua e definida pela geometria Sol-Terra-Lua. Por isso, a classificacao correta usa um modelo hibrido:

1. Modelo astronomico calcula a fase esperada pela data e horario.
2. Analise de pixels mede a aparencia da Lua na foto.
3. Dataset offline compara a assinatura visual da foto com amostras numericas.
4. O resultado final combina geometria, imagem e incerteza.


1. Modelo astronomico
---------------------
O site calcula a longitude ecliptica geocentrica aproximada do Sol e da Lua.

Para o Sol:
  n = JD - 2451545.0
  L = 280.460 + 0.9856474 * n
  g = 357.528 + 0.9856003 * n
  lambdaSol = L + 1.915 * sen(g) + 0.020 * sen(2g)

Para a Lua, o sistema usa elementos orbitais aproximados:
  N = longitude do nodo ascendente
  i = inclinacao orbital
  w = argumento do perigeu
  a = distancia media em raios terrestres
  e = excentricidade
  M = anomalia media

Com esses valores, ele calcula:
  E = anomalia excentrica
  v = anomalia verdadeira
  r = distancia da Lua
  lambdaLua = longitude ecliptica da Lua
  betaLua = latitude ecliptica da Lua

O angulo de fase usado no site e:
  fase = normalizar(lambdaLua - lambdaSol)

A iluminacao vem da formula:
  I = (1 - cos(fase)) / 2

Onde:
  fase proxima de 0 graus   = Lua Nova
  fase proxima de 90 graus  = Quarto Crescente
  fase proxima de 180 graus = Lua Cheia
  fase proxima de 270 graus = Quarto Minguante

Esse e o dado fisico principal. A foto nao define a verdade sozinha; ela confirma ou entra em conflito com o modelo.


2. Analise visual da foto
-------------------------
O sistema localiza o disco lunar na imagem usando pixels:

- converte a foto para luminancia;
- procura componentes claros/neutros contra o fundo;
- mede area, contraste, densidade e formato;
- estima o disco e o raio;
- calcula a regiao iluminada;
- mede lado iluminado, perfil horizontal, perfil vertical e centroide da luz.

As principais features extraidas sao:

- iluminacao estimada;
- lado iluminado: direito, esquerdo ou centro;
- perfil horizontal de brilho;
- perfil vertical de brilho;
- centroide horizontal;
- curva do terminador;
- qualidade da deteccao;
- contraste;
- tamanho relativo do disco.

Refino do disco pelo limbo
--------------------------
Em fases nao-cheias, a deteccao por componente pega so a parte acesa, com
centro deslocado e raio pequeno. O sistema refina a geometria assim:

- Raio = metade da EXTENSAO VERTICAL da regiao iluminada. Em qualquer fase
  a regiao acesa cobre quase todo o diametro vertical (as pontas do
  crescente tocam os polos), entao essa medida e estavel.
- Centro X pela geometria do limbo: em cada linha, a borda do limbo segue
  o circulo x = cx +/- raiz(R^2 - (y-cy)^2); a borda do terminador nao.
  Testa as duas hipoteses (limbo a esquerda / a direita) e escolhe a de
  menor dispersao entre as linhas.

Geometria do terminador
-----------------------
O terminador (limite luz/sombra) projetado no disco e uma elipse:

  nx = cos(fase) * sqrt(1 - ny^2)

Com o disco refinado, o sistema varre linha a linha e mede a MAGNITUDE
|cos(fase)| = |posicao do terminador| / corda (mediana entre as linhas).
Como e medida de POSICAO (nao de intensidade), e robusta a exposicao,
halo e brilho da camera.

Para a fase completa, tres decisoes sao separadas, cada uma na fonte mais
robusta:

- MAGNITUDE |cos(fase)|: posicao do terminador.
- SINAL (gibosa x crescente): o centro do disco esta iluminado? Centro
  aceso => >50% => gibosa (cos<0); centro escuro => crescente (cos>0).
- LADO (crescente x minguante): assimetria de brilho esquerda/direita.

Quando medido com confianca, o terminador e a fonte PRIMARIA de fase,
lado e iluminacao — as heuristicas de pixel so assumem perto da cheia ou
da nova, onde o terminador some (fresta fina demais) e elas funcionam bem.
Isso corrige o vies antigo, que superestimava crescentes e confundia
gibosas com lua cheia.


3. Banco de amostras offline
----------------------------
Os arquivos usados sao:
  lunalab_assets/moon_phase_dataset_index.json
  lunalab_assets/moon_phase_<fase>.json  (um arquivo por fase)

O banco so e baixado quando o usuario entra nas vistas Minha Foto ou
Campo (carregamento sob demanda), nunca no carregamento da pagina.

Ele contem 8 fases principais e 400 assinaturas por fase:

- Lua Nova
- Crescente
- Quarto Crescente
- Gibosa Crescente
- Lua Cheia
- Gibosa Minguante
- Quarto Minguante
- Minguante Final

Total:
  3.200 amostras numericas (~1,25 MB no total)

Como as amostras sao procedurais com ruido controlado, algumas centenas
por fase cobrem o mesmo espaco de variacao que dezenas de milhares;
amostras extras so repetem informacao sem melhorar a classificacao.

Essas amostras nao sao fotos reais. Sao assinaturas procedurais geradas por modelo matematico. Cada amostra representa uma possibilidade de iluminacao/forma dentro daquela fase.

Cada amostra contem:

- phaseAngleDeg
- illumination
- brightSide
- centroidX
- centroidY
- terminatorCurve
- crescentRatio
- widthProfile
- verticalProfile
- edgeSharpness
- textureConfidence


4. Hemisferio do observador
---------------------------
A convencao geometrica (usada pelo modelo e pelo dataset) descreve a Lua
como vista do hemisferio norte: crescente ilumina a DIREITA. No hemisferio
sul a Lua aparece invertida: crescente ilumina a ESQUERDA.

Por isso o sistema tem um seletor de hemisferio (padrao: Sul, Brasil).
Quando o hemisferio e sul, a leitura de pixels e espelhada antes de
comparar com o modelo e com o dataset, e o lado exibido ao usuario e o
lado APARENTE (como ele ve no ceu). Sem essa correcao, fotos do
hemisferio sul de lua crescente seriam classificadas como minguante.


5. Comparacao com o dataset
---------------------------
A foto analisada e transformada em uma assinatura parecida com as amostras:

  assinaturaFoto = {
    illumination,
    brightSide,
    centroidX,
    widthProfile,
    verticalProfile
  }

Depois o sistema compara com o banco usando distancia ponderada:

  score =
    diferencaIluminacao * peso
    + diferencaPerfilHorizontal * peso
    + diferencaPerfilVertical * peso
    + diferencaCentroide * peso
    + penalidadeLadoIluminado
    + desvioDaPreviaAstronomica * pesoPequeno

A previa astronomica (fase esperada pela data/hora) entra como reforco
suave no score: desempata casos ambiguos sem sobrepor a evidencia visual.

A classificacao usa k-NN com votacao: os 24 vizinhos mais proximos votam,
ponderados pela proximidade. A fase vencedora e a com maior soma de votos;
o angulo final e a media circular ponderada dos vizinhos dessa fase. A
confianca combina a fatia de votos com a qualidade do melhor vizinho -
mais robusto a ruido do que usar apenas a amostra mais proxima.

Quando o resultado do banco e combinado com a fase visual, a mistura de
angulos e circular (nao linear), para nao quebrar perto de 0/360 graus
(regiao da Lua Nova).

O dataset entra como reforco. Ele nao substitui o modelo astronomico. Se a confianca do banco for baixa, o sistema usa principalmente a analise visual e a geometria astronomica.


6. Resultado final
------------------
O resultado final considera:

- fase astronomica esperada pela data/hora;
- fase visual detectada na foto;
- diferenca de iluminacao;
- diferenca angular entre foto e modelo;
- qualidade da deteccao;
- encaixe com o dataset;
- coerencia geral.

Na interface, quando o banco participa, aparece:
  banco XX%

Isso indica a confianca da comparacao contra as amostras offline.


7. Por que esse modelo e mais correto
-------------------------------------
Cientificamente, a fase da Lua e uma propriedade geometrica. A imagem pode estar afetada por:

- exposicao da camera;
- nuvens;
- halo;
- zoom digital;
- blur;
- cor atmosferica;
- horizonte;
- texto ou marcacoes sobre a foto.

Por isso, a abordagem correta e:

  geometria astronomica + medicao da foto + incerteza

Nao e correto depender apenas de intervalos fixos da foto.
Nao e correto depender apenas de amostras sinteticas.
O modelo hibrido e mais robusto porque usa a fisica como referencia e a imagem como observacao.


8. Limitacoes atuais
--------------------
O modelo astronomico e aproximado e adequado para fase/iluminacao no navegador, mas nao substitui efemerides profissionais de alta precisao.

O dataset atual e sintetico. Para melhorar mais, o proximo passo seria adicionar fotos reais rotuladas, extraindo as mesmas assinaturas numericas.

O dataset e regeneravel de forma deterministica (RNG com seed fixa) via:
  node tools/generate_moon_phase_dataset.js
  node tools/split_moon_phase_dataset.js
