Eclipse path, cosmogram và bản đồ Vedic: trình trực quan hóa pure-SVG không cần headless-Chrome

Hạng mục Visualization trong lộ trình của chúng tôi đã hoàn thành 14/14: sáu endpoint cuối cùng bao gồm các bố cục đặc thù mà không có gói npm sẵn có - biểu đồ Vedic theo ba phong cách khu vực, cosmogram Hamburg-School, đường đi nhật thực trên bản đồ thế giới và bản đồ sao lập thể.

Quyết định then chốt: tất cả các bản render đều là chuỗi SVG thuần túy, không dùng headless Chrome. Điều này có nghĩa là phản hồi dưới một giây, chi phí mỗi lần gọi thấp và khả năng nhúng trực tiếp vào bất kỳ tài liệu email/PDF/web nào.

Hầu hết các hình ảnh chiêm tinh chất lượng xuất bản được tạo thông qua Chromium với mẫu SVG - điều này là bình thường đối với các báo cáo PDF. Nhưng các endpoint /v1/render/* được định hướng cho render lập trình theo thời gian thực:

• nhúng trực tiếp vào thành phần React của dashboard
• nhúng vào chiến dịch email
• truyền cho tác nhân LLM để phân tích đa phương thức

Headless Chrome không phù hợp - chi phí RAM và độ trễ không cho phép gọi nó 100 lần/phút cho một lô. Do đó, tất cả sáu trình render đều là một trình tạo chuỗi thuần túy, xuất ra đánh dấu SVG thông qua các hàm mẫu. Độ trễ dưới 100ms ngay cả với bộ nhớ đệm lạnh.

Trong truyền thống chiêm tinh Ấn Độ, có ba bố cục biểu đồ sinh, và mỗi bố cục đều có trọng lượng văn hóa ở khu vực của nó:

Bố cục “kim cương” cổ điển: nhà thứ 1 luôn ở trên cùng (các nhà cố định), các cung hoàng đạo xoay tùy thuộc vào Lagna. Phổ biến trong hầu hết các buổi tư vấn chính thống tiếng 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" }
  }'

Bạn có thể yêu cầu chuỗi SVG (format: "svg") hoặc một đối tượng JSON { svg, byteLength } (format: "json", mặc định).

Lưới vuông 4×4, các cung hoàng đạo cố định (Song Ngư luôn ở trên cùng bên trái, các cung khác theo chiều kim đồng hồ), số nhà thay đổi theo Lagna. Phổ biến ở Tamil Nadu, Kerala, Karnataka.

Hình vuông có đường chéo + hình vuông bên trong xoay - một hình học lai. Ít được biết đến nhất trong ba loại ở phương Tây, nhưng bắt buộc đối với các sản phẩm định hướng Bengali.

Cả ba đều chấp nhận cùng một chart-payload - endpoint được chọn theo kiểu trực quan hóa.

POST /v1/render/cosmogram - đây không phải là vòng tròn sinh. Đây là mặt số 90°, nơi tất cả các khía cạnh cứng (0°/90°/180°) được gộp lại thành một sự kết hợp. Công cụ này được Alfred Witte (Witte 1928) phát triển và sau đó được Reinhold Ebertin (Ebertin 1940) chính thức hóa làm nền tảng của cosmobiology.

Tại sao điều này hữu ích: trên biểu đồ 360° tiêu chuẩn, các khía cạnh cứng bị “phân tán” quanh vòng tròn, khó đọc các cụm. Trên mặt số 90°, chúng trở nên rõ ràng về mặt hình ảnh - một cụm 3-4 hành tinh trong một cung 22.5° có thể được nhìn thấy ngay lập tức.

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

Sẽ trả về SVG với một hình vuông 4×22.5° (các cung chính) + vị trí các hành tinh trên một vòng quay 90°.

POST /v1/render/eclipse-path chấp nhận đường theo dõi vĩ độ/kinh độ do người gọi cung cấp cho đường trung tâm của nhật thực và tùy chọn chiều rộng dải theo độ. Render là bản đồ thế giới hình chữ nhật đều (phép chiếu WGS-84 tiêu chuẩn) với lưới kinh vĩ tuyến + đường đi + lớp phủ dải.

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

Đường dẫn do người gọi cung cấp - đây là một lựa chọn thiết kế có chủ ý. Dữ liệu đường đi nhật thực đến từ nhiều nguồn chính thống khác nhau (NASA Eclipse Catalog, Five Millennium Canon of Solar Eclipses của Espenak & Meeus), mỗi nguồn có độ chính xác riêng. Endpoint không cố gắng tái tạo tính toán của NASA - nó render đường đi của bạn một cách đẹp mắt. Chúng tôi khuyến nghị NASA Eclipse Web Site làm nguồn dữ liệu, nhưng điều này nằm ngoài phạm vi của endpoint này.

Trường hợp sử dụng. Ứng dụng giáo dục hiển thị nhật thực tiếp theo với đường đi trên bản đồ. Hoặc tư vấn chiêm tinh muốn trực quan hóa “làn sóng” nhật thực qua các địa điểm quan trọng đối với người bản địa.

POST /v1/render/star-map chấp nhận danh sách các điểm (RA/Dec) với độ lớn và ký hiệu tùy chọn, render phép chiếu lập thể. Độ lớn được ánh xạ tới bán kính của điểm (ngôi sao sáng hơn = vòng tròn lớn hơn).

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

Các tham số:

• points: từ 1 đến 2000 ngôi sao/đối tượng
• observerLatDeg + zenithDecDeg: để chiếu chính xác từ điểm quan sát
• capAltitudeDeg: giới hạn độ cao (ví dụ, -18 cho chạng vạng thiên văn)

Trường hợp sử dụng. Widget bầu trời đêm nay trong ứng dụng chiêm tinh. Ngữ cảnh sinh Vedic với các ngôi sao Nakshatra được phủ lên các tọa độ thực. Sản phẩm giáo dục với bản đồ chòm sao.

Nếu cần raster (cho mạng xã hội, email, push), quy trình:

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

Chuyển đổi SVG → PNG thông qua sharp thêm khoảng 150ms, nhưng vẫn rẻ hơn headless Chrome. Thay vào đó - hãy giữ nguyên định dạng SVG và nhúng trực tiếp vào HTML thông qua các hệ thống mẫu (Astro, Vue, thành phần React với việc xuất chuỗi trực tiếp thông qua cơ chế khung làm việc tương ứng với việc tiền xử lý).

Tất cả sáu endpoint render trong lô này - Bậc 1: 10 tín dụng cho mỗi lần gọi. Bảng giá đầy đủ có tại Pricing.

Tài liệu với các lược đồ tham số đầy đủ - trong /docs/api/ → Render. Các định dạng Vedic, cosmogram, eclipse-path và star-map - mỗi loại đều có ví dụ về tham số và SVG phản hồi.