import { type EarthMapSource, type EarthTilesOptions } from "./map.ts";
/** The day this service's tile matrix, layers and terms were read. */
export declare const GIBS_READ = "2026-11-13";
/**
 * The id of the source `gibsTiles` makes. A view credits it while its tiles are on the screen.
 *
 * @example
 * ```ts
 * import { GIBS_ID } from "@johnmorrisdotca/chikyu-earth/door";
 *
 * console.log(GIBS_ID);
 * ```
 */
export declare const GIBS_ID = "gibs";
/**
 * How long a tile is given to arrive before the coarser picture is left as it is and the tile is not asked for again while it stays in view.
 *
 * @example
 * ```ts
 * import { GIBS_SLOW_MS } from "@johnmorrisdotca/chikyu-earth/door";
 *
 * console.log(GIBS_SLOW_MS);
 * ```
 */
export declare const GIBS_SLOW_MS = 2000;
/**
 * The acknowledgement NASA asks a client to show, in their words (English, read 2026-11-13). The Japanese is this package's translation of that sentence: NASA published none.
 *
 * @example
 * ```ts
 * import { GIBS_CREDIT } from "@johnmorrisdotca/chikyu-earth/door";
 *
 * console.log(GIBS_CREDIT.en.startsWith("We acknowledge"));
 * ```
 */
export declare const GIBS_CREDIT: {
    readonly en: "We acknowledge the use of imagery provided by services from NASA's Global Imagery Browse Services (GIBS), part of NASA's Earth Science Data and Information System (ESDIS).";
    readonly ja: "NASAの地球科学データ情報システム（ESDIS）の一部である Global Imagery Browse Services（GIBS）が提供する画像を使用していることを記します。";
};
/** A day the layer has imagery, inclusive, as the capabilities document listed it on 2026-11-13. Dates sort as text. */
interface DayRange {
    start: string;
    end: string;
}
interface GibsLayer {
    id: string;
    matrix: "31.25m" | "250m" | "500m";
    /** Empty for a picture that has no day (the shaded relief, and the annual Landsat mosaics, which have `years`). */
    ranges: readonly DayRange[];
    /** True when the picture is one day of the satellite and clouds are left in. */
    clouds: boolean;
    /** For a layer with one picture a year: the years' times, as the service names them (`yyyy-mm-dd`), oldest first. The newest is the one used unless a page names another of them. */
    years?: readonly string[];
    /**
     * For a layer that shows water as nearly black (the Landsat mosaics): the luminance (0 to 255) below which a pixel is clear and from which it is opaque, so the sea is left to the package's blue ocean and the picture is a land picture. Left out, only the black of no data is cleared (`NODATA_BELOW` and `NODATA_FULL`).
     */
    clear?: readonly [number, number];
    /** Multiplies each colour, to bring the picture to the look of the package's own pictures (found by comparing them over land, see NOTICE.md). */
    gain?: readonly [number, number, number];
    /** A sentence about the layer's own data, added to NASA's acknowledgement while its tiles are on the screen. */
    credit?: {
        en: string;
        ja: string;
    };
}
/**
 * The layers a page may ask for. The ranges are the days the capabilities document listed on 2026-11-13; a day outside them is not requested.
 * The two daily layers are true colour with the clouds left in. The shaded relief is the same kind of picture as the package's own level 5, and is only a stand-in.
 */
export declare const GIBS_LAYERS: Readonly<Record<string, GibsLayer>>;
/**
 * The layer a page gets without naming one: the Landsat annual true-colour mosaic (30 m, no cloud, land only; the year 2000, the newest it has). The daily layers are a named choice: `today` for MODIS Terra.
 * A layer id is taken as it is, and these short names stand for two of them.
 */
export declare const GIBS_DEFAULT_LAYER = "Landsat_WELD_CorrectedReflectance_TrueColor_Global_Annual";
/** The short names `tiles-finer-layer` takes besides a layer's own id: `landsat` (the default) and `today` (the daily picture of MODIS Terra, with its clouds). */
export declare const GIBS_NAMES: Readonly<Record<string, string>>;
/** How many days, counting the first, the default rule looks back for a day with imagery. */
export declare const GIBS_LOOKBACK_DAYS = 10;
/**
 * True when every sampled pixel is black, which is the picture the service returns for a day it has no swath for (a 200, not a 404).
 *
 * @param pixels - RGBA bytes.
 * @returns Whether every pixel is black.
 *
 * @example
 * ```ts
 * import { samplesAreBlank } from "@johnmorrisdotca/chikyu-earth/door";
 *
 * console.log(samplesAreBlank(new Uint8ClampedArray([0, 0, 0, 255])));
 * ```
 */
export declare function samplesAreBlank(pixels: Uint8ClampedArray): boolean;
/**
 * The UTC day `yyyy-mm-dd` of a moment.
 *
 * @param ms - Milliseconds since the epoch.
 * @returns The day.
 *
 * @example
 * ```ts
 * import { utcDay } from "@johnmorrisdotca/chikyu-earth/door";
 *
 * console.log(utcDay(Date.UTC(2026, 5, 21, 12)));
 * ```
 */
export declare function utcDay(ms: number): string;
/**
 * The UTC day before `ms`.
 *
 * @param ms - Milliseconds since the epoch.
 * @returns The day before.
 *
 * @example
 * ```ts
 * import { previousUtcDay } from "@johnmorrisdotca/chikyu-earth/door";
 *
 * console.log(previousUtcDay(Date.UTC(2026, 5, 21, 12)));
 * ```
 */
export declare function previousUtcDay(ms: number): string;
/**
 * Whether the layer may have imagery for a day: inside one of the ranges listed on 2026-11-13, or after the last of them (a daily layer goes on growing, and the list does not). A day before the layer's first day, or in a gap the list shows, has none, and is not asked for.
 */
export declare function gibsHasDay(layer: GibsLayer, day: string): boolean;
/** A day the layer can serve for a fixed rule (`latest`, the default, starts at the day before `ms`), or `undefined` when it lands where the layer has no imagery (nothing is requested). */
export declare function gibsDay(layer: GibsLayer, rule: string, ms: number): string | undefined;
/** The days the default rule looks at, newest first: from `start`, back, skipping days the layer is known to lack, until the layer's first day or `GIBS_LOOKBACK_DAYS` days have been counted. */
export declare function gibsCandidates(layer: GibsLayer, start: string): string[];
/** Forget what the default rule has settled (for a page that wants to look again, and for the tests). */
export declare function forgetGibsDays(): void;
/**
 * What `gibsTiles` takes. `time` is the moment the Earth is showing. The day requested is the day before that, unless `date` says otherwise.
 *
 * @example
 * ```ts
 * import type { GibsTilesOptions } from "@johnmorrisdotca/chikyu-earth/door";
 *
 * const options: GibsTilesOptions = { time: () => new Date("2026-06-21T12:00:00Z") };
 * console.log(typeof options.time);
 * ```
 */
export interface GibsTilesOptions extends EarthTilesOptions {
    /** The moment the view is showing. The default day is the UTC day before this. */
    time: () => Date;
    /** A layer id (see `GIBS_LAYERS`). Left out, the MODIS Terra daily true-colour layer. */
    layer?: string;
    /**
     * `latest` (the default): the most recent day with imagery, looked for from the day before `time` back, one tile under the middle of the view a day. `previous-day` (that day alone), `shown` (the UTC day of `time`), or one day `yyyy-mm-dd`.
     */
    date?: string;
    /** Called when the default rule has found its day, so the view draws again and asks for the tiles. */
    changed?: () => void;
    /** How many milliseconds a tile is given to arrive (`GIBS_SLOW_MS`, 2000, when left out). A page on a slow link can give it longer. */
    slowMs?: number;
}
/**
 * Where a tile's luminance (0 to 255) is at or below this, the picture has no data there (the service paints it black) and the loader draws it clear; from `NODATA_FULL` it is opaque, and between the two a share, so the edge of a gap is not a hard
 * black line. A layer may set its own limits (`clear`).
 */
export declare const NODATA_BELOW = 3;
/** The luminance from which a pixel is wholly opaque (see `NODATA_BELOW`). */
export declare const NODATA_FULL = 14;
/**
 * A map source that reads NASA's imagery service directly. It declares its own grid (512 pixel tiles, the Geographic matrix, which is not the package's pyramid). `need` names no tile for a day outside the layer's range.
 * `load` gives a tile two seconds, and treats a 404 or an all-black tile as no imagery. The clouds are not taken out of the daily layers.
 *
 * @param options - The clock, the layer and the day rule, and the `fetch` to use.
 * @returns The source. Its `layer` is `day`. It does not replace the package's own tiles: a view lays it over them, and only when the view is closer than those tiles serve.
 *
 * @example
 * ```ts
 * import { gibsTiles } from "@johnmorrisdotca/chikyu-earth/door";
 *
 * const source = gibsTiles({ time: () => new Date("2026-06-21T12:00:00Z") });
 * console.log(source.need({ lonMin: -1, lonMax: 1, latMin: -1, latMax: 1, layer: "day" }, 50000)[0]);
 * ```
 */
export declare function gibsTiles(options: GibsTilesOptions): EarthMapSource;
/**
 * The finer source an element makes from its attributes, the same object while the attributes are unchanged, or `undefined` when finer tiles are off or the view is limited to the package's own data.
 *
 * @param time - The moment the element is showing.
 * @param changed - Called when the source has found the day it will read, so the element draws again.
 * @returns A reader of the element's attributes.
 *
 * @example
 * ```ts
 * import { createFinerHolder } from "@johnmorrisdotca/chikyu-earth/door";
 *
 * const hold = createFinerHolder(() => new Date("2026-06-21T12:00:00Z"));
 * console.log(hold.source(() => null, false));
 * ```
 */
export declare function createFinerHolder(time: () => Date, changed?: () => void): {
    source(read: (name: string) => string | null, ownOnly: boolean): EarthMapSource | undefined;
};
export {};