Solar Geometry Examples
These examples demonstrate how to compute Layer 3 solar context using
the UmiTime class and the publicly exported solar-geometry
helpers. All examples match the current implementation and public API.
1. Solar Geometry via UmiTime
The UmiTime class exposes Layer 3 solar-context values as getters.
These values are derived from solar geometry and require precise latitude
and longitude to be accurate. Solar context depends on location, but the
underlying Umi‑Time value does not.
import { UmiTime } from "umi-time";
const umi = new UmiTime(
new Date(),
{ value: 35.14, uncertainty: 0 }, // latitude
{ value: -120.64, uncertainty: 0 } // longitude
);
console.log(umi.solarDeclination); // Sun's declination angle
console.log(umi.equationOfTime); // apparent vs mean solar time
console.log(umi.solarPosition); // { altitude, azimuth }
console.log(umi.sunrise); // umi of sunrise
console.log(umi.sunset); // umi of sunset
2. Solar Altitude (Standalone Helper)
The solarAltitude helper computes the apparent altitude of
the Sun above the observer's horizon.
import { solarAltitude } from "umi-time";
const utc = new Date();
const lat = 35.14;
const lon = -120.64;
const altitude = solarAltitude(utc, lat, lon);
console.log(altitude); // degrees above horizon
3. Solar Hour Angle
The hour angle describes how far the Sun is east or west of physical solar noon. It is a fundamental solar-geometry quantity used in the computation of sunrise, sunset, twilight, and other solar-context values.
import { UmiTime, getHourAngle } from "umi-time";
const umi = new UmiTime(
new Date(),
{ value: 35.14, uncertainty: 0 },
{ value: -120.64, uncertainty: 0 }
);
const eot = umi.equationOfTime;
const utc = umi.utc;
const lon = umi.longitude.value;
const hourAngle = getHourAngle(utc, lon, eot);
console.log(hourAngle); // degrees
4. UT Umi From Date
utUmiFromDate computes the umi position directly from a UTC
timestamp. This is the Layer 1 Umi‑Time transformation and is the same calculation
used internally by UmiTime.. Unlike the solar geometry
helpers, this calculation depends only on UTC and does not require a
location.
import { utUmiFromDate } from "umi-time";
const utc = new Date();
const umiValue = utUmiFromDate(utc);
console.log(umiValue); // 0–359
5. Angle Conversion
Basic helpers for converting between radians and degrees.
import { toDeg, toRad } from "umi-time";
console.log(toDeg(Math.PI)); // 180
console.log(toRad(180)); // 3.14159...
6. Combined Solar Geometry Example
A complete example showing how to compute multiple Layer 3
solar-context values using both UmiTime and standalone solar-geometry
helpers.
import {
UmiTime,
solarAltitude,
getHourAngle,
toDeg,
toRad
} from "umi-time";
const umi = new UmiTime(
new Date(),
{ value: 35.14, uncertainty: 0 },
{ value: -120.64, uncertainty: 0 }
);
// From UmiTime
const decl = umi.solarDeclination;
const eot = umi.equationOfTime;
const pos = umi.solarPosition;
// Standalone helpers
const alt = solarAltitude(umi.utc, umi.latitude.value, umi.longitude.value);
const hourAngle = getHourAngle(umi.utc, umi.longitude.value, eot);
console.log({ decl, eot, pos, alt, hourAngle });