@hebcal/noaa 0.8.14 → 0.8.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +17 -630
  2. package/package.json +9 -7
package/README.md CHANGED
@@ -11,634 +11,21 @@ Kosher Zmanim itself is a TS/JS port of the [KosherJava](https://github.com/Kosh
11
11
  $ npm install @hebcal/noaa
12
12
  ```
13
13
 
14
- ## Classes
15
-
16
- <dl>
17
- <dt><a href="#GeoLocation">GeoLocation</a></dt>
18
- <dd><p>A class that contains location information such as latitude and longitude required for astronomical calculations. The
19
- elevation field may not be used by some calculation engines and would be ignored if set.</p>
20
- </dd>
21
- <dt><a href="#NOAACalculator">NOAACalculator</a></dt>
22
- <dd><p>Implementation of sunrise and sunset methods to calculate astronomical times based on the <a
23
- href="http://noaa.gov">NOAA</a> algorithm. This calculator uses the Java algorithm based on the implementation by <a
24
- href="http://noaa.gov">NOAA - National Oceanic and Atmospheric Administration</a>&#39;s <a href =
25
- "http://www.srrb.noaa.gov/highlights/sunrise/sunrise.html">Surface Radiation Research Branch</a>. NOAA&#39;s <a
26
- href="http://www.srrb.noaa.gov/highlights/sunrise/solareqns.PDF">implementation</a> is based on equations from <a
27
- href="http://www.willbell.com/math/mc1.htm">Astronomical Algorithms</a> by <a
28
- href="http://en.wikipedia.org/wiki/Jean_Meeus">Jean Meeus</a>. Added to the algorithm is an adjustment of the zenith
29
- to account for elevation. The algorithm can be found in the <a
30
- href="http://en.wikipedia.org/wiki/Sunrise_equation">Wikipedia Sunrise Equation</a> article.</p>
31
- </dd>
32
- </dl>
33
-
34
- <a name="GeoLocation"></a>
35
-
36
- ## GeoLocation
37
- A class that contains location information such as latitude and longitude required for astronomical calculations. The
38
- elevation field may not be used by some calculation engines and would be ignored if set.
39
-
40
- **Kind**: global class
41
- **Version**: 1.1
42
- **Author**: &copy; Eliyahu Hershfeld 2004 - 2016
43
-
44
- * [GeoLocation](#GeoLocation)
45
- * [new GeoLocation(name, latitude, longitude, elevation, timeZoneId)](#new_GeoLocation_new)
46
- * [.getElevation()](#GeoLocation+getElevation) ⇒ <code>number</code>
47
- * [.setElevation(elevation)](#GeoLocation+setElevation)
48
- * [.getLatitude()](#GeoLocation+getLatitude) ⇒ <code>number</code>
49
- * [.getLongitude()](#GeoLocation+getLongitude) ⇒ <code>number</code>
50
- * [.getLocationName()](#GeoLocation+getLocationName) ⇒ <code>string</code> \| <code>null</code>
51
- * [.setLocationName(name)](#GeoLocation+setLocationName)
52
- * [.getTimeZone()](#GeoLocation+getTimeZone) ⇒ <code>string</code>
53
- * [.setTimeZone(timeZoneId)](#GeoLocation+setTimeZone)
54
-
55
- <a name="new_GeoLocation_new"></a>
56
-
57
- ### new GeoLocation(name, latitude, longitude, elevation, timeZoneId)
58
- GeoLocation constructor with parameters for all required fields.
59
-
60
-
61
- | Param | Type | Description |
62
- | --- | --- | --- |
63
- | name | <code>string</code> | The location name for display use such as &quot;Lakewood, NJ&quot; |
64
- | latitude | <code>number</code> | the latitude in a double format such as 40.095965 for Lakewood, NJ. <b>Note: </b> For latitudes south of the equator, a negative value should be used. |
65
- | longitude | <code>number</code> | double the longitude in a double format such as -74.222130 for Lakewood, NJ. <b>Note: </b> For longitudes west of the <a href="http://en.wikipedia.org/wiki/Prime_Meridian">Prime Meridian </a> (Greenwich), a negative value should be used. |
66
- | elevation | <code>number</code> | the elevation above sea level in Meters. Elevation is not used in most algorithms used for calculating sunrise and set. |
67
- | timeZoneId | <code>string</code> | the <code>TimeZone</code> for the location. |
68
-
69
- <a name="GeoLocation+getElevation"></a>
70
-
71
- ### geoLocation.getElevation() ⇒ <code>number</code>
72
- Method to get the elevation in Meters.
73
-
74
- **Kind**: instance method of [<code>GeoLocation</code>](#GeoLocation)
75
- **Returns**: <code>number</code> - Returns the elevation in Meters.
76
- <a name="GeoLocation+setElevation"></a>
77
-
78
- ### geoLocation.setElevation(elevation)
79
- Method to set the elevation in Meters <b>above </b> sea level.
80
-
81
- **Kind**: instance method of [<code>GeoLocation</code>](#GeoLocation)
82
-
83
- | Param | Type | Description |
84
- | --- | --- | --- |
85
- | elevation | <code>number</code> | The elevation to set in Meters. An Error will be thrown if the value is a negative. |
86
-
87
- <a name="GeoLocation+getLatitude"></a>
88
-
89
- ### geoLocation.getLatitude() ⇒ <code>number</code>
90
- **Kind**: instance method of [<code>GeoLocation</code>](#GeoLocation)
91
- **Returns**: <code>number</code> - Returns the latitude.
92
- <a name="GeoLocation+getLongitude"></a>
93
-
94
- ### geoLocation.getLongitude() ⇒ <code>number</code>
95
- **Kind**: instance method of [<code>GeoLocation</code>](#GeoLocation)
96
- **Returns**: <code>number</code> - Returns the longitude.
97
- <a name="GeoLocation+getLocationName"></a>
98
-
99
- ### geoLocation.getLocationName() ⇒ <code>string</code> \| <code>null</code>
100
- **Kind**: instance method of [<code>GeoLocation</code>](#GeoLocation)
101
- **Returns**: <code>string</code> \| <code>null</code> - Returns the location name.
102
- <a name="GeoLocation+setLocationName"></a>
103
-
104
- ### geoLocation.setLocationName(name)
105
- **Kind**: instance method of [<code>GeoLocation</code>](#GeoLocation)
106
-
107
- | Param | Type | Description |
108
- | --- | --- | --- |
109
- | name | <code>string</code> \| <code>null</code> | The setter method for the display name. |
110
-
111
- <a name="GeoLocation+getTimeZone"></a>
112
-
113
- ### geoLocation.getTimeZone() ⇒ <code>string</code>
114
- **Kind**: instance method of [<code>GeoLocation</code>](#GeoLocation)
115
- **Returns**: <code>string</code> - Returns the timeZone.
116
- <a name="GeoLocation+setTimeZone"></a>
117
-
118
- ### geoLocation.setTimeZone(timeZoneId)
119
- Method to set the TimeZone.
120
-
121
- **Kind**: instance method of [<code>GeoLocation</code>](#GeoLocation)
122
-
123
- | Param | Type | Description |
124
- | --- | --- | --- |
125
- | timeZoneId | <code>string</code> | The timeZone to set. |
126
-
127
- <a name="NOAACalculator"></a>
128
-
129
- ## NOAACalculator
130
- Implementation of sunrise and sunset methods to calculate astronomical times based on the <a
131
- href="http://noaa.gov">NOAA</a> algorithm. This calculator uses the Java algorithm based on the implementation by <a
132
- href="http://noaa.gov">NOAA - National Oceanic and Atmospheric Administration</a>'s <a href =
133
- "http://www.srrb.noaa.gov/highlights/sunrise/sunrise.html">Surface Radiation Research Branch</a>. NOAA's <a
134
- href="http://www.srrb.noaa.gov/highlights/sunrise/solareqns.PDF">implementation</a> is based on equations from <a
135
- href="http://www.willbell.com/math/mc1.htm">Astronomical Algorithms</a> by <a
136
- href="http://en.wikipedia.org/wiki/Jean_Meeus">Jean Meeus</a>. Added to the algorithm is an adjustment of the zenith
137
- to account for elevation. The algorithm can be found in the <a
138
- href="http://en.wikipedia.org/wiki/Sunrise_equation">Wikipedia Sunrise Equation</a> article.
139
-
140
- **Kind**: global class
141
- **Author**: &copy; Eliyahu Hershfeld 2011 - 2019
142
-
143
- * [NOAACalculator](#NOAACalculator)
144
- * [new NOAACalculator(geoLocation, date)](#new_NOAACalculator_new)
145
- * _instance_
146
- * [.getSunrise()](#NOAACalculator+getSunrise) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
147
- * [.getSeaLevelSunrise()](#NOAACalculator+getSeaLevelSunrise) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
148
- * [.getBeginCivilTwilight()](#NOAACalculator+getBeginCivilTwilight) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
149
- * [.getBeginNauticalTwilight()](#NOAACalculator+getBeginNauticalTwilight) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
150
- * [.getBeginAstronomicalTwilight()](#NOAACalculator+getBeginAstronomicalTwilight) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
151
- * [.getSunset()](#NOAACalculator+getSunset) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
152
- * [.getSeaLevelSunset()](#NOAACalculator+getSeaLevelSunset) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
153
- * [.getEndCivilTwilight()](#NOAACalculator+getEndCivilTwilight) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
154
- * [.getEndNauticalTwilight()](#NOAACalculator+getEndNauticalTwilight) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
155
- * [.getEndAstronomicalTwilight()](#NOAACalculator+getEndAstronomicalTwilight) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
156
- * [.getSunriseOffsetByDegrees(offsetZenith)](#NOAACalculator+getSunriseOffsetByDegrees) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
157
- * [.getSunsetOffsetByDegrees(offsetZenith)](#NOAACalculator+getSunsetOffsetByDegrees) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
158
- * [.getUTCSunrise0(zenith)](#NOAACalculator+getUTCSunrise0) ⇒ <code>number</code>
159
- * [.getUTCSeaLevelSunrise(zenith)](#NOAACalculator+getUTCSeaLevelSunrise) ⇒ <code>number</code>
160
- * [.getUTCSunset0(zenith)](#NOAACalculator+getUTCSunset0) ⇒ <code>number</code>
161
- * [.getUTCSeaLevelSunset(zenith)](#NOAACalculator+getUTCSeaLevelSunset) ⇒ <code>number</code>
162
- * [.getElevationAdjustment(elevation)](#NOAACalculator+getElevationAdjustment) ⇒ <code>number</code>
163
- * [.adjustZenith(zenith, elevation)](#NOAACalculator+adjustZenith) ⇒ <code>number</code>
164
- * [.getUTCSunrise(date, geoLocation, zenith, adjustForElevation)](#NOAACalculator+getUTCSunrise) ⇒
165
- * [.getUTCSunset(date, geoLocation, zenith, adjustForElevation)](#NOAACalculator+getUTCSunset) ⇒
166
- * [.getTemporalHour(startOfDay, endOfDay)](#NOAACalculator+getTemporalHour) ⇒ <code>number</code>
167
- * [.getSunTransit(startOfDay, endOfDay)](#NOAACalculator+getSunTransit) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
168
- * [.getDateFromTime(time, isSunrise)](#NOAACalculator+getDateFromTime) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
169
- * _static_
170
- * [.CIVIL_ZENITH](#NOAACalculator.CIVIL_ZENITH)
171
- * [.NAUTICAL_ZENITH](#NOAACalculator.NAUTICAL_ZENITH)
172
- * [.ASTRONOMICAL_ZENITH](#NOAACalculator.ASTRONOMICAL_ZENITH)
173
- * [.getTimeOffset(time, offset)](#NOAACalculator.getTimeOffset) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
174
- * [.getSolarElevation(date, lat, lon)](#NOAACalculator.getSolarElevation) ⇒ <code>number</code>
175
- * [.getSolarAzimuth(date, latitude, lon)](#NOAACalculator.getSolarAzimuth) ⇒ <code>number</code>
176
-
177
- <a name="new_NOAACalculator_new"></a>
178
-
179
- ### new NOAACalculator(geoLocation, date)
180
- A constructor that takes in <a href="http://en.wikipedia.org/wiki/Geolocation">geolocation</a> information as a
181
- parameter.
182
-
183
-
184
- | Param | Type | Description |
185
- | --- | --- | --- |
186
- | geoLocation | [<code>GeoLocation</code>](#GeoLocation) | The location information used for calculating astronomical sun times. |
187
- | date | <code>Temporal.PlainDate</code> | |
188
-
189
- <a name="NOAACalculator+getSunrise"></a>
190
-
191
- ### noaaCalculator.getSunrise() ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
192
- The getSunrise method Returns a `Date` representing the
193
- [elevation adjusted](getElevationAdjustment) sunrise time. The zenith used
194
- for the calculation uses [geometric zenith](GEOMETRIC_ZENITH) of 90&deg; plus
195
- [getElevationAdjustment](getElevationAdjustment). This is adjusted
196
- to add approximately 50/60 of a degree to account for 34 archminutes of refraction
197
- and 16 archminutes for the sun's radius for a total of [90.83333&deg;](adjustZenith).
198
-
199
- **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
200
- **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - the `Date` representing the exact sunrise time. If the calculation can't be computed such as
201
- in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it
202
- does not set, a null will be returned. See detailed explanation on top of the page.
203
- **See**
204
-
205
- - adjustZenith
206
- - getSeaLevelSunrise()
207
- - getUTCSunrise
208
-
209
- <a name="NOAACalculator+getSeaLevelSunrise"></a>
210
-
211
- ### noaaCalculator.getSeaLevelSunrise() ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
212
- A method that returns the sunrise without [elevation
213
- adjustment](getElevationAdjustment). Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible light,
214
- something that is not affected by elevation. This method returns sunrise calculated at sea level. This forms the
215
- base for dawn calculations that are calculated as a dip below the horizon before sunrise.
216
-
217
- **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
218
- **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - the `Date` representing the exact sea-level sunrise time. If the calculation can't be computed
219
- such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one
220
- where it does not set, a null will be returned. See detailed explanation on top of the page.
221
- **See**
222
-
223
- - getSunrise
224
- - getUTCSeaLevelSunrise
225
- - getSeaLevelSunset()
226
-
227
- <a name="NOAACalculator+getBeginCivilTwilight"></a>
228
-
229
- ### noaaCalculator.getBeginCivilTwilight() ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
230
- A method that returns the beginning of civil twilight (dawn) using a zenith of [96&deg;](CIVIL_ZENITH).
231
-
232
- **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
233
- **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - The `Date` of the beginning of civil twilight using a zenith of 96&deg;. If the calculation
234
- can't be computed, null will be returned. See detailed explanation on top of the page.
235
- **See**: CIVIL_ZENITH
236
- <a name="NOAACalculator+getBeginNauticalTwilight"></a>
237
-
238
- ### noaaCalculator.getBeginNauticalTwilight() ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
239
- A method that returns the beginning of nautical twilight using a zenith of [102&deg;](NAUTICAL_ZENITH).
240
-
241
- **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
242
- **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - The `Date` of the beginning of nautical twilight using a zenith of 102&deg;. If the
243
- calculation can't be computed null will be returned. See detailed explanation on top of the page.
244
- **See**: NAUTICAL_ZENITH
245
- <a name="NOAACalculator+getBeginAstronomicalTwilight"></a>
246
-
247
- ### noaaCalculator.getBeginAstronomicalTwilight() ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
248
- A method that returns the beginning of astronomical twilight using a zenith of [108&deg;](ASTRONOMICAL_ZENITH).
249
-
250
- **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
251
- **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - The `Date` of the beginning of astronomical twilight using a zenith of 108&deg;. If the
252
- calculation can't be computed, null will be returned. See detailed explanation on top of the page.
253
- **See**: ASTRONOMICAL_ZENITH
254
- <a name="NOAACalculator+getSunset"></a>
255
-
256
- ### noaaCalculator.getSunset() ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
257
- The getSunset method Returns a `Date` representing the
258
- [elevation adjusted](getElevationAdjustment) sunset time. The zenith used for
259
- the calculation uses [geometric zenith](GEOMETRIC_ZENITH) of 90&deg; plus
260
- [getElevationAdjustment](getElevationAdjustment). This is adjusted
261
- to add approximately 50/60 of a degree to account for 34 archminutes of refraction
262
- and 16 archminutes for the sun's radius for a total of [90.83333&deg;](adjustZenith).
263
- Note:
264
- In certain cases the calculates sunset will occur before sunrise. This will typically happen when a timezone
265
- other than the local timezone is used (calculating Los Angeles sunset using a GMT timezone for example). In this
266
- case the sunset date will be incremented to the following date.
267
-
268
- **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
269
- **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - The `Date` representing the exact sunset time. If the calculation can't be computed such as in
270
- the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it
271
- does not set, a null will be returned. See detailed explanation on top of the page.
272
- **See**
273
-
274
- - adjustZenith
275
- - getSeaLevelSunset()
276
- - getUTCSunset
277
-
278
- <a name="NOAACalculator+getSeaLevelSunset"></a>
279
-
280
- ### noaaCalculator.getSeaLevelSunset() ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
281
- A method that returns the sunset without [elevation
282
- adjustment](getElevationAdjustment). Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible light,
283
- something that is not affected by elevation. This method returns sunset calculated at sea level. This forms the
284
- base for dusk calculations that are calculated as a dip below the horizon after sunset.
285
-
286
- **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
287
- **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - The `Date` representing the exact sea-level sunset time. If the calculation can't be computed
288
- such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one
289
- where it does not set, a null will be returned. See detailed explanation on top of the page.
290
- **See**
291
-
292
- - getSunset
293
- - getUTCSeaLevelSunset
294
-
295
- <a name="NOAACalculator+getEndCivilTwilight"></a>
296
-
297
- ### noaaCalculator.getEndCivilTwilight() ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
298
- A method that returns the end of civil twilight using a zenith of [96&deg;](CIVIL_ZENITH).
299
-
300
- **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
301
- **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - The `Date` of the end of civil twilight using a zenith of [96&deg;](CIVIL_ZENITH). If
302
- the calculation can't be computed, null will be returned. See detailed explanation on top of the page.
303
- **See**: CIVIL_ZENITH
304
- <a name="NOAACalculator+getEndNauticalTwilight"></a>
305
-
306
- ### noaaCalculator.getEndNauticalTwilight() ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
307
- A method that returns the end of nautical twilight using a zenith of [102&deg;](NAUTICAL_ZENITH).
308
-
309
- **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
310
- **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - The `Date` of the end of nautical twilight using a zenith of [102&deg;](NAUTICAL_ZENITH)
311
- . If the calculation can't be computed, null will be returned. See detailed explanation on top of the
312
- page.
313
- **See**: NAUTICAL_ZENITH
314
- <a name="NOAACalculator+getEndAstronomicalTwilight"></a>
315
-
316
- ### noaaCalculator.getEndAstronomicalTwilight() ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
317
- A method that returns the end of astronomical twilight using a zenith of [108&deg;](ASTRONOMICAL_ZENITH).
318
-
319
- **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
320
- **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - The `Date` of the end of astronomical twilight using a zenith of [108&deg;](ASTRONOMICAL_ZENITH). If the calculation can't be computed, null will be returned. See detailed explanation on top
321
- of the page.
322
- **See**: ASTRONOMICAL_ZENITH
323
- <a name="NOAACalculator+getSunriseOffsetByDegrees"></a>
324
-
325
- ### noaaCalculator.getSunriseOffsetByDegrees(offsetZenith) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
326
- A utility method that returns the time of an offset by degrees below or above the horizon of
327
- [sunrise](getSunrise()). Note that the degree offset is from the vertical, so for a calculation of 14&deg;
328
- before sunrise, an offset of 14 + [GEOMETRIC_ZENITH](GEOMETRIC_ZENITH) = 104 would have to be passed as a parameter.
329
-
330
- **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
331
- **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - The `Date` of the offset after (or before) [getSunrise](getSunrise). If the calculation
332
- can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does
333
- not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the
334
- page.
335
-
336
- | Param | Type | Description |
337
- | --- | --- | --- |
338
- | offsetZenith | <code>number</code> | the degrees before [getSunrise](getSunrise) to use in the calculation. For time after sunrise use negative numbers. Note that the degree offset is from the vertical, so for a calculation of 14&deg; before sunrise, an offset of 14 + [GEOMETRIC_ZENITH](GEOMETRIC_ZENITH) = 104 would have to be passed as a parameter. |
339
-
340
- <a name="NOAACalculator+getSunsetOffsetByDegrees"></a>
341
-
342
- ### noaaCalculator.getSunsetOffsetByDegrees(offsetZenith) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
343
- A utility method that returns the time of an offset by degrees below or above the horizon of [sunset](getSunset()). Note that the degree offset is from the vertical, so for a calculation of 14&deg; after sunset, an
344
- offset of 14 + [GEOMETRIC_ZENITH](GEOMETRIC_ZENITH) = 104 would have to be passed as a parameter.
345
-
346
- **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
347
- **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - The `Date`of the offset after (or before) [getSunset](getSunset). If the calculation can't
348
- be computed such as in the Arctic Circle where there is at least one day a year where the sun does not
349
- rise, and one where it does not set, a null will be returned. See detailed explanation on top of the
350
- page.
351
-
352
- | Param | Type | Description |
353
- | --- | --- | --- |
354
- | offsetZenith | <code>number</code> | the degrees after [getSunset](getSunset) to use in the calculation. For time before sunset use negative numbers. Note that the degree offset is from the vertical, so for a calculation of 14&deg; after sunset, an offset of 14 + [GEOMETRIC_ZENITH](GEOMETRIC_ZENITH) = 104 would have to be passed as a parameter. |
355
-
356
- <a name="NOAACalculator+getUTCSunrise0"></a>
357
-
358
- ### noaaCalculator.getUTCSunrise0(zenith) ⇒ <code>number</code>
359
- A method that returns the sunrise in UTC time without correction for time zone offset from GMT and without using
360
- daylight savings time.
361
-
362
- **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
363
- **Returns**: <code>number</code> - The time in the format: 18.75 for 18:45:00 UTC/GMT. If the calculation can't be computed such as in the
364
- Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does
365
- not set, `NaN` will be returned. See detailed explanation on top of the page.
366
-
367
- | Param | Type | Description |
368
- | --- | --- | --- |
369
- | zenith | <code>number</code> | the degrees below the horizon. For time after sunrise use negative numbers. |
370
-
371
- <a name="NOAACalculator+getUTCSeaLevelSunrise"></a>
372
-
373
- ### noaaCalculator.getUTCSeaLevelSunrise(zenith) ⇒ <code>number</code>
374
- A method that returns the sunrise in UTC time without correction for time zone offset from GMT and without using
375
- daylight savings time. Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible
376
- light, something that is not affected by elevation. This method returns UTC sunrise calculated at sea level. This
377
- forms the base for dawn calculations that are calculated as a dip below the horizon before sunrise.
378
-
379
- **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
380
- **Returns**: <code>number</code> - The time in the format: 18.75 for 18:45:00 UTC/GMT. If the calculation can't be computed such as in the
381
- Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does
382
- not set, `NaN` will be returned. See detailed explanation on top of the page.
383
- **See**
384
-
385
- - getUTCSunrise
386
- - getUTCSeaLevelSunset
387
-
388
-
389
- | Param | Type | Description |
390
- | --- | --- | --- |
391
- | zenith | <code>number</code> | the degrees below the horizon. For time after sunrise use negative numbers. |
392
-
393
- <a name="NOAACalculator+getUTCSunset0"></a>
394
-
395
- ### noaaCalculator.getUTCSunset0(zenith) ⇒ <code>number</code>
396
- A method that returns the sunset in UTC time without correction for time zone offset from GMT and without using
397
- daylight savings time.
398
-
399
- **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
400
- **Returns**: <code>number</code> - The time in the format: 18.75 for 18:45:00 UTC/GMT. If the calculation can't be computed such as in the
401
- Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does
402
- not set, `NaN` will be returned. See detailed explanation on top of the page.
403
- **See**: getUTCSeaLevelSunset
404
-
405
- | Param | Type | Description |
406
- | --- | --- | --- |
407
- | zenith | <code>number</code> | the degrees below the horizon. For time after sunset use negative numbers. |
408
-
409
- <a name="NOAACalculator+getUTCSeaLevelSunset"></a>
410
-
411
- ### noaaCalculator.getUTCSeaLevelSunset(zenith) ⇒ <code>number</code>
412
- A method that returns the sunset in UTC time without correction for elevation, time zone offset from GMT and
413
- without using daylight savings time. Non-sunrise and sunset calculations such as dawn and dusk, depend on the
414
- amount of visible light, something that is not affected by elevation. This method returns UTC sunset calculated
415
- at sea level. This forms the base for dusk calculations that are calculated as a dip below the horizon after
416
- sunset.
417
-
418
- **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
419
- **Returns**: <code>number</code> - The time in the format: 18.75 for 18:45:00 UTC/GMT. If the calculation can't be computed such as in the
420
- Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does
421
- not set, `NaN` will be returned. See detailed explanation on top of the page.
422
- **See**
423
-
424
- - getUTCSunset
425
- - getUTCSeaLevelSunrise
426
-
427
-
428
- | Param | Type | Description |
429
- | --- | --- | --- |
430
- | zenith | <code>number</code> | the degrees below the horizon. For time before sunset use negative numbers. |
431
-
432
- <a name="NOAACalculator+getElevationAdjustment"></a>
433
-
434
- ### noaaCalculator.getElevationAdjustment(elevation) ⇒ <code>number</code>
435
- Method to return the adjustment to the zenith required to account for the elevation. Since a person at a higher
436
- elevation can see farther below the horizon, the calculation for sunrise / sunset is calculated below the horizon
437
- used at sea level. This is only used for sunrise and sunset and not times before or after it such as
438
- [nautical twilight](getBeginNauticalTwilight()) since those
439
- calculations are based on the level of available light at the given dip below the horizon, something that is not
440
- affected by elevation, the adjustment should only made if the zenith == 90&deg; [adjusted](adjustZenith)
441
- for refraction and solar radius. The algorithm used is
442
-
443
- <pre>
444
- elevationAdjustment = Math.toDegrees(Math.acos(earthRadiusInMeters / (earthRadiusInMeters + elevationMeters)));
445
- </pre>
446
-
447
- The source of this algorithm is <a href="http://www.calendarists.com">Calendrical Calculations</a> by Edward M.
448
- Reingold and Nachum Dershowitz. An alternate algorithm that produces an almost identical (but not accurate)
449
- result found in Ma'aglay Tzedek by Moishe Kosower and other sources is:
450
-
451
- <pre>
452
- elevationAdjustment = 0.0347 * Math.sqrt(elevationMeters);
453
- </pre>
454
-
455
- **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
456
- **Returns**: <code>number</code> - the adjusted zenith
457
-
458
- | Param | Type | Description |
459
- | --- | --- | --- |
460
- | elevation | <code>number</code> | elevation in Meters. |
461
-
462
- <a name="NOAACalculator+adjustZenith"></a>
463
-
464
- ### noaaCalculator.adjustZenith(zenith, elevation) ⇒ <code>number</code>
465
- Adjusts the zenith of astronomical sunrise and sunset to account for solar refraction, solar radius and
466
- elevation. The value for Sun's zenith and true rise/set Zenith (used in this class and subclasses) is the angle
467
- that the center of the Sun makes to a line perpendicular to the Earth's surface. If the Sun were a point and the
468
- Earth were without an atmosphere, true sunset and sunrise would correspond to a 90&deg; zenith. Because the Sun
469
- is not a point, and because the atmosphere refracts light, this 90&deg; zenith does not, in fact, correspond to
470
- true sunset or sunrise, instead the centre of the Sun's disk must lie just below the horizon for the upper edge
471
- to be obscured. This means that a zenith of just above 90&deg; must be used. The Sun subtends an angle of 16
472
- minutes of arc, and atmospheric refraction
473
- accounts for 34 minutes or so, giving a total
474
- of 50 arcminutes. The total value for ZENITH is 90+(5/6) or 90.8333333&deg; for true sunrise/sunset. Since a
475
- person at an elevation can see blow the horizon of a person at sea level, this will also adjust the zenith to
476
- account for elevation if available. Note that this will only adjust the value if the zenith is exactly 90 degrees.
477
- For values below and above this no correction is done. As an example, astronomical twilight is when the sun is
478
- 18&deg; below the horizon or [108&deg;
479
- below the zenith](ASTRONOMICAL_ZENITH). This is traditionally calculated with none of the above mentioned adjustments. The same goes
480
- for various <em>tzais</em> and <em>alos</em> times such as the
481
- [16.1&deg;](ZmanimCalendar#ZENITH_16_POINT_1) dip used in
482
- [ComplexZmanimCalendar#getAlos16Point1Degrees](ComplexZmanimCalendar#getAlos16Point1Degrees).
483
-
484
- **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
485
- **Returns**: <code>number</code> - The zenith adjusted to include the sun's radius, refracton
486
- and [elevation](getElevationAdjustment) adjustment. This will only be adjusted for
487
- sunrise and sunset (if the zenith == 90&deg;)
488
- **See**: getElevationAdjustment
489
-
490
- | Param | Type | Description |
491
- | --- | --- | --- |
492
- | zenith | <code>number</code> | the azimuth below the vertical zenith of 90&deg;. For sunset typically the [zenith](adjustZenith) used for the calculation uses geometric zenith of 90&deg; and [adjusts](adjustZenith) this slightly to account for solar refraction and the sun's radius. Another example would be [getEndNauticalTwilight](getEndNauticalTwilight) that passes [NAUTICAL_ZENITH](NAUTICAL_ZENITH) to this method. |
493
- | elevation | <code>number</code> | elevation in Meters. |
494
-
495
- <a name="NOAACalculator+getUTCSunrise"></a>
496
-
497
- ### noaaCalculator.getUTCSunrise(date, geoLocation, zenith, adjustForElevation) ⇒
498
- A method that calculates UTC sunrise as well as any time based on an angle above or below sunrise.
499
-
500
- **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
501
- **Returns**: The UTC time of sunrise in 24 hour format. 5:45:00 AM will return 5.75.0. If an error was encountered in
502
- the calculation (expected behavior for some locations such as near the poles,
503
- `NaN` will be returned.
504
-
505
- | Param | Description |
506
- | --- | --- |
507
- | date | Used to calculate day of year. |
508
- | geoLocation | The location information used for astronomical calculating sun times. |
509
- | zenith | the azimuth below the vertical zenith of 90 degrees. for sunrise typically the [zenith](adjustZenith) used for the calculation uses geometric zenith of 90&deg; and [adjusts](adjustZenith) this slightly to account for solar refraction and the sun's radius. Another example would be [getBeginNauticalTwilight](getBeginNauticalTwilight) that passes [NAUTICAL_ZENITH](NAUTICAL_ZENITH) to this method. |
510
- | adjustForElevation | Should the time be adjusted for elevation |
511
-
512
- <a name="NOAACalculator+getUTCSunset"></a>
513
-
514
- ### noaaCalculator.getUTCSunset(date, geoLocation, zenith, adjustForElevation) ⇒
515
- A method that calculates UTC sunset as well as any time based on an angle above or below sunset.
516
-
517
- **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
518
- **Returns**: The UTC time of sunset in 24 hour format. 5:45:00 AM will return 5.75.0. If an error was encountered in
519
- the calculation (expected behavior for some locations such as near the poles,
520
- `NaN` will be returned.
521
-
522
- | Param | Description |
523
- | --- | --- |
524
- | date | Used to calculate day of year. |
525
- | geoLocation | The location information used for astronomical calculating sun times. |
526
- | zenith | the azimuth below the vertical zenith of 90&deg;. For sunset typically the [zenith](adjustZenith) used for the calculation uses geometric zenith of 90&deg; and [adjusts](adjustZenith) this slightly to account for solar refraction and the sun's radius. Another example would be [getEndNauticalTwilight](getEndNauticalTwilight) that passes [NAUTICAL_ZENITH](NAUTICAL_ZENITH) to this method. |
527
- | adjustForElevation | Should the time be adjusted for elevation |
528
-
529
- <a name="NOAACalculator+getTemporalHour"></a>
530
-
531
- ### noaaCalculator.getTemporalHour(startOfDay, endOfDay) ⇒ <code>number</code>
532
- A utility method that will allow the calculation of a temporal (solar) hour based on the sunrise and sunset
533
- passed as parameters to this method. An example of the use of this method would be the calculation of a
534
- non-elevation adjusted temporal hour by passing in [sea level sunrise](getSeaLevelSunrise()) and
535
- [sea level sunset](getSeaLevelSunset()) as parameters.
536
-
537
- **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
538
- **Returns**: <code>number</code> - the <code>long</code> millisecond length of the temporal hour. If the calculation can't be computed a
539
- `NaN` will be returned. See detailed explanation on top of the page.
540
- **See**: getTemporalHour()
541
-
542
- | Param | Type | Description |
543
- | --- | --- | --- |
544
- | startOfDay | <code>Temporal.ZonedDateTime</code> \| <code>null</code> | The start of the day. |
545
- | endOfDay | <code>Temporal.ZonedDateTime</code> \| <code>null</code> | The end of the day. |
546
-
547
- <a name="NOAACalculator+getSunTransit"></a>
548
-
549
- ### noaaCalculator.getSunTransit(startOfDay, endOfDay) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
550
- A method that returns sundial or solar noon. It occurs when the Sun is <a href
551
- ="http://en.wikipedia.org/wiki/Transit_%28astronomy%29">transiting</a> the <a
552
- href="http://en.wikipedia.org/wiki/Meridian_%28astronomy%29">celestial meridian</a>. In this class it is
553
- calculated as halfway between the sunrise and sunset passed to this method. This time can be slightly off the
554
- real transit time due to changes in declination (the lengthening or shortening day).
555
-
556
- **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
557
- **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - The `Date` representing Sun's transit. If the calculation can't be computed such as in the
558
- Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does
559
- not set, null will be returned. See detailed explanation on top of the page.
560
-
561
- | Param | Type | Description |
562
- | --- | --- | --- |
563
- | startOfDay | <code>Temporal.ZonedDateTime</code> \| <code>null</code> | the start of day for calculating the sun's transit. This can be sea level sunrise, visual sunrise (or any arbitrary start of day) passed to this method. |
564
- | endOfDay | <code>Temporal.ZonedDateTime</code> \| <code>null</code> | the end of day for calculating the sun's transit. This can be sea level sunset, visual sunset (or any arbitrary end of day) passed to this method. |
565
-
566
- <a name="NOAACalculator+getDateFromTime"></a>
567
-
568
- ### noaaCalculator.getDateFromTime(time, isSunrise) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
569
- A method that returns a `Date` from the time passed in as a parameter.
570
-
571
- **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
572
- **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - The Date.
573
- **Access**: protected
574
-
575
- | Param | Type | Description |
576
- | --- | --- | --- |
577
- | time | <code>number</code> | The time to be set as the time for the `Date`. The time expected is in the format: 18.75 for 6:45:00 PM. |
578
- | isSunrise | <code>boolean</code> | true if the time is sunrise, and false if it is sunset |
579
-
580
- <a name="NOAACalculator.CIVIL_ZENITH"></a>
581
-
582
- ### NOAACalculator.CIVIL\_ZENITH
583
- Sun's zenith at civil twilight (96&deg;).
584
-
585
- **Kind**: static property of [<code>NOAACalculator</code>](#NOAACalculator)
586
- <a name="NOAACalculator.NAUTICAL_ZENITH"></a>
587
-
588
- ### NOAACalculator.NAUTICAL\_ZENITH
589
- Sun's zenith at nautical twilight (102&deg;).
590
-
591
- **Kind**: static property of [<code>NOAACalculator</code>](#NOAACalculator)
592
- <a name="NOAACalculator.ASTRONOMICAL_ZENITH"></a>
593
-
594
- ### NOAACalculator.ASTRONOMICAL\_ZENITH
595
- Sun's zenith at astronomical twilight (108&deg;).
596
-
597
- **Kind**: static property of [<code>NOAACalculator</code>](#NOAACalculator)
598
- <a name="NOAACalculator.getTimeOffset"></a>
599
-
600
- ### NOAACalculator.getTimeOffset(time, offset) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
601
- A utility method that returns a date offset by the offset time passed in. Please note that the level of light
602
- during twilight is not affected by elevation, so if this is being used to calculate an offset before sunrise or
603
- after sunset with the intent of getting a rough "level of light" calculation, the sunrise or sunset time passed
604
- to this method should be sea level sunrise and sunset.
605
-
606
- **Kind**: static method of [<code>NOAACalculator</code>](#NOAACalculator)
607
- **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - the `Date` with the offset in milliseconds added to it
608
-
609
- | Param | Type | Description |
610
- | --- | --- | --- |
611
- | time | <code>Temporal.ZonedDateTime</code> \| <code>null</code> | the start time |
612
- | offset | <code>number</code> | the offset in milliseconds to add to the time. |
613
-
614
- <a name="NOAACalculator.getSolarElevation"></a>
615
-
616
- ### NOAACalculator.getSolarElevation(date, lat, lon) ⇒ <code>number</code>
617
- Return the <a href="http://en.wikipedia.org/wiki/Celestial_coordinate_system">Solar Elevation</a> for the
618
- horizontal coordinate system at the given location at the given time. Can be negative if the sun is below the
619
- horizon. Not corrected for altitude.
620
-
621
- **Kind**: static method of [<code>NOAACalculator</code>](#NOAACalculator)
622
- **Returns**: <code>number</code> - solar elevation in degrees - horizon is 0 degrees, civil twilight is -6 degrees
623
-
624
- | Param | Type | Description |
625
- | --- | --- | --- |
626
- | date | <code>Temporal.ZonedDateTime</code> | time of calculation |
627
- | lat | <code>number</code> | latitude of location for calculation |
628
- | lon | <code>number</code> | longitude of location for calculation |
629
-
630
- <a name="NOAACalculator.getSolarAzimuth"></a>
631
-
632
- ### NOAACalculator.getSolarAzimuth(date, latitude, lon) ⇒ <code>number</code>
633
- Return the <a href="http://en.wikipedia.org/wiki/Celestial_coordinate_system">Solar Azimuth</a> for the
634
- horizontal coordinate system at the given location at the given time. Not corrected for altitude. True south is 0
635
- degrees.
636
-
637
- **Kind**: static method of [<code>NOAACalculator</code>](#NOAACalculator)
638
-
639
- | Param | Type | Description |
640
- | --- | --- | --- |
641
- | date | <code>Temporal.ZonedDateTime</code> | time of calculation |
642
- | latitude | <code>number</code> | latitude of location for calculation |
643
- | lon | <code>number</code> | longitude of location for calculation |
14
+ ## Synopsis
15
+ ```javascript
16
+ import {GeoLocation, NOAACalculator} from '@hebcal/noaa';
17
+ import {Temporal} from 'temporal-polyfill';
18
+
19
+ const latitude = 39.73915;
20
+ const longitude = -104.9847;
21
+ const elevtion = 1636;
22
+ const tzid = 'America/Denver';
23
+ const gloc = new GeoLocation(null, latitude, longitude, elevtion, tzid);
24
+ const plainDate = new Temporal.PlainDate(2020, 6, 5); // Friday June 5 2020
25
+ const noaa = new NOAACalculator(gloc, plainDate);
26
+
27
+ const zdt = noaa.getSunset();
28
+ console.log(zdt.toString()); // '2020-06-05T20:32:57.848-06:00[America/Denver]'
29
+ ```
644
30
 
31
+ ## [API Documentation](https://hebcal.github.io/api/noaa/index.html)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hebcal/noaa",
3
- "version": "0.8.14",
3
+ "version": "0.8.15",
4
4
  "description": "sunrise and sunset via NOAA algorithm with elevation, based on KosherJava",
5
5
  "author": "Michael J. Radwin (https://github.com/mjradwin)",
6
6
  "contributors": [
@@ -23,6 +23,7 @@
23
23
  "types": "./dist/index.d.ts"
24
24
  },
25
25
  "scripts": {
26
+ "docs": "typedoc",
26
27
  "test": "ava",
27
28
  "build": "npm run build:cjs && mv dist/index.js dist/index.cjs && npm run build:es6 && mv dist/index.js dist/index.mjs",
28
29
  "build:cjs": "tsc -p ./tsconfig-cjs.json",
@@ -43,12 +44,13 @@
43
44
  "dist/*"
44
45
  ],
45
46
  "devDependencies": {
46
- "@types/node": "20.12.7",
47
- "ava": "^6.1.2",
48
- "gts": "^5.3.0",
49
- "typescript": "^5.4.5"
47
+ "@types/node": "22.10.2",
48
+ "ava": "^6.2.0",
49
+ "gts": "^5.3.1",
50
+ "typedoc": "^0.27.4",
51
+ "typescript": "^5.7.2"
50
52
  },
51
- "peerDependencies": {
52
- "temporal-polyfill": "^0.2.4"
53
+ "dependencies": {
54
+ "temporal-polyfill": "^0.2.5"
53
55
  }
54
56
  }