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 في مكوّن React للوحة التحكم
• embed في حملة بريد إلكتروني
• نقل إلى وكيل LLM للتحليل المتعدد الوسائط

Headless Chrome لا يناسب - RAM‑cost و latency لا يسمحان باستدعائه 100 مرة/دقيقة على دفعة واحدة. لذلك جميع الستة renderers هي string‑builder نقي، يُصدر SVG عبر template‑функції. Latency تحت 100 ms حتى على ذاكرة تخزين مؤقت باردة.

في Indian‑astrology التقليد يعرف ثلاثة layout‑и لخرائط الميلاد، ولكل منها وزن ثقافي في منطقته:

التخطيط الكلاسيكي “diamond”: البيت الأول دائمًا في الأعلى (بيوت ثابتة)، العلامات تدور حسب Lagna. شائع في معظم الاستشارات hindi‑mainstream.

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

يمكن طلب SVG‑стрінг (format: "svg") أو غلاف JSON مع { svg, byteLength } (format: "json", default).

شبكة مربعة 4×4، العلامات ثابتة (Pisces دائمًا في الأعلى‑يسار، والبقية باتجاه عقارب الساعة)، أرقام البيوت تتحرك حسب Lagna. شائع في Tamil Nadu، Kerala، Karnataka.

مربع مع أقطاب + مربع داخلي مدور - هندسة هجينة. الأقل شهرة من بين الثلاثة في الغرب، لكنه ضروري لمنتجات موجهة لـ Bengali.

جميع الثلاثة تقبل نفس chart‑payload - يتم اختيار endpoint حسب نمط التصور.

POST /v1/render/cosmogram - هذا ليس دائرة ميلاد. إنه قرص 90° حيث تتجمع جميع hard aspects (0°/90°/180°) في اتصال. الأداة طُورت بواسطة ألفريد ويت (Witte 1928) ولاحقًا صاغها راينغولد إبرتين (Ebertin 1940) كأساس للـ cosmobiology.

لماذا هذا مفيد: في الخريطة القياسية 360° تكون hard aspects “مبعثرة” حول الدائرة، يصعب قراءة التجمعات. في قرص 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:00",
    "timezoneOffset": 3,
    "latitude": 50.45,
    "longitude": 30.52
  }'

سيعيد SVG مع مربع 4×22.5° (cardinal sectors) + مواضع الكواكب على دوران واحد 90°.

POST /v1/render/eclipse-path يقبل مسار lat/lon مقدم من المتصل لخط مركزية الكسوف وخيارياً band‑width بالدرجات. العرض - خريطة عالمية إيكويركتنجولار (إسقاط 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" }
  }'

المسار المقدم من المتصل - هذا اختيار تصميم متعمد. بيانات Eclipse‑path تأتي من مصادر قانونية مختلفة (NASA Eclipse Catalog، Five Millennium Canon of Solar Eclipses من Espenak & Meeus)، كل منها بدقة خاصة. الـ Endpoint لا يحاول replikovať حسابات NASA - بل يرسم مسارك بشكل جميل. كمصدر بيانات نوصي بـ NASA Eclipse Web Site، لكن هذا خارج نطاق هذا endpoint.

Use case. تطبيق تعليمي يُظهر الكسوف التالي مع مسار عبر الخريطة. أو استشارة فلكية تريد تصور “موجة” الكسوف عبر المواقع المهمة للمواليد.

POST /v1/render/star-map يقبل قائمة نقاط (RA/Dec) مع magnitude اختياري و glyph، يرسم إسقاط stereographic. يتم ربط Magnitude بنقطة radius (نجم أكثر سطوعًا = دائرة أكبر).

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 في astrology‑app. سياق Vedic للولادة مع نجوم‑نقوش مدمجة على إحداثيات حقيقية. منتج تعليمي مع خريطة الأبراج.

إذا كنت بحاجة إلى raster (للشبكات الاجتماعية، البريد الإلكتروني، الإشعارات)، السلسلة:

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 ms، وهو لا يزال أرخص من headless Chrome. بدلاً من ذلك - احتفظ بـ SVG وأدرجه inline في HTML عبر أنظمة القوالب (Astro, Vue, React component مع إخراج مباشر للسلسلة عبر آلية الإطار المناسبة مع pre‑sanitization).

جميع الستة /v1/render/* endpoints لهذه الفئة - Tier 1: 10 أرصدة لكل استدعاء. جدول الأسعار الكامل - على التسعير.

الوثائق مع مخططات المعلمات الكاملة - في /docs/api/ → Render. صيغ Vedic، cosmogram، eclipse‑path و star‑map - كل منها مع مثال للمعلمات و response‑صورة SVG.