Time and Animation

/**
 * Astronomical Julian Date with high precision time representation
 */
class JulianDate {
  constructor(julianDayNumber?: number, secondsOfDay?: number, timeStandard?: TimeStandard);
  dayNumber: number;
  secondsOfDay: number;
  
  static fromGregorianDate(year: number, month: number, day: number, hour?: number, minute?: number, second?: number, millisecond?: number, result?: JulianDate): JulianDate;
  static fromDate(date: Date, result?: JulianDate): JulianDate;
  static fromIso8601(iso8601String: string, result?: JulianDate): JulianDate;
  static now(result?: JulianDate): JulianDate;
  static toGregorianDate(julianDate: JulianDate, result?: GregorianDate): GregorianDate;
  static toDate(julianDate: JulianDate): Date;
  static toIso8601(julianDate: JulianDate, precision?: number): string;
  static clone(julianDate: JulianDate, result?: JulianDate): JulianDate;
  static compare(left: JulianDate, right: JulianDate): number;
  static equals(left?: JulianDate, right?: JulianDate): boolean;
  static equalsEpsilon(left: JulianDate, right: JulianDate, epsilon: number): boolean;
  static totalDays(julianDate: JulianDate): number;
  static secondsDifference(left: JulianDate, right: JulianDate): number;
  static daysDifference(left: JulianDate, right: JulianDate): number;
  static computeTaiMinusUtc(julianDate: JulianDate): number;
  static addSeconds(julianDate: JulianDate, seconds: number, result?: JulianDate): JulianDate;
  static addMinutes(julianDate: JulianDate, minutes: number, result?: JulianDate): JulianDate;
  static addHours(julianDate: JulianDate, hours: number, result?: JulianDate): JulianDate;
  static addDays(julianDate: JulianDate, days: number, result?: JulianDate): JulianDate;
  static lessThan(left: JulianDate, right: JulianDate): boolean;
  static lessThanOrEquals(left: JulianDate, right: JulianDate): boolean;
  static greaterThan(left: JulianDate, right: JulianDate): boolean;
  static greaterThanOrEquals(left: JulianDate, right: JulianDate): boolean;
  
  clone(result?: JulianDate): JulianDate;
  equals(right?: JulianDate): boolean;
  toString(): string;
}

/**
 * Gregorian calendar date representation
 */
class GregorianDate {
  constructor(year?: number, month?: number, day?: number, hour?: number, minute?: number, second?: number, millisecond?: number, isLeapSecond?: boolean);
  year: number;
  month: number;
  day: number;
  hour: number;
  minute: number;
  second: number;
  millisecond: number;
  isLeapSecond: boolean;
}

/**
 * Time standards for Julian date calculations
 */
enum TimeStandard {
  UTC = 0,
  TAI = 1
}

/**
 * Leap second information
 */
class LeapSecond {
  constructor(date?: JulianDate, offset?: number);
  julianDate: JulianDate;
  offset: number;
}

/**
 * Time constants and conversion utilities
 */
const TimeConstants = {
  SECONDS_PER_MILLISECOND: 0.001,
  SECONDS_PER_MINUTE: 60.0,
  MINUTES_PER_HOUR: 60.0,
  HOURS_PER_DAY: 24.0,
  SECONDS_PER_HOUR: 3600.0,
  MINUTES_PER_DAY: 1440.0,
  SECONDS_PER_DAY: 86400.0,
  DAYS_PER_JULIAN_CENTURY: 36525.0,
  PICOSECOND: 0.000000001,
  MODIFIED_JULIAN_DATE_DIFFERENCE: 2400000.5
};

/**
 * Clock for managing simulation time and animation
 */
class Clock {
  constructor(options?: ClockOptions);
  startTime: JulianDate;
  stopTime: JulianDate;
  currentTime: JulianDate;
  multiplier: number;
  clockStep: ClockStep;
  clockRange: ClockRange;
  canAnimate: boolean;
  shouldAnimate: boolean;
  readonly onTick: Event;
  
  tick(): JulianDate;
  computeCurrentTime(): JulianDate;
}

interface ClockOptions {
  startTime?: JulianDate;
  stopTime?: JulianDate;
  currentTime?: JulianDate;
  multiplier?: number;
  clockStep?: ClockStep;
  clockRange?: ClockRange;
  canAnimate?: boolean;
  shouldAnimate?: boolean;
}

/**
 * Clock stepping modes
 */
enum ClockStep {
  TICK_DEPENDENT = 0,
  SYSTEM_CLOCK_MULTIPLIER = 1,
  SYSTEM_CLOCK = 2
}

/**
 * Clock range behaviors when reaching start/stop times
 */
enum ClockRange {
  UNBOUNDED = 0,
  CLAMPED = 1,
  LOOP_STOP = 2
}

/**
 * Time interval with start and stop times
 */
class TimeInterval {
  constructor(options?: TimeIntervalOptions);
  start: JulianDate;
  stop: JulianDate;
  isStartIncluded: boolean;
  isStopIncluded: boolean;
  data?: any;
  readonly isEmpty: boolean;
  
  static fromIso8601(options: TimeIntervalFromIso8601Options, result?: TimeInterval): TimeInterval;
  static toIso8601(timeInterval: TimeInterval, precision?: number): string;
  static clone(timeInterval?: TimeInterval, result?: TimeInterval): TimeInterval;
  static equals(left?: TimeInterval, right?: TimeInterval, dataComparer?: TimeInterval.DataComparer): boolean;
  static equalsEpsilon(left: TimeInterval, right: TimeInterval, epsilon: number, dataComparer?: TimeInterval.DataComparer): boolean;
  static intersect(left: TimeInterval, right: TimeInterval, result?: TimeInterval, mergeCallback?: TimeInterval.MergeCallback): TimeInterval;
  static contains(timeInterval: TimeInterval, julianDate: JulianDate): boolean;
  
  clone(result?: TimeInterval): TimeInterval;
  equals(right?: TimeInterval, dataComparer?: TimeInterval.DataComparer): boolean;
  toString(): string;
}

interface TimeIntervalOptions {
  start?: JulianDate;
  stop?: JulianDate;
  isStartIncluded?: boolean;
  isStopIncluded?: boolean;
  data?: any;
}

interface TimeIntervalFromIso8601Options {
  iso8601: string;
  isStartIncluded?: boolean;
  isStopIncluded?: boolean;
  data?: any;
}

namespace TimeInterval {
  type DataComparer = (leftData: any, rightData: any) => boolean;
  type MergeCallback = (leftData: any, rightData: any) => any;
}

/**
 * Collection of time intervals with efficient querying
 */
class TimeIntervalCollection {
  constructor(intervals?: TimeInterval[]);
  readonly start: JulianDate;
  readonly stop: JulianDate;
  readonly length: number;
  readonly isEmpty: boolean;
  readonly isStartIncluded: boolean;
  readonly isStopIncluded: boolean;
  readonly changedEvent: Event;
  
  get(index: number): TimeInterval;
  removeAll(): void;
  findIntervalContainingDate(date: JulianDate): TimeInterval;
  findDataForIntervalContainingDate(date: JulianDate): any;
  contains(julianDate: JulianDate): boolean;
  indexOf(date: JulianDate): number;
  findInterval(options?: TimeIntervalCollectionFindOptions): TimeInterval;
  addInterval(interval: TimeInterval, dataComparer?: TimeInterval.DataComparer): void;
  removeInterval(interval: TimeInterval): boolean;
  intersect(other: TimeIntervalCollection, dataComparer?: TimeInterval.DataComparer, mergeCallback?: TimeInterval.MergeCallback): TimeIntervalCollection;
  equals(right?: TimeIntervalCollection, dataComparer?: TimeInterval.DataComparer): boolean;
}

interface TimeIntervalCollectionFindOptions {
  start?: JulianDate;
  stop?: JulianDate;
  isStartIncluded?: boolean;
  isStopIncluded?: boolean;
}

/**
 * Interpolation algorithms for animated properties
 */
enum InterpolationAlgorithm {
  LINEAR = 0,
  LAGRANGE = 1,
  HERMITE = 2
}

/**
 * Linear interpolation implementation
 */
class LinearApproximation {
  static getRequiredDataPoints(degree: number): number;
  static interpolateOrderZero(x: number, xTable: number[], yTable: number[], yStride: number, result?: number[]): number[];
}

/**
 * Lagrange polynomial interpolation
 */
class LagrangePolynomialApproximation {
  static getRequiredDataPoints(degree: number): number;
  static interpolateOrderZero(x: number, xTable: number[], yTable: number[], yStride: number, inputOrder: number, outputOrder?: number, result?: number[]): number[];
}

/**
 * Hermite spline interpolation
 */
class HermitePolynomialApproximation {
  static getRequiredDataPoints(degree: number, inputOrder?: number): number;
  static interpolateOrderZero(x: number, xTable: number[], yTable: number[], yStride: number, inputOrder: number, outputOrder?: number, result?: number[]): number[];
}

/**
 * Extrapolation types for properties beyond sampled data
 */
enum ExtrapolationType {
  NONE = 0,
  HOLD = 1,
  EXTRAPOLATE = 2
}

/**
 * Spline interpolation for smooth curves
 */
class CatmullRomSpline {
  readonly times: number[];
  readonly points: Cartesian3[];
  readonly firstTangent: Cartesian3;
  readonly lastTangent: Cartesian3;
  
  static create(options: CatmullRomSplineOptions): CatmullRomSpline;
  
  evaluate(time: number, result?: Cartesian3): Cartesian3;
  findTimeInterval(time: number): number;
  wrapTime(time: number): number;
  clampTime(time: number): number;
}

interface CatmullRomSplineOptions {
  times: number[];
  points: Cartesian3[];
  firstTangent?: Cartesian3;
  lastTangent?: Cartesian3;
}

/**
 * Linear spline interpolation
 */
class LinearSpline {
  readonly times: number[];
  readonly points: Cartesian3[];
  
  static create(options: LinearSplineOptions): LinearSpline;
  
  evaluate(time: number, result?: Cartesian3): Cartesian3;
  findTimeInterval(time: number): number;
  wrapTime(time: number): number;
  clampTime(time: number): number;
}

interface LinearSplineOptions {
  times: number[];
  points: Cartesian3[];
}

/**
 * Quaternion spline for rotation interpolation
 */
class QuaternionSpline {
  readonly times: number[];
  readonly points: Quaternion[];
  readonly innerQuadrangles: Quaternion[];
  
  static create(options: QuaternionSplineOptions): QuaternionSpline;
  
  evaluate(time: number, result?: Quaternion): Quaternion;
  findTimeInterval(time: number): number;
  wrapTime(time: number): number;
  clampTime(time: number): number;
}

interface QuaternionSplineOptions {
  times: number[];
  points: Quaternion[];
  firstInnerQuadrangle?: Quaternion;
  lastInnerQuadrangle?: Quaternion;
}

/**
 * Weighted spline for non-uniform interpolation
 */
class WeightedSpline {
  readonly times: number[];
  readonly points: number[];
  readonly weights: number[];
  
  static create(options: WeightedSplineOptions): WeightedSpline;
  
  evaluate(time: number): number;
  findTimeInterval(time: number): number;
  wrapTime(time: number): number;
  clampTime(time: number): number;
}

interface WeightedSplineOptions {
  times: number[];
  points: number[];
  weights: number[];
}

/**
 * Animation path for smooth camera or object movement
 */
class PathInterpolator {
  readonly times: number[];
  readonly spline: Spline;
  
  static create(options: PathInterpolatorOptions): PathInterpolator;
  
  evaluate(time: number): {
    position: Cartesian3;
    velocity: Cartesian3;
    acceleration: Cartesian3;
  };
  
  findTimeInterval(time: number): number;
}

interface PathInterpolatorOptions {
  times: number[];
  positions: Cartesian3[];
  velocities?: Cartesian3[];
  accelerations?: Cartesian3[];
}

/**
 * Flight path animation with banking and smooth turns
 */
class FlightPath {
  constructor(options: FlightPathOptions);
  readonly times: number[];
  readonly positions: Cartesian3[];
  readonly orientations: Quaternion[];
  readonly duration: number;
  
  evaluate(time: number): {
    position: Cartesian3;
    orientation: Quaternion;
  };
  
  sampleFlight(numberOfSamples: number): FlightSample[];
}

interface FlightPathOptions {
  times: number[];
  positions: Cartesian3[];
  orientations?: Quaternion[];
  bankAngles?: number[];
  speeds?: number[];
}

interface FlightSample {
  time: number;
  position: Cartesian3;
  orientation: Quaternion;
  velocity: Cartesian3;
}

/**
 * Time-dynamic position property for moving objects
 */
class SampledPositionProperty {
  constructor(referenceFrame?: ReferenceFrame, numberOfDerivatives?: number);
  readonly referenceFrame: ReferenceFrame;
  readonly numberOfDerivatives: number;
  interpolationDegree: number;
  interpolationAlgorithm: InterpolationAlgorithm;
  forwardExtrapolationType: ExtrapolationType;
  forwardExtrapolationDuration: number;
  backwardExtrapolationType: ExtrapolationType;
  backwardExtrapolationDuration: number;
  readonly isConstant: boolean;
  readonly definitionChanged: Event;
  
  getValue(time: JulianDate, result?: Cartesian3): Cartesian3;
  getValueInReferenceFrame(time: JulianDate, referenceFrame: ReferenceFrame, result?: Cartesian3): Cartesian3;
  addSample(time: JulianDate, position: Cartesian3, derivatives?: Cartesian3[]): void;
  addSamples(times: JulianDate[], positions: Cartesian3[], derivatives?: Cartesian3[][]): void;
  addSamplesPackedArray(packedSamples: number[], epoch?: JulianDate): void;
  removeSample(time: JulianDate): boolean;
  removeProperty(time: JulianDate): void;
  setInterpolationOptions(options?: InterpolationOptions): void;
  equals(other?: Property): boolean;
}

/**
 * Time-dynamic property with sampled values
 */
class SampledProperty {
  constructor(type: number, derivativeTypes?: number[]);
  readonly type: number;
  readonly derivativeTypes: number[];
  interpolationDegree: number;
  interpolationAlgorithm: InterpolationAlgorithm;
  forwardExtrapolationType: ExtrapolationType;
  forwardExtrapolationDuration: number;
  backwardExtrapolationType: ExtrapolationType;
  backwardExtrapolationDuration: number;
  readonly isConstant: boolean;
  readonly definitionChanged: Event;
  
  getValue(time: JulianDate, result?: any): any;
  addSample(time: JulianDate, value: any, derivatives?: any[]): void;
  addSamples(times: JulianDate[], values: any[], derivativeValues?: any[][]): void;
  addSamplesPackedArray(packedSamples: number[], epoch?: JulianDate): void;
  removeSample(time: JulianDate): boolean;
  removeProperty(time: JulianDate): void;
  equals(other?: Property): boolean;
}

/**
 * Property that varies over time intervals
 */
class TimeIntervalCollectionProperty {
  constructor(type?: number);
  readonly intervals: TimeIntervalCollection;
  readonly isConstant: boolean;
  readonly definitionChanged: Event;
  
  getValue(time: JulianDate, result?: any): any;
  equals(other?: Property): boolean;
}

/**
 * Composite property combining multiple time-varying properties
 */
class CompositePositionProperty {
  constructor(referenceFrame?: ReferenceFrame);
  readonly referenceFrame: ReferenceFrame;
  readonly intervals: TimeIntervalCollection;
  readonly isConstant: boolean;
  readonly definitionChanged: Event;
  
  getValue(time: JulianDate, result?: Cartesian3): Cartesian3;
  getValueInReferenceFrame(time: JulianDate, referenceFrame: ReferenceFrame, result?: Cartesian3): Cartesian3;
  equals(other?: Property): boolean;
}

/**
 * Velocity vector property for dynamic objects
 */
class VelocityVectorProperty {
  constructor(position?: PositionProperty, normalize?: boolean);
  position?: PositionProperty;
  normalize: boolean;
  readonly isConstant: boolean;
  readonly definitionChanged: Event;
  
  getValue(time: JulianDate, result?: Cartesian3): Cartesian3;
  equals(other?: Property): boolean;
}

/**
 * Orientation property for time-dynamic rotations
 */
class VelocityOrientationProperty {
  constructor(position?: PositionProperty, ellipsoid?: Ellipsoid);
  position?: PositionProperty;
  ellipsoid: Ellipsoid;
  readonly isConstant: boolean;
  readonly definitionChanged: Event;
  
  getValue(time: JulianDate, result?: Quaternion): Quaternion;
  equals(other?: Property): boolean;
}

/**
 * Animation controller for coordinating multiple animated objects
 */
class AnimationController {
  constructor(scene: Scene);
  readonly scene: Scene;
  readonly animations: AnimationState[];
  speedMultiplier: number;
  
  add(options: AnimationOptions): AnimationState;
  remove(animation: AnimationState): boolean;
  removeAll(): void;
  update(time: JulianDate): void;
  getByName(name: string): AnimationState;
}

interface AnimationOptions {
  name?: string;
  startTime?: JulianDate;
  stopTime?: JulianDate;
  duration?: number;
  delay?: number;
  easingFunction?: EasingFunction;
  onUpdate?: (animation: AnimationState, progress: number) => void;
  onComplete?: (animation: AnimationState) => void;
  loop?: boolean;
  reverse?: boolean;
}

/**
 * Individual animation state
 */
class AnimationState {
  readonly name: string;
  readonly startTime: JulianDate;
  readonly stopTime: JulianDate;
  readonly duration: number;
  readonly delay: number;
  readonly easingFunction: EasingFunction;
  readonly onUpdate?: (animation: AnimationState, progress: number) => void;
  readonly onComplete?: (animation: AnimationState) => void;
  readonly loop: boolean;
  readonly reverse: boolean;
  
  start(): void;
  stop(): void;
  pause(): void;
  resume(): void;
  reset(): void;
  getProgress(): number;
  isActive(): boolean;
  isComplete(): boolean;
}

/**
 * Easing functions for smooth animation transitions
 */
type EasingFunction = (time: number) => number;

const EasingFunction = {
  LINEAR: (t: number) => t,
  QUADRATIC_IN: (t: number) => t * t,
  QUADRATIC_OUT: (t: number) => t * (2 - t),
  QUADRATIC_IN_OUT: (t: number) => t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t,
  CUBIC_IN: (t: number) => t * t * t,
  CUBIC_OUT: (t: number) => (--t) * t * t + 1,
  CUBIC_IN_OUT: (t: number) => t < 0.5 ? 4 * t * t * t : (t - 1) * (2 * t - 2) * (2 * t - 2) + 1,
  QUARTIC_IN: (t: number) => t * t * t * t,
  QUARTIC_OUT: (t: number) => 1 - (--t) * t * t * t,
  QUARTIC_IN_OUT: (t: number) => t < 0.5 ? 8 * t * t * t * t : 1 - 8 * (--t) * t * t * t,
  QUINTIC_IN: (t: number) => t * t * t * t * t,
  QUINTIC_OUT: (t: number) => 1 + (--t) * t * t * t * t,
  QUINTIC_IN_OUT: (t: number) => t < 0.5 ? 16 * t * t * t * t * t : 1 + 16 * (--t) * t * t * t * t,
  SINUSOIDAL_IN: (t: number) => 1 - Math.cos(t * Math.PI / 2),
  SINUSOIDAL_OUT: (t: number) => Math.sin(t * Math.PI / 2),
  SINUSOIDAL_IN_OUT: (t: number) => 0.5 * (1 - Math.cos(Math.PI * t)),
  EXPONENTIAL_IN: (t: number) => t === 0 ? 0 : Math.pow(2, 10 * (t - 1)),
  EXPONENTIAL_OUT: (t: number) => t === 1 ? 1 : 1 - Math.pow(2, -10 * t),
  EXPONENTIAL_IN_OUT: (t: number) => {
    if (t === 0) return 0;
    if (t === 1) return 1;
    if (t < 0.5) return 0.5 * Math.pow(2, 10 * (2 * t - 1));
    return 0.5 * (2 - Math.pow(2, -10 * (2 * t - 1)));
  },
  CIRCULAR_IN: (t: number) => 1 - Math.sqrt(1 - t * t),
  CIRCULAR_OUT: (t: number) => Math.sqrt(1 - (t - 1) * (t - 1)),
  CIRCULAR_IN_OUT: (t: number) => {
    if (t < 0.5) return 0.5 * (1 - Math.sqrt(1 - 4 * t * t));
    return 0.5 * (Math.sqrt(1 - 4 * (t - 1) * (t - 1)) + 1);
  },
  ELASTIC_IN: (t: number) => {
    if (t === 0) return 0;
    if (t === 1) return 1;
    return -Math.pow(2, 10 * (t - 1)) * Math.sin((t - 1.1) * 5 * Math.PI);
  },
  ELASTIC_OUT: (t: number) => {
    if (t === 0) return 0;
    if (t === 1) return 1;
    return Math.pow(2, -10 * t) * Math.sin((t - 0.1) * 5 * Math.PI) + 1;
  },
  BACK_IN: (t: number) => t * t * (2.7 * t - 1.7),
  BACK_OUT: (t: number) => (--t) * t * (2.7 * t + 1.7) + 1,
  BOUNCE_IN: (t: number) => 1 - EasingFunction.BOUNCE_OUT(1 - t),
  BOUNCE_OUT: (t: number) => {
    if (t < 1 / 2.75) return 7.5625 * t * t;
    if (t < 2 / 2.75) return 7.5625 * (t -= 1.5 / 2.75) * t + 0.75;
    if (t < 2.5 / 2.75) return 7.5625 * (t -= 2.25 / 2.75) * t + 0.9375;
    return 7.5625 * (t -= 2.625 / 2.75) * t + 0.984375;
  }
};

interface InterpolationOptions {
  interpolationDegree?: number;
  interpolationAlgorithm?: InterpolationAlgorithm;
}

interface ReferenceFrame {
  FIXED: 0;
  INERTIAL: 1;
}

interface Spline {
  evaluate(time: number, result?: any): any;
  findTimeInterval(time: number): number;
}

interface PositionProperty extends Property {
  referenceFrame: ReferenceFrame;
  getValue(time: JulianDate, result?: Cartesian3): Cartesian3;
  getValueInReferenceFrame(time: JulianDate, referenceFrame: ReferenceFrame, result?: Cartesian3): Cartesian3;
}

interface Property {
  isConstant: boolean;
  definitionChanged: Event;
  getValue(time: JulianDate, result?: any): any;
  equals(other?: Property): boolean;
}

interface Quaternion {
  x: number;
  y: number;
  z: number;
  w: number;
}

// ISO 8601 duration parsing utilities
const Iso8601 = {
  MAXIMUM_VALUE: JulianDate.fromIso8601('9999-12-31T23:59:59Z'),
  MINIMUM_VALUE: JulianDate.fromIso8601('0001-01-01T00:00:00Z'),
  
  parseDuration(duration: string): number;
  parseDate(date: string): JulianDate;
  formatDuration(duration: number): string;
  formatDate(date: JulianDate): string;
}