ootk-core

/** * @author Theodore Kruczek. * @license MIT * @copyright (c) 2022-2025 Theodore Kruczek Permission is * hereby granted, free of charge, to any person obtaining a copy of this * software and associated documentation files (the "Software"), to deal in the * Software without restriction, including without limitation the rights to use, * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of * the Software, and to permit persons to whom the Software is furnished to do * so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included in * all copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE * SOFTWARE. * @copyright (c) 2011-2015, Vladimir Agafonkin * @copyright (c) 2022 Robert Gester https://github.com/hypnos3/suncalc3 * @see suncalc.LICENSE.md * Some of the math in this file was originally created by Vladimir Agafonkin. * Robert Gester's update was referenced for documentation. There were a couple * of bugs in both versions so there will be some differences if you are * migrating from either to this library. * * suncalc is a JavaScript library for calculating sun/moon position and light * phases. https://github.com/mourner/suncalc * It was reworked and enhanced by Robert Gester. * * The original suncalc is released under the terms of the BSD 2-Clause License. */ import { AzEl, Degrees, EpochUTC, Kilometers, Meters, RaDec, Radians, SunTime, Vector3D } from '../main.js'; /** * Sun metrics and operations. */ export declare class Sun { private static readonly J0_; private static readonly J1970_; private static readonly J2000_; static readonly e: number; /** * Array representing the times for different phases of the sun. Each element * in the array contains: * - The angle in degrees representing the time offset from solar noon. * - The name of the start time for the phase. * - The name of the end time for the phase. */ private static readonly times_; /** * Gravitational parameter of the Sun. (km³/s²) */ static readonly mu = 132712428000; /** * The angle of the penumbra of the Sun, in radians. */ static readonly penumbraAngle: Radians; /** * The radius of the Sun in kilometers. */ static readonly radius: Kilometers; /** * The mean solar flux of the Sun. (W/m²) */ static readonly solarFlux = 1367; /** * The solar pressure exerted by the Sun. (N/m²) It is calculated as the solar * flux divided by the speed of light. */ static readonly solarPressure: number; /** * The angle of the umbra, in radians. */ static readonly umbraAngle: Radians; private constructor(); /** * Calculates the azimuth and elevation of the Sun for a given date, latitude, * and longitude. * @param date - The date for which to calculate the azimuth and elevation. * @param lat - The latitude in degrees. * @param lon - The longitude in degrees. * @param c - The right ascension and declination of the target. Defaults to * the Sun's right ascension and declination * @returns An object containing the azimuth and elevation of the Sun in * radians. */ static azEl(date: Date, lat: Degrees, lon: Degrees, c?: RaDec): AzEl<Radians>; /** * get number of days for a dateValue since 2000 * See: https://en.wikipedia.org/wiki/Epoch_(astronomy) * @param date date as timestamp to get days * @returns count of days */ static date2jSince2000(date: Date): number; /** * Calculates the angular diameter of the Sun given the observer's position * and the Sun's position. * @param obsPos The observer's position in kilometers. * @param sunPos The Sun's position in kilometers. * @returns The angular diameter of the Sun in radians. */ static diameter(obsPos: Vector3D<Kilometers>, sunPos: Vector3D<Kilometers>): Radians; /** * Calculate eclipse angles given a satellite ECI position and Sun ECI * position. * @param satPos the satellite position * @param sunPos the sun position * @returns [central body angle, central body apparent radius, sun apparent] */ static eclipseAngles(satPos: Vector3D<Kilometers>, sunPos: Vector3D<Kilometers>): [Radians, Radians, Radians]; /** * Ecliptic latitude measures the distance north or south of the ecliptic, * attaining +90° at the north ecliptic pole (NEP) and -90° at the south * ecliptic pole (SEP). The ecliptic itself is 0° latitude. * @param B - ? * @returns ecliptic latitude */ static eclipticLatitude(B: number): number; /** * Ecliptic longitude, also known as celestial longitude, measures the angular * distance of an object along the ecliptic from the primary direction. It is * measured positive eastwards in the fundamental plane (the ecliptic) from 0° * to 360°. The primary direction (0° ecliptic longitude) points from the * Earth towards the Sun at the vernal equinox of the Northern Hemisphere. Due * to axial precession, the ecliptic longitude of most "fixed stars" increases * by about 50.3 arcseconds per year, or 83.8 arcminutes per century. * @param M - solar mean anomaly * @returns ecliptic longitude */ static eclipticLongitude(M: number): Radians; /** * returns set time for the given sun altitude * @param h - height at 0 * @param lw - rad * -lng * @param phi - rad * lat; * @param dec - declination * @param n - Julian cycle * @param M - solar mean anomal * @param L - ecliptic longitude * @returns set time */ static getSetJulian(h: Meters, lw: number, phi: number, dec: number, n: number, M: number, L: number): number; /** * Calculates the time of the sun based on the given azimuth. * @param dateValue - The date value or Date object. * @param lat - The latitude in degrees. * @param lon - The longitude in degrees. * @param az - The azimuth in radians or degrees. * @param isDegrees - Indicates if the azimuth is in degrees. Default is false. * @returns The calculated time of the sun. * @throws Error if the azimuth, latitude, or longitude is missing. */ static getSunTimeByAz(dateValue: number | Date, lat: Degrees, lon: Degrees, az: Radians | Degrees, isDegrees?: boolean): Date; /** * Calculates sun times for a given date and latitude/longitude * * Default altitude is 0 meters. If `isUtc` is `true`, the times are returned * as UTC, otherwise in local time. * @param dateVal - The date value or Date object. * @param lat - The latitude in degrees. * @param lon - The longitude in degrees. * @param alt - The altitude in meters. Default is 0. * @param isUtc - Indicates if the times should be returned as UTC. Default is * false. * @returns An object containing the times of the sun. */ static getTimes(dateVal: Date | number, lat: Degrees, lon: Degrees, alt?: Meters, isUtc?: boolean): SunTime; /** * hour angle * @param h - heigh at 0 * @param phi - rad * lat; * @param dec - declination * @returns hour angle */ static hourAngle(h: number, phi: number, dec: number): number; /** * convert Julian calendar to date object * @param julian day number in Julian calendar to convert * @returns result date as timestamp */ static julian2date(julian: number): Date; /** * Julian cycle * * The Julian cycle is a period of 7980 years after which the positions of the * Sun, Moon, and planets repeat. It is used in astronomical calculations to * determine the position of celestial bodies. * * The Julian Period starts at noon on January 1, 4713 B.C.E. (Julian * calendar) and lasts for 7980 years. This was determined because it is a * time period long enough to include all of recorded history and includes * some time in the future that would incorporate the three important * calendrical cycles, the Golden Number Cycle, the Solar Cycle, and the Roman * Indiction. * * The Golden Number Cycle is a cycle of 19 years, while the Solar Cycle is a * cycle of 28 years and the Roman Indiction repeats every 15 years. Thus the * Julian Period is calculated to be 7980 years long or 2,914,695 days because * 19*28*15 = 7980. * @param date - Date object for calculating julian cycle * @param lon - Degrees longitude * @returns julian cycle */ static julianCycle(date: Date, lon: Degrees): number; /** * Calculate the lighting ratio given a satellite ECI position [satPos] _(km)_ * and Sun ECI position [sunPos] _(km)_. * * Returns `1.0` if the satellite is fully illuminated and `0.0` when fully * eclipsed. * @param satPos - The position of the satellite. * @param sunPos - The position of the sun. * @returns The lighting ratio. */ static lightingRatio(satPos: Vector3D<Kilometers>, sunPos: Vector3D<Kilometers>): number; /** * Calculates the lighting factor based on the position of the satellite and the sun. * @deprecated This method was previously used. It is now deprecated and will be removed * in a future release. * @param satPos The position of the satellite. * @param sunPos The position of the sun. * @returns The lighting factor. */ static sunlightLegacy(satPos: Vector3D, sunPos: Vector3D): number; /** * Calculates the position vector of the Sun at a given epoch in the * Earth-centered inertial (ECI) coordinate system. * @param epoch - The epoch in UTC. * @returns The position vector of the Sun in Kilometers. */ static position(epoch: EpochUTC): Vector3D<Kilometers>; /** * Calculate the Sun's apparent ECI position _(km)_ from Earth for a given UTC * [epoch]. * @param epoch - The epoch in UTC. * @returns The Sun's apparent ECI position in kilometers. */ static positionApparent(epoch: EpochUTC): Vector3D<Kilometers>; /** * Calculates the right ascension and declination of the Sun for a given date. * @param date - The date for which to calculate the right ascension and declination. * @returns An object containing the declination and right ascension of the Sun. */ static raDec(date: Date): RaDec; /** * Return `true` if the ECI satellite position [posSat] is in eclipse at the * given UTC [epoch]. * @param epoch - The epoch in UTC. * @param posSat - The ECI position of the satellite in kilometers. * @returns `true` if the satellite is in eclipse. */ static shadow(epoch: EpochUTC, posSat: Vector3D<Kilometers>): boolean; /** * side real time * @param d - julian day * @param lw - longitude of the observer * @returns sidereal time */ static siderealTime(d: number, lw: Radians): number; /** * solar transit in Julian * @param ds approxTransit * @param M solar mean anomal * @param L ecliptic longitude * @returns solar transit in Julian */ static solarTransitJulian(ds: number, M: number, L: number): number; /** * The approximate transit time * @param Ht hourAngle * @param lw rad * -lng * @param n Julian cycle * @returns approx transit */ private static approxTransit_; private static calculateJnoon_; /** * returns set time for the given sun altitude * @param alt altitude at 0 * @param lw lng * @param phi lat * @param dec declination * @param n Julian cycle * @param M solar mean anomal * @param L ecliptic longitude * @returns sunset time in days since 2000 */ private static getSetJ_; private static julianCycle_; /** * calculates the obderver angle * @param alt the observer altitude (in meters) relative to the horizon * @returns height for further calculations */ private static observerAngle_; /** * get solar mean anomaly * @param d julian day * @returns solar mean anomaly */ private static solarMeanAnomaly_; }