Eclipse path, cosmogram і Vedic-карти: pure-SVG візуалізатори без headless-Chrome

Категорія Visualization на нашому роадмапі закрита 14/14: шість фінальних ендпоінтів закривають специфічні layout-и, для яких немає готового npm-пакета — Vedic-чарти у трьох регіональних стилях, Hamburg-School cosmogram, eclipse-path на світовій мапі та stereographic star-map.

Ключове рішення: усі рендери — pure SVG-стрінг, без headless Chrome. Це значить subsecond response, низький cost-per-call, і можливість inline-у в будь-який email/PDF/web-документ.

Більшість publication-grade astrology-картинок створюються через Chromium з SVG-шаблоном — це нормально для PDF-репортів. Але /v1/render/* ендпоінти орієнтовані на програмний рендер у real-time:

• inline у dashboard React-компоненті
• embed у email-кампанію
• передача в LLM-агент для multimodal aналізу

Headless Chrome не підходить — RAM-cost і latency не дозволяють викликати його по 100 разів/хв на одну партію. Тому всі шість рендерерів — це чистий string-builder, який емітить SVG-розмітку через template-функції. Latency під 100мс навіть на холодному кешу.

В Indian-astrology традиція знає три layout-и натальної карти, і кожен має культурний weight у своєму регіоні:

Класичний “diamond” layout: 1-й будинок завжди вгорі (фіксовані houses), знаки обертаються залежно від Lagna. Поширений у більшості hindi-mainstream consultations.

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",
    "timezoneOffset": 3,
    "latitude": 50.45,
    "longitude": 30.52,
    "options": { "format": "svg" }
  }'

Можна попросити SVG-стрінг (format: "svg") або JSON-обгортку з { svg, byteLength } (format: "json", default).

Квадратна сітка 4×4, знаки фіксовані (Pisces завжди top-left, інші за годинниковою стрілкою), номера будинків плавають за Lagna. Поширений у Tamil Nadu, Kerala, Karnataka.

Квадрат із діагоналями + внутрішній повернутий квадрат — гібридна геометрія. Найменш відома з трьох на Заході, але обов’язкова для Bengali-orientation продуктів.

Усі три приймають той самий chart-payload — endpoint обирається за стилем візуалізації.

POST /v1/render/cosmogram — це не натальне коло. Це 90°-дайл, де всі hard aspects (0°/90°/180°) колапсують у з’єднання. Інструмент розроблений Альфредом Вітте (Witte 1928) і пізніше формалізований Райнгольдом Ебертіном (Ebertin 1940) як основа cosmobiology.

Чому це корисно: на стандартному 360°-чарті жорсткі аспекти “розмазані” по колу, важко зчитати кластери. На 90°-дайлі вони стають візуально очевидні — кластер з 3-4 планет в одному 22.5°-секторі видно одразу.

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",
    "timezoneOffset": 3,
    "latitude": 50.45,
    "longitude": 30.52
  }'

Поверне SVG з квадратом 4×22.5° (cardinal sectors) + положеннями планет на одному обертанні 90°.

POST /v1/render/eclipse-path приймає caller-supplied lat/lon track для лінії центральності затемнення та опціонально band-width у градусах. Рендер — equirectangular world map (стандартна проекція WGS-84) з 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 — це навмисний design choice. Eclipse-path data приходить з різних канонічних джерел (NASA Eclipse Catalog, Five Millennium Canon of Solar Eclipses від Espenak & Meeus), кожне з власною точністю. Endpoint не намагається replikувати NASA computation — він рендерить ваш track красиво. Як data source ми рекомендуємо NASA Eclipse Web Site, але це поза скоупом цього endpoint-а.

Use case. Educational app, який показує наступне затемнення з трасою через карту. Або astrology-consultation, який хоче візуалізувати “wave” затемнення через важливі для нативу локації.

POST /v1/render/star-map приймає список точок (RA/Dec) з опціональною magnitude та glyph, рендерить stereographic projection. Magnitude мапиться на radius point-а (яскравіша зірка = більший круг).

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

Параметри:

• points — від 1 до 2000 зірок/об’єктів
• observerLatDeg + zenithDecDeg — для коректної проекції з точки спостерігача
• capAltitudeDeg — обмеження висоти (наприклад, -18 для астрономічних сутінок)

Use case. Sky-tonight widget у astrology-app. Vedic натальний контекст з зорями-наксатрами, накладеними на справжні координати. Education-продукт із картою сузір’їв.

Якщо потрібен raster (для соц-сетей, email, 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

SVG → PNG конверсія через sharp додає ~150мс, що все одно дешевше за headless Chrome. Альтернативно — залиште як SVG і вставте inline у HTML через template-systems (Astro, Vue, React component із прямим виведенням string-у через відповідний механізм фреймворку із pre-санітизацією).

Усі шість /v1/render/* ендпоінтів цієї партії — Tier 2 (20 credits). Конкретні credit-числа дивись на Pricing.

Документація з повними схемами параметрів — у /docs/api/ → Render. Vedic-формати, cosmogram, eclipse-path і star-map — кожен з прикладом параметрів та response-сним SVG.