import type { Vec3 } from "./ephemeris.ts";
/**
 * The field of view, in degrees, of a camera riding along at zoom 1 (the Earth's view from outside is 35).
 *
 * @example
 * ```ts
 * import { RIDE_FOV } from "@johnmorrisdotca/chikyu-earth/space";
 *
 * console.log(RIDE_FOV);
 * ```
 */
export declare const RIDE_FOV = 60;
/**
 * Where a riding camera looks: `down` straight at the Earth's centre (the ground goes by under the camera), or `horizon` tipped forward along the way it is going until the horizon
 * is a little above the middle of the view. A drag looks round from there on the spot with the horizon kept level: sideways turns about the local vertical, all the way round, and up and down only tips the view, from straight down to 20 degrees above the horizon.
 *
 * @example
 * ```ts
 * import type { RideLook } from "@johnmorrisdotca/chikyu-earth/space";
 *
 * const looks: RideLook[] = ["down", "horizon"];
 * console.log(looks.join(" or "));
 * ```
 */
export type RideLook = "down" | "horizon";
/**
 * A way to face while riding, as from the windows of a plane or a boat: `ahead` along the way it goes, `behind` the opposite, `left` and `right` across that way as seen facing ahead, `down` straight at the Earth and `up` straight away from it.
 *
 * @example
 * ```ts
 * import { RIDE_FACES, type RideFace } from "@johnmorrisdotca/chikyu-earth/space";
 *
 * const face: RideFace = "ahead";
 * console.log(RIDE_FACES.includes(face));
 * ```
 */
export type RideFace = "ahead" | "behind" | "left" | "right" | "down" | "up";
/**
 * Every facing, in the order of a row of buttons.
 *
 * @example
 * ```ts
 * import { RIDE_FACES } from "@johnmorrisdotca/chikyu-earth/space";
 *
 * console.log(RIDE_FACES.join(" "));
 * ```
 */
export declare const RIDE_FACES: readonly RideFace[];
/**
 * Yaw and tilt, in radians, that put a camera looking at a satellite on a facing. `down` is straight above it, looking down at it and the Earth. `ahead` looks along the way it goes.
 *
 * @param face - The facing.
 * @returns The yaw and tilt to give `aboveAxes`.
 *
 * @example
 * ```ts
 * import { faceOffset } from "@johnmorrisdotca/chikyu-earth/space";
 *
 * console.log(faceOffset("down").tilt, faceOffset("ahead").tilt > 1);
 * ```
 */
export declare function faceOffset(face: RideFace): {
    yaw: number;
    tilt: number;
};
/**
 * The field of view, in degrees, of a riding camera at a zoom: the natural 60 divided by the zoom, held between 1.5 and 100 (a zoom of 40, the most a ride takes, is 1.5 degrees).
 *
 * @param zoom - The shared controls' zoom.
 * @returns The field of view in degrees.
 *
 * @example
 * ```ts
 * import { rideFov } from "@johnmorrisdotca/chikyu-earth/space";
 *
 * console.log(rideFov(1), rideFov(6), rideFov(100));
 * ```
 */
export declare function rideFov(zoom: number): number;
/**
 * How many degrees the camera turns for a change of the controls' yaw at a zoom. The controls wrap their yaw into -180 to 180, so a page adds up the turns itself, change by change (`wrapYaw` of the change, scaled by this at the zoom of the moment), and hands
 * the total to `ridePose` as `turn`: a drag the whole way round is then a turn the whole way round, and the pace follows the field of view at any zoom.
 *
 * @param change - The change of yaw, in degrees, between two views of the controls (already brought into -180 to 180).
 * @param zoom - The shared controls' zoom at the moment.
 * @returns The turn, in degrees.
 *
 * @example
 * ```ts
 * import { rideTurnDegrees } from "@johnmorrisdotca/chikyu-earth/space";
 *
 * console.log(rideTurnDegrees(180, 1), rideTurnDegrees(180, 6));
 * ```
 */
export declare function rideTurnDegrees(change: number, zoom: number): number;
/**
 * The range of the controls' tilt that does something in the `horizon` look: from straight down to a little above the horizon. A tilt beyond it moves nothing, so a page holds the tilt to it, and a drag back starts moving at once instead of after the
 * excess is dragged back. It depends on the height (the horizon is further from straight down the higher the camera is) and the zoom. The `down` look has no such range.
 *
 * @param distance - The camera's distance from the Earth's centre, in Earth radii.
 * @param look - The look.
 * @param zoom - The shared controls' zoom.
 * @returns The lowest and highest tilt, or `null` for the `down` look.
 *
 * @example
 * ```ts
 * import { rideTiltLimits } from "@johnmorrisdotca/chikyu-earth/space";
 *
 * const range = rideTiltLimits(1.066, "horizon", 1);
 * console.log(range && `${range.min.toFixed(0)} to ${range.max.toFixed(0)}`, rideTiltLimits(1.066, "down", 1));
 * ```
 */
export declare function rideTiltLimits(distance: number, look: RideLook, zoom: number): {
    min: number;
    max: number;
} | null;
/**
 * What `ridePose` is asked: the camera's place and its way of travel (any length), where it looks, and the shared controls' yaw, tilt and zoom.
 *
 * @example
 * ```ts
 * import type { RideInput } from "@johnmorrisdotca/chikyu-earth/space";
 *
 * const input: RideInput = { position: [1.066, 0, 0], velocity: [0, 0, -7.66], look: "down", yaw: 0, tilt: 0, zoom: 1 };
 * console.log(input.look);
 * ```
 */
export interface RideInput {
    /** The camera's place in Earth radii from the Earth's centre, in the scene's axes. */
    position: Vec3;
    /** Its direction of travel, in any unit: only the direction is used. */
    velocity: Vec3;
    look: RideLook;
    /** The shared controls' yaw in degrees (a drag across the view is 180): turns the camera to look along its picture's left, so the ground moves right. 0 has the way it is going at the top of the picture. */
    yaw: number;
    /** The shared controls' tilt in degrees (a drag down the view is 60): tips the camera to look towards the bottom of its picture, so the ground moves up. */
    tilt: number;
    /** 1 is the natural view; more narrows the field of view. */
    zoom: number;
    /**
     * The heading in degrees, accumulated by the caller (see `rideTurnDegrees`): used in place of `yaw` when given, so a turn of more than half a way round is not undone by the controls wrapping their yaw, and a change of zoom does not swing it.
     */
    turn?: number;
    /** In the `horizon` look, the facing the yaw and tilt look round from. `ahead` when not given. */
    face?: RideFace;
}
/**
 * The camera `ridePose` works out: where it is, which way it looks, which way is up in the picture, its field of view in degrees, and how big the Earth looks from there (its angular radius in degrees).
 *
 * @example
 * ```ts
 * import type { RidePose } from "@johnmorrisdotca/chikyu-earth/space";
 *
 * const describe = (pose: RidePose): string => `looking ${pose.forward.map((n) => n.toFixed(2)).join(",")} with a ${pose.fov} degree view`;
 * console.log(typeof describe);
 * ```
 */
export interface RidePose {
    position: Vec3;
    forward: Vec3;
    up: Vec3;
    fov: number;
    earthRadiusDegrees: number;
}
/**
 * Where a ride puts the camera: `outside` (the default) a little way off the satellite, behind and above it, so the satellite is in the picture; `inside` at the satellite itself, looking out of it, as a ride always was.
 *
 * @example
 * ```ts
 * import type { RideViewpoint } from "@johnmorrisdotca/chikyu-earth/space";
 *
 * const viewpoints: RideViewpoint[] = ["outside", "inside"];
 * console.log(viewpoints.join(" or "));
 * ```
 */
export type RideViewpoint = "outside" | "inside";
/**
 * How big the model of the ridden satellite is drawn as the camera rises above it in a ride above: `distance` (the default) lets it shrink as one over the height and hand over to the ordinary mark between 1,000 and 2,000 km, `fixed` keeps the same share of the picture at every height, as 0.46.1 did.
 *
 * @example
 * ```ts
 * import type { RideModelSize } from "@johnmorrisdotca/chikyu-earth/space";
 *
 * const sizes: RideModelSize[] = ["distance", "fixed"];
 * console.log(sizes.join(" or "));
 * ```
 */
export type RideModelSize = "distance" | "fixed";
/**
 * How far an outside ride keeps the camera from the satellite, in kilometres. The satellite itself is a few metres across, so it is drawn far larger than life (a model about a fifth of the picture's height across): not to scale, and the page says so in its caption.
 *
 * @example
 * ```ts
 * import { OUTSIDE_KM } from "@johnmorrisdotca/chikyu-earth/space";
 *
 * console.log(OUTSIDE_KM);
 * ```
 */
export declare const OUTSIDE_KM = 25;
/**
 * The camera of an outside ride: the pose `ridePose` works out for a camera at the satellite, moved to `OUTSIDE_KM` back along its own line of sight so the satellite is in front of it. Looking along the way it goes (`look: "horizon"`) the satellite sits a little below the middle of the picture, so the camera is behind and above it; looking
 * down (`look: "down"`) it is at the middle, with the camera straight above it. Where the satellite sits in the picture does not change with the zoom. Which way the camera looks and which way is up are the pose's own, so the look-around is the same as from the satellite itself; the camera goes round the satellite as it looks about. Pure. Never nearer the ground than half the satellite's height.
 *
 * @param pose - The pose from `ridePose` for the camera at the satellite.
 * @param look - The look the pose was made with.
 * @param low - How far below the middle of the picture the satellite is, as a share of half its height (0 the middle, 1 the bottom edge); by default 0.8 looking along and 0 looking down.
 * @returns The pose moved back from the satellite, with how far the camera is from it in Earth radii and how many degrees below the middle of the picture the satellite is.
 *
 * @example
 * ```ts
 * import { outsidePose, ridePose } from "@johnmorrisdotca/chikyu-earth/space";
 *
 * const at = ridePose({ position: [1.066, 0, 0], velocity: [0, 0, -7.66], look: "horizon", yaw: 0, tilt: 0, zoom: 1 });
 * const out = outsidePose(at, "horizon");
 * console.log(out.distance.toFixed(4), out.below.toFixed(1), out.pose.position.map((n) => n.toFixed(4)).join(","));
 * ```
 */
export declare function outsidePose(pose: RidePose, look: RideLook, low?: number): {
    pose: RidePose;
    distance: number;
    below: number;
};
/**
 * The camera of a body-borne view: at `position`, looking at the Earth, with the way the body is going at the top of the picture. `look: "horizon"` tips it forward until the horizon is a little above the middle. A drag looks about from there on the spot:
 * `yaw` turns the camera to its left and `tilt` tips it towards the bottom of its picture, so the ground follows the pointer (right for a drag right, up for a drag up); the angle for each pixel of the drag is the field of view's, so the pace is the same at any zoom.
 * In the `horizon` look a sideways drag turns about the local vertical (the line from the Earth's centre through the camera), all the way round, and up and down only tips the view, from straight down to 20 degrees above the horizon, so the horizon stays level and
 * nothing rolls; in the `down` look the camera turns about its own up. `zoom` narrows the field of view.
 *
 * @param input - The camera's place, its way of travel, the look, and the shared controls' yaw, tilt and zoom.
 * @returns The camera's place, forward and up directions (unit vectors), its field of view, and the Earth's angular radius from there.
 *
 * @example
 * ```ts
 * import { ridePose } from "@johnmorrisdotca/chikyu-earth/space";
 *
 * const pose = ridePose({ position: [1.066, 0, 0], velocity: [0, 0, -7.66], look: "down", yaw: 0, tilt: 0, zoom: 1 });
 * console.log(pose.forward.map((n) => n.toFixed(2)).join(","), pose.earthRadiusDegrees.toFixed(0));
 * ```
 */
export declare function ridePose(input: RideInput): RidePose;