Eclipse path, cosmogram a Vedic karty: pure-SVG vizualizéry bez headless-Chrome

Kategorie Visualization na naší roadmapě je uzavřena 14/14: šest finálních endpointů pokrývá specifické layouty, pro které neexistuje hotový npm balíček – védské grafy ve třech regionálních stylech, kosmogram Hamburské školy, dráha zatmění na světové mapě a stereografická hvězdná mapa.

Klíčové rozhodnutí: všechny rendery jsou čistý SVG string, bez headless Chrome. To znamená subsekundovou odezvu, nízké náklady na volání a možnost vložení do jakéhokoli e-mailu/PDF/webového dokumentu.

Většina astrologických obrázků v publikační kvalitě se vytváří pomocí Chromia s SVG šablonou – to je normální pro PDF reporty. Ale endpointy /v1/render/* jsou zaměřeny na programový render v reálném čase:

• inline v React komponentě dashboardu
• vložení do e-mailové kampaně
• předání LLM agentovi pro multimodální analýzu

Headless Chrome není vhodný – náklady na RAM a latence neumožňují volat jej 100krát/min na jednu dávku. Proto všech šest rendererů je čistý string-builder, který emituje SVG markup pomocí template funkcí. Latence pod 100 ms i na studené cache.

V indické astrologické tradici existují tři layouty natální mapy a každý má ve svém regionu kulturní váhu:

Klasický “diamond” layout: 1. dům je vždy nahoře (fixní houses), znamení se otáčejí v závislosti na Lagně. Rozšířený ve většině hindských mainstreamových konzultací.

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

Můžeš si vyžádat SVG string (format: "svg") nebo JSON obálku s { svg, byteLength } (format: "json", default).

Čtvercová mřížka 4×4, znamení jsou fixní (Ryby vždy vlevo nahoře, ostatní po směru hodinových ručiček), čísla domů se pohybují podle Lagny. Rozšířený v Tamil Nadu, Kerale, Karnatace.

Čtverec s diagonálami + vnitřní otočený čtverec – hybridní geometrie. Nejméně známý ze tří na Západě, ale nezbytný pro produkty s bengálskou orientací.

Všechny tři přijímají stejný chart-payload – endpoint se vybírá podle stylu vizualizace.

POST /v1/render/cosmogram – to není natální kruh. Je to 90° ciferník, kde se všechny tvrdé aspekty (0°/90°/180°) kolabují do konjunkce. Nástroj vyvinul Alfred Witte (Witte 1928) a později formalizoval Reinhold Ebertin (Ebertin 1940) jako základ kosmobiologie.

Proč je to užitečné: na standardním 360° grafu jsou tvrdé aspekty “rozmazané” po kruhu, je obtížné číst shluky. Na 90° ciferníku se stávají vizuálně zřejmými – shluk 3-4 planet v jednom 22.5° sektoru je viditelný okamžitě.

curl -X POST https://api.astroway.info/v1/render/cosmogram \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "date": "1990-05-15",
    "time": "14:30:00",
    "timezoneOffset": 3,
    "latitude": 50.45,
    "longitude": 30.52
  }'

Vrátí SVG se čtvercem 4×22.5° (kardinální sektory) + pozicemi planet na jedné 90° rotaci.

POST /v1/render/eclipse-path přijímá caller-supplied lat/lon track pro linii centrality zatmění a volitelně šířku pásma ve stupních. Render je ekvirektangulární mapa světa (standardní projekce WGS-84) s graticule + path-line + band-overlay.

curl -X POST https://api.astroway.info/v1/render/eclipse-path \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "path": [
      { "latitude": 38.5, "longitude": -125.0, "time": "2026-08-12T17:30Z" },
      { "latitude": 41.2, "longitude": -105.3, "time": "2026-08-12T17:42Z" },
      { "latitude": 44.8, "longitude": -85.7, "time": "2026-08-12T17:54Z" }
    ],
    "bandWidthDeg": 1.2,
    "title": "Eclipse 2026-08-12",
    "options": { "width": 1200, "height": 600, "showGraticule": true, "pathColor": "#ff5500" }
  }'

Caller-supplied path – to je záměrná designová volba. Data o dráze zatmění pocházejí z různých kanonických zdrojů (NASA Eclipse Catalog, Five Millennium Canon of Solar Eclipses od Espenak & Meeus), každý s vlastní přesností. Endpoint se nesnaží replikovat výpočty NASA – renderuje tvůj track krásně. Jako datový zdroj doporučujeme NASA Eclipse Web Site, ale to je mimo rozsah tohoto endpointu.

Případ použití. Vzdělávací aplikace, která ukazuje další zatmění s trasou přes mapu. Nebo astrologická konzultace, která chce vizualizovat “vlnu” zatmění přes důležité lokace pro nativa.

POST /v1/render/star-map přijímá seznam bodů (RA/Dec) s volitelnou magnitudou a glyfem, renderuje stereografickou projekci. Magnituda se mapuje na poloměr bodu (jasnější hvězda = větší kruh).

curl -X POST https://api.astroway.info/v1/render/star-map \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "points": [
      { "raHours": 5.92, "decDeg": 7.41, "magnitude": 0.45, "name": "Betelgeuse" },
      { "raHours": 6.75, "decDeg": -16.72, "magnitude": -1.46, "name": "Sirius" },
      { "raHours": 5.24, "decDeg": -8.20, "magnitude": 0.18, "name": "Rigel" }
    ],
    "observerLatDeg": 50.45,
    "zenithDecDeg": 50.45,
    "capAltitudeDeg": -18,
    "title": "Sky at midnight, Kyiv"
  }'

Parametry:

• points: od 1 do 2000 hvězd/objektů
• observerLatDeg + zenithDecDeg: pro korektní projekci z bodu pozorovatele
• capAltitudeDeg: omezení výšky (například -18 pro astronomický soumrak)

Případ použití. Widget “Obloha dnes večer” v astrologické aplikaci. Védický natální kontext s hvězdami-nakšatrami, překrytými na skutečné souřadnice. Vzdělávací produkt s mapou souhvězdí.

Pokud potřebuješ raster (pro sociální sítě, e-mail, push), pipeline:

import { Astroway } from "@astroway/sdk";
import sharp from "sharp";

const client = new Astroway({ apiKey: process.env.ASTROWAY_KEY });

const { svg } = await client.render.eclipsePath({
  path: eclipseTrack,
  bandWidthDeg: 1.2,
  options: { width: 1200, height: 600, format: "json" },
});

const png = await sharp(Buffer.from(svg))
  .resize(1200, 600)
  .png()
  .toBuffer();

// upload to CDN, get URL

Konverze SVG → PNG přes sharp přidává ~150 ms, což je stále levnější než headless Chrome. Alternativně – ponech jako SVG a vlož inline do HTML přes template-systémy (Astro, Vue, React komponenta s přímým výstupem stringu přes odpovídající mechanismus frameworku s pre-sanitizací).

Všech šest renderovacích endpointů této dávky – Tier 1: 10 kreditů za volání. Kompletní tabulka tarifů – na Ceny.

Dokumentace s kompletními schématy parametrů – v /docs/api/ → Render. Védské formáty, kosmogram, dráha zatmění a hvězdná mapa – každý s příkladem parametrů a response-ovým SVG.