# Imagens SVG de Cartas

`/v1/render/*` devolve o mapa como SVG pronto: roda natal, bi‑ e tri‑roda, composto, mapas védicos (norte, sul, leste), grelha de aspetos, cosmograma, fase da Lua, linha do tempo, biorritmos, faixa de eclipse e mapa estelar. Tu envias os dados de nascimento, nós calculamos o mapa e desenhá‑lo. Lista completa de rotas e parâmetros está no [guia da API](/docs/api/).

O mesmo código de renderização está publicado como pacote npm [`@astroway/render`](https://www.npmjs.com/package/@astroway/render): se já tens os dados do mapa, a roda pode ser desenhada no browser ou no teu servidor, e será idêntica ao que a API devolve, byte a byte. A versão da renderização é devolvida no cabeçalho `X-Render-Version`.

## Pedido

```bash
curl -X POST https://api.astroway.info/v1/render/wheel-western \
  -H "X-Api-Key: $ASTROWAY_KEY" -H "Content-Type: application/json" \
  -d '{"date":"1990-05-15","time":"14:30:00","timezoneOffset":3,"latitude":50.45,"longitude":30.52,
       "options":{"theme":"css","format":"svg"}}' > wheel.svg
```

`format: "svg"` devolve o próprio ficheiro, o padrão `json` encapsula a string SVG numa resposta API normal. Temas: `light`, `dark`, `console` e `css`.

## Tema css: cores do teu site

Com `theme: "css"` cada cor no SVG é escrita como uma variável CSS com a cor do tema claro como reserva, por exemplo `var(--aw-ring, #222)`. Insere o SVG nas páginas HTML (não em `<img>`: as variáveis não são passadas para lá) e define as variáveis:

```css
.chart {
  --aw-chart-bg: transparent;
  --aw-ring: #444;
  --aw-fg: currentColor;
  --aw-aspect-tense: crimson;
}
```

Sem qualquer variável o mapa aparece exatamente como `light`. A regra CSS da tua página tem prioridade sobre a variável, por isso um elemento isolado pode ser recolorido com uma classe.

| Variável | O que colore |
|---|---|
| `--aw-chart-bg` | fundo do mapa |
| `--aw-fg`, `--aw-muted` | glifos e legendas, texto secundário e marcadores |
| `--aw-ring` | círculos e linhas da grelha |
| `--aw-houses-fill` | campo do mapa védico, disco do mapa estelar, mapa de eclipse |
| `--aw-benefic` | planetas do círculo externo, lagna no mapa védico, eventos da linha do tempo sem cor própria |
| `--aw-malefic` | símbolo de retrogradação ℞, faixa de eclipse |
| `--aw-aspect-harmonious`, `--aw-aspect-tense`, `--aw-aspect-neutral`, `--aw-aspect-minor`, `--aw-aspect-quintile` | linhas e símbolos dos aspetos |
| `--aw-moon-shadow`, `--aw-moon-light` | fase da Lua |
| `--aw-cycle-physical`, `--aw-cycle-emotional`, `--aw-cycle-intellectual` | biorritmos |

## Classes e data‑atributos

No tema `css` as rodas ocidentais (`wheel-western`, `bi-wheel`, `tri-wheel`, `composite`) e a grelha de aspetos têm classes fixas. Os nomes são apenas adicionados, nunca renomeados, por isso podes aplicar estilos e scripts a eles.

- Roda: `aw-bg`, `aw-ring`, `aw-sign aw-sign-leo`, `aw-sign-line`, `aw-tick`, `aw-house-cusp`, `aw-house-number`, eixos `aw-axis aw-asc` (`aw-dsc`, `aw-mc`, `aw-ic`), os seus rótulos `aw-label aw-axis-label`, título `aw-title`.
- Planeta: grupo `<g class="aw-planet aw-planet-sun">`, retrograda tem também `aw-retrograde`, planetas do círculo externo `aw-layer-1`. Dentro `aw-glyph`, `aw-retro` (símbolo ℞) e `aw-planet-tick`.
- Aspeto: linha `aw-aspect aw-aspect-trine`, linha entre dois mapas também `aw-cross-aspect`.
- Grelha de aspetos: `aw-grid-header`, `aw-grid-cell`, `aw-aspect aw-aspect-square`, `aw-orb`.

O grupo de planeta tem `data-planet` (`sun`, `north-node`, `lilith`; no círculo externo `b-sun`, no terceiro `c-sun`) e `data-label` com o nome e a posição: `Mercury 8°00' Taurus, retrograde`. A linha de aspeto e a célula da grelha têm `data-a` e `data-b`. Assim são realçados todos os aspetos do planeta ao passar o rato:

```js
svg.querySelectorAll('.aw-planet').forEach((g) => g.addEventListener('mouseenter', () => {
  const id = g.dataset.planet;
  svg.querySelectorAll('.aw-aspect').forEach((line) =>
    line.classList.toggle('is-on', line.dataset.a === id || line.dataset.b === id));
}));
```

## Os teus rótulos: labels

As rodas ocidentais aceitam `options.labels`: as tuas palavras para os rótulos dos eixos, para `<title>` e `<desc>` que os leitores de ecrã leem, e para os nomes em `data-label`. As chaves que não existirem permanecem em inglês; nós próprios não traduzimos nada.

```json
"options": {
  "theme": "css",
  "labels": {
    "asc": "Асц", "mc": "МС", "title": "Натальна карта",
    "bodies": { "Sun": "Сонце", "Moon": "Місяць" },
    "signs": ["Овен","Телець","Близнюки","Рак","Лев","Діва","Терези","Скорпіон","Стрілець","Козеріг","Водолій","Риби"],
    "retrograde": "ретроградний"
  }
}
```

`bodies` tem chaves em inglês (`Sun`, `North Node`), `signs` são exatamente doze nomes, começando por Áries, cada rótulo até 40 caracteres.

## Aspetos entre dois mapas

`/v1/render/bi-wheel` com `options.crossAspects: true` desenha em tracejado os aspetos entre o mapa interno e o externo, o mesmo conjunto que `POST /v1/synastry` devolve como `crossAspects`. O par onde um dos corpos não está desenhado é ignorado. Por padrão está desativado.

## Mapa pronto em vez dos dados de nascimento

Se já tens o mapa, porque acabaste de chamar `POST /v1/chart`, envia os seus `data` no campo `chart` em vez dos dados de nascimento, e nós apenas o desenharemos. É assim que funcionam `wheel-western`, `aspect-grid` e `bi-wheel` (lá `natal.chart` e `outer.chart`, ambos devem ser mapas prontos). A imagem será byte a byte igual à gerada a partir dos dados de nascimento.

```json
{ "chart": { "planets": [ ... ], "houses": { "cusps": [ ... ], "ascendant": 7.77, "mc": 277.12 }, "aspects": [ ... ] },
  "options": { "theme": "css" } }
```

Os campos extras da resposta podem ser deixados. Verifica‑se o que é desenhado: de 1 a 30 corpos, longitudes de 0 a 360, exatamente 12 cúspides. Um corpo que tem tanto `chart` como dados de nascimento gera um erro 400.

## Custo

Chamar `/v1/render/*` com dados de nascimento custa 10 créditos, pois o mapa é calculado. Com um mapa pronto `chart` as chamadas `/v1/render/wheel-western`, `/v1/render/aspect-grid` e `/v1/render/bi-wheel` custam 1 crédito. Tema, classes e rótulos não afetam o preço.