Eclipse path, cosmogram και Vedic-χάρτες: pure-SVG visualizers χωρίς headless-Chrome

Η κατηγορία Visualization στον οδικό χάρτη μας ολοκληρώθηκε 14/14: έξι τελικά endpoints καλύπτουν συγκεκριμένες διατάξεις (layouts) για τις οποίες δεν υπάρχει έτοιμο πακέτο npm - Vedic χάρτες σε τρία περιφερειακά στυλ, κοσμόγραμμα Σχολής του Αμβούργου, διαδρομή έκλειψης σε παγκόσμιο χάρτη και στερεογραφικό χάρτη αστεριών.

Βασική απόφαση: όλες οι αποδόσεις - καθαρό SVG string, χωρίς headless Chrome. Αυτό σημαίνει subsecond response, χαμηλό κόστος ανά κλήση, και δυνατότητα ενσωμάτωσης (inline) σε οποιοδήποτε έγγραφο email/PDF/web.

Οι περισσότερες εικόνες αστρολογίας ποιότητας δημοσίευσης δημιουργούνται μέσω Chromium με ένα πρότυπο SVG - αυτό είναι φυσιολογικό για αναφορές PDF. Όμως τα endpoints /v1/render/* είναι προσανατολισμένα στην προγραμματική απόδοση σε πραγματικό χρόνο:

• ενσωμάτωση (inline) σε ένα React component πίνακα ελέγχου
• ενσωμάτωση (embed) σε μια καμπάνια email
• μεταφορά σε έναν LLM-agent για πολυτροπική ανάλυση

Το Headless Chrome δεν είναι κατάλληλο - το κόστος RAM και η καθυστέρηση (latency) δεν επιτρέπουν την κλήση του 100 φορές/λεπτό για μία παρτίδα. Επομένως, και οι έξι renderers είναι καθαροί string-builders, οι οποίοι εκπέμπουν σήμανση SVG μέσω συναρτήσεων προτύπων. Η καθυστέρηση (latency) είναι κάτω από 100ms ακόμα και σε κρύα cache.

Στην Ινδική αστρολογία, η παράδοση γνωρίζει τρεις διατάξεις (layouts) γενέθλιου χάρτη, και κάθε μία έχει πολιτισμικό βάρος στην περιοχή της:

Κλασική διάταξη “διαμάντι”: ο 1ος οίκος είναι πάντα στην κορυφή (σταθεροί houses), τα ζώδια περιστρέφονται ανάλογα με τον Lagna. Διαδεδομένο στις περισσότερες 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 string (format: "svg") ή ένα JSON wrapper με { svg, byteLength } (format: "json", default).

Τετράγωνο πλέγμα 4×4, τα ζώδια είναι σταθερά (οι Ιχθύες πάντα πάνω αριστερά, τα υπόλοιπα δεξιόστροφα), οι αριθμοί των οίκων κινούνται ανάλογα με τον Lagna. Διαδεδομένο σε Tamil Nadu, Kerala, Karnataka.

Τετράγωνο με διαγώνιες + εσωτερικό περιστρεφόμενο τετράγωνο - υβριδική γεωμετρία. Η λιγότερο γνωστή από τις τρεις στη Δύση, αλλά απαραίτητη για προϊόντα με προσανατολισμό Μπενγκάλι.

Και οι τρεις δέχονται το ίδιο chart-payload - το endpoint επιλέγεται με βάση το στυλ οπτικοποίησης.

POST /v1/render/cosmogram - αυτό δεν είναι γενέθλιος κύκλος. Είναι ένα καντράν 90°, όπου όλες οι σκληρές όψεις (0°/90°/180°) συμπτύσσονται σε σύνοδο. Ένα εργαλείο που αναπτύχθηκε από τον Alfred Witte (Witte 1928) και αργότερα επισημοποιήθηκε από τον Reinhold Ebertin (Ebertin 1940) ως βάση της κοσμοβιολογίας.

Γιατί είναι χρήσιμο: σε έναν τυπικό χάρτη 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° (καρδινάλιους τομείς) + τις θέσεις των πλανητών σε μία περιστροφή 90°.

POST /v1/render/eclipse-path δέχεται ένα caller-supplied lat/lon track για τη γραμμή κεντρικότητας της έκλειψης και προαιρετικά το εύρος ζώνης (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" }
  }'

Το caller-supplied path είναι μια σκόπιμη σχεδιαστική επιλογή. Τα δεδομένα διαδρομής έκλειψης προέρχονται από διάφορες κανονικές πηγές (NASA Eclipse Catalog, Five Millennium Canon of Solar Eclipses από τους Espenak & Meeus), καθεμία με τη δική της ακρίβεια. Το endpoint δεν προσπαθεί να αναπαράγει τους υπολογισμούς της NASA - αποδίδει όμορφα το track σου. Ως πηγή δεδομένων συνιστούμε το NASA Eclipse Web Site, αλλά αυτό είναι εκτός του πεδίου εφαρμογής αυτού του endpoint.

Περίπτωση χρήσης. Εκπαιδευτική εφαρμογή, η οποία δείχνει την επόμενη έκλειψη με τη διαδρομή της στον χάρτη. Ή μια αστρολογική συμβουλευτική, η οποία θέλει να οπτικοποιήσει το “κύμα” της έκλειψης μέσω σημαντικών τοποθεσιών για τον γενέθλιο.

POST /v1/render/star-map δέχεται μια λίστα σημείων (RA/Dec) με προαιρετική magnitude και glyph, αποδίδοντας στερεογραφική προβολή. Η 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 για αστρονομικό λυκόφως)

Περίπτωση χρήσης. Widget “Ο ουρανός απόψε” σε εφαρμογή αστρολογίας. Vedic γενέθλιο πλαίσιο με αστέρια-nakshatras, τοποθετημένα σε πραγματικές συντεταγμένες. Εκπαιδευτικό προϊόν με χάρτη αστερισμών.

Εάν χρειάζεσαι raster (για μέσα κοινωνικής δικτύωσης, email, push), η διαδικασία είναι:

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 προσθέτει ~150ms, κάτι που είναι ακόμα φθηνότερο από το headless Chrome. Εναλλακτικά - άφησέ το ως SVG και ενσωμάτωσέ το (inline) σε HTML μέσω συστημάτων προτύπων (Astro, Vue, React component με άμεση έξοδο string μέσω του αντίστοιχου μηχανισμού του framework με προ-απολύμανση).

Όλα τα έξι endpoints απόδοσης αυτής της παρτίδας - Tier 1: 10 μονάδες ανά κλήση. Ο πλήρης πίνακας τιμών - στο Pricing.

Η τεκμηρίωση με πλήρη σχήματα παραμέτρων - στο /docs/api/ → Render. Vedic μορφές, cosmogram, eclipse-path και star-map - κάθε ένα με παράδειγμα παραμέτρων και SVG απόκρισης.