Eclipse path, cosmogram و Vedic-خرائط: pure-SVG مُصَوِّرات بدون headless-Chrome

فئة Visualization على خارطة طريقنا مكتملة 14/14: ستة endpoints نهائية تغطي تخطيطات (layouts) محددة لا توجد حزمة npm جاهزة لها - مخططات Vedic بثلاثة أنماط إقليمية، كوزموغرام مدرسة هامبورغ (Hamburg-School cosmogram)، مسار الكسوف (eclipse-path) على خريطة العالم، وخريطة النجوم المجسمة (stereographic star-map).

القرار الرئيسي: جميع عمليات العرض (renders) هي سلاسل SVG خالصة، بدون headless Chrome. هذا يعني استجابة في أقل من ثانية، تكلفة منخفضة لكل استدعاء، وإمكانية تضمينها مباشرة في أي مستند بريد إلكتروني/PDF/ويب.

يتم إنشاء معظم صور علم التنجيم ذات الجودة العالية للنشر عبر Chromium باستخدام قالب SVG - وهذا أمر طبيعي لتقارير PDF. لكن endpoints /v1/render/* موجهة نحو العرض البرمجي في الوقت الفعلي:

• تضمين مباشر في مكون React للوحة القيادة
• تضمين في حملة بريد إلكتروني
• تمرير إلى وكيل LLM للتحليل متعدد الوسائط

Headless Chrome غير مناسب، فتكلفتها من حيث الذاكرة (RAM-cost) وزمن الاستجابة (latency) لا تسمح باستدعائها 100 مرة/دقيقة لكل دفعة. لذلك، فإن جميع أدوات العرض الستة هي منشئات سلاسل (string-builders) خالصة، تصدر ترميز SVG عبر دوال القوالب (template-functions). زمن استجابة أقل من 100 مللي ثانية حتى مع ذاكرة التخزين المؤقت الباردة.

في تقاليد علم التنجيم الهندي، هناك ثلاثة تخطيطات (layouts) للمخطط الفلكي (natal chart)، ولكل منها وزن ثقافي في منطقته:

التخطيط “الماسي” الكلاسيكي: المنزل الأول دائمًا في الأعلى (منازل ثابتة)، العلامات تدور اعتمادًا على Lagna. شائع في معظم الاستشارات الهندية السائدة.

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", الافتراضي).

شبكة مربعة 4×4، العلامات ثابتة (Pisces دائمًا في أعلى اليسار، والبقية في اتجاه عقارب الساعة)، أرقام المنازل تطفو وفقًا لـ Lagna. شائع في تاميل نادو، كيرالا، كارناتاكا.

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

جميع الثلاثة تقبل نفس حمولة المخطط (chart-payload) - يتم اختيار الـ endpoint بناءً على نمط التصور.

POST /v1/render/cosmogram - هذا ليس مخططًا فلكيًا (natal circle). إنه قرص 90 درجة، حيث تنهار جميع الجوانب الصعبة (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:00",
    "timezoneOffset": 3,
    "latitude": 50.45,
    "longitude": 30.52
  }'

سيعيد SVG بمربع 4×22.5 درجة (cardinal sectors) + مواقع الكواكب في دورة واحدة بزاوية 90 درجة.

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

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

حالة الاستخدام. تطبيق تعليمي يعرض الكسوف التالي مع مساره عبر الخريطة. أو استشارة فلكية ترغب في تصور “موجة” الكسوف عبر المواقع المهمة للمولود.

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

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 لشفق فلكي)

حالة الاستخدام. أداة “سماء الليلة” (Sky-tonight widget) في تطبيق فلكي. سياق فلكي فيديك (Vedic natal context) مع نجوم ناكشاترا (nakshatras) مطبقة على الإحداثيات الحقيقية. منتج تعليمي مع خريطة للأبراج.

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

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

الوثائق مع مخططات المعلمات الكاملة - في /docs/api/ → Render. تنسيقات Vedic، الكوزموغرام، مسار الكسوف، وخريطة النجوم - كل منها مع مثال للمعلمات و SVG المستجيب.