jspredict-dc/types/jspredict-dc.d.ts

Satellite propagation and visibility utilities built on satellite.js.

declare module 'jspredict-dc' {
  /** 观察者位置，按 [纬度, 经度, 海拔公里] 顺序传入。 */
  export type ObserverLocation = [number, number, number];
  /** 支持对象式写法的观察者位置。 */
  export interface ObserverLocationObject {
    /** 纬度，单位为度（支持 latitude 或 lat）。 */
    latitude?: number;
    lat?: number;
    /** 经度，单位为度（支持 longitude、lon 或 lng）。 */
    longitude?: number;
    lon?: number;
    lng?: number;
    /** 海拔高度，单位为公里（支持 altitude、height 或 alt）。 */
    altitude?: number;
    height?: number;
    alt?: number;
    /** 海拔高度，单位为米（支持 altMeters、altitudeMeters 或 heightMeters）。 */
    altMeters?: number;
    altitudeMeters?: number;
    heightMeters?: number;
  }
  /** 观察者位置的数组写法或对象写法。 */
  export type ObserverLocationInput = ObserverLocation | ObserverLocationObject;

  /** 单次过境窗口，包含起止时间、峰值仰角和方位角范围。 */
  export interface Transit {
    /** 过境开始时间戳，单位为毫秒。 */
    start: number;
    /** 过境结束时间戳，单位为毫秒。 */
    end: number;
    /** 峰值仰角，单位为度。 */
    maxElevation: number;
    /** 峰值仰角出现时的方位角，单位为度。 */
    apexAzimuth: number;
    /** 峰值仰角出现时刻，单位为毫秒。 */
    apexTime: number | null;
    /** 过境过程中的最大方位角，单位为度。 */
    maxAzimuth: number;
    /** 过境过程中的最小方位角，单位为度。 */
    minAzimuth: number;
    /** 过境持续时长，单位为毫秒。 */
    duration: number;
  }

  /** findTransits 调试诊断信息。 */
  export interface TransitDiagnostics {
    /** 诊断扫描步长，单位为毫秒。 */
    scanStepMs: number;
    /** 该时间窗内观测到的最大仰角，单位为度。 */
    maxElevationInWindow: number | null;
    /** 最接近地平线的时间点，毫秒时间戳。 */
    closestToHorizonAt: number | null;
    /** closestToHorizonAt 对应仰角，单位为度。 */
    closestToHorizonElevation: number | null;
    /** 最近一次接近地平线（|elevation|<=1°）的时间点。 */
    latestNearHorizonAt: number | null;
    /** 诊断扫描采样点数量。 */
    sampledPoints: number;
    /** 本次过境搜索所使用的阈值，单位为度。 */
    thresholdElevation: number;
    /** 过境搜索迭代次数。 */
    searchIterations: number;
    /** 过境搜索终止原因。 */
    terminationReason: 'badSat' | 'noTransitPredicted' | 'windowEnded' | 'maxTransitsReached' | 'maxIterationsReached';
    /** 搜索循环最近一次推进到的时间点。 */
    lastScanTime: number;
  }

  /** findTransits 调试返回值。 */
  export interface TransitDebugResult {
    transits: Transit[];
    diagnostics: TransitDiagnostics;
  }

  /** findTransitsDebug 可选参数。 */
  export interface FindTransitsDebugOptions {
    /** 诊断扫描步长，支持毫秒数、字符串数值或单位对象。 */
    scanStepMs?: number | string | { [unit: string]: number };
  }

  /** 传播后的惯性系位置和速度。 */
  export interface Eci {
    /** 位置向量，单位为公里。 */
    position: { x: number; y: number; z: number };
    /** 速度向量，单位为公里/秒。 */
    velocity: { x: number; y: number; z: number };
  }

  /** 单时刻观测结果，包含地理位置、日照状态和可选的地面观测量。 */
  export interface ObserveResult {
    /** 观测时刻的毫秒时间戳。 */
    timestamp: number;
    eci: Eci;
    /** 格林尼治平恒星时。 */
    gmst: number;
    /** 纬度，单位为度。 */
    latitude: number;
    /** 经度，单位为度。 */
    longitude: number;
    /** 海拔高度，单位为公里。 */
    altitude: number;
    /** 可见覆盖范围直径，单位为公里。 */
    footprint: number;
    /** 是否处于日照状态。 */
    sunlit: boolean;
    /** 处于地影时的阴影深度。 */
    eclipseDepth: number;
    /** 观测者坐标存在时的方位角，单位为度。 */
    azimuth?: number;
    /** 观测者坐标存在时的仰角，单位为度。 */
    elevation?: number;
    /** 观测者坐标存在时的斜距，单位为公里。 */
    rangeSat?: number;
    /** 观测者坐标存在时的多普勒因子。 */
    doppler?: number;
  }

  /** OMM / JSON GP 的标准字段集合。 */
  export interface OmmRecord {
    OBJECT_NAME?: string;
    OBJECT_ID?: string;
    CENTER_NAME?: string;
    REF_FRAME?: string;
    TIME_SYSTEM?: string;
    MEAN_MOTION?: string | number;
    ECCENTRICITY?: string | number;
    INCLINATION?: string | number;
    RA_OF_ASC_NODE?: string | number;
    ARG_OF_PERICENTER?: string | number;
    MEAN_ANOMALY?: string | number;
    EPHEMERIS_TYPE?: string | number;
    CLASSIFICATION_TYPE?: string;
    NORAD_CAT_ID?: string | number;
    ELEMENT_SET_NO?: string | number;
    REV_AT_EPOCH?: string | number;
    BSTAR?: string | number;
    MEAN_MOTION_DOT?: string | number;
    MEAN_MOTION_DDOT?: string | number;
    EPOCH?: string | Date;
    [key: string]: unknown;
  }

  /** TLE 的两行文本结构。 */
  export interface TleSource {
    name?: string;
    line1: string;
    line2: string;
  }

  export type OrbitFormat = 'tle' | 'omm' | 'satrec';

  /** 统一后的轨道根数字段。 */
  export interface OrbitElements {
    epoch: string | null;
    epochMs: number | null;
    epochYear: number | null;
    epochDayOfYear: number | null;
    meanMotion: number | null;
    meanMotionFirstDerivative: number | null;
    meanMotionSecondDerivative: number | null;
    bstar: number | null;
    inclination: number | null;
    rightAscensionOfAscendingNode: number | null;
    eccentricity: number | null;
    argumentOfPerigee: number | null;
    meanAnomaly: number | null;
    semiMajorAxisKm: number | null;
    orbitalPeriodSeconds: number | null;
    revolutionNumberAtEpoch: number | null;
    ephemerisType: string | null;
  }

  /** 统一后的轨道元数据。 */
  export interface OrbitMetadata extends OrbitElements {
    format: OrbitFormat;
    name: string | null;
    noradCatalogNumber: string | null;
    classification: string | null;
    internationalDesignator: string | null;
    launchYear: number | null;
    launchNumberOfYear: number | null;
    launchPiece: string | null;
    objectType?: string | null;
    countryCode?: string | null;
    launchDate?: string | null;
    decayDate?: string | null;
    centerName: string | null;
    referenceFrame: string | null;
    referenceFrameEpoch?: string | null;
    timeSystem: string | null;
    meanElementTheory: string | null;
    creationDate?: string | null;
    originator?: string | null;
    comment?: string | null;
    elementSetNumber: number | null;
    orbitClass: 'LEO' | 'MEO' | 'GEO' | 'HEO' | 'DEEP_SPACE' | null;
    isDeepSpace: boolean;
    raw: unknown;
  }

  /** 归一化后的轨道源结构。 */
  export interface OrbitSource {
    kind: 'tle' | 'omm' | 'satrec';
    tle?: TleSource;
    omm?: OmmRecord;
    satrec?: unknown;
    source?: string;
  }

  /** 可传入库中的轨道源总输入。 */
  export type OrbitSourceInput = string | TleSource | OmmRecord | OrbitSource | unknown;

  /** jspredict-dc 对外暴露的完整 API。 */
  export interface JSPredictDC {
    /** 默认最多返回的过境条目数。 */
    DEFAULT_MAX_TRANSITS: number;
    /** 开关式调试日志输出。 */
    printIntervalInfo(open: boolean): boolean;
    /** 兼容旧名的调试开关。 */
    setDebugIntervalLogging(open: boolean): boolean;
    /** 设置最大迭代次数。 */
    setMax(max?: number): number;
    /** 兼容旧名的最大迭代次数设置。 */
    setIterationLimit(max?: number): number;

    /** 将任意轨道源归一化成内部标准结构。 */
    normalizeOrbitSource(source: OrbitSourceInput): OrbitSource;
    /** 统一解析轨道源的身份、历元和轨道要素。 */
    parseOrbitMetadata(source: OrbitSourceInput): OrbitMetadata;
    /** 只返回统一后的轨道根数字段。 */
    parseOrbitElements(source: OrbitSourceInput): OrbitElements;
    /** 解析 TLE，并返回更完整的 TLE 元数据。 */
    parseTle(source: OrbitSourceInput): OrbitMetadata;
    /** 从 TLE 文本构建轨道源。 */
    fromTle(line1OrText: string, line2?: string): OrbitSource;
    /** 从 JSON GP 记录构建轨道源。 */
    fromJsonGp(record: OmmRecord): OrbitSource;
    /** 从 OMM XML 构建轨道源。 */
    fromOmmXml(xml: string): OrbitSource;

    /** 计算给定时刻的观测结果。 */
    observeAt(source: OrbitSourceInput, observerLocation?: ObserverLocationInput, start?: number | Date | string): ObserveResult | null;
    /** 兼容旧名的单时刻观测接口。 */
    getPositionByTime(source: OrbitSourceInput, observerLocation?: ObserverLocationInput, start?: number | Date | string): ObserveResult | null;

    /** 在时间段内按固定步长采样星历。 */
    ephemeris(source: OrbitSourceInput, observerLocation: ObserverLocationInput, start: number | Date | string, end: number | Date | string, interval?: number | string | { [unit: string]: number }): ObserveResult[];
    /** 兼容旧名的星历采样接口。 */
    getEphemeris(source: OrbitSourceInput, observerLocation: ObserverLocationInput, start: number | Date | string, end: number | Date | string, interval?: number | string | { [unit: string]: number }): ObserveResult[];

    /** 搜索过境窗口。 */
    findTransits(source: OrbitSourceInput, observerLocation: ObserverLocationInput, start: number | Date | string, end: number | Date | string, minElevation?: number, maxTransits?: number): Transit[];
    /** 兼容旧名的过境搜索接口。 */
    transits(source: OrbitSourceInput, observerLocation: ObserverLocationInput, start: number | Date | string, end: number | Date | string, minElevation?: number, maxTransits?: number): Transit[];
    /** 过境搜索调试接口，返回结果与诊断信息。 */
    findTransitsDebug(
      source: OrbitSourceInput,
      observerLocation: ObserverLocationInput,
      start: number | Date | string,
      end: number | Date | string,
      minElevation?: number,
      maxTransits?: number,
      options?: FindTransitsDebugOptions
    ): TransitDebugResult;

    /** 返回单个过境窗口。 */
    transitSegment(source: OrbitSourceInput, observerLocation: ObserverLocationInput, start: number | Date | string, end: number | Date | string): Transit | null;
    /** 兼容旧名的单窗口过境搜索。 */
    getTransitSegment(source: OrbitSourceInput, observerLocation: ObserverLocationInput, start: number | Date | string, end: number | Date | string): Transit | null;

    /** 返回观测者可见窗口的起止时间数组。 */
    visibilityWindows(source: OrbitSourceInput, observerLocation: ObserverLocationInput, start: number | Date | string, end: number | Date | string): number[][];
    /** 兼容旧名的可见窗口接口。 */
    getVisibilityWindows(source: OrbitSourceInput, observerLocation: ObserverLocationInput, start: number | Date | string, end: number | Date | string): number[][];
    /** 语义更清晰的地面观测可见窗口接口。 */
    groundVisibilityWindows(source: OrbitSourceInput, observerLocation: ObserverLocationInput, start: number | Date | string, end: number | Date | string): number[][];
    /** groundVisibilityWindows 的兼容别名。 */
    getGroundVisibilityWindows(source: OrbitSourceInput, observerLocation: ObserverLocationInput, start: number | Date | string, end: number | Date | string): number[][];

    /** 计算两颗卫星之间的可见窗口。 */
    satelliteVisibilityWindows(source1: OrbitSourceInput, source2: OrbitSourceInput, start: number | Date | string, end: number | Date | string, stepSeconds?: number): number[][];
    /** 兼容旧名的卫星互见窗口接口。 */
    getSatelliteVisibilityWindows(source1: OrbitSourceInput, source2: OrbitSourceInput, start: number | Date | string, end: number | Date | string, stepSeconds?: number): number[][];

    /** 根据轨道源估算轨道周期。 */
    orbitalPeriodFromOrbitSource(source: OrbitSourceInput): number;
    /** 兼容旧名的轨道周期接口。 */
    orbitalPeriodFromTle(source: OrbitSourceInput): number;
    /** 兼容旧名的轨道周期接口。 */
    getOrbitalPeriodByTle(source: OrbitSourceInput): number;

    /** 根据笛卡尔坐标估算轨道周期。 */
    orbitalPeriodFromCartesian3(cartesian3?: [number, number, number]): number;
    /** 兼容旧名的笛卡尔周期接口。 */
    getOrbitalPeriodByCartesian3(cartesian3?: [number, number, number]): number;
  }

  const jspredict_dc: JSPredictDC;
  export default jspredict_dc;
}