# Immagini delle carte SVG

`/v1/render/*` restituisce una carta come SVG pronto: ruota natale, bi- e tri-ruota, composito, carte vediche (nord, sud, est), griglia degli aspetti, cosmogramma, fase lunare, timeline, bioritmi, fascia di eclissi e carta stellare. Tu invii i dati di nascita, noi calcoliamo la carta e la disegniamo. L'elenco completo dei percorsi e dei parametri è nel [riferimento API](/docs/api/).

Lo stesso codice di disegno è pubblicato come pacchetto npm [`@astroway/render`](https://www.npmjs.com/package/@astroway/render): se hai già i dati della carta, la ruota può essere disegnata nel browser o sul tuo server, e corrisponderà byte per byte a ciò che l'API restituisce. L'API restituisce la versione del disegno nell'header `X-Render-Version`.

## Richiesta

```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"` restituisce il file stesso, il `json` tipico avvolge la stringa SVG in una normale risposta API. Temi: `light`, `dark`, `console` e `css`.

## Tema css: i colori del tuo sito

Con `theme: "css"` ogni colore nell'SVG è scritto come variabile CSS con il colore del tema chiaro come fallback, ad esempio `var(--aw-ring, #222)`. Inserisci l'SVG nell'HTML della pagina (non in `<img>`: lì le variabili non passano) e imposta le variabili:

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

Senza alcuna variabile, la carta appare esattamente come `light`. La regola CSS della tua pagina è più forte della variabile, quindi un singolo elemento può essere ricolorato con una classe.

| Variabile | Cosa colora |
|---|---|
| `--aw-chart-bg` | sfondo della carta |
| `--aw-fg`, `--aw-muted` | glifi e etichette, testo secondario e tacche |
| `--aw-ring` | cerchi e linee della griglia |
| `--aw-houses-fill` | campo della carta vedica, disco della carta stellare, mappa dell'eclissi |
| `--aw-benefic` | pianeti del cerchio esterno, lagna nella carta vedica, eventi della timeline senza un colore proprio |
| `--aw-malefic` | segno di retrogradazione ℞, fascia di eclissi |
| `--aw-aspect-harmonious`, `--aw-aspect-tense`, `--aw-aspect-neutral`, `--aw-aspect-minor`, `--aw-aspect-quintile` | linee e simboli degli aspetti |
| `--aw-moon-shadow`, `--aw-moon-light` | fase lunare |
| `--aw-cycle-physical`, `--aw-cycle-emotional`, `--aw-cycle-intellectual` | bioritmi |

## Classi e attributi data

Nel tema `css` le ruote occidentali (`wheel-western`, `bi-wheel`, `tri-wheel`, `composite`) e la griglia degli aspetti hanno classi fisse. I nomi vengono solo aggiunti, mai rinominati, quindi puoi scrivere stili e script su di essi.

- Ruota: `aw-bg`, `aw-ring`, `aw-sign aw-sign-leo`, `aw-sign-line`, `aw-tick`, `aw-house-cusp`, `aw-house-number`, assi `aw-axis aw-asc` (`aw-dsc`, `aw-mc`, `aw-ic`), le loro etichette `aw-label aw-axis-label`, titolo `aw-title`.
- Pianeta: gruppo `<g class="aw-planet aw-planet-sun">`, retrogrado ha anche `aw-retrograde`, pianeti del cerchio esterno `aw-layer-1`. All'interno `aw-glyph`, `aw-retro` (segno ℞) e `aw-planet-tick`.
- Aspetto: linea `aw-aspect aw-aspect-trine`, linea tra due carte anche `aw-cross-aspect`.
- Griglia degli aspetti: `aw-grid-header`, `aw-grid-cell`, `aw-aspect aw-aspect-square`, `aw-orb`.

Il gruppo del pianeta ha `data-planet` (`sun`, `north-node`, `lilith`; sul cerchio esterno `b-sun`, sul terzo `c-sun`) e `data-label` con nome e posizione: `Mercury 8°00' Taurus, retrograde`. La linea dell'aspetto e la cella della griglia hanno `data-a` e `data-b`. Così vengono evidenziati tutti gli aspetti del pianeta al passaggio del mouse:

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

## Le tue etichette: labels

Le ruote occidentali accettano `options.labels`: le tue parole per le etichette degli assi, per `<title>` e `<desc>`, che vengono lette dagli screen reader, e per i nomi in `data-label`. Le chiavi mancanti rimangono in inglese; noi stessi non traduciamo nulla.

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

`bodies` ha chiavi in inglese (`Sun`, `North Node`), `signs` sono esattamente dodici nomi, a partire dall'Ariete, ogni etichetta fino a 40 caratteri.

## Aspetti tra due carte

`/v1/render/bi-wheel` con `options.crossAspects: true` disegna con un tratteggio gli aspetti tra la carta interna e quella esterna, lo stesso set che `POST /v1/synastry` restituisce come `crossAspects`. Una coppia in cui uno dei corpi non è disegnato viene saltata. Disabilitato di default.

## Carta pronta invece dei dati di nascita

Se hai già la carta, perché hai appena chiamato `POST /v1/chart`, invia i suoi `data` nel campo `chart` invece dei dati di nascita, e noi la disegneremo soltanto. Così funzionano `wheel-western`, `aspect-grid` e `bi-wheel` (lì `natal.chart` e `outer.chart`, entrambi devono essere carte pronte). L'immagine risulterà byte per byte la stessa che con i dati di nascita.

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

I campi extra della risposta possono non essere tagliati. Viene controllato ciò che viene disegnato: da 1 a 30 corpi, longitudini da 0 a 360, esattamente 12 cuspidi. Un corpo che ha sia `chart` che i dati di nascita viene rifiutato con 400.

## Costo

La chiamata a `/v1/render/*` con i dati di nascita costa 10 crediti, perché la carta viene calcolata. Con una carta `chart` pronta, le chiamate a `/v1/render/wheel-western`, `/v1/render/aspect-grid` e `/v1/render/bi-wheel` costano 1 credito. Tema, classi ed etichette non influiscono sul prezzo.