Calculating Moon illumination, terminator angle and wobble

[offsky]

This great library already calculates the phase of the moon. I was wondering if it might be possible to also calculate the illuminated fraction of the moon, which isn't the same as the phase, due to it being a sphere. Im currently using the code here to get this value, so that I can accurately draw a picture of the moon.
https://github.com/mourner/suncalc/blob/master/suncalc.js#L230

There is another thing that would be useful that I haven't found anywhere. And I am sorry that I dont even know the correct terminology to describe it, so hopefully this makes sense. The moon wobbles slightly, so you can see different parts on different nights. Google calls this "Libration", so I'll go with that. Also, the angle of the terminator with respect to the moon's pole changes. To more accurately draw the moon (as I am trying to do) it would be super helpful if Astronomy Engine could calculate these values.

This may be outside the scope of this library, but I thought I would ask :)

[cosinekitty]

Hi again, Jake! About the illuminated fraction, take a look at the object returned by the Illumination function. It is a JavaScript class called IlluminationInfo. It contains both the phase and fraction values.

About libration, no, currently Astronomy Engine does not calculate that. I don't know how to do that yet, but I have added issue #126 as a reminder to research it to determine feasibility.

[offsky]

Doh! I should have read your docs more carefully about the illumination function. Looking at it now. Thanks!

[offsky]

Does "libration" include the angle of the terminator too? Because that might be easier to calculate than the wobble. As far as I understand it, it changes because of the 5deg tilt of the moons orbit, so I think (being no expert) that the positions of the moon and earth relative to the sun are all thats needed. I am probably wrong.

[cosinekitty]

I totally understand it is easy to miss something, because there is a lot of stuff in this library! I'm happy to provide guidance.

The terminator angle is where the sunlit portion of the Moon ends and the shaded part begins (at least, for an ideal spheroid without craters, mountains, etc). In addition, the moon's libration affects which portions of the Moon are visible. If you imagine holding a ball that is lit by a lamp, you can rotate the orientation you are holding it, without moving the ball's center in space, and the terminator will not change, even though you are seeing different parts of the ball. At least, the terminator does not change in the sense of angles of light/dark as seen from an observer on the Earth. So knowing the relative centers of the Sun, Earth, and Moon are not enough to determine libration.

Libration is a wobbling caused by the imperfect tidal locking of the Moon. If the Moon's orbit around the Earth (or more accurately, the Earth/Moon co-orbit around their common barycenter) were perfectly circular, there would be no libration, and the exact same portion of the Moon's near side would always be visible. The Moon is tidally locked with the same side facing the Earth, but only on average. The Moon's orbit is not circular, or even elliptical. It is a total mess because of the Earth and the Moon both orbiting the Sun, causing a complicated 3-body system. (As a side note, calculating Earth/Moon dynamics is by far the most complicated thing in all of Astronomy Engine.)

At times when the Moon is closer to the Earth, its orbital speed increases, and this causes a discrepancy between its rotation rate and its orbital speed. The same thing happens in reverse when it is farther than its mean distance from the Earth.

The libration wobble is caused by a complicated dance of tidal forces and conservation of angular momentum, and likely includes some plastic deformation terms for the hot interiors of both bodies. I doubt it is simple to calculate, but I will at least take a look to see what experts have written about it.

Libration would certainly be a nice addition to Astronomy Engine, but I would need to find a published algorithm and authoritative test data to verify I implemented it correctly. It would also need to be a small enough amount of code to justify inclusion, since I suspect only a minority of developers would use it.

[offsky]

Thanks for the explanation. I am enjoying learning about all of this.