@openglobus/og 1.0.0-rc10 → 1.0.0-rc11

package/lib/Globe.d.ts

@@ -42,6 +42,7 @@ export interface IGlobeParams {
     sun?: {
         active?: boolean;
         stopped?: boolean;
+        localDateTime?: Date | null;
     };
     navigation?: {
         active?: boolean;

package/lib/camera/PlanetCamera.d.ts

@@ -128,7 +128,7 @@ declare class PlanetCamera extends Camera {
      * @public
      * @param {LonLat} lonlat - New camera and camera view position.
      * @param {LonLat} [lookLonLat] - Look up coordinates.
-     * @param {Vec3} [up] - Camera UP vector. Default (0,1,0)
+     * @param {Vec3} [up] - Camera UP vector. Defaults to the local surface normal for an explicit look point.
      */
     setLonLat(lonlat: LonLat, lookLonLat?: LonLat, up?: Vec3): void;
     /**

package/lib/control/Sun.d.ts

@@ -1,20 +1,44 @@
 import { Control } from "./Control";
 import type { IControlParams } from "./Control";
 import { Clock } from "../Clock";
+import type { JulianDate } from "../astro/jd";
 import { Vec3 } from "../math/Vec3";
+import type { PlanetCamera } from "../camera/PlanetCamera";
 interface ISunParams extends IControlParams {
     activationHeight?: number;
     offsetVertical?: number;
     offsetHorizontal?: number;
     stopped?: boolean;
+    localDateTime?: Date | null;
 }
 /**
  * Real Sun geocentric position control that place the Sun on the right place by the Earth.
+ * @class
+ *
+ * @example <caption>Lighting frozen at 21:30 local solar time under the camera</caption>
+ * new Sun({ localDateTime: new Date(2026, 7, 3, 21, 30) })
+ *
+ * @param {ISunParams} [options] - Options:
+ * @param {number} [options.activationHeight=12079000.0] - Camera height above which the Sun takes its real position by the clock.
+ * @param {number} [options.offsetVertical=-5000000] - Vertical offset of the camera following light.
+ * @param {number} [options.offsetHorizontal=5000000] - Horizontal offset of the camera following light.
+ * @param {boolean} [options.stopped=false] - Stops the control, leaving the Sun on its real position by the clock.
+ * @param {Date} [options.localDateTime] - Lights the scene by a fixed local apparent solar time under the camera
+ * instead of the camera following light, below activationHeight. At 12:00 the Sun stands on the meridian there,
+ * while the date sets the season. Read for the wall clock numbers it shows locally, so it is not an instant in
+ * time: one parsed from an absolute timestamp reads as the machine's time zone renders it. The Clock is left
+ * untouched, and while the control is stopped this is ignored.
  */
 export declare class Sun extends Control {
     activationHeight: number;
     offsetVertical: number;
     offsetHorizontal: number;
+    /**
+     * Fixed local apparent solar time under the camera, or null for the camera following light.
+     * @public
+     * @type {Date | null}
+     */
+    localDateTime: Date | null;
     protected _currDate: number;
     protected _prevDate: number;
     protected _clockPtr: Clock | null;
@@ -30,7 +54,37 @@ export declare class Sun extends Control {
     onactivate(): void;
     bindClock(clock: Clock): void;
     getPosition(): Vec3;
+    /**
+     * Sets a fixed local apparent solar time under the camera.
+     * @public
+     * @param {Date | null} localDateTime - Local date and time, or null to restore the camera following light.
+     */
+    setLocalDateTime(localDateTime: Date | null): void;
     protected _setSunPosition3v(position: Vec3): void;
+    /**
+     * Returns a light position offset from the camera along its own up and right axes,
+     * so that nearby terrain is lit regardless of the real Sun direction.
+     * @protected
+     * @param {PlanetCamera} cam - Planet camera.
+     * @returns {Vec3} -
+     */
+    protected _getCameraFollowingPosition(cam: PlanetCamera): Vec3;
+    /**
+     * Returns the julian date at which localDateTime is the local apparent solar time at lon.
+     * Local mean solar time is the first guess, then the measured subsolar longitude corrects it;
+     * that point drifts -360 degrees a day, so a residual of d degrees is worth -d / 360 of a day.
+     * @protected
+     * @param {number} lon - Longitude under the camera, degrees.
+     * @returns {JulianDate} -
+     */
+    protected _getLocalDateTimeJulian(lon: number): JulianDate;
+    /**
+     * Returns the Sun position for localDateTime at the location under the camera.
+     * @protected
+     * @param {PlanetCamera} cam - Planet camera.
+     * @returns {Vec3} -
+     */
+    protected _getLocalDateTimePosition(cam: PlanetCamera): Vec3;
     protected _draw(): void;
 }
 export {};