Skip to main content

Class: GeoTIFF

Defined in: packages/geotiff/src/geotiff.ts:85

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: packages/geotiff/src/geotiff.ts:105

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


cachedPrimaryImageTags​

readonly cachedPrimaryImageTags: CachedPrimaryImageTags

Defined in: packages/geotiff/src/geotiff.ts:102

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: packages/geotiff/src/geotiff.ts:113

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: packages/geotiff/src/geotiff.ts:128

Parsed GDALMetadata tag, if present.


gkd​

readonly gkd: GeoKeyDirectory

Defined in: packages/geotiff/src/geotiff.ts:125

The GeoKeyDirectory of the primary IFD.


image​

readonly image: TiffImage

Defined in: packages/geotiff/src/geotiff.ts:119

The primary (full-resolution) TiffImage.


maskImage​

readonly maskImage: TiffImage | null

Defined in: packages/geotiff/src/geotiff.ts:122

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


overviews​

readonly overviews: Overview[]

Defined in: packages/geotiff/src/geotiff.ts:92

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: packages/geotiff/src/geotiff.ts:116

The underlying Tiff instance.

Accessors​

bbox​

Get Signature​

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

Defined in: packages/geotiff/src/geotiff.ts:473

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: packages/geotiff/src/geotiff.ts:459

The color interpretation of each band in index order.

Returns​

ColorInterp[]


count​

Get Signature​

get count(): number

Defined in: packages/geotiff/src/geotiff.ts:454

Number of bands (samples per pixel).

Returns​

number


crs​

Get Signature​

get crs(): string | number | ProjJson

Defined in: packages/geotiff/src/geotiff.ts:380

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: packages/geotiff/src/geotiff.ts:393

Image height in pixels.

Returns​

number


isTiled​

Get Signature​

get isTiled(): boolean

Defined in: packages/geotiff/src/geotiff.ts:418

Whether the primary image is tiled.

Returns​

boolean


nodata​

Get Signature​

get nodata(): number | null

Defined in: packages/geotiff/src/geotiff.ts:413

The no data value, or null if not set.

Returns​

number | null


offsets​

Get Signature​

get offsets(): number[]

Defined in: packages/geotiff/src/geotiff.ts:440

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: packages/geotiff/src/geotiff.ts:449

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: packages/geotiff/src/geotiff.ts:430

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: packages/geotiff/src/geotiff.ts:398

The number of tiles in the x and y directions

Returns​

TiffImageTileCount


tileHeight​

Get Signature​

get tileHeight(): number

Defined in: packages/geotiff/src/geotiff.ts:408

Tile height in pixels.

Returns​

number


tileWidth​

Get Signature​

get tileWidth(): number

Defined in: packages/geotiff/src/geotiff.ts:403

Tile width in pixels.

Returns​

number


transform​

Get Signature​

get transform(): Affine

Defined in: packages/geotiff/src/geotiff.ts:489

Return the dataset's georeferencing transformation matrix.

Returns​

Affine


width​

Get Signature​

get width(): number

Defined in: packages/geotiff/src/geotiff.ts:388

Image width in pixels.

Returns​

number

Methods​

fetchTile()​

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

Defined in: packages/geotiff/src/geotiff.ts:511

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 off the main thread, such as the one defaultDecoderPool returns. If not provided, the tile is decoded on the main thread.

signal?​

AbortSignal

An optional AbortSignal to cancel the fetch request.

Returns​

Promise<Tile>


fetchTiles()​

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

Defined in: packages/geotiff/src/geotiff.ts:539

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: packages/geotiff/src/geotiff.ts:584

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.


read()​

read(options?): Promise<RasterArray>

Defined in: packages/geotiff/src/geotiff.ts:567

Read the pixels of a window of the full-resolution image.

Fetches every tile that the window touches, stitches them together, and keeps only the pixels inside the window.

Parameters​

options?​

Optional parameters for reading.

pool?​

DecoderPool

An optional DecoderPool for decoding the tiles off the main thread, such as the one defaultDecoderPool returns. If not provided, the tiles are decoded on the main thread.

signal?​

AbortSignal

An optional AbortSignal to cancel the fetch requests.

window?​

Window

The Window of pixels to read. Defaults to the whole image.

Returns​

Promise<RasterArray>

A RasterArray of the window's pixels, with a mask if the image has a mask IFD.

Throws​

A WindowError if the window is invalid or extends outside the image.


xy()​

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

Defined in: packages/geotiff/src/geotiff.ts:600

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" = "center"

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: packages/geotiff/src/geotiff.ts:321

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: packages/geotiff/src/geotiff.ts:212

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: packages/geotiff/src/geotiff.ts:336

Create a new GeoTIFF from a URL, reading through a RangeReader.

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: packages/geotiff/src/geotiff.ts:175

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. Cache and chunk it: cogeotiff reads offset-table entries one at a time.

signal?​

AbortSignal

An optional AbortSignal to cancel the header reads.

Returns​

Promise<GeoTIFF>