@openwaters/almanac 0.5.0 → 0.7.0

package/dist/planetModels.js

@@ -0,0 +1,467 @@
+import { earthHelioVector, vsopRotate, vsopSphereToRect } from './sun.js';
+import { C_AUDAY, PI2 } from './nutation.js';
+// VsopFormula / CalcVsop: pinned astronomy.ts#L3191 / #L3255.
+function vsopFormula(formula, t, clampAngle) {
+    let tpower = 1, coord = 0;
+    for (const series of formula) {
+        let sum = 0;
+        for (const [ampl, phas, freq] of series)
+            sum += ampl * Math.cos(phas + (t * freq));
+        let incr = tpower * sum;
+        if (clampAngle)
+            incr %= PI2;
+        coord += incr;
+        tpower *= t;
+    }
+    return coord;
+}
+/** INTERNAL: geometric Sun-centered vector in AU, J2000 mean equator. */
+export function planetHelioVector(planet, tt) {
+    if (planet === 'earth')
+        return earthHelioVector(tt);
+    const model = models[planet], t = tt / 365250;
+    const lon = vsopFormula(model[0], t, true);
+    const lat = vsopFormula(model[1], t, false);
+    const rad = vsopFormula(model[2], t, false);
+    return vsopRotate(vsopSphereToRect(lon, lat, rad));
+}
+// BackdatePosition / BodyPosition / CorrectLightTravel: pinned astronomy.ts#L4170–L4313.
+export function planetGeoVectorEqj(planet, tt, aberration = true) {
+    let ltime = tt, dt = 0;
+    const fixedEarth = aberration ? null : earthHelioVector(tt);
+    for (let iter = 0; iter < 10; ++iter) {
+        // Backdating Earth along with the planet supplies upstream's aberration correction.
+        const earth = fixedEarth ?? earthHelioVector(ltime), target = planetHelioVector(planet, ltime);
+        const pos = { x: target.x - earth.x, y: target.y - earth.y, z: target.z - earth.z };
+        const lt = Math.sqrt(pos.x * pos.x + pos.y * pos.y + pos.z * pos.z) / C_AUDAY;
+        if (lt > 1)
+            throw new Error('Object is too distant for light-travel solver.');
+        const next = tt - lt;
+        dt = Math.abs(next - ltime);
+        if (dt < 1e-9)
+            return pos;
+        ltime = next;
+    }
+    throw new Error(`Light-travel time solver did not converge: dt = ${dt}`);
+}
+const models = {
+    mercury: [
+        [
+            [
+                [4.40250710144, 0.00000000000, 0.00000000000],
+                [0.40989414977, 1.48302034195, 26087.90314157420],
+                [0.05046294200, 4.47785489551, 52175.80628314840],
+                [0.00855346844, 1.16520322459, 78263.70942472259],
+                [0.00165590362, 4.11969163423, 104351.61256629678],
+                [0.00034561897, 0.77930768443, 130439.51570787099],
+                [0.00007583476, 3.71348404924, 156527.41884944518]
+            ],
+            [
+                [26087.90313685529, 0.00000000000, 0.00000000000],
+                [0.01131199811, 6.21874197797, 26087.90314157420],
+                [0.00292242298, 3.04449355541, 52175.80628314840],
+                [0.00075775081, 6.08568821653, 78263.70942472259],
+                [0.00019676525, 2.80965111777, 104351.61256629678]
+            ]
+        ],
+        [
+            [
+                [0.11737528961, 1.98357498767, 26087.90314157420],
+                [0.02388076996, 5.03738959686, 52175.80628314840],
+                [0.01222839532, 3.14159265359, 0.00000000000],
+                [0.00543251810, 1.79644363964, 78263.70942472259],
+                [0.00129778770, 4.83232503958, 104351.61256629678],
+                [0.00031866927, 1.58088495658, 130439.51570787099],
+                [0.00007963301, 4.60972126127, 156527.41884944518]
+            ],
+            [
+                [0.00274646065, 3.95008450011, 26087.90314157420],
+                [0.00099737713, 3.14159265359, 0.00000000000]
+            ]
+        ],
+        [
+            [
+                [0.39528271651, 0.00000000000, 0.00000000000],
+                [0.07834131818, 6.19233722598, 26087.90314157420],
+                [0.00795525558, 2.95989690104, 52175.80628314840],
+                [0.00121281764, 6.01064153797, 78263.70942472259],
+                [0.00021921969, 2.77820093972, 104351.61256629678],
+                [0.00004354065, 5.82894543774, 130439.51570787099]
+            ],
+            [
+                [0.00217347740, 4.65617158665, 26087.90314157420],
+                [0.00044141826, 1.42385544001, 52175.80628314840]
+            ]
+        ]
+    ],
+    venus: [
+        [
+            [
+                [3.17614666774, 0.00000000000, 0.00000000000],
+                [0.01353968419, 5.59313319619, 10213.28554621100],
+                [0.00089891645, 5.30650047764, 20426.57109242200],
+                [0.00005477194, 4.41630661466, 7860.41939243920],
+                [0.00003455741, 2.69964447820, 11790.62908865880],
+                [0.00002372061, 2.99377542079, 3930.20969621960],
+                [0.00001317168, 5.18668228402, 26.29831979980],
+                [0.00001664146, 4.25018630147, 1577.34354244780],
+                [0.00001438387, 4.15745084182, 9683.59458111640],
+                [0.00001200521, 6.15357116043, 30639.85663863300]
+            ],
+            [
+                [10213.28554621638, 0.00000000000, 0.00000000000],
+                [0.00095617813, 2.46406511110, 10213.28554621100],
+                [0.00007787201, 0.62478482220, 20426.57109242200]
+            ]
+        ],
+        [
+            [
+                [0.05923638472, 0.26702775812, 10213.28554621100],
+                [0.00040107978, 1.14737178112, 20426.57109242200],
+                [0.00032814918, 3.14159265359, 0.00000000000]
+            ],
+            [
+                [0.00287821243, 1.88964962838, 10213.28554621100]
+            ]
+        ],
+        [
+            [
+                [0.72334820891, 0.00000000000, 0.00000000000],
+                [0.00489824182, 4.02151831717, 10213.28554621100],
+                [0.00001658058, 4.90206728031, 20426.57109242200],
+                [0.00001378043, 1.12846591367, 11790.62908865880],
+                [0.00001632096, 2.84548795207, 7860.41939243920],
+                [0.00000498395, 2.58682193892, 9683.59458111640],
+                [0.00000221985, 2.01346696541, 19367.18916223280],
+                [0.00000237454, 2.55136053886, 15720.83878487840]
+            ],
+            [
+                [0.00034551041, 0.89198706276, 10213.28554621100]
+            ]
+        ]
+    ],
+    mars: [
+        [
+            [
+                [6.20347711581, 0.00000000000, 0.00000000000],
+                [0.18656368093, 5.05037100270, 3340.61242669980],
+                [0.01108216816, 5.40099836344, 6681.22485339960],
+                [0.00091798406, 5.75478744667, 10021.83728009940],
+                [0.00027744987, 5.97049513147, 3.52311834900],
+                [0.00010610235, 2.93958560338, 2281.23049651060],
+                [0.00012315897, 0.84956094002, 2810.92146160520],
+                [0.00008926784, 4.15697846427, 0.01725365220],
+                [0.00008715691, 6.11005153139, 13362.44970679920],
+                [0.00006797556, 0.36462229657, 398.14900340820],
+                [0.00007774872, 3.33968761376, 5621.84292321040],
+                [0.00003575078, 1.66186505710, 2544.31441988340],
+                [0.00004161108, 0.22814971327, 2942.46342329160],
+                [0.00003075252, 0.85696614132, 191.44826611160],
+                [0.00002628117, 0.64806124465, 3337.08930835080],
+                [0.00002937546, 6.07893711402, 0.06731030280],
+                [0.00002389414, 5.03896442664, 796.29800681640],
+                [0.00002579844, 0.02996736156, 3344.13554504880],
+                [0.00001528141, 1.14979301996, 6151.53388830500],
+                [0.00001798806, 0.65634057445, 529.69096509460],
+                [0.00001264357, 3.62275122593, 5092.15195811580],
+                [0.00001286228, 3.06796065034, 2146.16541647520],
+                [0.00001546404, 2.91579701718, 1751.53953141600],
+                [0.00001024902, 3.69334099279, 8962.45534991020],
+                [0.00000891566, 0.18293837498, 16703.06213349900],
+                [0.00000858759, 2.40093811940, 2914.01423582380],
+                [0.00000832715, 2.46418619474, 3340.59517304760],
+                [0.00000832720, 4.49495782139, 3340.62968035200],
+                [0.00000712902, 3.66335473479, 1059.38193018920],
+                [0.00000748723, 3.82248614017, 155.42039943420],
+                [0.00000723861, 0.67497311481, 3738.76143010800],
+                [0.00000635548, 2.92182225127, 8432.76438481560],
+                [0.00000655162, 0.48864064125, 3127.31333126180],
+                [0.00000550474, 3.81001042328, 0.98032106820],
+                [0.00000552750, 4.47479317037, 1748.01641306700],
+                [0.00000425966, 0.55364317304, 6283.07584999140],
+                [0.00000415131, 0.49662285038, 213.29909543800],
+                [0.00000472167, 3.62547124025, 1194.44701022460],
+                [0.00000306551, 0.38052848348, 6684.74797174860],
+                [0.00000312141, 0.99853944405, 6677.70173505060],
+                [0.00000293198, 4.22131299634, 20.77539549240],
+                [0.00000302375, 4.48618007156, 3532.06069281140],
+                [0.00000274027, 0.54222167059, 3340.54511639700],
+                [0.00000281079, 5.88163521788, 1349.86740965880],
+                [0.00000231183, 1.28242156993, 3870.30339179440],
+                [0.00000283602, 5.76885434940, 3149.16416058820],
+                [0.00000236117, 5.75503217933, 3333.49887969900],
+                [0.00000274033, 0.13372524985, 3340.67973700260],
+                [0.00000299395, 2.78323740866, 6254.62666252360]
+            ],
+            [
+                [3340.61242700512, 0.00000000000, 0.00000000000],
+                [0.01457554523, 3.60433733236, 3340.61242669980],
+                [0.00168414711, 3.92318567804, 6681.22485339960],
+                [0.00020622975, 4.26108844583, 10021.83728009940],
+                [0.00003452392, 4.73210393190, 3.52311834900],
+                [0.00002586332, 4.60670058555, 13362.44970679920],
+                [0.00000841535, 4.45864030426, 2281.23049651060]
+            ],
+            [
+                [0.00058152577, 2.04961712429, 3340.61242669980],
+                [0.00013459579, 2.45738706163, 6681.22485339960]
+            ]
+        ],
+        [
+            [
+                [0.03197134986, 3.76832042431, 3340.61242669980],
+                [0.00298033234, 4.10616996305, 6681.22485339960],
+                [0.00289104742, 0.00000000000, 0.00000000000],
+                [0.00031365539, 4.44651053090, 10021.83728009940],
+                [0.00003484100, 4.78812549260, 13362.44970679920]
+            ],
+            [
+                [0.00217310991, 6.04472194776, 3340.61242669980],
+                [0.00020976948, 3.14159265359, 0.00000000000],
+                [0.00012834709, 1.60810667915, 6681.22485339960]
+            ]
+        ],
+        [
+            [
+                [1.53033488271, 0.00000000000, 0.00000000000],
+                [0.14184953160, 3.47971283528, 3340.61242669980],
+                [0.00660776362, 3.81783443019, 6681.22485339960],
+                [0.00046179117, 4.15595316782, 10021.83728009940],
+                [0.00008109733, 5.55958416318, 2810.92146160520],
+                [0.00007485318, 1.77239078402, 5621.84292321040],
+                [0.00005523191, 1.36436303770, 2281.23049651060],
+                [0.00003825160, 4.49407183687, 13362.44970679920],
+                [0.00002306537, 0.09081579001, 2544.31441988340],
+                [0.00001999396, 5.36059617709, 3337.08930835080],
+                [0.00002484394, 4.92545639920, 2942.46342329160],
+                [0.00001960195, 4.74249437639, 3344.13554504880],
+                [0.00001167119, 2.11260868341, 5092.15195811580],
+                [0.00001102816, 5.00908403998, 398.14900340820],
+                [0.00000899066, 4.40791133207, 529.69096509460],
+                [0.00000992252, 5.83861961952, 6151.53388830500],
+                [0.00000807354, 2.10217065501, 1059.38193018920],
+                [0.00000797915, 3.44839203899, 796.29800681640],
+                [0.00000740975, 1.49906336885, 2146.16541647520]
+            ],
+            [
+                [0.01107433345, 2.03250524857, 3340.61242669980],
+                [0.00103175887, 2.37071847807, 6681.22485339960],
+                [0.00012877200, 0.00000000000, 0.00000000000],
+                [0.00010815880, 2.70888095665, 10021.83728009940]
+            ],
+            [
+                [0.00044242249, 0.47930604954, 3340.61242669980],
+                [0.00008138042, 0.86998389204, 6681.22485339960]
+            ]
+        ]
+    ],
+    jupiter: [
+        [
+            [
+                [0.59954691494, 0.00000000000, 0.00000000000],
+                [0.09695898719, 5.06191793158, 529.69096509460],
+                [0.00573610142, 1.44406205629, 7.11354700080],
+                [0.00306389205, 5.41734730184, 1059.38193018920],
+                [0.00097178296, 4.14264726552, 632.78373931320],
+                [0.00072903078, 3.64042916389, 522.57741809380],
+                [0.00064263975, 3.41145165351, 103.09277421860],
+                [0.00039806064, 2.29376740788, 419.48464387520],
+                [0.00038857767, 1.27231755835, 316.39186965660],
+                [0.00027964629, 1.78454591820, 536.80451209540],
+                [0.00013589730, 5.77481040790, 1589.07289528380],
+                [0.00008246349, 3.58227925840, 206.18554843720],
+                [0.00008768704, 3.63000308199, 949.17560896980],
+                [0.00007368042, 5.08101194270, 735.87651353180],
+                [0.00006263150, 0.02497628807, 213.29909543800],
+                [0.00006114062, 4.51319998626, 1162.47470440780],
+                [0.00004905396, 1.32084470588, 110.20632121940],
+                [0.00005305285, 1.30671216791, 14.22709400160],
+                [0.00005305441, 4.18625634012, 1052.26838318840],
+                [0.00004647248, 4.69958103684, 3.93215326310],
+                [0.00003045023, 4.31676431084, 426.59819087600],
+                [0.00002609999, 1.56667394063, 846.08283475120],
+                [0.00002028191, 1.06376530715, 3.18139373770],
+                [0.00001764763, 2.14148655117, 1066.49547719000],
+                [0.00001722972, 3.88036268267, 1265.56747862640],
+                [0.00001920945, 0.97168196472, 639.89728631400],
+                [0.00001633223, 3.58201833555, 515.46387109300],
+                [0.00001431999, 4.29685556046, 625.67019231240],
+                [0.00000973272, 4.09764549134, 95.97922721780]
+            ],
+            [
+                [529.69096508814, 0.00000000000, 0.00000000000],
+                [0.00489503243, 4.22082939470, 529.69096509460],
+                [0.00228917222, 6.02646855621, 7.11354700080],
+                [0.00030099479, 4.54540782858, 1059.38193018920],
+                [0.00020720920, 5.45943156902, 522.57741809380],
+                [0.00012103653, 0.16994816098, 536.80451209540],
+                [0.00006067987, 4.42422292017, 103.09277421860],
+                [0.00005433968, 3.98480737746, 419.48464387520],
+                [0.00004237744, 5.89008707199, 14.22709400160]
+            ],
+            [
+                [0.00047233601, 4.32148536482, 7.11354700080],
+                [0.00030649436, 2.92977788700, 529.69096509460],
+                [0.00014837605, 3.14159265359, 0.00000000000]
+            ]
+        ],
+        [
+            [
+                [0.02268615702, 3.55852606721, 529.69096509460],
+                [0.00109971634, 3.90809347197, 1059.38193018920],
+                [0.00110090358, 0.00000000000, 0.00000000000],
+                [0.00008101428, 3.60509572885, 522.57741809380],
+                [0.00006043996, 4.25883108339, 1589.07289528380],
+                [0.00006437782, 0.30627119215, 536.80451209540]
+            ],
+            [
+                [0.00078203446, 1.52377859742, 529.69096509460]
+            ]
+        ],
+        [
+            [
+                [5.20887429326, 0.00000000000, 0.00000000000],
+                [0.25209327119, 3.49108639871, 529.69096509460],
+                [0.00610599976, 3.84115365948, 1059.38193018920],
+                [0.00282029458, 2.57419881293, 632.78373931320],
+                [0.00187647346, 2.07590383214, 522.57741809380],
+                [0.00086792905, 0.71001145545, 419.48464387520],
+                [0.00072062974, 0.21465724607, 536.80451209540],
+                [0.00065517248, 5.97995884790, 316.39186965660],
+                [0.00029134542, 1.67759379655, 103.09277421860],
+                [0.00030135335, 2.16132003734, 949.17560896980],
+                [0.00023453271, 3.54023522184, 735.87651353180],
+                [0.00022283743, 4.19362594399, 1589.07289528380],
+                [0.00023947298, 0.27458037480, 7.11354700080],
+                [0.00013032614, 2.96042965363, 1162.47470440780],
+                [0.00009703360, 1.90669633585, 206.18554843720],
+                [0.00012749023, 2.71550286592, 1052.26838318840],
+                [0.00007057931, 2.18184839926, 1265.56747862640],
+                [0.00006137703, 6.26418240033, 846.08283475120],
+                [0.00002616976, 2.00994012876, 1581.95934828300]
+            ],
+            [
+                [0.01271801520, 2.64937512894, 529.69096509460],
+                [0.00061661816, 3.00076460387, 1059.38193018920],
+                [0.00053443713, 3.89717383175, 522.57741809380],
+                [0.00031185171, 4.88276958012, 536.80451209540],
+                [0.00041390269, 0.00000000000, 0.00000000000]
+            ]
+        ]
+    ],
+    saturn: [
+        [
+            [
+                [0.87401354025, 0.00000000000, 0.00000000000],
+                [0.11107659762, 3.96205090159, 213.29909543800],
+                [0.01414150957, 4.58581516874, 7.11354700080],
+                [0.00398379389, 0.52112032699, 206.18554843720],
+                [0.00350769243, 3.30329907896, 426.59819087600],
+                [0.00206816305, 0.24658372002, 103.09277421860],
+                [0.00079271300, 3.84007056878, 220.41264243880],
+                [0.00023990355, 4.66976924553, 110.20632121940],
+                [0.00016573588, 0.43719228296, 419.48464387520],
+                [0.00014906995, 5.76903183869, 316.39186965660],
+                [0.00015820290, 0.93809155235, 632.78373931320],
+                [0.00014609559, 1.56518472000, 3.93215326310],
+                [0.00013160301, 4.44891291899, 14.22709400160],
+                [0.00015053543, 2.71669915667, 639.89728631400],
+                [0.00013005299, 5.98119023644, 11.04570026390],
+                [0.00010725067, 3.12939523827, 202.25339517410],
+                [0.00005863206, 0.23656938524, 529.69096509460],
+                [0.00005227757, 4.20783365759, 3.18139373770],
+                [0.00006126317, 1.76328667907, 277.03499374140],
+                [0.00005019687, 3.17787728405, 433.71173787680],
+                [0.00004592550, 0.61977744975, 199.07200143640],
+                [0.00004005867, 2.24479718502, 63.73589830340],
+                [0.00002953796, 0.98280366998, 95.97922721780],
+                [0.00003873670, 3.22283226966, 138.51749687070],
+                [0.00002461186, 2.03163875071, 735.87651353180],
+                [0.00003269484, 0.77492638211, 949.17560896980],
+                [0.00001758145, 3.26580109940, 522.57741809380],
+                [0.00001640172, 5.50504453050, 846.08283475120],
+                [0.00001391327, 4.02333150505, 323.50541665740],
+                [0.00001580648, 4.37265307169, 309.27832265580],
+                [0.00001123498, 2.83726798446, 415.55249061210],
+                [0.00001017275, 3.71700135395, 227.52618943960],
+                [0.00000848642, 3.19150170830, 209.36694217490]
+            ],
+            [
+                [213.29909521690, 0.00000000000, 0.00000000000],
+                [0.01297370862, 1.82834923978, 213.29909543800],
+                [0.00564345393, 2.88499717272, 7.11354700080],
+                [0.00093734369, 1.06311793502, 426.59819087600],
+                [0.00107674962, 2.27769131009, 206.18554843720],
+                [0.00040244455, 2.04108104671, 220.41264243880],
+                [0.00019941774, 1.27954390470, 103.09277421860],
+                [0.00010511678, 2.74880342130, 14.22709400160],
+                [0.00006416106, 0.38238295041, 639.89728631400],
+                [0.00004848994, 2.43037610229, 419.48464387520],
+                [0.00004056892, 2.92133209468, 110.20632121940],
+                [0.00003768635, 3.64965330780, 3.93215326310]
+            ],
+            [
+                [0.00116441330, 1.17988132879, 7.11354700080],
+                [0.00091841837, 0.07325195840, 213.29909543800],
+                [0.00036661728, 0.00000000000, 0.00000000000],
+                [0.00015274496, 4.06493179167, 206.18554843720]
+            ]
+        ],
+        [
+            [
+                [0.04330678039, 3.60284428399, 213.29909543800],
+                [0.00240348302, 2.85238489373, 426.59819087600],
+                [0.00084745939, 0.00000000000, 0.00000000000],
+                [0.00030863357, 3.48441504555, 220.41264243880],
+                [0.00034116062, 0.57297307557, 206.18554843720],
+                [0.00014734070, 2.11846596715, 639.89728631400],
+                [0.00009916667, 5.79003188904, 419.48464387520],
+                [0.00006993564, 4.73604689720, 7.11354700080],
+                [0.00004807588, 5.43305312061, 316.39186965660]
+            ],
+            [
+                [0.00198927992, 4.93901017903, 213.29909543800],
+                [0.00036947916, 3.14159265359, 0.00000000000],
+                [0.00017966989, 0.51979431110, 426.59819087600]
+            ]
+        ],
+        [
+            [
+                [9.55758135486, 0.00000000000, 0.00000000000],
+                [0.52921382865, 2.39226219573, 213.29909543800],
+                [0.01873679867, 5.23549604660, 206.18554843720],
+                [0.01464663929, 1.64763042902, 426.59819087600],
+                [0.00821891141, 5.93520042303, 316.39186965660],
+                [0.00547506923, 5.01532618980, 103.09277421860],
+                [0.00371684650, 2.27114821115, 220.41264243880],
+                [0.00361778765, 3.13904301847, 7.11354700080],
+                [0.00140617506, 5.70406606781, 632.78373931320],
+                [0.00108974848, 3.29313390175, 110.20632121940],
+                [0.00069006962, 5.94099540992, 419.48464387520],
+                [0.00061053367, 0.94037691801, 639.89728631400],
+                [0.00048913294, 1.55733638681, 202.25339517410],
+                [0.00034143772, 0.19519102597, 277.03499374140],
+                [0.00032401773, 5.47084567016, 949.17560896980],
+                [0.00020936596, 0.46349251129, 735.87651353180],
+                [0.00009796004, 5.20477537945, 1265.56747862640],
+                [0.00011993338, 5.98050967385, 846.08283475120],
+                [0.00020839300, 1.52102476129, 433.71173787680],
+                [0.00015298404, 3.05943814940, 529.69096509460],
+                [0.00006465823, 0.17732249942, 1052.26838318840],
+                [0.00011380257, 1.73105427040, 522.57741809380],
+                [0.00003419618, 4.94550542171, 1581.95934828300]
+            ],
+            [
+                [0.06182981340, 0.25843511480, 213.29909543800],
+                [0.00506577242, 0.71114625261, 206.18554843720],
+                [0.00341394029, 5.79635741658, 426.59819087600],
+                [0.00188491195, 0.47215589652, 220.41264243880],
+                [0.00186261486, 3.14159265359, 0.00000000000],
+                [0.00143891146, 1.40744822888, 7.11354700080]
+            ],
+            [
+                [0.00436902572, 4.78671677509, 213.29909543800]
+            ]
+        ]
+    ]
+};

package/dist/planets.d.ts

@@ -0,0 +1,32 @@
+import { type Planet, type Observer } from './types.js';
+import { type AltAz } from './transforms.js';
+/** Geometric Sun-centered AU vector in the fixed J2000 mean equatorial frame. */
+export interface HeliocentricPosition {
+    xAu: number;
+    yAu: number;
+    zAu: number;
+}
+/** Apparent geocentric position on the true equator and equinox of date. */
+export interface PlanetPosition {
+    raDeg: number;
+    decDeg: number;
+    distanceAu: number;
+}
+/** Geometric phase and approximate airless visual magnitude, plus apparent solar separation. */
+export interface PlanetIllumination {
+    fraction: number;
+    phaseAngleDeg: number;
+    magnitude: number;
+    elongationDeg: number;
+}
+export declare function planetIlluminationAtTT(planet: Planet, tt: number): PlanetIllumination;
+/** Approximate airless magnitude includes Saturn's rings; elongation is apparent separation from the Sun. */
+export declare function planetIllumination(planet: Planet, time: Date): PlanetIllumination;
+/** INTERNAL: TT-labeled evidence bypasses the civil-time Delta-T conversion. */
+export declare function planetApparentAtTT(planet: Planet, tt: number): PlanetPosition;
+/** Geometric position at the requested instant; accepts Earth. */
+export declare function planetHeliocentricPosition(planet: Planet, time: Date): HeliocentricPosition;
+/** Apparent geocentric position with light-time, aberration, precession, and nutation. */
+export declare function planetPosition(planet: Planet, time: Date): PlanetPosition;
+/** Refracted topocentric position; altitude remains relative to the horizontal plane. */
+export declare function planetAltAz(planet: Planet, time: Date, observer: Observer): AltAz;

package/dist/planets.js

@@ -0,0 +1,104 @@
+import { assertPlanet, assertSupported, assertObserver } from './types.js';
+import { ttDays, ttDaysFromUt, utDays } from './time.js';
+import { gyration, PrecessDirection, equatorialFromVector, DEG2RAD, RAD2DEG, earthTilt, eclipticToEquatorial } from './nutation.js';
+import { planetHelioVector, planetGeoVectorEqj } from './planetModels.js';
+import { topoAltAzUnrefracted, refract } from './transforms.js';
+import { angleBetweenDeg } from './illumination.js';
+import { earthHelioVector, sunGeoVectorEqj } from './sun.js';
+// VisualMagnitude: https://github.com/cosinekitty/astronomy/blob/865d3da7d8112bbc7911238052c6af4aaf877181/source/js/astronomy.ts#L4901.
+function visualMagnitude(planet, phase, helioDist, geoDist) {
+    let c0, c1 = 0, c2 = 0, c3 = 0;
+    switch (planet) {
+        case 'mercury':
+            c0 = -0.60;
+            c1 = 4.98;
+            c2 = -4.88;
+            c3 = 3.02;
+            break;
+        case 'venus':
+            if (phase < 163.6) {
+                c0 = -4.47;
+                c1 = 1.03;
+                c2 = 0.57;
+                c3 = 0.13;
+            }
+            else {
+                c0 = 0.98;
+                c1 = -1.02;
+            }
+            break;
+        case 'mars':
+            c0 = -1.52;
+            c1 = 1.60;
+            break;
+        case 'jupiter':
+            c0 = -9.40;
+            c1 = 0.50;
+            break;
+        default: throw new Error('unsupported planet in visualMagnitude');
+    }
+    const x = phase / 100;
+    let mag = c0 + x * (c1 + x * (c2 + x * c3));
+    mag += 5 * Math.log10(helioDist * geoDist);
+    return mag;
+}
+// SaturnMagnitude: pinned astronomy.ts#L4927; Ecliptic: #L3013.
+function saturnMagnitude(phase, helioDist, geoDist, gc, tt) {
+    const ecl = eclipticToEquatorial(-earthTilt(tt).tobl, gyration(gc, tt, PrecessDirection.From2000));
+    const lat = RAD2DEG * Math.atan2(ecl.z, Math.hypot(ecl.x, ecl.y));
+    let lon = RAD2DEG * Math.atan2(ecl.y, ecl.x);
+    if (lon < 0)
+        lon += 360;
+    const ir = DEG2RAD * 28.06, nr = DEG2RAD * (169.51 + (3.82e-5 * tt));
+    const tilt = Math.asin(Math.sin(DEG2RAD * lat) * Math.cos(ir) - Math.cos(DEG2RAD * lat) * Math.sin(ir) * Math.sin(DEG2RAD * lon - nr));
+    const sinTilt = Math.sin(Math.abs(tilt));
+    let mag = -9 + 0.044 * phase;
+    mag += sinTilt * (-2.6 + 1.2 * sinTilt);
+    mag += 5 * Math.log10(helioDist * geoDist);
+    return mag;
+}
+// Illumination: pinned astronomy.ts#L5066; AngleFromSun: #L4869.
+export function planetIlluminationAtTT(planet, tt) {
+    const earth = earthHelioVector(tt), hc = planetHelioVector(planet, tt);
+    const gc = { x: hc.x - earth.x, y: hc.y - earth.y, z: hc.z - earth.z };
+    const phaseAngleDeg = angleBetweenDeg(gc, hc);
+    const helioDist = Math.sqrt(hc.x * hc.x + hc.y * hc.y + hc.z * hc.z);
+    const geoDist = Math.sqrt(gc.x * gc.x + gc.y * gc.y + gc.z * gc.z);
+    const magnitude = planet === 'saturn' ? saturnMagnitude(phaseAngleDeg, helioDist, geoDist, gc, tt) : visualMagnitude(planet, phaseAngleDeg, helioDist, geoDist);
+    return { fraction: (1 + Math.cos(DEG2RAD * phaseAngleDeg)) / 2, phaseAngleDeg, magnitude,
+        elongationDeg: angleBetweenDeg(sunGeoVectorEqj(tt), planetGeoVectorEqj(planet, tt)) };
+}
+/** Approximate airless magnitude includes Saturn's rings; elongation is apparent separation from the Sun. */
+export function planetIllumination(planet, time) {
+    assertPlanet(planet);
+    assertSupported(time);
+    return planetIlluminationAtTT(planet, ttDays(time));
+}
+/** INTERNAL: TT-labeled evidence bypasses the civil-time Delta-T conversion. */
+export function planetApparentAtTT(planet, tt) {
+    const direction = equatorialFromVector(gyration(planetGeoVectorEqj(planet, tt), tt, PrecessDirection.From2000));
+    // Aberration changes direction, not physical range; keep Earth at reception for distance.
+    const range = planetGeoVectorEqj(planet, tt, false);
+    return { raDeg: direction.raDeg, decDeg: direction.decDeg, distanceAu: Math.hypot(range.x, range.y, range.z) };
+}
+/** Geometric position at the requested instant; accepts Earth. */
+export function planetHeliocentricPosition(planet, time) {
+    assertPlanet(planet, true);
+    assertSupported(time);
+    const p = planetHelioVector(planet, ttDays(time));
+    return { xAu: p.x, yAu: p.y, zAu: p.z };
+}
+/** Apparent geocentric position with light-time, aberration, precession, and nutation. */
+export function planetPosition(planet, time) {
+    assertPlanet(planet);
+    assertSupported(time);
+    return planetApparentAtTT(planet, ttDays(time));
+}
+/** Refracted topocentric position; altitude remains relative to the horizontal plane. */
+export function planetAltAz(planet, time, observer) {
+    assertPlanet(planet);
+    assertSupported(time);
+    assertObserver(observer);
+    const ut = utDays(time);
+    return refract(topoAltAzUnrefracted(planetGeoVectorEqj(planet, ttDaysFromUt(ut)), ut, observer));
+}

package/dist/solar.d.ts

@@ -67,7 +67,7 @@ export declare function eclipseKindFromUmbra(k: number): 'total' | 'annular';
  *      interval, or if no visible eclipse remains before the end of it.
  * @throws {RangeError} if `after` is invalid or `observer` is out of range.
  */
-export declare function nextSolarEclipse(after: Date, observer: Observer): SolarEclipse;
+export declare function nextSolarEclipse(after: Date, observer: Observer, heightAboveGroundM?: number): SolarEclipse;
 /**
  * The last solar eclipse `observer` can see whose peak falls strictly before
  * `before`, skipping peaks within 100 ms of it, just as `nextSolarEclipse`
@@ -77,6 +77,6 @@ export declare function nextSolarEclipse(after: Date, observer: Observer): Solar
  *      interval, or if no visible eclipse remains after the start of it.
  * @throws {RangeError} if `before` is invalid or `observer` is out of range.
  */
-export declare function previousSolarEclipse(before: Date, observer: Observer): SolarEclipse;
+export declare function previousSolarEclipse(before: Date, observer: Observer, heightAboveGroundM?: number): SolarEclipse;
 /** Solar eclipses `observer` can see with peaks in `[startUtc, endUtc)`, sorted ascending. Contacts may fall outside the window. */
-export declare function solarEclipses(startUtc: Date, endUtc: Date, observer: Observer): SolarEclipse[];
+export declare function solarEclipses(startUtc: Date, endUtc: Date, observer: Observer, heightAboveGroundM?: number): SolarEclipse[];