import type { GeoPoint } from "../types.ts";
import type { Satellites } from "./types.ts";
/**
 * How many neighbours `nearest` returns when `count` is left out.
 *
 * @example
 * ```ts
 * import { NEAREST_COUNT } from "@johnmorrisdotca/chikyu-earth/satellites";
 *
 * console.log(NEAREST_COUNT);
 * ```
 */
export declare const NEAREST_COUNT = 5;
/**
 * One satellite and how near it is. `angle` is degrees, for `by: "sky"`. `distance` is kilometres, for `by: "space"`.
 *
 * @example
 * ```ts
 * import type { Neighbour } from "@johnmorrisdotca/chikyu-earth/satellites";
 *
 * const one: Neighbour = { index: 0, name: "ISS (ZARYA)", noradId: 25544, distance: { kilometres: 420, uncertaintyKm: 1, unit: "km" } };
 * console.log(one.distance?.unit);
 * ```
 */
export interface Neighbour {
    index: number;
    name: string;
    noradId: number;
    /** Degrees, when asked `by: "sky"`. */
    angle?: number;
    /** Kilometres, when asked `by: "space"`. */
    distance?: {
        kilometres: number;
        uncertaintyKm: number;
        unit: "km";
    };
}
/**
 * A place on the ground, a direction in the sky from an observer, or another satellite of the same group.
 *
 * @example
 * ```ts
 * import type { NearestTarget } from "@johnmorrisdotca/chikyu-earth/satellites";
 *
 * const target: NearestTarget = { place: { lon: -0.13, lat: 51.51 } };
 * console.log("place" in target);
 * ```
 */
export type NearestTarget = {
    place: GeoPoint;
    heightM?: number;
} | {
    azimuth: number;
    elevation: number;
    observer: GeoPoint & {
        heightM?: number;
    };
} | {
    satellite: number;
};
/**
 * What `nearest` may be asked. `date` is required.
 *
 * @example
 * ```ts
 * import type { NearestOptions } from "@johnmorrisdotca/chikyu-earth/satellites";
 *
 * const options: NearestOptions = { date: Date.UTC(2026, 10, 2), by: "space", count: 5 };
 * console.log(options.by);
 * ```
 */
export interface NearestOptions {
    /** How many to return, nearest first. {@link NEAREST_COUNT} when left out. */
    count?: number;
    /** Drop anything further than this: kilometres for `by: "space"`, degrees for `by: "sky"`. No limit when left out. */
    within?: number;
    /** `"space"` (kilometres, the default) or `"sky"` (the angle at the observer). */
    by?: "sky" | "space";
    /** The moment, milliseconds since the Unix epoch. */
    date: number;
    /** Where the sky is seen from, when the target is a satellite and `by` is `"sky"`. */
    observer?: GeoPoint & {
        heightM?: number;
    };
}
/**
 * The satellites nearest a place, a direction in the sky, or another satellite, at one moment. One SGP4 call (`exact`) for each satellite that can be placed.
 * It does not run again by itself. `by: "space"` answers with kilometres; `by: "sky"` with the angle in degrees. Nearest first.
 *
 * @param group - The satellites, from `createSatellites`.
 * @param target - A place, a direction (`azimuth`, `elevation`, `observer`), or `{ satellite: index }`.
 * @param options - `date` (required), `count` (5), `within`, `by` (`"space"`), and `observer` for a satellite seen in the sky.
 * @returns The neighbours, nearest first.
 *
 * @example
 * ```ts
 * import { createSatellites, nearest } from "@johnmorrisdotca/chikyu-earth/satellites";
 *
 * const group = createSatellites([]);
 * console.log(nearest(group, { place: { lon: 0, lat: 0 } }, { date: Date.UTC(2026, 10, 2) }).length);
 * ```
 */
export declare function nearest(group: Satellites, target: NearestTarget, options: NearestOptions): Neighbour[];
/**
 * Every satellite within `radius` of a target, nearest first. Kilometres for `by: "space"`, degrees for `by: "sky"`. The same one pass as `nearest`.
 *
 * @param group - The satellites.
 * @param target - A place, a direction, or a satellite.
 * @param radius - The limit, in the unit `by` uses.
 * @param options - As `nearest`, without `count` and `within`.
 * @returns The neighbours inside the limit.
 *
 * @example
 * ```ts
 * import { createSatellites, within } from "@johnmorrisdotca/chikyu-earth/satellites";
 *
 * const group = createSatellites([]);
 * console.log(within(group, { place: { lon: 0, lat: 0 } }, 1000, { date: Date.UTC(2026, 10, 2) }).length);
 * ```
 */
export declare function within(group: Satellites, target: NearestTarget, radius: number, options: Omit<NearestOptions, "count" | "within">): Neighbour[];
/**
 * The closest the two satellites come between `from` and `to`. The span is sampled every `stepMs` (60 seconds when left out), and the moment of the closest sample is then refined between its two neighbours,
 * to a tenth of a second, because two satellites close in at several kilometres a second and the closest sample alone can be hundreds of kilometres too far. The uncertainty is the elements' own: the
 * square root of the sum of the squares of the two satellites' rough uncertainties (1 km, and 1 km more for each day the elements have aged at that moment), not a published covariance.
 * Two SGP4 calls a sample, and about 20 more for the refinement. It does not run again by itself.
 *
 * @param group - The satellites.
 * @param a - The index of one satellite.
 * @param b - The index of the other.
 * @param from - The start, milliseconds since the Unix epoch.
 * @param to - The end.
 * @param stepMs - The sample step, at least 1000.
 * @returns The closest moment, or null when either satellite cannot be placed.
 *
 * @example
 * ```ts
 * import { closeApproach, createSatellites } from "@johnmorrisdotca/chikyu-earth/satellites";
 *
 * const group = createSatellites([]);
 * console.log(closeApproach(group, 0, 1, 0, 60_000));
 * ```
 */
export declare function closeApproach(group: Satellites, a: number, b: number, from: number, to: number, stepMs?: number): {
    at: number;
    kilometres: number;
    uncertaintyKm: number;
} | null;
/**
 * The slant range from a place to a satellite that is straight overhead, for a test or a page: it is the satellite's height. Positions are kilometres in one frame.
 *
 * @param heightKm - How far above the ground the satellite is.
 * @returns The distance, which is `heightKm`.
 *
 * @example
 * ```ts
 * import { overheadKm } from "@johnmorrisdotca/chikyu-earth/satellites";
 *
 * console.log(overheadKm(420));
 * ```
 */
export declare function overheadKm(heightKm: number): number;