Eclipse path, cosmogram i Vedic-mapy: pure-SVG wizualizatory bez headless-Chrome

Kategoria Visualization na naszej mapie drogowej jest zamknięta 14/14: sześć finalnych endpointów obejmuje specyficzne layouty, dla których nie ma gotowego pakietu npm – wykresy wedyjskie w trzech stylach regionalnych, kosmogram Szkoły Hamburskiej, ścieżka zaćmienia na mapie świata oraz stereograficzna mapa gwiazd.

Kluczowa decyzja: wszystkie rendery to czysty string SVG, bez headless Chrome. Oznacza to odpowiedź w czasie poniżej sekundy, niski koszt za wywołanie i możliwość wstawienia inline do dowolnego dokumentu email/PDF/web.

Większość grafik astrologicznych o jakości publikacyjnej jest tworzona za pomocą Chromium z szablonem SVG – to normalne dla raportów PDF. Ale endpointy /v1/render/* są zorientowane na programowy render w czasie rzeczywistym:

• inline w komponencie React dashboardu
• osadzenie w kampanii e-mailowej
• przekazanie do agenta LLM do analizy multimodalnej

Headless Chrome nie nadaje się – koszt pamięci RAM i opóźnienie nie pozwalają na wywoływanie go 100 razy/minutę dla jednej partii. Dlatego wszystkie sześć rendererów to czysty string-builder, który emituje znacznik SVG za pomocą funkcji szablonowych. Opóźnienie poniżej 100 ms nawet na zimnej pamięci podręcznej.

W tradycji astrologii indyjskiej znane są trzy layouty mapy natalnej, a każdy z nich ma kulturowe znaczenie w swoim regionie:

Klasyczny layout “diamentowy”: 1. dom zawsze na górze (stałe houses), znaki obracają się w zależności od Lagny. Powszechny w większości głównych konsultacji hindi.

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

Możesz poprosić o string SVG (format: "svg") lub opakowanie JSON z { svg, byteLength } (format: "json", domyślnie).

Kwadratowa siatka 4×4, znaki stałe (Ryby zawsze w lewym górnym rogu, pozostałe zgodnie z ruchem wskazówek zegara), numery domów zmieniają się wraz z Lagną. Powszechny w Tamil Nadu, Kerali, Karnatace.

Kwadrat z przekątnymi + wewnętrzny obrócony kwadrat – geometria hybrydowa. Najmniej znana z trzech na Zachodzie, ale obowiązkowa dla produktów zorientowanych na Bengal.

Wszystkie trzy przyjmują ten sam chart-payload – endpoint jest wybierany na podstawie stylu wizualizacji.

POST /v1/render/cosmogram – to nie jest koło natalne. To tarcza 90°, gdzie wszystkie hard aspects (0°/90°/180°) zbiegają się w koniunkcję. Narzędzie opracowane przez Alfreda Witte (Witte 1928) i później sformalizowane przez Reinholda Ebertina (Ebertin 1940) jako podstawa kosmobiologii.

Dlaczego to jest przydatne: na standardowym wykresie 360° twarde aspekty są “rozmazane” po okręgu, trudno odczytać klastry. Na tarczy 90° stają się one wizualnie oczywiste – klaster 3-4 planet w jednym sektorze 22.5° jest widoczny od razu.

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

Zwróci SVG z kwadratem 4×22.5° (cardinal sectors) + położeniami planet na jednym obrocie 90°.

POST /v1/render/eclipse-path przyjmuje dostarczony przez wywołującego lat/lon track dla linii centralności zaćmienia oraz opcjonalnie band-width w stopniach. Render to equirectangular world map (standardowa projekcja WGS-84) z 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 celowy wybór projektowy. Dane o ścieżce zaćmienia pochodzą z różnych kanonicznych źródeł (NASA Eclipse Catalog, Five Millennium Canon of Solar Eclipses od Espenak & Meeus), każde z własną dokładnością. Endpoint nie próbuje replikować obliczeń NASA – renderuje twój track pięknie. Jako data source polecamy NASA Eclipse Web Site, ale to wykracza poza zakres tego endpointu.

Przypadek użycia. Aplikacja edukacyjna, która pokazuje następne zaćmienie z trasą na mapie. Lub astrology-consultation, która chce zwizualizować “falę” zaćmienia przez ważne dla natywa lokalizacje.

POST /v1/render/star-map przyjmuje listę punktów (RA/Dec) z opcjonalną magnitude i glyph, renderuje stereographic projection. Magnitude jest mapowana na radius punktu (jaśniejsza gwiazda = większe koło).

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 gwiazd/obiektów
• observerLatDeg + zenithDecDeg: dla poprawnej projekcji z punktu obserwatora
• capAltitudeDeg: ograniczenie wysokości (na przykład -18 dla zmierzchu astronomicznego)

Przypadek użycia. Widget “niebo dziś wieczorem” w astrology-app. Wedyjski kontekst natalny z gwiazdami-nakszatrami nałożonymi na prawdziwe współrzędne. Produkt edukacyjny z mapą konstelacji.

Jeśli potrzebujesz rastra (do mediów społecznościowych, e-maila, 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

Konwersja SVG → PNG za pomocą sharp dodaje ~150 ms, co i tak jest tańsze niż headless Chrome. Alternatywnie – zostaw jako SVG i wstaw inline do HTML za pomocą template-systems (Astro, Vue, komponent React z bezpośrednim wyprowadzeniem stringa za pomocą odpowiedniego mechanizmu frameworka z pre-sanitizacją).

Wszystkie sześć endpointów renderowania z tej partii – Tier 1: 10 kredytów za wywołanie. Pełna tabela taryf – na Cennik.

Dokumentacja z pełnymi schematami parametrów – w /docs/api/ → Render. Formaty wedyjskie, kosmogram, eclipse-path i star-map – każdy z przykładem parametrów i przykładowym SVG odpowiedzi.