ascii-side-of-the-moon 1.0.9 → 1.0.11

package/dist/index.d.cts

@@ -1,3 +1,10 @@
+/**
+ * Reference frame for viewing the moon.
+ * - celestial_up: Standard geocentric orientation with celestial north up
+ * - celestial_down: Inverted geocentric orientation with celestial south up
+ * - observer: Observer-relative orientation with zenith up, uses lat/lon to calculate parallactic angle
+ */
+type Frame = "celestial_up" | "celestial_down" | "observer";
 interface MoonLibration {
     /** Ecliptic longitude libration (degrees). */
     elon: number;
@@ -57,8 +64,16 @@ interface RenderOptions {
     invert?: boolean;
     /** If true, prefer legacy block elements instead of twelfth-circle glyphs. (Unused now.) */
     forceLegacySymbols?: boolean;
-    /** Controls whether the renderer draws the horizon overlay (default true). */
+    /** Controls whether the renderer draws the horizon overlay (default true for observer frame). */
     showHorizon?: boolean;
+    /**
+     * Reference frame for viewing the moon.
+     * - celestial_up: Standard geocentric orientation with celestial north up (no parallactic rotation)
+     * - celestial_down: Inverted geocentric orientation with celestial south up (180° rotation)
+     * - observer: Observer-relative orientation with zenith up (uses parallactic angle from MoonState.position)
+     * Defaults to 'observer' if MoonState.position is available, 'celestial_up' otherwise.
+     */
+    frame?: Frame;
 }
 
 declare function getMoonState(date: Date, observerLocation?: ObserverLocation): MoonState;
@@ -82,8 +97,11 @@ declare function getMoonPhase(moonState: MoonState): string;
  * 2. Calculate sun direction in CELESTIAL frame (standard north-up orientation)
  * 3. Apply Lambertian phase lighting to create illumination mask (in celestial frame)
  * 4. Combine texture with phase mask (both in celestial frame)
- * 5. Rotate the COMBINED result by parallactic angle to match observer's view
- * 6. Optionally overlay horizon line
+ * 5. Rotate the COMBINED result based on frame:
+ *    - celestial_up: no rotation (celestial north up)
+ *    - celestial_down: 180° rotation (celestial south up)
+ *    - observer: rotate by parallactic angle to match observer's view (zenith up)
+ * 6. Optionally overlay horizon line (only for observer frame)
  *
  * Key insight: The phase illumination is a property of the moon itself (which physical
  * areas are lit by the sun). When we rotate the moon's appearance for the observer,
@@ -92,4 +110,4 @@ declare function getMoonPhase(moonState: MoonState): string;
  */
 declare function renderMoon(state: MoonState, _options?: RenderOptions): string;
 
-export { type MoonLibration, type MoonPhase, type MoonPosition, type MoonSize, type MoonState, type ObserverLocation, type RenderOptions, getMoonPhase, getMoonState, renderMoon };
+export { type Frame, type MoonLibration, type MoonPhase, type MoonPosition, type MoonSize, type MoonState, type ObserverLocation, type RenderOptions, getMoonPhase, getMoonState, renderMoon };

package/dist/index.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Reference frame for viewing the moon.
+ * - celestial_up: Standard geocentric orientation with celestial north up
+ * - celestial_down: Inverted geocentric orientation with celestial south up
+ * - observer: Observer-relative orientation with zenith up, uses lat/lon to calculate parallactic angle
+ */
+type Frame = "celestial_up" | "celestial_down" | "observer";
 interface MoonLibration {
     /** Ecliptic longitude libration (degrees). */
     elon: number;
@@ -57,8 +64,16 @@ interface RenderOptions {
     invert?: boolean;
     /** If true, prefer legacy block elements instead of twelfth-circle glyphs. (Unused now.) */
     forceLegacySymbols?: boolean;
-    /** Controls whether the renderer draws the horizon overlay (default true). */
+    /** Controls whether the renderer draws the horizon overlay (default true for observer frame). */
     showHorizon?: boolean;
+    /**
+     * Reference frame for viewing the moon.
+     * - celestial_up: Standard geocentric orientation with celestial north up (no parallactic rotation)
+     * - celestial_down: Inverted geocentric orientation with celestial south up (180° rotation)
+     * - observer: Observer-relative orientation with zenith up (uses parallactic angle from MoonState.position)
+     * Defaults to 'observer' if MoonState.position is available, 'celestial_up' otherwise.
+     */
+    frame?: Frame;
 }
 
 declare function getMoonState(date: Date, observerLocation?: ObserverLocation): MoonState;
@@ -82,8 +97,11 @@ declare function getMoonPhase(moonState: MoonState): string;
  * 2. Calculate sun direction in CELESTIAL frame (standard north-up orientation)
  * 3. Apply Lambertian phase lighting to create illumination mask (in celestial frame)
  * 4. Combine texture with phase mask (both in celestial frame)
- * 5. Rotate the COMBINED result by parallactic angle to match observer's view
- * 6. Optionally overlay horizon line
+ * 5. Rotate the COMBINED result based on frame:
+ *    - celestial_up: no rotation (celestial north up)
+ *    - celestial_down: 180° rotation (celestial south up)
+ *    - observer: rotate by parallactic angle to match observer's view (zenith up)
+ * 6. Optionally overlay horizon line (only for observer frame)
  *
  * Key insight: The phase illumination is a property of the moon itself (which physical
  * areas are lit by the sun). When we rotate the moon's appearance for the observer,
@@ -92,4 +110,4 @@ declare function getMoonPhase(moonState: MoonState): string;
  */
 declare function renderMoon(state: MoonState, _options?: RenderOptions): string;
 
-export { type MoonLibration, type MoonPhase, type MoonPosition, type MoonSize, type MoonState, type ObserverLocation, type RenderOptions, getMoonPhase, getMoonState, renderMoon };
+export { type Frame, type MoonLibration, type MoonPhase, type MoonPosition, type MoonSize, type MoonState, type ObserverLocation, type RenderOptions, getMoonPhase, getMoonState, renderMoon };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import*as T from'astronomy-engine';var s=T.default??T;function p($,g){let n=new Date($.getTime());return n.setDate(n.getDate()+g),n}function z($){return ($%360+360)%360}function P($){let g=s.GeoVector(s.Body.Sun,$,true),n=s.GeoVector(s.Body.Moon,$,true),t=s.EquatorFromVector(g),_=s.EquatorFromVector(n),B=(t.ra-_.ra)*15*s.DEG2RAD,M=_.dec*s.DEG2RAD,a=t.dec*s.DEG2RAD,o=Math.sin(B),i=Math.cos(B),e=o,m=Math.cos(M)*Math.tan(a)-Math.sin(M)*i,A=Math.atan2(e,m)*s.RAD2DEG;return z(A)}function D($){let g=($%24+24)%24;return g>12&&(g-=24),g}function X($){let g=s.Illumination(s.Body.Moon,$).phase_fraction;return s.Illumination(s.Body.Moon,p($,1)).phase_fraction>g}function N($,g,n){let t=s.SiderealTime($),_=g.longitude/15,B=D(_+t-n.ra)*15*s.DEG2RAD,M=g.latitude*s.DEG2RAD,a=n.dec*s.DEG2RAD,o=Math.sin(B),i=Math.tan(M)*Math.cos(a)-Math.sin(a)*Math.cos(B);return Math.atan2(o,i)*s.RAD2DEG}function Y($,g){let n=new s.Observer(g.latitude,g.longitude,g.elevationMeters??0),t=s.Equator(s.Body.Moon,$,n,true,true),_=s.Horizon($,n,t.ra,t.dec,"normal");return {azimuth:z(_.azimuth),altitude:_.altitude,parallacticAngle:N($,g,t)}}function G($,g){let n=s.Illumination(s.Body.Moon,$),t=s.Libration($);return {date:$,phase:{phaseAngleDeg:n.phase_angle,illuminatedFraction:n.phase_fraction,isWaxing:X($),brightLimbAngle:P($)},size:{distanceKm:t.dist_km,angularDiameterDeg:t.diam_deg},libration:{elon:t.elon,elat:t.elat},position:g?Y($,g):void 0}}function H($){let{phaseAngleDeg:g,illuminatedFraction:n}=$.phase,t=$.phase.isWaxing??g>90,_=(g%360+360)%360,R=_>180?360-_:_,B=10,M=10,a=8,o=.98,i=.02,e=.02;return R<=B||n>=o?"Full Moon":R>=180-M||n<=i?"New Moon":Math.abs(R-90)<=a||Math.abs(n-.5)<=e?t?"First Quarter":"Last Quarter":R<90?t?"Waxing Gibbous":"Waning Gibbous":t?"Waxing Crescent":"Waning Crescent"}var K={moons:[{index:0,distance_km:405493.5,libration_elat:-0.888,libration_elon:-0.412,ascii:`                                                            
+import*as z from'astronomy-engine';var o=z.default??z;function Y($,g){let n=new Date($.getTime());return n.setDate(n.getDate()+g),n}function j($){return ($%360+360)%360}function G($){let g=o.GeoVector(o.Body.Sun,$,true),n=o.GeoVector(o.Body.Moon,$,true),_=o.EquatorFromVector(g),t=o.EquatorFromVector(n),B=(_.ra-t.ra)*15*o.DEG2RAD,e=t.dec*o.DEG2RAD,s=_.dec*o.DEG2RAD,a=Math.sin(B),i=Math.cos(B),r=a,l=Math.cos(e)*Math.tan(s)-Math.sin(e)*i,m=Math.atan2(r,l)*o.RAD2DEG;return j(m)}function H($){let g=($%24+24)%24;return g>12&&(g-=24),g}function v($){let g=o.Illumination(o.Body.Moon,$).phase_fraction;return o.Illumination(o.Body.Moon,Y($,1)).phase_fraction>g}function J($,g,n){let _=o.SiderealTime($),t=g.longitude/15,B=H(t+_-n.ra)*15*o.DEG2RAD,e=g.latitude*o.DEG2RAD,s=n.dec*o.DEG2RAD,a=Math.sin(B),i=Math.tan(e)*Math.cos(s)-Math.sin(s)*Math.cos(B);return Math.atan2(a,i)*o.RAD2DEG}function V($,g){let n=new o.Observer(g.latitude,g.longitude,g.elevationMeters??0),_=o.Equator(o.Body.Moon,$,n,true,true),t=o.Horizon($,n,_.ra,_.dec,"normal");return {azimuth:j(t.azimuth),altitude:t.altitude,parallacticAngle:J($,g,_)}}function Q($,g){let n=o.Illumination(o.Body.Moon,$),_=o.Libration($);return {date:$,phase:{phaseAngleDeg:n.phase_angle,illuminatedFraction:n.phase_fraction,isWaxing:v($),brightLimbAngle:G($)},size:{distanceKm:_.dist_km,angularDiameterDeg:_.diam_deg},libration:{elon:_.elon,elat:_.elat},position:g?V($,g):void 0}}function I($){let{phaseAngleDeg:g,illuminatedFraction:n}=$.phase,_=$.phase.isWaxing??g>90,t=(g%360+360)%360,R=t>180?360-t:t,B=10,e=10,s=8,a=.98,i=.02,r=.02;return R<=B||n>=a?"Full Moon":R>=180-e||n<=i?"New Moon":Math.abs(R-90)<=s||Math.abs(n-.5)<=r?_?"First Quarter":"Last Quarter":R<90?_?"Waxing Gibbous":"Waning Gibbous":_?"Waxing Crescent":"Waning Crescent"}var Z={moons:[{index:0,distance_km:405493.5,libration_elat:-0.888,libration_elon:-0.412,ascii:`                                                            
                                                             
                         ._     . -   .                      
                        ,_++> a, +.    \`-.                   
@@ -894,12 +894,12 @@ import*as T from'astronomy-engine';var s=T.default??T;function p($,g){let n=new
                       'FFF'"Z"@MGR^^'\`                      
                                                             
                                                             
-`}]};var c=60,d=29,J=-45;function V($){let g=$.split(`
-`),n=1/0,t=-1/0,_=1/0,R=-1/0;if(g.forEach((a,o)=>{let i=a.search(/\S/);if(i!==-1){let e=a.search(/\s+$/);n=Math.min(n,i),t=Math.max(t,e===-1?a.length-1:e-1),_===1/0&&(_=o),R=o;}}),n===1/0)return {width:c,height:d,centerX:Math.floor(c/2),centerY:Math.floor(d/2)};let B=t-n+1,M=R-_+1;return {width:B,height:M,centerX:n+Math.floor(B/2),centerY:_+Math.floor(M/2)}}function L($,g,n){return Math.min(n,Math.max(g,$))}function x($){return $*Math.PI/180}function Q($,g,n,t=0){let _=x($),R=x(t),B;g!==void 0?B=x(g):B=x(n?270:90);let M=-Math.sin(B),a=-Math.cos(B),o=M*Math.sin(_),i=a*Math.sin(_),e=Math.cos(_),m=i*Math.cos(R)-e*Math.sin(R),A=i*Math.sin(R)+e*Math.cos(R);i=m,e=A;let W=Math.sqrt(o*o+i*i+e*e);return {sx:o/W,sy:i/W,sz:e/W}}function I($,g,n,t,_){let R=1/c,B=1/d,M=[-0.5,-0.25,0,.25,.5],a=0,o=0;for(let i of M)for(let e of M){let m=$+i*R,A=g+e*B,W=m*m+A*A;if(W>1)continue;let w=Math.sqrt(Math.max(0,1-W)),b=m*n+A*t+w*_;a+=Math.max(0,b),o++;}return o===0?0:a/o}function S($){let t=0,_=1/0;for(let R=0;R<K.moons.length;R++){let B=K.moons[R],M=Math.abs(B.distance_km-$.size.distanceKm)*1,a=Math.abs(B.libration_elat-$.libration.elat)*1e4,o=Math.abs(B.libration_elon-$.libration.elon)*1e4,i=M+a+o;i<_&&(_=i,t=R);}return K.moons[t]}var k=22/10;function q($,g,n,t){let _=(g%360+360)%360;if(Math.abs(_)<.1)return $;let R=$.split(`
-`),B=R.length,M=R[0]?.length??0,a=n??(M-1)/2,o=t??(B-1)/2,i=_*Math.PI/180,e=Math.cos(i),m=Math.sin(i),A=Array.from({length:B},()=>Array(M).fill(" "));for(let W=0;W<B;W++)for(let w=0;w<M;w++){let b=w-a,F=(W-o)*k,r=b*e-F*m,E=b*m+F*e,u=Math.round(r+a),y=Math.round(E/k+o);if(u>=0&&u<M&&y>=0&&y<B){let l=R[y]?.[u]??" ";A[W][w]=l;}}return A.map(W=>W.join("")).join(`
-`)}function C($,g={}){let t=(g??{}).showHorizon!==false,_=S($),R=_.ascii.split(`
-`),B=V(_.ascii),{sx:M,sy:a,sz:o}=Q($.phase.phaseAngleDeg,$.phase.brightLimbAngle,$.phase.isWaxing,$.libration.elat),i=Array.from({length:d},()=>Array(c).fill(0)),e=Array.from({length:d},()=>Array(c).fill(-1)),m=Array.from({length:d},()=>Array(c).fill(false)),A=0,W=0;for(let r=0;r<d;r++)for(let E=0;E<c;E++){let u=E-B.centerX,y=r-B.centerY,l=u/(B.width/2),f=y/(B.height/2),h=l*l+f*f;if(h>1){i[r][E]=0,e[r][E]=-1;continue}m[r][E]=true,A++;let Z=I(l,f,M,a,o);i[r][E]=Z,Z>0&&W++;let j=Math.sqrt(Math.max(0,1-h));e[r][E]=l*M+f*a+j*o;}let w=Array.from({length:d},()=>Array(c).fill(false));if(W>0)for(let r=0;r<d;r++)for(let E=0;E<c;E++)w[r][E]=i[r][E]>0;else {let r=L($.phase.illuminatedFraction??0,0,1),E=Math.max(1,Math.round(r*A)),u=[];for(let y=0;y<d;y++)for(let l=0;l<c;l++)m[y][l]&&u.push({ix:l,iy:y,v:e[y][l]});u.sort((y,l)=>l.v-y.v);for(let y=0;y<Math.min(E,u.length);y++){let{ix:l,iy:f}=u[y];w[f][l]=true;}}let b=[];for(let r=0;r<d;r++){let E="",u=R[r]??"";for(let y=0;y<c;y++)w[r][y]?E+=u[y]??" ":E+=" ";b.push(E);}let F=b.join(`
-`);if($.position?.parallacticAngle!==void 0){let r=-$.position.parallacticAngle+J;Math.abs(r)>.1&&(F=q(F,r,B.centerX,B.centerY));}return t?U(F,$,B):F}function U($,g,n){let t=g.position;if(!t||g.size.angularDiameterDeg<=0)return $;let _=t.altitude??0,R=g.size.angularDiameterDeg/2,B=_+R;if(_-R>=0)return $;let a=$.split(`
-`),o=g.size.angularDiameterDeg/Math.max(1,n.height),i=n.centerY+_/o;i=Math.round(L(i,0,d-1));let e;return B<=0?e=`${Math.abs(_).toFixed(1).replace(/\.0$/,"")}-deg-below-horizon`:e="horizon",a[i]=O(e),a.join(`
-`)}function O($){let n=`--${$.trim().replace(/\s+/g,"-")}--`;if(n.length>c&&(n=n.slice(0,c)),n.length===c)return n;let t=c-n.length,_=Math.floor(t/2),R=t-_;return "-".repeat(_)+n+"-".repeat(R)}export{H as getMoonPhase,G as getMoonState,C as renderMoon};//# sourceMappingURL=index.mjs.map
+`}]};var c=60,A=29,p=-45;function q($){let g=$.split(`
+`),n=1/0,_=-1/0,t=1/0,R=-1/0;if(g.forEach((s,a)=>{let i=s.search(/\S/);if(i!==-1){let r=s.search(/\s+$/);n=Math.min(n,i),_=Math.max(_,r===-1?s.length-1:r-1),t===1/0&&(t=a),R=a;}}),n===1/0)return {width:c,height:A,centerX:Math.floor(c/2),centerY:Math.floor(A/2)};let B=_-n+1,e=R-t+1;return {width:B,height:e,centerX:n+Math.floor(B/2),centerY:t+Math.floor(e/2)}}function X($,g,n){return Math.min(n,Math.max(g,$))}function T($){return $*Math.PI/180}function C($,g,n,_=0){let t=T($),R=T(_),B;g!==void 0?B=T(g):B=T(n?270:90);let e=-Math.sin(B),s=-Math.cos(B),a=e*Math.sin(t),i=s*Math.sin(t),r=Math.cos(t),l=i*Math.cos(R)-r*Math.sin(R),m=i*Math.sin(R)+r*Math.cos(R);i=l,r=m;let W=Math.sqrt(a*a+i*i+r*r);return {sx:a/W,sy:i/W,sz:r/W}}function U($,g,n,_,t){let R=1/c,B=1/A,e=[-0.5,-0.25,0,.25,.5],s=0,a=0;for(let i of e)for(let r of e){let l=$+i*R,m=g+r*B,W=l*l+m*m;if(W>1)continue;let d=Math.sqrt(Math.max(0,1-W)),f=l*n+m*_+d*t;s+=Math.max(0,f),a++;}return a===0?0:s/a}function O($){let _=0,t=1/0;for(let R=0;R<Z.moons.length;R++){let B=Z.moons[R],e=Math.abs(B.distance_km-$.size.distanceKm)*1,s=Math.abs(B.libration_elat-$.libration.elat)*1e4,a=Math.abs(B.libration_elon-$.libration.elon)*1e4,i=e+s+a;i<t&&(t=i,_=R);}return Z.moons[_]}var P=22/10;function D($,g,n,_){let t=(g%360+360)%360;if(Math.abs(t)<.1)return $;let R=$.split(`
+`),B=R.length,e=R[0]?.length??0,s=n??(e-1)/2,a=_??(B-1)/2,i=t*Math.PI/180,r=Math.cos(i),l=Math.sin(i),m=Array.from({length:B},()=>Array(e).fill(" "));for(let W=0;W<B;W++)for(let d=0;d<e;d++){let f=d-s,F=(W-a)*P,h=f*r-F*l,x=f*l+F*r,w=Math.round(h+s),M=Math.round(x/P+a);if(w>=0&&w<e&&M>=0&&M<B){let y=R[M]?.[w]??" ";m[W][d]=y;}}return m.map(W=>W.join("")).join(`
+`)}function $$($,g){return g.frame!==void 0?g.frame:$.position!==void 0?"observer":"celestial_up"}function n$($,g={}){let n=g??{},_=$$($,n),t=n.showHorizon??_==="observer",R=O($),B=q(R.ascii),e=R.ascii;Math.abs(p)>.1&&(e=D(e,p,B.centerX,B.centerY));let s=e.split(`
+`),{sx:a,sy:i,sz:r}=C($.phase.phaseAngleDeg,$.phase.brightLimbAngle,$.phase.isWaxing,$.libration.elat),l=Array.from({length:A},()=>Array(c).fill(0)),m=Array.from({length:A},()=>Array(c).fill(-1)),W=Array.from({length:A},()=>Array(c).fill(false)),d=0,f=0;for(let M=0;M<A;M++)for(let y=0;y<c;y++){let b=y-B.centerX,E=M-B.centerY,u=b/(B.width/2),K=E/(B.height/2),k=u*u+K*K;if(k>1){l[M][y]=0,m[M][y]=-1;continue}W[M][y]=true,d++;let L=U(u,K,a,i,r);l[M][y]=L,L>0&&f++;let N=Math.sqrt(Math.max(0,1-k));m[M][y]=u*a+K*i+N*r;}let F=Array.from({length:A},()=>Array(c).fill(false));if(f>0)for(let M=0;M<A;M++)for(let y=0;y<c;y++)F[M][y]=l[M][y]>0;else {let M=X($.phase.illuminatedFraction??0,0,1),y=Math.max(1,Math.round(M*d)),b=[];for(let E=0;E<A;E++)for(let u=0;u<c;u++)W[E][u]&&b.push({ix:u,iy:E,v:m[E][u]});b.sort((E,u)=>u.v-E.v);for(let E=0;E<Math.min(y,b.length);E++){let{ix:u,iy:K}=b[E];F[K][u]=true;}}let h=[];for(let M=0;M<A;M++){let y="",b=s[M]??"";for(let E=0;E<c;E++)F[M][E]?y+=b[E]??" ":y+=" ";h.push(y);}let x=h.join(`
+`),w=0;return _==="celestial_down"?w=180:_==="observer"&&$.position?.parallacticAngle!==void 0&&(w=-$.position.parallacticAngle),Math.abs(w)>.1&&(x=D(x,w,B.centerX,B.centerY)),t?g$(x,$,B):x}function g$($,g,n){let _=g.position;if(!_||g.size.angularDiameterDeg<=0)return $;let t=_.altitude??0,R=g.size.angularDiameterDeg/2,B=t+R;if(t-R>=0)return $;let s=$.split(`
+`),a=g.size.angularDiameterDeg/Math.max(1,n.height),i=n.centerY+t/a;i=Math.round(X(i,0,A-1));let r;return B<=0?r=`${Math.abs(t).toFixed(1).replace(/\.0$/,"")}-deg-below-horizon`:r="horizon",s[i]=_$(r),s.join(`
+`)}function _$($){let n=`--${$.trim().replace(/\s+/g,"-")}--`;if(n.length>c&&(n=n.slice(0,c)),n.length===c)return n;let _=c-n.length,t=Math.floor(_/2),R=_-t;return "-".repeat(t)+n+"-".repeat(R)}export{I as getMoonPhase,Q as getMoonState,n$ as renderMoon};//# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map