@openglobus/og 1.0.0-rc22 → 1.0.0-rc23

package/lib/Globe.d.ts

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

package/lib/control/Sun.d.ts

@@ -4,42 +4,53 @@ import { Clock } from "../Clock";
 import type { JulianDate } from "../astro/jd";
 import { Vec3 } from "../math/Vec3";
 import type { PlanetCamera } from "../camera/PlanetCamera";
+import type { LonLat } from "../LonLat";
 interface ISunParams extends IControlParams {
     activationHeight?: number;
     offsetVertical?: number;
     offsetHorizontal?: number;
     stopped?: boolean;
     localDateTime?: Date | null;
+    dateTime?: Date | null;
+    useTimeZones?: boolean;
 }
 /**
  * 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) })
+ * @example <caption>Lighting frozen at 21:30 on the local clock under the camera</caption>
+ * new Sun({ localDateTime: new Date(Date.UTC(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 the local apparent solar time under the camera
- * instead of the camera following light. At 12:00 the Sun stands on the meridian there, while the date sets the
- * season. Read by its UTC clock, so it is not an instant in time but the numbers a wall clock shows: build it
- * with Date.UTC. While it is set it drives the light at any height, whether the control is stopped or not, and
- * the Clock is left untouched.
+ * @param {Date} [options.localDateTime] - Local clock time under the camera — wall-clock numbers,
+ * not an instant: build it with Date.UTC. Civil time with useTimeZones, solar time otherwise.
+ * @param {Date} [options.dateTime] - Instant in time the Sun takes its real position at.
+ * @param {boolean} [options.useTimeZones=false] - Reads localDateTime by the time zone of the point.
+ * Leave off on bodies without civil time.
  */
 export declare class Sun extends Control {
     activationHeight: number;
     offsetVertical: number;
     offsetHorizontal: number;
     /**
-     * Local apparent solar time under the camera, read by its UTC clock,
+     * Local clock time under the camera, read by its UTC clock,
      * or null for the camera following light.
      * @public
      * @type {Date | null}
      */
     localDateTime: Date | null;
+    /**
+     * Instant in time the Sun takes its real position at,
+     * or null for the camera following light.
+     * @public
+     * @type {Date | null}
+     */
+    dateTime: Date | null;
+    protected _useTimeZones: boolean;
     protected _currDate: number;
     protected _prevDate: number;
     protected _redrawDate: number;
@@ -49,6 +60,9 @@ export declare class Sun extends Control {
     protected _f: number;
     protected _k: number;
     protected _sunlightPosition: Vec3;
+    protected _localLon: number;
+    protected _localLat: number;
+    protected _localJd: number;
     constructor(options?: ISunParams);
     oninit(): void;
     protected _onClockTick: () => void;
@@ -58,11 +72,24 @@ export declare class Sun extends Control {
     bindClock(clock: Clock): void;
     getPosition(): Vec3;
     /**
-     * Sets the local apparent solar time under the camera, read by its UTC clock.
+     * Reads localDateTime by the time zone of the point instead of the solar clock.
+     * @public
+     * @type {boolean}
+     */
+    get useTimeZones(): boolean;
+    set useTimeZones(useTimeZones: boolean);
+    /**
+     * Sets the local clock time under the camera, read by its UTC clock.
      * @public
      * @param {Date | null} localDateTime - Local date and time, or null to restore the camera following light.
      */
     setLocalDateTime(localDateTime: Date | null): void;
+    /**
+     * Sets the instant in time the Sun takes its real position at.
+     * @public
+     * @param {Date | null} dateTime - Instant in time, or null to restore the camera following light.
+     */
+    setDateTime(dateTime: Date | null): void;
     protected _setSunPosition3v(position: Vec3): void;
     /**
      * Returns a light position offset from the camera along its own up and right axes,
@@ -82,9 +109,11 @@ export declare class Sun extends Control {
      * @param {number} lon - Longitude under the camera, degrees.
      * @returns {JulianDate} -
      */
-    protected _getLocalJulian(utc: JulianDate, lon: number): JulianDate;
+    protected _getSolarJulian(utc: JulianDate, lon: number): JulianDate;
+    protected _localDateTimeToUtc(lonLat: LonLat): Date | null;
     /**
-     * Returns the Sun position for localDateTime at the location under the camera.
+     * Returns the Sun position for localDateTime at the location under the camera:
+     * the real position at the civil instant with useTimeZones, the solar reading otherwise.
      * @protected
      * @param {PlanetCamera} cam - Planet camera.
      * @returns {Vec3} -

package/lib/control/timeline/TimelineControl.d.ts

@@ -17,15 +17,16 @@ type TimelineControlEventsList = [
     "stopdrag",
     "startdragcurrent",
     "stopdragcurrent",
-    "localtime",
-    "suntime",
-    "sundate"
+    "changetimelinetime",
+    "changelocaltime",
+    "changelocaldatetime"
 ];
 interface ITimelineControlParams extends IControlParams {
     name?: string;
     current?: Date;
     rangeStart?: Date;
     rangeEnd?: Date;
+    use24HourClock?: boolean;
 }
 declare class TimelineControl extends Control {
     protected _timelineView: TimelineView;
@@ -40,8 +41,17 @@ declare class TimelineControl extends Control {
      */
     get model(): TimelineModel;
     /** Date the Sun marker stands on. Setting it moves the marker without dispatching. */
-    get sunDate(): Date;
-    set sunDate(date: Date);
+    get localDateTime(): Date;
+    set localDateTime(date: Date);
+    /** Scale time notation: 24-hour, or 12-hour with am/pm. */
+    get use24HourClock(): boolean;
+    set use24HourClock(use24HourClock: boolean);
+    /** True while the timeline current lights the scene. Setting it also moves the toggle. */
+    get timelineTime(): boolean;
+    set timelineTime(isActive: boolean);
+    protected _applyTimelineTime(isActive: boolean): void;
+    /** Lights the scene by the Sun marker, the civil clock time under the camera. */
+    applyLocalDateTime(): void;
     /**
      * Adds a colored time interval drawn on the scale, e.g. one per telemetry track.
      * Spans that overlap in time are placed on separate rows automatically, and the

package/lib/control/timeline/TimelineView.d.ts

@@ -12,6 +12,7 @@ interface ITimelineViewParams extends IViewParams {
     minDate?: Date;
     maxDate?: Date;
     fillStyle?: string;
+    use24HourClock?: boolean;
 }
 declare const TOUCH_MODE_NONE = 0;
 declare const TOUCH_MODE_CURRENT = 1;
@@ -29,9 +30,9 @@ type TimelineViewEventsList = [
     "playback",
     "pause",
     "visibility",
-    "localtime",
-    "suntime",
-    "sundate"
+    "changetimelinetime",
+    "changelocaltime",
+    "changelocaldatetime"
 ];
 type TimelineTouchMode = typeof TOUCH_MODE_NONE | typeof TOUCH_MODE_CURRENT | typeof TOUCH_MODE_PINCH | typeof TOUCH_MODE_SCALE | typeof TOUCH_MODE_SUN;
 interface ITimelineTouchPointer {
@@ -57,8 +58,9 @@ declare class TimelineView extends View<TimelineModel> {
     protected _isCurrentMouseOver: boolean;
     protected _isSunDragging: boolean;
     protected _isSunMouseOver: boolean;
-    protected _sunDate: Date;
-    protected _sunTime: boolean;
+    protected _localDateTime: Date;
+    protected _useLocalDateTime: boolean;
+    protected _use24HourClock: boolean;
     protected _minWidth: number;
     protected _canvasScale: number;
     protected _millisecondsInPixel: number;
@@ -66,7 +68,7 @@ declare class TimelineView extends View<TimelineModel> {
     protected _clickRangeStart: Date;
     protected _clickRangeEnd: Date;
     protected _clickCurrentDate: Date;
-    protected _clickSunDate: Date;
+    protected _clickLocalDateTime: Date;
     protected _clickTime: number;
     protected _clickDelay: number;
     protected _clickMoveTolerance: number;
@@ -83,8 +85,8 @@ declare class TimelineView extends View<TimelineModel> {
     protected _playBackBtn: ToggleButton;
     protected _multiplierEl: HTMLSelectElement | null;
     protected _buttons: ButtonGroup;
+    protected _timelineTimeBtn: ToggleButton;
     protected _localTimeBtn: ToggleButton;
-    protected _sunTimeBtn: ToggleButton;
     protected _visibility: boolean;
     constructor(options?: ITimelineViewParams);
     protected _onResizeObserver(): void;
@@ -98,22 +100,25 @@ declare class TimelineView extends View<TimelineModel> {
      * @public
      * @type {boolean}
      */
-    get localTime(): boolean;
-    set localTime(localTime: boolean);
+    get timelineTime(): boolean;
+    set timelineTime(timelineTime: boolean);
     /**
      * True while the Sun is set from its own marker instead of the timeline.
      * @public
      * @type {boolean}
      */
-    get sunTime(): boolean;
-    set sunTime(sunTime: boolean);
+    get use24HourClock(): boolean;
+    set use24HourClock(use24HourClock: boolean);
+    protected _notchColor(time: number): string;
+    get localTime(): boolean;
+    set localTime(localTime: boolean);
     /**
      * Date the Sun marker stands on.
      * @public
      * @type {Date}
      */
-    get sunDate(): Date;
-    set sunDate(date: Date);
+    get localDateTime(): Date;
+    set localDateTime(date: Date);
     setVisibility(visibility: boolean): void;
     protected _createMultiplier(): HTMLSelectElement;
     protected _syncMultiplier(): void;

package/lib/control/timeline/timelineUtils.d.ts

@@ -1,7 +1,7 @@
 type BaselineType = "alphabetic" | "bottom" | "hanging" | "ideographic" | "middle" | "top";
 type AlignType = "center" | "end" | "left" | "right" | "start";
 export declare function addSeconds(date: Date, seconds: number): Date;
-export declare function dateToStr(date: Date, showTime?: boolean, showMilliseconds?: boolean): string;
+export declare function dateToStr(date: Date, showTime?: boolean, showMilliseconds?: boolean, use24HourClock?: boolean): string;
 export declare function createCanvasHTML(): HTMLCanvasElement;
 export declare function getNearestTimeLeft(t: number, div: number): number;
 export declare function drawNotch(ctx: CanvasRenderingContext2D, xOffset?: number, size?: number, thickness?: number, color?: string): void;