Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Astronoby::Moon#current_phase_fraction #115

Merged
merged 1 commit into from
Dec 10, 2024

Conversation

rhannequin
Copy link
Owner

While #illuminated_fraction already provides a valid information on how much the Moon seems illuminated as observed from the Earth, it doesn't help deduce the current phase name. When the Moon is 45% illuminated, it can be either the First Quarter or the Last Quarter, there is no way of knowing without calculating when is was the previous Full Moon and when is the next one.

To help with this, we introduce #current_phase_fraction, based on the mean elongation, which is a number from 0 to 1 which always increase while we're getting closer to the next New Moon.

As it is using #mean_elongation, the result is not extremely precise, however it is precise enough to deduce the current phase name for a given day.

For a user wanting to get accurate phase times, it is preferred to use ::monthly_phase_events.

# ~ time of first quarter in December 2024
time = Time.utc(2024, 12, 8, 15, 26)

Astronoby::Moon.new(time: time)
  .illuminated_fraction
  .round(2)
# => 0.5

Astronoby::Moon.new(time: time)
  .current_phase_fraction
  .round(2)
# => 0.26

# ~ time of last quarter in December 2024
time = Time.utc(2024, 12, 22, 22, 18)

Astronoby::Moon.new(time: time)
  .illuminated_fraction
  .round(2)
# => 0.5

Astronoby::Moon.new(time: time)
  .current_phase_fraction
  . round(2)
# => 0.74

Fixes #101

While `#illuminated_fraction` already provides a valid information on
how much the Moon seems illuminated as observed from the Earth, it
doesn't help deduce the current phase name. When the Moon is 45% illuminated,
it can be either the First Quarter or the Last Quarter, there is no way
of knowing without calculating when is was the previous Full Moon and
when is the next one.

To help with this, we introduce `#current_phase_fraction`, based on the
mean elongation, which is a number from 0 to 1 which always increase
while we're getting closer to the next New Moon.

As it is using `#mean_elongation`, the result is not extremely precise,
however it is precise enough to deduce the current phase name for a
given day.

For a user wanting to get accurate phase times, it is preferred to use
`::monthly_phase_events`.

```rb
 # ~ time of first quarter in December 2024
time = Time.utc(2024, 12, 8, 15, 26)

Astronoby::Moon.new(time: time)
  .illuminated_fraction
  .round(2)
 # => 0.5

Astronoby::Moon.new(time: time)
  .current_phase_fraction
  .round(2)
 # => 0.26

 # ~ time of last quarter in December 2024
time = Time.utc(2024, 12, 22, 22, 18)

Astronoby::Moon.new(time: time)
  .illuminated_fraction
  .round(2)
 # => 0.5

Astronoby::Moon.new(time: time)
  .current_phase_fraction
  . round(2)
 # => 0.74
```

Fixes #101
@rhannequin rhannequin self-assigned this Dec 9, 2024
@trevorturk
Copy link

🥳

@rhannequin rhannequin merged commit 1ea6600 into main Dec 10, 2024
26 checks passed
@rhannequin rhannequin deleted the add-moon-current-phase-fraction branch December 10, 2024 09:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Moon "phase" and "phase name"
2 participants