import type { BitmapLike, ImageTile, MapPlace, TileSource } from "../data-door.ts";
import { type TileId, type TileLayer } from "../realistic/tiles.ts";
import type { MapGrid } from "./grid.ts";
/**
 * What a map source draws: `day` and `night` are the Earth's pictures, which the realistic Earth lays tiles over; `clouds` and `water` are the door's for the whole-Earth layers they are, which the package does not tile or draw yet.
 *
 * @example
 * ```ts
 * import type { MapLayer } from "@johnmorrisdotca/chikyu-earth/door";
 *
 * const layers: MapLayer[] = ["day", "night", "clouds", "water"];
 * console.log(layers.join(", "));
 * ```
 */
export type MapLayer = "day" | "night" | "clouds" | "water";
/**
 * The place a map source is asked about: the family's `MapPlace` in degrees (longitude from `lonMin` to `lonMax`, which may pass 180 and is at most a whole turn, latitude from `latMin` to `latMax`), and the layer it is for.
 *
 * @example
 * ```ts
 * import type { EarthMapPlace } from "@johnmorrisdotca/chikyu-earth/door";
 *
 * const place: EarthMapPlace = { lonMin: 170, lonMax: 190, latMin: -10, latMax: 10, layer: "day" };
 * console.log(place.layer);
 * ```
 */
export type EarthMapPlace = MapPlace & {
    layer?: string;
};
/**
 * A source of the Earth's map in tiles for one layer (or every layer of a folder): a `TileSource` of the family's map shape (the place is a `MapPlace`, the detail is the pixels across the whole circumference, a tile is an
 * `ImageTile`) that says which `layer` it is for. A `layer` of `"*"` is every layer of a folder (the place then names the one, in `place.layer`, and the keys start with its name). The keys a source returns end in
 * `level/column/row` on the package's pyramid. `levels` says which levels the source has when that has to be asked (a folder's manifest); left out, levels 3 and 4.
 *
 * @example
 * ```ts
 * import type { EarthMapSource } from "@johnmorrisdotca/chikyu-earth/door";
 *
 * const layers = (sources: readonly EarthMapSource[]): string[] => sources.map((source) => source.layer);
 * console.log(layers([]));
 * ```
 */
export type EarthMapSource = TileSource<EarthMapPlace, number, ImageTile> & {
    layer: MapLayer | "*";
    levels?(layer: string, signal: AbortSignal): TileLayer | undefined | Promise<TileLayer | undefined>;
    /**
     * The source's own grid, when it is not the package's pyramid (`2^(L+1)` columns by `2^L` rows). The loader places tiles from this. Left out, the pyramid is unchanged.
     */
    grid?: MapGrid;
    /** True when the source's tiles may have transparent pixels (a place it has no data for), so the loader draws them blended and the picture underneath shows through. */
    holes?: boolean;
    /**
     * How the loader draws this source's tiles, on the graphics card: `clear` is the luminance (0 to 255) at or below which a pixel is wholly transparent and from which it is wholly opaque, and `gain` multiplies each colour. Left out, tiles are drawn as they are.
     */
    look?: {
        clear: readonly [number, number];
        gain?: readonly [number, number, number];
    };
};
/**
 * The levels a source has when it does not say: levels 3 and 4 (8192 and 16384 pixels across), the two the package's cutter makes beyond its own 4096 pixel picture.
 *
 * @example
 * ```ts
 * import { DEFAULT_LEVELS } from "@johnmorrisdotca/chikyu-earth/door";
 *
 * console.log(DEFAULT_LEVELS.levels.map((level) => level.width));
 * ```
 */
export declare const DEFAULT_LEVELS: TileLayer;
/**
 * The level, column and row a tile key ends in, or `undefined` for a key that does not end in three numbers.
 *
 * @param key - The tile's key.
 * @returns Where the tile is in the pyramid, or `undefined` for a key that does not end in three numbers.
 *
 * @example
 * ```ts
 * import { tileKeyParts } from "@johnmorrisdotca/chikyu-earth/door";
 *
 * console.log(tileKeyParts("day/3/12/5"));
 * ```
 */
export declare function tileKeyParts(key: string): TileId | undefined;
/**
 * The place a tile covers, in degrees: what a view asks a source about to get that tile's key.
 *
 * @param tile - A tile of the pyramid.
 * @returns The tile's longitude and latitude bounds.
 *
 * @example
 * ```ts
 * import { tilePlace } from "@johnmorrisdotca/chikyu-earth/door";
 *
 * console.log(tilePlace({ level: 3, col: 0, row: 0 }));
 * ```
 */
export declare function tilePlace(tile: TileId): MapPlace;
/**
 * The keys of the tiles that cover a place at a detail, on the package's pyramid: the level is the lowest whose width is at least `detail` pixels round (or the finest there is), and the tiles are every one the place touches.
 * Pure. A source of your own can build its `need` on it.
 *
 * @param place - The part of the map, in degrees.
 * @param detail - The pixels across the whole circumference wanted.
 * @param layer - The levels the source has; `DEFAULT_LEVELS` where left out.
 * @param prefix - Put before each key (`"day/"`), for a folder of several layers.
 * @returns The keys, `[<prefix>]level/column/row`, row by row; none for a place with no area.
 *
 * @example
 * ```ts
 * import { mapKeys } from "@johnmorrisdotca/chikyu-earth/door";
 *
 * console.log(mapKeys({ lonMin: -10, lonMax: 10, latMin: -5, latMax: 5 }, 8192));
 * ```
 */
export declare function mapKeys(place: MapPlace, detail: number, layer?: TileLayer, prefix?: string): string[];
/**
 * What `earthTiles` takes.
 *
 * @example
 * ```ts
 * import type { EarthTilesOptions } from "@johnmorrisdotca/chikyu-earth/door";
 *
 * const options: EarthTilesOptions = { fetch: (url, init) => fetch(url, init) };
 * console.log(typeof options.fetch);
 * ```
 */
export interface EarthTilesOptions {
    /** The `fetch` to use: the global one where left out. It is called as `fetch(address, { mode: "cors", signal })`. */
    fetch?: (url: string, init?: RequestInit) => Promise<Response>;
    /** Makes a picture of a tile's bytes: `createImageBitmap` where left out. */
    decode?: (blob: Blob) => Promise<BitmapLike>;
}
/**
 * What a decoded picture holds in memory, with its mipmaps (4/3 of its bytes): the `bytes` of a map source.
 *
 * @param tile - The tile.
 * @returns Bytes.
 *
 * @example
 * ```ts
 * import { imageBytes } from "@johnmorrisdotca/chikyu-earth/door";
 *
 * console.log(imageBytes({ width: 512, height: 512, image: { width: 512, height: 512 } }));
 * ```
 */
export declare function imageBytes(tile: ImageTile): number;
/**
 * The package's own finer map tiles as a source: a folder with a `manifest.json` and a tile for each layer, level and place at `<layer>/<level>/<column>/<row>.webp` (made by `scripts/make-earth-tiles.py`). This is what the `tiles`
 * attribute of `<chikyu-earth-realistic>` means, and what the Earth is drawn from where no source of yours covers a layer. It is for every layer in the folder (`layer: "*"`); the manifest says which levels each has, and it is read once
 * for the source, only when a view first wants more than the 4096 pixel picture. Its `id` is `chikyu-tiles`, and a view counts it as the package's own data.
 *
 * @param base - The folder's address, with or without the closing slash.
 * @param options - The `fetch` and the decoder to use.
 * @returns The source.
 *
 * @example
 * ```ts no-run
 * import { earthTiles } from "@johnmorrisdotca/chikyu-earth/door";
 *
 * const mine = earthTiles("/tiles/");
 * console.log(mine.need({ lonMin: 0, lonMax: 20, latMin: 0, latMax: 10, layer: "day" }, 8192));
 * ```
 */
export declare function earthTiles(base: string, options?: EarthTilesOptions): EarthMapSource;
/**
 * The folder source of an address, the same object each time: what an element makes of its `tiles` attribute, so that two elements on a page with the same folder share one source and its pictures.
 *
 * @param base - The folder's address.
 * @returns The source `earthTiles` makes for it.
 *
 * @example
 * ```ts no-run
 * import { folderSource } from "@johnmorrisdotca/chikyu-earth/door";
 *
 * console.log(folderSource("/tiles/") === folderSource("/tiles/"));
 * ```
 */
export declare function folderSource(base: string): EarthMapSource;