astro_chart 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ddcb896268ae30564a7041611a7811b707a7547affa849de1d4498bf2e1553f
-  data.tar.gz: 7773d2a228e636ad928e90f408fa36375e87bc0fc1a7745d6534a861269ea121
+  metadata.gz: 373643f3dc987aeb880aad6a15a5dd6a509367683c7ee1463ce7086b3e06980f
+  data.tar.gz: ec28b6b542ae7aaaa03997e744718b62dcf6a69c4372e1fcdb5196cb87110e4e
 SHA512:
-  metadata.gz: cee34349b951431356fb2a776d40e0ede18cfeafbdb6564221aed0e80374a623a4ed58fab8de96bd6b99b98a7593518fd7f6a9737a508dd0aba0be12a128a749
-  data.tar.gz: dff024c7b6f9dcfa20f5882eecc95ad99fcf0fc6381f187f2c072485694caabd094f107fd2a09865086700c24cfc72a7326b4b11dfffb800fd2ae3b03e284376
+  metadata.gz: e5a812f264e71b82bbe09489d7098254b29f0e7fb648c2eb84aa244091d7e62cebab9cfaa7420da59b44392227bc3dc1b110c1aaa6f6dbe02de60ab6a80e5a3a
+  data.tar.gz: 9c8e709366b24a5c28db55223c68edbfe1e705f9b9ec4d95f1e5dae1a6a72e6d8419597d900c80f832126b2bb53c930ddf636d4e7db93bc4ca7208346f8e8905

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.5.1 (2026-08-07)
+
+**Ecliptic latitude → accurate astrocartography.** Additive.
+
+- New `AstroChart::Ephemeris.ecliptic_latlon(jd, id)` — apparent geocentric
+  ecliptic [longitude, latitude] for the Sun, Moon, VSOP87 planets and Pluto
+  (the geocentric vector was already computed; latitude was simply discarded).
+- `Astrocartography.lines` now forms RA/Dec from each body's **true** ecliptic
+  latitude instead of β = 0, so the Moon and Pluto lines (β up to ~5° / ~17°)
+  are placed correctly. The longitude methods delegate to the new latitude-
+  aware ones, so planetary longitudes remain byte-identical (Swiss oracle spec
+  still passes).
+
+## 0.5.0 (2026-08-07)
+
+**Astrocartography (星象地圖).** All pure Ruby, additive.
+
+- New `AstroChart::Astrocartography.lines(jd)` — the relocational map lines for
+  the ten bodies at a birth instant: the MC and IC meridian longitudes, and
+  the ASC (rising) and DSC (setting) horizon curves as latitude/longitude
+  segments (broken where a body is circumpolar). Built from the body's RA/Dec
+  and Greenwich apparent sidereal time; verified independently (body altitude
+  ≈ 0 along every ASC/DSC point, LST = RA on the MC). Ecliptic latitude is
+  approximated as 0 (exact for the Sun; largest error for the Moon/Pluto).
+
 ## 0.4.0 (2026-08-06)
 
 **Traditional dignities, transit timing, two more house systems, minor

data/lib/astro_chart/astrocartography.rb

@@ -0,0 +1,109 @@
+require_relative "ephemeris"
+require_relative "pure/core"
+
+module AstroChart
+  # Astrocartography (星象地圖 / relocational lines).
+  #
+  # For a fixed birth instant, every body is angular (on the horizon or the
+  # meridian) along particular curves across the globe. We return, per body,
+  # four lines in geographic coordinates (longitude east-positive, −180..180):
+  #
+  #   MC  — the body culminates on the upper meridian (a vertical meridian).
+  #   IC  — the body is on the lower meridian (a vertical meridian).
+  #   ASC — the body rises on the eastern horizon (a curve of latitude points).
+  #   DSC — the body sets on the western horizon (a curve of latitude points).
+  #
+  # Method (Meeus, positional astronomy): from the body's apparent ecliptic
+  # longitude λ and the true obliquity ε we form its equatorial coordinates
+  # (RA α, Dec δ); with the Greenwich apparent sidereal time (GST):
+  #   MC longitude  = α − GST
+  #   IC longitude  = α − GST + 180°
+  # and at latitude φ the body is on the horizon when its hour angle is
+  #   H = ±arccos(−tanφ·tanδ)   (no solution ⇒ circumpolar, the line ends),
+  # rising at H = −H0 (eastern), setting at H = +H0 (western), giving
+  #   longitude = α + H − GST.
+  #
+  # RA/Dec use each body's true apparent ecliptic latitude (via
+  # Ephemeris.ecliptic_latlon), so the lines are accurate for the high-latitude
+  # bodies (Moon, Pluto) too — not just longitude-only approximations.
+  module Astrocartography
+    Core = Pure::Core
+    DEG2RAD = Core::DEG2RAD
+    RAD2DEG = Core::RAD2DEG
+
+    # The ten bodies conventionally mapped.
+    BODIES = ["太陽", "月亮", "水星", "金星", "火星", "木星",
+              "土星", "天王星", "海王星", "冥王星"].freeze
+
+    # Latitude span and step for the rising/setting curves (degrees).
+    LAT_MIN = -75
+    LAT_MAX = 75
+    LAT_STEP = 1
+
+    module_function
+
+    # jd_ut: birth Julian Day (UT).
+    # Returns Array of:
+    #   { "planet" => "太陽",
+    #     "mc" => <lon>, "ic" => <lon>,            # single geographic longitudes
+    #     "asc" => [ [ [lat,lon], ... ], ... ],    # rising curve, as segments
+    #     "dsc" => [ [ [lat,lon], ... ], ... ] }   # setting curve, as segments
+    def lines(jd_ut)
+      gst = Core.apparent_sidereal_deg(jd_ut)
+      eps = Core.true_obliquity(Core.jd_tt(jd_ut)) * DEG2RAD
+
+      BODIES.map do |name|
+        lam_deg, beta_deg = Ephemeris.ecliptic_latlon(jd_ut, Ephemeris::PLANETS[name])
+        lam = lam_deg * DEG2RAD
+        beta = beta_deg * DEG2RAD
+        # RA/Dec from apparent ecliptic longitude, latitude and obliquity
+        # (Meeus, Astronomical Algorithms, eqs. 13.3–13.4).
+        ra = Core.norm360(Math.atan2(
+          Math.sin(lam) * Math.cos(eps) - Math.tan(beta) * Math.sin(eps),
+          Math.cos(lam)
+        ) * RAD2DEG)
+        dec = Math.asin(Math.sin(beta) * Math.cos(eps) + Math.cos(beta) * Math.sin(eps) * Math.sin(lam))
+
+        {
+          "planet" => name,
+          "mc"     => norm180(ra - gst),
+          "ic"     => norm180(ra - gst + 180.0),
+          "asc"    => horizon_curve(ra, dec, gst, :rising),
+          "dsc"    => horizon_curve(ra, dec, gst, :setting),
+        }
+      end
+    end
+
+    # Segments of [lat, lon] points where the body is on the eastern (rising)
+    # or western (setting) horizon. A circumpolar latitude breaks the curve, so
+    # the result is an array of contiguous segments (each a polyline).
+    def horizon_curve(ra_deg, dec_rad, gst, mode)
+      tan_dec = Math.tan(dec_rad)
+      segments = []
+      current = []
+      lat = LAT_MIN.to_f
+      while lat <= LAT_MAX
+        x = -Math.tan(lat * DEG2RAD) * tan_dec
+        if x.abs <= 1.0
+          h0 = Math.acos(x) * RAD2DEG
+          hour = mode == :rising ? -h0 : h0
+          current << [lat.round(2), norm180(ra_deg + hour - gst)]
+        elsif !current.empty?
+          segments << current
+          current = []
+        end
+        lat += LAT_STEP
+      end
+      segments << current unless current.empty?
+      segments
+    end
+
+    # Normalize degrees to (−180, 180].
+    def norm180(deg)
+      d = Core.norm360(deg)
+      d > 180.0 ? d - 360.0 : d
+    end
+
+    private_class_method :horizon_curve, :norm180
+  end
+end

data/lib/astro_chart/ephemeris.rb

@@ -102,6 +102,12 @@ module AstroChart
       end
     end
 
+    # Apparent geocentric ecliptic [longitude, latitude] in degrees. Pure
+    # backend only (the Swiss extension exposes latitude via its own API).
+    def self.ecliptic_latlon(jd, planet_id)
+      Pure.ecliptic_latlon(jd, planet_id)
+    end
+
     # Apparent daily motion in ecliptic longitude (degrees/day), via central
     # difference of calc_ut at jd ± 0.5 day. The difference is folded into
     # (-180, 180] so the 0°/360° wraparound never produces a spurious value.

data/lib/astro_chart/pure/moon.rb

@@ -182,10 +182,16 @@ module AstroChart
       # --- 月球視黃經（度，[0,360)）。引數 **JD(UT)**。 ---
       # 幾何黃經（平春分點 of date）+ 章動 Δψ = 視黃經（真春分點 of date）。
       def apparent_longitude(jd_ut)
+        apparent_ecliptic(jd_ut)[0]
+      end
+
+      # Apparent geocentric ecliptic [longitude, latitude] in degrees. JD(UT).
+      # ELP-2000 gives β directly; nutation shifts longitude only.
+      def apparent_ecliptic(jd_ut)
         tt = Core.jd_tt(jd_ut)
-        lam, _beta, _delta = geometric_position(tt)
+        lam, beta, = geometric_position(tt)
         dpsi_deg, = Core.nutation(tt)
-        Core.norm360(lam + dpsi_deg)
+        [Core.norm360(lam + dpsi_deg), beta]
       end
 
       # --- 真（密切）北交點視黃經（度，[0,360)）。引數 **JD(UT)**。 ---

data/lib/astro_chart/pure/pluto.rb

@@ -94,6 +94,11 @@ module AstroChart
       # 冥王星視黃道經度（度，真春分點 of date）。
       # jd_ut: JD(UT)。超出 Meeus Ch. 37 適用範圍（1885–2099）raise DomainError。
       def apparent_longitude(jd_ut)
+        apparent_ecliptic(jd_ut)[0]
+      end
+
+      # Apparent geocentric ecliptic [longitude, latitude] in degrees. JD(UT).
+      def apparent_ecliptic(jd_ut)
         jd_tt = Core.jd_tt(jd_ut)
         unless jd_tt >= JD_TT_MIN && jd_tt < JD_TT_MAX
           raise Core::DomainError,
@@ -121,9 +126,11 @@ module AstroChart
           tau = new_tau
         end
 
-        lambda_mean = Math.atan2(gy, gx) * RAD2DEG # 平春分點 of date
-        dpsi, = Core.nutation(jd_tt)
-        Core.norm360(lambda_mean + dpsi)
+        dpsi, = Core.nutation(jd_tt) # 平春分點 of date → 真春分點
+        [
+          Core.norm360(Math.atan2(gy, gx) * RAD2DEG + dpsi),
+          Math.asin(gz / Math.sqrt(gx * gx + gy * gy + gz * gz)) * RAD2DEG,
+        ]
       end
 
       # --- 冥王星日心直角座標（AU，黃道座標，旋轉到 jd_frame_tt 的平春分點） ---

data/lib/astro_chart/pure/vsop87.rb

@@ -61,6 +61,20 @@ module AstroChart
         end
       end
 
+      # Apparent geocentric ecliptic [longitude, latitude] in degrees. The Sun's
+      # geocentric ecliptic latitude is ~0 (well under 1″), returned as 0.0.
+      def apparent_ecliptic(planet_id, jd_ut)
+        tt = Core.jd_tt(jd_ut)
+        if planet_id == SUN_ID
+          [sun_apparent_longitude(tt), 0.0]
+        elsif PLANET_KEYS.key?(planet_id)
+          planet_apparent_ecliptic(PLANET_KEYS.fetch(planet_id), tt)
+        else
+          raise Core::DomainError,
+                "Vsop87 不支援 planet_id=#{planet_id}（僅太陽 0 與行星 2..8）"
+        end
+      end
+
       # --- 太陽（Meeus Ch. 25 高精度法） ---
       def sun_apparent_longitude(jd_tt)
         l, _b, r = heliocentric_fk5(:earth, jd_tt)
@@ -75,8 +89,14 @@ module AstroChart
       # 重算——兩者同取 t-τ 等效把光行時與（地球速度造成的）光行差
       # 一併涵蓋（planetary aberration；Meeus Ch. 33 註）。τ 迭代兩輪。
       def planet_apparent_longitude(planet_key, jd_tt)
+        planet_apparent_ecliptic(planet_key, jd_tt)[0]
+      end
+
+      # Geocentric apparent ecliptic [longitude, latitude] (degrees) for a VSOP87
+      # planet, via the light-time-corrected geocentric rectangular vector.
+      def planet_apparent_ecliptic(planet_key, jd_tt)
         tau = 0.0
-        x = y = 0.0
+        x = y = z = 0.0
         2.times do
           ex, ey, ez = heliocentric_rect(:earth, jd_tt - tau)
           px, py, pz = heliocentric_rect(planet_key, jd_tt - tau)
@@ -86,9 +106,11 @@ module AstroChart
           delta = Math.sqrt(x * x + y * y + z * z)
           tau = LIGHT_TIME_DAYS_PER_AU * delta
         end
-        lambda_deg = Math.atan2(y, x) * RAD2DEG
         dpsi_deg, = Core.nutation(jd_tt)
-        Core.norm360(lambda_deg + dpsi_deg)
+        [
+          Core.norm360(Math.atan2(y, x) * RAD2DEG + dpsi_deg),
+          Math.asin(z / Math.sqrt(x * x + y * y + z * z)) * RAD2DEG,
+        ]
       end
 
       # --- 日心黃道直角座標（FK5 修正後；黃道與分點皆為 of date） ---

data/lib/astro_chart/pure.rb

@@ -49,6 +49,23 @@ module AstroChart
       end
     end
 
+    # Apparent geocentric ecliptic [longitude, latitude] in degrees for the Sun,
+    # Moon, VSOP87 planets and Pluto (nodes are not physical bodies).
+    def ecliptic_latlon(jd_ut, planet_id)
+      case planet_id
+      when *VSOP87_PLANET_IDS
+        Vsop87.apparent_ecliptic(planet_id, jd_ut)
+      when MOON_ID
+        Moon.apparent_ecliptic(jd_ut)
+      when PLUTO_ID
+        Pluto.apparent_ecliptic(jd_ut)
+      else
+        raise ArgumentError,
+              "ecliptic_latlon unsupported planet_id #{planet_id.inspect} " \
+              "(supported: Sun 0, planets 2-8, Moon, Pluto)"
+      end
+    end
+
     # House cusps + ascendant + MC. Placidus ("P") and Whole Sign ("W").
     # hsys accepts "P"/"W" or 80/87 (ord values) to mirror the C extension's int argument.
     def houses(jd_ut, latitude, longitude, hsys = "P")

data/lib/astro_chart/version.rb

@@ -1,3 +1,3 @@
 module AstroChart
-  VERSION = "0.4.0"
+  VERSION = "0.5.1"
 end

data/lib/astro_chart.rb

@@ -20,6 +20,7 @@ require_relative "astro_chart/progressions"
 require_relative "astro_chart/composite"
 require_relative "astro_chart/solar_return"
 require_relative "astro_chart/draconic"
+require_relative "astro_chart/astrocartography"
 require_relative "astro_chart/dignities"
 require_relative "astro_chart/profection"
 require_relative "astro_chart/transit_timing"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: astro_chart
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Huang Yudi
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-06 00:00:00.000000000 Z
+date: 2026-08-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tzinfo
@@ -69,6 +69,7 @@ files:
 - astro_chart.gemspec
 - lib/astro_chart.rb
 - lib/astro_chart/aspects.rb
+- lib/astro_chart/astrocartography.rb
 - lib/astro_chart/chart.rb
 - lib/astro_chart/composite.rb
 - lib/astro_chart/dignities.rb