Overview

gdal wraps libgdal — the premier open-source geospatial data library (Geospatial Data Abstraction Library). It provides two subsystems: GDAL for raster I/O (satellite imagery, elevation models, GeoTIFF, HDF5) and OGR for vector I/O (Shapefile, GeoJSON, KML, PostGIS, WFS).

Key capabilities include coordinate reprojection between EPSG codes, WKT, and PROJ strings; raster band arithmetic and warping; vector feature queries and spatial/attribute filters; and in-memory format conversion equivalent to the gdal_translate and ogr2ogr command-line tools.

Comparison

Library	Relationship to gdal
rasterio	Python wrapper around this same libgdal C core; gdal gives you the same access directly from PascalAI without a Python runtime
QGIS	Desktop GIS application that uses GDAL as its data I/O layer; gdal gives you programmatic access to that same I/O without the GUI or processing framework
PostGIS	Stores and queries vector geometry inside PostgreSQL; gdal complements it by handling file-based I/O and coordinate reprojection that PostGIS does not do natively

Quick Start

Read a GeoTIFF and print band statistics

uses gdal;

GDALInit();

var ds := OpenRaster('elevation.tif', 0);
var info := GetRasterInfo(ds);
WriteLn('Size: ' + IntToStr(info.Width) + ' x ' + IntToStr(info.Height));
WriteLn('Bands: ' + IntToStr(info.BandCount));
WriteLn('Projection: ' + info.Projection);

var band := GetBand(ds, 1);
var pixels := ReadBandFloat(band, 0, 0, info.Width, info.Height);
WriteLn('Pixels read: ' + IntToStr(Length(pixels)));

CloseRaster(ds);
FreeRasterInfo(info);
GDALCleanup();

Read vector features from a Shapefile

uses gdal;

GDALInit();

var src := OpenVector('countries.shp', 0);
var layer := GetLayer(src, 0);
SetAttributeFilter(layer, 'POP_EST > 50000000');

var feat := NextFeature(layer);
while feat <> 0 do
begin
  var fi := GetFeatureInfo(feat);
  WriteLn(fi.GeomWKT);
  FreeFeature(feat);
  feat := NextFeature(layer);
end;

CloseVector(src);

Types

type
  { Opaque handles }
  TGDALDataset   = Integer; { raster dataset handle }
  TGDALBand      = Integer; { raster band handle }
  TOGRDataSource = Integer; { vector datasource handle }
  TOGRLayer      = Integer; { vector layer handle }
  TOGRFeature    = Integer; { vector feature handle }
  TOGRGeometry   = Integer; { geometry handle }

  { Raster dataset metadata }
  TGDALInfo = record
    Width      : Integer;  { raster width in pixels }
    Height     : Integer;  { raster height in pixels }
    BandCount  : Integer;  { number of bands }
    Projection : String;   { WKT projection string }
    GeoTransX  : Double;   { top-left X coordinate }
    GeoTransY  : Double;   { top-left Y coordinate }
    PixelSizeX : Double;   { pixel width in projection units }
    PixelSizeY : Double;   { pixel height (negative = north-up) }
    DataType   : Integer;  { GDALDataType enum value }
    DriverName : String;   { e.g. 'GTiff', 'HDF5', 'netCDF' }
  end;

  { Vector feature metadata }
  TOGRFeatureInfo = record
    FID        : Integer;  { feature ID }
    GeomWKT    : String;   { geometry as WKT string }
    FieldNames : String;   { comma-separated field names }
    FieldValues: String;   { tab-separated field values }
  end;

  { Vector layer metadata }
  TOGRLayerInfo = record
    Name        : String;  { layer name }
    FeatureCount: Integer; { total features (-1 if unknown) }
    GeomType    : Integer; { OGRwkbGeometryType enum value }
    SRS         : String;  { spatial reference as WKT }
  end;

Initialization

Call GDALInit once at program start to register all built-in format drivers. Call GDALCleanup before exit to release driver resources.

Function	Description
GDALInit()	Register all GDAL/OGR format drivers. Must be called before any other GDAL function.
GDALCleanup()	Destroy all drivers and release global resources. Call at program exit.
GDALVersion()	Returns the GDAL version string, e.g. 'GDAL 3.6.2, released 2023/01/05'

function GDALInit(): Boolean;
  external 'libpai_gdal.so' name 'pai_gdal_init';

function GDALCleanup(): Boolean;
  external 'libpai_gdal.so' name 'pai_gdal_cleanup';

function GDALVersion(): String;
  external 'libpai_gdal.so' name 'pai_gdal_version';

Raster Open / Create

Open existing raster files or create new ones. The access parameter is 0 for read-only and 1 for read/write.

Function	Description
OpenRaster(path, access)	Open a raster file. Returns a TGDALDataset handle, or 0 on failure.
CreateRaster(path, driver, width, height, bands, dataType)	Create a new raster file using the named driver (e.g. 'GTiff'). Returns a writable dataset handle.
GetRasterInfo(ds)	Return a TGDALInfo record with size, band count, projection, geotransform, and driver name.
GetBand(ds, bandIndex)	Return a handle to the Nth band (1-based). Use for reading or writing pixel data.

function OpenRaster(path: String; access: Integer): TGDALDataset;
  external 'libpai_gdal.so' name 'pai_gdal_open_raster';

function CreateRaster(path, driver: String; width, height, bands, dataType: Integer): TGDALDataset;
  external 'libpai_gdal.so' name 'pai_gdal_create_raster';

function GetRasterInfo(ds: TGDALDataset): TGDALInfo;
  external 'libpai_gdal.so' name 'pai_gdal_get_raster_info';

function GetBand(ds: TGDALDataset; bandIndex: Integer): TGDALBand;
  external 'libpai_gdal.so' name 'pai_gdal_get_band';

Raster Read / Write

Read pixel data as floating-point arrays or RGBA byte arrays. Write float arrays back to a band. Window reads allow efficient sub-region extraction.

Function	Description
ReadBandFloat(band, xOff, yOff, width, height)	Read the entire requested window as a flat array of Double in row-major order.
ReadBandWindow(band, xOff, yOff, srcW, srcH, dstW, dstH)	Read a source window and resample to dstW × dstH (decimation or zoom).
ReadRGBA(ds, xOff, yOff, width, height)	Read the dataset as an interleaved RGBA byte array (4 bytes per pixel).
WriteBandFloat(band, xOff, yOff, width, height, data)	Write a flat array of Double into the band window. Dataset must be open read/write.

function ReadBandFloat(band: TGDALBand; xOff, yOff, width, height: Integer): array of Double;
  external 'libpai_gdal.so' name 'pai_gdal_read_band_float';

function ReadBandWindow(band: TGDALBand; xOff, yOff, srcW, srcH, dstW, dstH: Integer): array of Double;
  external 'libpai_gdal.so' name 'pai_gdal_read_band_window';

function ReadRGBA(ds: TGDALDataset; xOff, yOff, width, height: Integer): array of Byte;
  external 'libpai_gdal.so' name 'pai_gdal_read_rgba';

function WriteBandFloat(band: TGDALBand; xOff, yOff, width, height: Integer; data: array of Double): Boolean;
  external 'libpai_gdal.so' name 'pai_gdal_write_band_float';

Raster Transform

Reproject or convert raster files. WarpRaster reprojects to a target SRS in one call; TranslateRaster converts between formats.

Function	Description
WarpRaster(srcPath, dstPath, dstSRS)	Reproject srcPath to dstSRS (EPSG code, WKT, or PROJ string) and write the result to dstPath.
TranslateRaster(srcPath, dstPath, driver, options)	Convert a raster to a different format. driver is e.g. 'GTiff', 'PNG'. options is a space-separated creation options string.

function WarpRaster(srcPath, dstPath, dstSRS: String): Boolean;
  external 'libpai_gdal.so' name 'pai_gdal_warp_raster';

function TranslateRaster(srcPath, dstPath, driver, options: String): Boolean;
  external 'libpai_gdal.so' name 'pai_gdal_translate_raster';

Reproject a GeoTIFF from WGS84 to Web Mercator

uses gdal;

GDALInit();
WarpRaster('dem_wgs84.tif', 'dem_webmerc.tif', 'EPSG:3857');
WriteLn('Reprojected to Web Mercator');
GDALCleanup();

Raster Close / Free

Function	Description
CloseRaster(ds)	Flush pending writes and close the dataset, releasing its file handle.
FreeRasterInfo(info)	Release memory allocated for a TGDALInfo record returned by GetRasterInfo.

procedure CloseRaster(ds: TGDALDataset);
  external 'libpai_gdal.so' name 'pai_gdal_close_raster';

procedure FreeRasterInfo(var info: TGDALInfo);
  external 'libpai_gdal.so' name 'pai_gdal_free_raster_info';

Vector Open / Query

Open vector datasources and iterate over features. Use SetSpatialFilter or SetAttributeFilter to limit the feature set before calling NextFeature.

Function	Description
OpenVector(path, access)	Open a vector datasource. access: 0=read-only, 1=update. Returns 0 on failure.
LayerCount(src)	Return the number of layers in the datasource.
GetLayer(src, index)	Return the layer handle at the given 0-based index.
NextFeature(layer)	Return the next feature handle in the layer iteration. Returns 0 when exhausted.
GetFeatureInfo(feat)	Return a TOGRFeatureInfo with FID, WKT geometry, and field names/values.
SetSpatialFilter(layer, wkt)	Restrict iteration to features whose geometry intersects the WKT envelope or polygon.
SetAttributeFilter(layer, sql)	Restrict iteration using a SQL WHERE clause, e.g. 'population > 1000000'.
FreeFeature(feat)	Release the feature handle returned by NextFeature.

function OpenVector(path: String; access: Integer): TOGRDataSource;
  external 'libpai_gdal.so' name 'pai_gdal_open_vector';

function LayerCount(src: TOGRDataSource): Integer;
  external 'libpai_gdal.so' name 'pai_gdal_layer_count';

function GetLayer(src: TOGRDataSource; index: Integer): TOGRLayer;
  external 'libpai_gdal.so' name 'pai_gdal_get_layer';

function NextFeature(layer: TOGRLayer): TOGRFeature;
  external 'libpai_gdal.so' name 'pai_gdal_next_feature';

function GetFeatureInfo(feat: TOGRFeature): TOGRFeatureInfo;
  external 'libpai_gdal.so' name 'pai_gdal_get_feature_info';

function SetSpatialFilter(layer: TOGRLayer; wkt: String): Boolean;
  external 'libpai_gdal.so' name 'pai_gdal_set_spatial_filter';

function SetAttributeFilter(layer: TOGRLayer; sql: String): Boolean;
  external 'libpai_gdal.so' name 'pai_gdal_set_attribute_filter';

procedure FreeFeature(feat: TOGRFeature);
  external 'libpai_gdal.so' name 'pai_gdal_free_feature';

Vector Write

Create new vector datasources, add layers, and write features as WKT geometry strings.

Function	Description
CreateVectorDS(path, driver)	Create a new vector datasource. driver is e.g. 'GeoJSON', 'ESRI Shapefile', 'KML'.
CreateLayer(src, name, srs, geomType)	Add a new layer to the datasource. srs is a WKT or EPSG string; geomType is an OGR geometry type integer.
CreateFeatureWKT(layer, wkt, fieldData)	Append a feature to a layer. wkt is the geometry; fieldData is a tab-separated list of name=value pairs.

function CreateVectorDS(path, driver: String): TOGRDataSource;
  external 'libpai_gdal.so' name 'pai_gdal_create_vector_ds';

function CreateLayer(src: TOGRDataSource; name, srs: String; geomType: Integer): TOGRLayer;
  external 'libpai_gdal.so' name 'pai_gdal_create_layer';

function CreateFeatureWKT(layer: TOGRLayer; wkt, fieldData: String): Boolean;
  external 'libpai_gdal.so' name 'pai_gdal_create_feature_wkt';

Write a GeoJSON point file

uses gdal;

GDALInit();

var ds := CreateVectorDS('cities.geojson', 'GeoJSON');
var layer := CreateLayer(ds, 'cities', 'EPSG:4326', 1); { 1 = wkbPoint }

CreateFeatureWKT(layer, 'POINT(-43.1729 -22.9068)', 'name=Rio de Janeiro'#9'pop=6748000');
CreateFeatureWKT(layer, 'POINT(-46.6333 -23.5505)', 'name=Sao Paulo'#9'pop=12325232');

CloseVector(ds);
WriteLn('cities.geojson written');
GDALCleanup();

Vector Transform / Close

Function	Description
TranslateVector(srcPath, dstPath, driver, options)	Convert a vector datasource to a different format (ogr2ogr equivalent). options is a space-separated string of OGR creation options.
CloseVector(src)	Flush writes and close the datasource, releasing all layer and feature handles.

function TranslateVector(srcPath, dstPath, driver, options: String): Boolean;
  external 'libpai_gdal.so' name 'pai_gdal_translate_vector';

procedure CloseVector(src: TOGRDataSource);
  external 'libpai_gdal.so' name 'pai_gdal_close_vector';