Class: GeoTIFF

Defined in: geotiff.ts:78

A high-level GeoTIFF abstraction built on @cogeotiff/core's Tiff and TiffImage classes.

This class separates data IFDs from mask IFDs, pairs them by resolution level, and exposes sorted overviews. Intentionally mirrors the Python async-geotiff API as closely as possible.

Construct via GeoTIFF.fromUrl, GeoTIFF.fromArrayBuffer, GeoTIFF.open or GeoTIFF.fromTiff.

See

Overview for reduced-resolution overview images.

Properties

cachedMaskImageTags

readonly cachedMaskImageTags: CachedSubImageTags | null

Defined in: geotiff.ts:98

Cached TIFF tags of maskImage, or null if there's no mask.

---

cachedPrimaryImageTags

readonly cachedPrimaryImageTags: CachedPrimaryImageTags

Defined in: geotiff.ts:95

Cached TIFF tags of the primary image, pre-fetched when opening the GeoTIFF. The overviews use these too, except for their own CachedSubImageTags.

---

dataSource

readonly dataSource: Pick<Source, "fetch">

Defined in: geotiff.ts:106

The data source used for fetching tile data.

This is typically the raw source (e.g. HTTP or memory) rather than a layered source with caching and chunking, to avoid unnecessary copying of tile data through cache layers.

---

gdalMetadata

readonly gdalMetadata: GDALMetadata | null

Defined in: geotiff.ts:121

Parsed GDALMetadata tag, if present.

---

gkd

readonly gkd: GeoKeyDirectory

Defined in: geotiff.ts:118

The GeoKeyDirectory of the primary IFD.

---

image

readonly image: TiffImage

Defined in: geotiff.ts:112

The primary (full-resolution) TiffImage.

---

maskImage

readonly maskImage: TiffImage | null

Defined in: geotiff.ts:115

The mask IFD of the full-resolution GeoTIFF, if any.

---

overviews

readonly overviews: Overview[]

Defined in: geotiff.ts:85

Reduced-resolution overview levels, sorted finest-to-coarsest.

Does not include the full-resolution image — use fetchTile on the GeoTIFF instance itself for that.

---

tiff

readonly tiff: Tiff

Defined in: geotiff.ts:109

The underlying Tiff instance.

Accessors

bbox

Get Signature

get bbox(): [number, number, number, number]

Defined in: geotiff.ts:499

Bounding box [minX, minY, maxX, maxY] in the CRS.

The box around the image's four corners, so it holds the whole image when GeoTIFF.transform is rotated or skewed.

Returns

[number, number, number, number]

---

colorInterp

Get Signature

get colorInterp(): ColorInterp[]

Defined in: geotiff.ts:485

The color interpretation of each band in index order.

Returns

ColorInterp[]

---

count

Get Signature

get count(): number

Defined in: geotiff.ts:480

Number of bands (samples per pixel).

Returns

number

---

crs

Get Signature

get crs(): string | number | ProjJson

Defined in: geotiff.ts:406

Coordinate reference system information.

• If crs is a number, it is an EPSG code.
• If crs is an object, it is a PROJJSON object.
• If crs is a string, it is an ESRI WKT (this is rare).

The result is cached after the first access.

Returns

string | number | ProjJson

---

height

Get Signature

get height(): number

Defined in: geotiff.ts:419

Image height in pixels.

Returns

number

---

isTiled

Get Signature

get isTiled(): boolean

Defined in: geotiff.ts:444

Whether the primary image is tiled.

Returns

boolean

---

nodata

Get Signature

get nodata(): number | null

Defined in: geotiff.ts:439

The no data value, or null if not set.

Returns

number | null

---

offsets

Get Signature

get offsets(): number[]

Defined in: geotiff.ts:466

The offset for each band (0-indexed), defaulting to 0.

Extracted from the GDALMetadata TIFF tag.

Returns

number[]

---

scales

Get Signature

get scales(): number[]

Defined in: geotiff.ts:475

The scale for each band (0-indexed), defaulting to 1.

Extracted from the GDALMetadata TIFF tag.

Returns

number[]

---

storedStats

Get Signature

get storedStats(): ReadonlyMap<number, BandStatistics> | null

Defined in: geotiff.ts:456

The pre-existing statistics for each band, if available.

Extracted from the GDALMetadata TIFF tag; never computed on demand. Keys are 1-based band indices to match GDAL's convention.

Returns null if no statistics are stored in the file.

Returns

ReadonlyMap<number, BandStatistics> | null

---

tileCount

Get Signature

get tileCount(): TiffImageTileCount

Defined in: geotiff.ts:424

The number of tiles in the x and y directions

Returns

TiffImageTileCount

---

tileHeight

Get Signature

get tileHeight(): number

Defined in: geotiff.ts:434

Tile height in pixels.

Returns

number

---

tileWidth

Get Signature

get tileWidth(): number

Defined in: geotiff.ts:429

Tile width in pixels.

Returns

number

---

transform

Get Signature

get transform(): Affine

Defined in: geotiff.ts:515

Return the dataset's georeferencing transformation matrix.

Returns

Affine

---

width

Get Signature

get width(): number

Defined in: geotiff.ts:414

Image width in pixels.

Returns

number

Methods

fetchTile()

fetchTile(x, y, options?): Promise<Tile>

Defined in: geotiff.ts:537

Fetch a single tile from the full-resolution image.

Parameters

x

number

The tile column index (0-based).

y

number

The tile row index (0-based).

options?

Optional parameters for fetching the tile.

boundless?

boolean

Whether to clip tiles that are partially outside the image bounds. When true, no clipping is applied and edge tiles are returned at the full nominal tile size. Defaults to true.

pool?

DecoderPool

An optional DecoderPool for decoding the tile data. If not provided, a new decoder will be created for each tile.

signal?

AbortSignal

An optional AbortSignal to cancel the fetch request.

Returns

Promise<Tile>

---

fetchTiles()

fetchTiles(xy, options?): Promise<Tile[]>

Defined in: geotiff.ts:565

Fetch multiple tiles in parallel.

A future implementation may coalesce contiguous byte ranges to reduce the number of HTTP requests.

Parameters

xy

[number, number][]

Array of [x, y] tile coordinates.

options?

Optional parameters (same as fetchTile).

boundless?

boolean

pool?

DecoderPool

signal?

AbortSignal

Returns

Promise<Tile[]>

Array of Tile objects in the same order as xy.

See

fetchTile for single-tile fetching.

---

index()

index(x, y, op?): [number, number]

Defined in: geotiff.ts:591

Get the (row, col) pixel index containing the geographic coordinate (x, y).

Parameters

x

number

x coordinate in the CRS.

y

number

y coordinate in the CRS.

op?

(n) => number

Rounding function applied to fractional pixel indices. Defaults to Math.floor.

Returns

[number, number]

[row, col] pixel indices.

---

xy()

xy(row, col, offset?): [number, number]

Defined in: geotiff.ts:607

Get the geographic (x, y) coordinate of the pixel at (row, col).

Parameters

row

number

Pixel row.

col

number

Pixel column.

offset?

"center" | "ul" | "ur" | "ll" | "lr"

Which part of the pixel to return. Defaults to "center".

Returns

[number, number]

[x, y] in the CRS.

---

fromArrayBuffer()

static fromArrayBuffer(input): Promise<GeoTIFF>

Defined in: geotiff.ts:314

Create a GeoTIFF from an ArrayBuffer containing the entire file.

This is a convenience method that wraps the ArrayBuffer in a memory source and calls GeoTIFF.open. For large files, consider using GeoTIFF.fromUrl or GeoTIFF.open with a chunked HTTP source to avoid loading the entire file into memory at once.

Parameters

input

ArrayBuffer

The ArrayBuffer containing the GeoTIFF file data.

Returns

Promise<GeoTIFF>

A Promise that resolves to a GeoTIFF instance.

---

fromTiff()

static fromTiff(tiff, dataSource, options?): Promise<GeoTIFF>

Defined in: geotiff.ts:205

Create a GeoTIFF from an already-initialised Tiff instance.

All IFDs are walked; mask IFDs are matched to data IFDs by matching (width, height). Overviews are sorted from finest to coarsest resolution.

Parameters

tiff

Tiff

dataSource

Pick<Source, "fetch">

A source for fetching tile data. This is separate from the source used to construct the TIFF to allow for separate caching implementations.

options?

debug?

boolean

When true, the returned GeoTIFF logs each tile/mask data fetch to the console.

signal?

AbortSignal

An optional AbortSignal to cancel header tag reads.

Returns

Promise<GeoTIFF>

---

fromUrl()

static fromUrl(url, options?): Promise<GeoTIFF>

Defined in: geotiff.ts:335

Create a new GeoTIFF from a URL.

Wraps the HTTP source with a fixed-size block-aligned LRU cache tuned for TIFF metadata. cogeotiff's lazy per-entry reads (for tile offsets, byte counts, and other tag values) are served by the block cache; adjacent entries within a single block hit one underlying request. Tile data reads bypass the cache and go straight to the raw HTTP source.

Parameters

url

string | URL

The URL of the GeoTIFF to open.

options?

GeoTIFFFromUrlOptions = {}

Optional parameters; see GeoTIFFFromUrlOptions.

Returns

Promise<GeoTIFF>

A Promise that resolves to a GeoTIFF instance.

---

open()

static open(options): Promise<GeoTIFF>

Defined in: geotiff.ts:168

Open a GeoTIFF from a @cogeotiff/core Source.

This creates and initialises the underlying Tiff, then classifies IFDs.

Parameters

options

dataSource

Pick<Source, "fetch">

A source for fetching tile data. This is separate from the source used to construct the TIFF to allow for separate caching implementations.

debug?

boolean

When true, the returned GeoTIFF logs each tile/mask data fetch to the console. Off by default.

headerSource

Source

The source used to construct the TIFF. This is typically a layered source with caching and chunking, to optimise access to TIFF tags and IFDs. Callers who want to control the initial read size should compose a SourceChunk of the desired block size; cogeotiff's default defaultReadSize (16 KiB) gets padded up by the chunking layer anyway.

signal?

AbortSignal

An optional AbortSignal to cancel the header reads.

Returns

Promise<GeoTIFF>