mirror of
https://github.com/acamarata/moon-sighting-dart.git
synced 2026-07-01 03:04:36 +00:00
147 lines
4.3 KiB
Markdown
147 lines
4.3 KiB
Markdown
# API Reference
|
|
|
|
## getMoonPhase
|
|
|
|
```dart
|
|
MoonPhaseResult getMoonPhase([DateTime? date])
|
|
```
|
|
|
|
Returns the moon phase for the given UTC date, or the current moment if `date` is null.
|
|
|
|
### MoonPhaseResult fields
|
|
|
|
| Field | Type | Description |
|
|
| --- | --- | --- |
|
|
| `phase` | `MoonPhaseName` | Enum: `newMoon`, `waxingCrescent`, `firstQuarter`, `waxingGibbous`, `fullMoon`, `waningGibbous`, `lastQuarter`, `waningCrescent` |
|
|
| `phaseName` | `String` | Human-readable phase name |
|
|
| `phaseSymbol` | `String` | Moon emoji for the current phase |
|
|
| `illumination` | `double` | Percent illuminated (0-100) |
|
|
| `age` | `double` | Hours since the last new moon |
|
|
| `elongationDeg` | `double` | Moon-Sun elongation in degrees |
|
|
| `isWaxing` | `bool` | True when illumination is increasing |
|
|
| `nextNewMoon` | `DateTime` | Next new moon (UTC) |
|
|
| `nextFullMoon` | `DateTime` | Next full moon (UTC) |
|
|
| `prevNewMoon` | `DateTime` | Previous new moon (UTC) |
|
|
|
|
---
|
|
|
|
## getMoonPosition
|
|
|
|
```dart
|
|
MoonPosition getMoonPosition(
|
|
DateTime? date,
|
|
double lat,
|
|
double lon, {
|
|
double elevation = 0,
|
|
})
|
|
```
|
|
|
|
Computes the topocentric position of the moon for an observer at the given location. Applies atmospheric refraction to the altitude.
|
|
|
|
| Parameter | Type | Default | Description |
|
|
| --- | --- | --- | --- |
|
|
| `date` | `DateTime?` | now | UTC date and time |
|
|
| `lat` | `double` | required | Observer latitude (-90 to 90) |
|
|
| `lon` | `double` | required | Observer longitude (-180 to 180) |
|
|
| `elevation` | `double` | 0 | Observer elevation in meters |
|
|
|
|
### MoonPosition fields
|
|
|
|
| Field | Type | Description |
|
|
| --- | --- | --- |
|
|
| `azimuth` | `double` | Degrees from North, clockwise (0-360) |
|
|
| `altitude` | `double` | Degrees above horizon (refraction applied) |
|
|
| `distance` | `double` | Earth-Moon distance in km |
|
|
| `parallacticAngle` | `double` | Parallactic angle in radians |
|
|
|
|
---
|
|
|
|
## getMoonIllumination
|
|
|
|
```dart
|
|
MoonIlluminationResult getMoonIllumination([DateTime? date])
|
|
```
|
|
|
|
Returns illumination data for the given UTC date, or now if null.
|
|
|
|
### MoonIlluminationResult fields
|
|
|
|
| Field | Type | Description |
|
|
| --- | --- | --- |
|
|
| `fraction` | `double` | Illuminated fraction (0-1) |
|
|
| `phase` | `double` | Phase cycle position (0=new, 0.25=first quarter, 0.5=full, 0.75=last quarter) |
|
|
| `angle` | `double` | Bright limb position angle in radians |
|
|
| `isWaxing` | `bool` | True when waxing |
|
|
|
|
---
|
|
|
|
## getMoonVisibilityEstimate
|
|
|
|
```dart
|
|
MoonVisibilityEstimate getMoonVisibilityEstimate(
|
|
DateTime? date,
|
|
double lat,
|
|
double lon, {
|
|
double elevation = 0,
|
|
})
|
|
```
|
|
|
|
Estimates lunar crescent visibility using the Odeh (2006) criterion. Pass a post-sunset time for meaningful results.
|
|
|
|
| Parameter | Type | Default | Description |
|
|
| --- | --- | --- | --- |
|
|
| `date` | `DateTime?` | now | UTC date and time (use post-sunset) |
|
|
| `lat` | `double` | required | Observer latitude |
|
|
| `lon` | `double` | required | Observer longitude |
|
|
| `elevation` | `double` | 0 | Observer elevation in meters |
|
|
|
|
### MoonVisibilityEstimate fields
|
|
|
|
| Field | Type | Description |
|
|
| --- | --- | --- |
|
|
| `v` | `double` | Odeh V parameter |
|
|
| `zone` | `OdehZone` | Visibility zone (a, b, c, or d) |
|
|
| `description` | `String` | Human-readable zone description |
|
|
| `isVisibleNakedEye` | `bool` | True for zone A |
|
|
| `isVisibleWithOpticalAid` | `bool` | True for zones A and B |
|
|
| `arcl` | `double` | Sun-Moon elongation in degrees |
|
|
| `arcv` | `double` | Arc of vision in degrees |
|
|
| `w` | `double` | Crescent width in arc minutes |
|
|
| `moonAboveHorizon` | `bool` | True if the moon is above the horizon at the given time |
|
|
|
|
### OdehZone values
|
|
|
|
| Zone | V threshold | Meaning |
|
|
| --- | --- | --- |
|
|
| A | V >= 5.65 | Visible with naked eye |
|
|
| B | V >= 2.00 | Visible with optical aid, may be naked-eye visible |
|
|
| C | V >= -0.96 | Visible with optical aid only |
|
|
| D | V < -0.96 | Not visible even with optical aid |
|
|
|
|
---
|
|
|
|
## getMoon
|
|
|
|
```dart
|
|
MoonSnapshot getMoon(
|
|
DateTime? date,
|
|
double lat,
|
|
double lon, {
|
|
double elevation = 0,
|
|
})
|
|
```
|
|
|
|
Convenience function that runs all four computations in one call.
|
|
|
|
### MoonSnapshot fields
|
|
|
|
| Field | Type | Description |
|
|
| --- | --- | --- |
|
|
| `phase` | `MoonPhaseResult` | Phase result |
|
|
| `position` | `MoonPosition` | Position result |
|
|
| `illumination` | `MoonIlluminationResult` | Illumination result |
|
|
| `visibility` | `MoonVisibilityEstimate` | Visibility estimate |
|
|
|
|
---
|
|
|
|
[Home](Home)
|