Class: GeoTIFF

Defined in: geotiff.ts:66

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

cachedTags

readonly cachedTags: CachedTags

Defined in: geotiff.ts:79

Cached TIFF tags that are pre-fetched when opening the GeoTIFF.

---

dataSource

readonly dataSource: Pick<Source, "fetch">

Defined in: geotiff.ts:87

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:102

Parsed GDALMetadata tag, if present.

---

gkd

readonly gkd: GeoKeyDirectory

Defined in: geotiff.ts:99

The GeoKeyDirectory of the primary IFD.

---

image

readonly image: TiffImage

Defined in: geotiff.ts:93

The primary (full-resolution) TiffImage.

---

maskImage

readonly maskImage: TiffImage | null

Defined in: geotiff.ts:96

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

---

overviews

readonly overviews: Overview[]

Defined in: geotiff.ts:73

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:90

The underlying Tiff instance.

Accessors

bbox

Get Signature

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

Defined in: geotiff.ts:451

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

Returns

[number, number, number, number]

---

count

Get Signature

get count(): number

Defined in: geotiff.ts:446

Number of bands (samples per pixel).

Returns

number

---

crs

Get Signature

get crs(): string | number | ProjJson

Defined in: geotiff.ts:372

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:385

Image height in pixels.

Returns

number

---

isTiled

Get Signature

get isTiled(): boolean

Defined in: geotiff.ts:410

Whether the primary image is tiled.

Returns

boolean

---

nodata

Get Signature

get nodata(): number | null

Defined in: geotiff.ts:405

The no data value, or null if not set.

Returns

number | null

---

offsets

Get Signature

get offsets(): number[]

Defined in: geotiff.ts:432

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:441

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:422

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:390

The number of tiles in the x and y directions

Returns

TiffImageTileCount

---

tileHeight

Get Signature

get tileHeight(): number

Defined in: geotiff.ts:400

Tile height in pixels.

Returns

number

---

tileWidth

Get Signature

get tileWidth(): number

Defined in: geotiff.ts:395

Tile width in pixels.

Returns

number

---

transform

Get Signature

get transform(): Affine

Defined in: geotiff.ts:458

Return the dataset's georeferencing transformation matrix.

Returns

Affine

---

width

Get Signature

get width(): number

Defined in: geotiff.ts:380

Image width in pixels.

Returns

number

Methods

fetchTile()

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

Defined in: geotiff.ts:480

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:504

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:526

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:542

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:280

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:184

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:301

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:147

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>