ConceptsGeoRawImage

GeoRawImage

Georeferenced image data structure for geospatial AI processing

The GeoRawImage class extends the Hugging Face RawImage class to provide georeferencing capabilities essential for geospatial AI tasks. It maintains spatial context by storing coordinate reference system (CRS) information and geographic bounds, enabling seamless conversion between pixel and world coordinates.

Class Structure

class GeoRawImage extends RawImage {
  // Core image properties (inherited from RawImage)
  data: Uint8ClampedArray | Uint8Array;
  width: number;
  height: number;
  channels: 1 | 2 | 3 | 4;
 
  // Georeferencing properties
  private bounds: Bounds;
  private transform: Transform;
  private crs: string;
}

Constructor

new GeoRawImage(
  data: Uint8ClampedArray | Uint8Array,
  width: number,
  height: number,
  channels: 1 | 2 | 3 | 4,
  bounds: Bounds,
  crs?: string
)

Parameters

ParameterTypeDescription
dataUint8ClampedArray | Uint8ArrayRaw image pixel data
widthnumberImage width in pixels
heightnumberImage height in pixels
channels1 | 2 | 3 | 4Number of color channels
boundsBoundsGeographic bounds of the image
crsstringCoordinate reference system (default: “EPSG:4326”)

Bounds Interface

interface Bounds {
  north: number; // max latitude
  south: number; // min latitude
  east: number; // max longitude
  west: number; // min longitude
}

Transform Interface

interface Transform {
  // Affine transformation matrix components
  a: number; // x scale
  b: number; // y skew
  c: number; // x offset
  d: number; // x skew
  e: number; // y scale
  f: number; // y offset
}

Methods

Coordinate Conversion

pixelToWorld(x: number, y: number): [number, number]

Converts pixel coordinates to geographic coordinates (longitude, latitude).

const geoImage = new GeoRawImage(data, 512, 512, 3, bounds);
const [longitude, latitude] = geoImage.pixelToWorld(256, 256);
console.log(`Center coordinates: ${longitude}, ${latitude}`);

worldToPixel(lon: number, lat: number): [number, number]

Converts geographic coordinates to pixel coordinates.

const [x, y] = geoImage.worldToPixel(-122.4194, 37.7749);
console.log(`San Francisco pixel coordinates: ${x}, ${y}`);

Information Retrieval

getBounds(): Bounds

Returns a copy of the image’s geographic bounds.

const bounds = geoImage.getBounds();
console.log(`Image covers: ${bounds.west} to ${bounds.east} longitude`);

getCRS(): string

Returns the coordinate reference system identifier.

const crs = geoImage.getCRS();
console.log(`CRS: ${crs}`); // "EPSG:4326"

Image Operations

clone(): GeoRawImage

Creates a deep copy of the GeoRawImage, preserving all georeferencing information.

const originalImage = new GeoRawImage(data, 512, 512, 3, bounds);
const clonedImage = originalImage.clone();
 
// Both images have identical properties but separate data
console.log(clonedImage.getBounds()); // Same bounds as original
console.log(clonedImage.data !== originalImage.data); // true

Static Methods

fromRawImage(rawImage: RawImage, bounds: Bounds, crs?: string): GeoRawImage

Creates a GeoRawImage from an existing RawImage and georeferencing information.

import { RawImage } from "@huggingface/transformers";
 
const rawImage = new RawImage(data, width, height, channels);
const bounds = {
  north: 37.7849,
  south: 37.7649,
  east: -122.4094,
  west: -122.4294,
};
 
const geoImage = GeoRawImage.fromRawImage(rawImage, bounds);

Inherited Methods

As an extension of RawImage, GeoRawImage inherits all standard image processing methods:

Tensor Conversion

// Convert to tensor for AI model input
const tensor = geoImage.toTensor("CHW"); // Channels-Height-Width format

Image Saving

// Save image
await geoImage.save("debug_image.png");

Image Resizing

// Resize while maintaining georeferencing
const resized = geoImage.resize(256, 256);

Integration with AI Tasks

All AI tasks in @geobase-js/geoai.js return results that include a GeoRawImage:

interface ObjectDetectionResults {
  detections: GeoJSON.FeatureCollection;
  geoRawImage: GeoRawImage;
}
ConceptsModel Pipeline