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.

Determining which side of a vehicle to sit on requires knowing precisely when and where the sun rises, reaches its zenith, and sets — not just at the trip’s origin, but at every point the vehicle passes through. Helios addresses this by importing two independent solar calculation libraries: SunCalc_function.js, built around Volodymyr Agafonkin’s algorithm, and suncalc.js, a later version of the same author’s work. Each library is used for a distinct purpose in the calculation pipeline.
Credit is due to Volodymyr Agafonkin, creator of the JavaScript SunCalc module. His work underpins all solar event timing in Helios. The original library is available at github.com/mourner/suncalc.

​
SunCalc_function.js — getDayInfo

SunCalc_function.js exports a factory function sunCalc(). Calling it returns an object whose getDayInfo method accepts a date, a latitude, and a longitude and returns a complete picture of the solar day at that location: 
getDayInfo(date, lat, lng, detailed)
The return value has the following shape: 
{
  "dawn": "Date",
  "sunrise": {
    "start": "Date",
    "end":   "Date"
  },
  "transit": "Date",
  "sunset": {
    "start": "Date",
    "end":   "Date"
  },
  "dusk": "Date"
}
The transit field is solar noon — the moment the sun crosses the local meridian at its highest point. sunrise.start marks the moment the sun’s upper limb first appears above the horizon, while sunrise.end marks the moment the sun’s lower limb clears the horizon (the disk is fully above). sunset.start marks the moment the upper limb first touches the horizon on the way down, and sunset.end marks the moment the lower limb disappears below it. In index_def.js, the library is imported and initialised once: 
import sunCalc from "./SunCalc_function.js";
let { getDayInfo } = sunCalc();
It is then called at the origin and destination to capture the day’s solar envelope: 
let tiempo1 = getDayInfo(salida, latitudOrigen, longitudOrigen);
let tiempo2 = getDayInfo(llegada, latitudDestino, longitudDestino);

​
suncalc.js — getTimes

suncalc.js is the standalone ES-module edition of SunCalc. Its key method for Helios is: 
getTimes(date, lat, lng, height)
getTimes returns an object with solarNoon and nadir as top-level properties, plus named sunrise and sunset times for several horizon angles (civil, nautical, astronomical, golden hour). Helios uses solarNoon specifically: 
import { SunCalc } from "./suncalc.js";
let { getTimes } = SunCalc;

// Solar noon at origin
let times = getTimes(salida, latitudOrigen, longitudOrigen);
datos.start.solarnoon = times.solarNoon;

// Solar noon at destination
times = getTimes(llegada, latitudDestino, longitudDestino);
datos.end.solarnoon = times.solarNoon;
These two solarNoon values are stored on the datos.start and datos.end objects and are available for reference throughout the result-rendering phase.

​
Why two libraries?

The two libraries serve different roles:
LibraryUsed byPurpose
SunCalc_function.js (getDayInfo)computeRouteSections in routeSolar.jsIterative sunrise/sunset detection along the moving route
suncalc.js (getTimes)index_def.jsFinal solarNoon values attached to the origin and destination
computeRouteSections calls getDayInfo thousands of times as it converges on the exact geographic coordinates and timestamps of each solar event. It needs sunrise.end and sunset.start to answer the binary question “is it daytime right now?” at any interpolated point along the route. The getDayInfo interface — which returns those two timestamps directly — is the right fit for that tight loop. getTimes from suncalc.js is used outside that loop, in index_def.js, to attach a solarNoon timestamp to the origin and destination data objects. Both libraries implement the same underlying astronomical model; requiring them to agree to within 5 minutes provides an implicit cross-check on the coordinate and time inputs.

​
isThereDaylightNow

The binary daylight check that drives the entire convergence loop lives in routeSolar.js: 
function isThereDaylightNow(here, now, getDayInfo) {
    let amanecer = getDayInfo(now, here.lat, here.lon).sunrise.end;
    let ocaso = getDayInfo(now, here.lat, here.lon).sunset.start;
    return (now.getTime() >= amanecer.getTime() && now.getTime() < ocaso.getTime());
}
The function takes the current interpolated position (here, with lat and lon fields), the current moment in time (now, a Date), and the getDayInfo function as an injected dependency. It returns true if now falls between sunrise.end and sunset.start at that location — that is, if the sun’s disk is fully above the horizon. This function is called in two places inside computeRouteSections:
  1. Before the outer loop — to decide whether to search for a sunset first (already daytime) or a sunrise first (currently night).
  2. Inside the convergence loop — to determine whether the current estimated position is still on the correct side of the solar event being sought, and to adjust the RATE pointer forward or backward accordingly.

Build docs developers (and LLMs) love

Get started for freeTalk to us