# SVG‑obrazki map

`/v1/render/*` zwraca mapę jako gotowy SVG: koło węgla, dwu- i trzykrotnie koło, kompozycja, kartę węgla (północna, południowa, wschodnia), siatkę aspektów, kosmogramę, fazę Księżyca, czasoprzestrzeń, biorytmy, pas cień i gwiazdkę. Przesyłasz dane urodzenia, my rysujemy mapę. Pełna lista tras i parametrów w [dokumencie API](/docs/api/).

Ten sam kod rysowania został opublikowany jako pakiet npm [`@astroway/render`](https://www.npmjs.com/package/@astroway/render): jeśli dane mapy u ciebie już są, koło można namalować w przeglądarce czy na swoim serwerze, i będzie się zgadzało z tym, co zwraca API, bajt w bajcie. Wersję rysowania API zwraca w nagłówku `X-Render-Version`.

## Zapytanie

```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"` zwraca sam plik, typowy `json` zwraca linijkę SVG w typowej odpowiedzi API. Tematy: `light`, `dark`, `console` i `css`.

## Temat css: kolory Twojej strony

Z `theme: "css"` każdy kolor w SVG jest zapisany jako zmienna CSS z kolorem jasnej tematy jako rezerwowym, np. `var(--aw-ring, #222)`. Wstaw SVG do strony HTML (nie do `<img>`: tam zmienne nie przechodzą) i ustal zmienną:

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

Bez żadnych zmiennych mapa wygląda dokładnie jak `light`. Reguła CSS Twojej strony jest silniejsza niż zmienna, więc każdy element można przebarwić klasą.

| Zmienna | Co barwi |
|---|---|
| `--aw-chart-bg` | tło mapy |
| `--aw-fg`, `--aw-muted` | znaki i opisy, drugorzędny tekst i podziałki |
| `--aw-ring` | koła i linie siatki |
| `--aw-houses-fill` | pole kartę węgla, dysk gwiazdkowej mapy, mapa cienia |
| `--aw-benefic` | planety zewnętrznego koła, lagna w kartę węgla, wydarzenia czasoprzestrzeni bez własnego koloru |
| `--aw-malefic` | znak ruchu wstecznego ℞, pas cienia |
| `--aw-aspect-harmonious`, `--aw-aspect-tense`, `--aw-aspect-neutral`, `--aw-aspect-minor`, `--aw-aspect-quintile` | linie i znaki aspektów |
| `--aw-moon-shadow`, `--aw-moon-light` | fazę Księżyca |
| `--aw-cycle-physical`, `--aw-cycle-emotional`, `--aw-cycle-intellectual` | biorytmy |

## Klasa i data-atrybuty

W temacie `css` zachodnie koła (`wheel-western`, `bi-wheel`, `tri-wheel`, `composite`) i siatka aspektów mają stałe klasy. Nazwy tylko dodaje, nigdy nie zmienia, więc na nich można pisać style i skrypty.

- Koło: `aw-bg`, `aw-ring`, `aw-sign aw-sign-leo`, `aw-sign-line`, `aw-tick`, `aw-house-cusp`, `aw-house-number`, osie `aw-axis aw-asc` (`aw-dsc`, `aw-mc`, `aw-ic`), ich opisy `aw-label aw-axis-label`, tytuł `aw-title`.
- Planeta: grupa `<g class="aw-planet aw-planet-sun">`, ruch wsteczny ma jeszcze `aw-retrograde`, planety zewnętrznego koła `aw-layer-1`. Wewnątrz `aw-glyph`, `aw-retro` (znak ℞) i `aw-planet-tick`.
- Aspekt: linia `aw-aspect aw-aspect-trine`, linia między dwoma kartami ma jeszcze `aw-cross-aspect`.
- Siatka aspektów: `aw-grid-header`, `aw-grid-cell`, `aw-aspect aw-aspect-square`, `aw-orb`.

Grupa planety ma `data-planet` (`sun`, `north-node`, `lilith`; na zewnętrznym koło `b-sun`, na trzecim `c-sun`) i `data-label` z nazwą i pozycją: `Mercury 8°00' Taurus, ruch wsteczny`. Linia aspektu i komórka siatki ma `data-a` i `data-b`. Tak podświetla się wszystkie aspekty planety przy przejściu:

```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));
}));
```

## Swój opis: labels

Zachodnie koła przyjmują `options.labels`: Twoje słowa dla opisów osi, dla `<title>` i `<desc>`, które czytają ekranowe czytelniki, i dla nazw w `data-label`. Klucze, których nie ma, zostają angielskimi; samemu nic nie tłumaczę.

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

`bodies` ma klucze angielskie (`Sun`, `North Node`), `signs` to dokładnie dwanaście nazw, zaczynając od Bicia, każdy opis do 40 znaków.

## Aspekty między dwoma kartami

`/v1/render/bi-wheel` z `options.crossAspects: true` rysuje punktami aspekty między wewnętrzną i zewnętrzną kartą, ten sam zestaw, który `POST /v1/synastry` zwraca jako `crossAspects`. Para, w której jedno z ciał nie jest namalowane, jest pomijana. Typowo wyłączony.

## Gotowa mapa zamiast danych urodzenia

Jeśli mapa u ciebie już jest, bo właśnie wywołałeś `POST /v1/chart`, nadaj ją `data` w polu `chart` zamiast danych urodzenia, i my tylko namalujemy ją. Tak działają `wheel-western`, `aspect-grid` i `bi-wheel` (tam `natal.chart` i `outer.chart`, obie mają być gotowymi kartami). Zobrazienie wychodzi bajt w bajcie tak samo, jak z danych urodzenia.

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

Zbyteczne pola odpowiedzi można nie ciąć. Sprawdzany jest to, co namalowane jest: od 1 do 30 ciał, długości od 0 do 360, dokładnie 12 kuśpidów. Ciało, w którym jest i `chart`, i dane urodzenia, odchodzi z 400.

## Cena

Wywołanie `/v1/render/*` z danymi urodzenia kosztuje 10 kredytów, bo mapa jest policzona. Z gotową kartą `chart` wywołania `/v1/render/wheel-western`, `/v1/render/aspect-grid` i `/v1/render/bi-wheel` kosztują 1 kredyt. Temat, klasy i opisy nie wpływają na cenę.