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

Категорія Visualization na našem roadmapu je uzavřena 14/14: šest finálních endpointů uzavírá specifické layouty, pro které není připravený npm balíček - Vedic grafy ve třech regionálních stylech, Hamburg-School cosmogram, eclipse-path na světové mapě a stereografická hvězdná mapa.

Klíčové řešení: všechny renderery jsou čistý SVG řetězec, bez headless Chrome. To znamená subsecond response, nízký cost-per-call a možnost inline vložení do jakéhokoli e-mailu/PDF/web dokumentu.

Většina publikací hodných astrologických obrázků se vytváří přes Chromium se SVG šablonou - je to normální pro PDF sestavy. Ale endpointy /v1/render/* jsou zaměřeny na programový render v reálném čase:

• inline v dashboard React komponentě
• embed 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 za minutu na jednu dávku. Proto všech šest renderérů je čistý string-builder, který produkuje SVG značku prostřednictvím šablonových funkcí. Latence pod 100 ms i při studeném cache.

V indické astrologii tradice zná tři layouty natální karty, a každý má kulturní váhu ve svém regionu:

Klasický ‘diamond’ layout: 1. dům je vždy nahoře (pevné domy), znamení se otáčejí v závislosti na Lagna. Rozšířený ve většině hindských mainstream 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š požadovat SVG řetězec (format: "svg") nebo JSON obálku s { svg, byteLength } (format: "json", výchozí).

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

Čtverec s diagonálami + vnitřní otočený čtverec - hybridní geometrie. Nejméně známá ze tří na Západě, ale povinná pro produkty orientované na Bengálsko.

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

POST /v1/render/cosmogram - to není natalní kolo. Jedná se o 90° ciferník, kde všechny tvrdé aspekty (0°/90°/180°) kolabují do spojení. Nástroj vyvinul Alfred Witte (Witte 1928) a později jej formalizoval Reinhold Ebertin (Ebertin 1940) jako základ cosmobiologie.

Proč je to užitečné: na standardním 360° grafu jsou tvrdé aspekty „rozmazané“ po kruhu, těžko se čtou klastry. Na 90° ciferníku se stávají vizuálně zřejmými - klastr 3-4 planet v jednom sektoru 22,5° je vidět 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 s čtvercem 4×22,5° (kardinální sektory) + pozicemi planet na jednom otočení 90°.

POST /v1/render/eclipse-path přijímá lat/lon track poskytnutý volajícím pro linii centrality zatmění a volitelně šířku pásma ve stupních. Výstup je rovníková světová mapa (standardní projekce WGS-84) s graticule + čárou trasy + překrytím pásma.

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" }
  }'

Cesta poskytnutá volajícím je záměrná volba designu. Data eclipse-path pocházejí z různých kanonických zdrojů (NASA Eclipse Catalog, Five Millennium Canon of Solar Eclipses od Espenaka & Meeus), každá s vlastní přesností. Endpoint se nesnaží replikovat výpočet NASA - jednoduše vykreslí váš track pěkně. Jako zdroj dat doporučujeme NASA Eclipse Web Site, ale to je mimo rozsah tohoto endpointu.

Příklad použití. Vzdělávací aplikace, která ukazuje následující zatmění se stopou na mapě. Nebo astrologická konzultace, která chce vizualizovat „vlnu“ zatmění přes důležitá místa pro rodilého.

POST /v1/render/star-map přijímá seznam bodů (RA/Dec) s volitelnou magnitudou a glyfem, vykreslí 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: 1 až 2000 hvězd/objektů
• observerLatDeg + zenithDecDeg: pro správnou projekci z pozorovatele
• capAltitudeDeg: omezení výšky (např. -18 pro astronomický soumrak)

Příklad použití. Widget Sky-tonight v astrologické aplikaci. Vedický natální kontext s hvězdami-nakshatrami naloženými na skutečné souřadnice. Vzdělávací produkt s mapou souhvězdí.

Pokud potřebuješ rastrový obrázek (pro sociální sítě, e-mail, push), kanál:

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

Převod SVG → PNG přes sharp přidá ~150 ms, což je stále levnější než headless Chrome. Alternativně můžeš nechat jako SVG a vložit inline do HTML přes systémy šablon (Astro, Vue, React komponenta s přímým výstupem řetězce prostřednictvím příslušného mechanismu frameworku s předchozí sanitizací).

Všech šest endpointů /v1/render/* této partie - Tier 1: 10 kreditů za volání. Úplný ceník je na Ceník.

Dokumentace s úplnými schématy parametrů - v /docs/api/ → Render. Vedic formáty, cosmogram, eclipse-path a star-map - každý s příkladem parametrů a odpovědí ve formátu SVG.