Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/V3RNE42/helios/llms.txt

Use this file to discover all available pages before exploring further.

Helios bundles two solar position calculation libraries. SunCalc_function.js is used by the route algorithm for sunrise/sunset detection; suncalc.js provides the getTimes function used for attaching solar noon to each route section in the main application logic.

​
SunCalc_function.js

SunCalc_function.js exports a single default factory function. Call it once to obtain the solar calculation methods: 
import sunCalcFactory from './SunCalc_function.js';

const { getDayInfo, getSunPosition } = sunCalcFactory();

​
getDayInfo(date, lat, lng, detailed?)

Returns a day-info object containing the principal solar events for a given date and location.
​
date
Date
required
The date for which to calculate solar events.
​
lat
number
required
Latitude in decimal degrees.
​
lng
number
required
Longitude in decimal degrees.
​
detailed
boolean
When true, the returned object is extended with morningTwilight and nightTwilight breakdowns.
Returns an object with the following properties:
PropertyTypeDescription
dawnDateNautical twilight start (morning).
sunrise.startDateGeometric sunrise — bottom of the solar disc touches the horizon.
sunrise.endDateOptical sunrise end — top of the solar disc clears the horizon.
transitDateSolar noon — the Sun crosses the meridian.
sunset.startDateOptical sunset start — top of the solar disc touches the horizon.
sunset.endDateGeometric sunset — bottom of the solar disc sets below the horizon.
duskDateNautical twilight end (evening).
When detailed: true, two additional properties are included: morningTwilight
Sub-propertyDescription
astronomical.start / .endAstronomical twilight window in the morning.
nautical.start / .endNautical twilight window in the morning.
civil.start / .endCivil twilight window in the morning.
nightTwilight
Sub-propertyDescription
civil.start / .endCivil twilight window in the evening.
nautical.start / .endNautical twilight window in the evening.
astronomical.start / .endAstronomical twilight window in the evening.

​
getSunPosition(date, lat, lng)

Returns the Sun’s position in the sky for a given moment and location.
​
date
Date
required
The date and time of observation.
​
lat
number
required
Latitude in decimal degrees.
​
lng
number
required
Longitude in decimal degrees.
Returns { azimuth: number, altitude: number } — both values in radians.

​
suncalc.js

suncalc.js exposes its API through a named SunCalc export: 
import { SunCalc } from './suncalc.js';

const { getTimes } = SunCalc;

​
getTimes(date, lat, lng, height?)

Calculates sun times for a given date, latitude/longitude, and optional observer height.
​
date
Date
required
The date for which to calculate sun times.
​
lat
number
required
Latitude in decimal degrees.
​
lng
number
required
Longitude in decimal degrees.
​
height
number
Observer height in metres above the horizon. Defaults to 0.
Returns an object that includes solarNoon (Date) and nadir (Date), plus named rise/set pairs for each configured solar angle: sunrise/sunset, sunriseEnd/sunsetStart, dawn/dusk, nauticalDawn/nauticalDusk, nightEnd/night, and goldenHourEnd/goldenHour. In index_def.js, getTimes is called at both origin and destination to populate datos.start.solarnoon and datos.end.solarnoon: 
import { SunCalc } from './suncalc.js';

const { getTimes } = SunCalc;

const times = getTimes(salida, latitudOrigen, longitudOrigen);
datos.start.solarnoon = times.solarNoon;

​
Consistency guarantee

The test suite verifies that getTimes(...).solarNoon and getDayInfo(...).transit agree to within 5 minutes for the same inputs, ensuring that solar noon is reported consistently regardless of which library path is used: 
it("el mediodía solar de getTimes coincide con el 'transit' de getDayInfo (< 5 min)", () => {
    const d = new Date(Date.UTC(2026, 5, 15, 12, 0));
    const noonA = getTimes(d, MADRID.lat, MADRID.lon).solarNoon;
    const noonB = getDayInfo(d, MADRID.lat, MADRID.lon).transit;
    const diffMin = Math.abs(noonA.getTime() - noonB.getTime()) / 60000;
    expect(diffMin).toBeLessThan(5);
});
Both SunCalc_function.js and suncalc.js are based on the SunCalc algorithm created by Volodymyr Agafonkin. The original library is available at github.com/mourner/suncalc.

Build docs developers (and LLMs) love

Get started for freeTalk to us