gdal_dart 0.2.4

Dart FFI package for raster and vector geodata based on GDAL.

gdal_dart

Dart-FFI-Paket für Raster- und Vektor-Geodaten auf Basis von GDAL.

Lesen, Schreiben und Abfragen von GeoTIFF-Dateien sowie Lesen von Vektor-Formaten (GeoJSON, GeoPackage, Shapefile) aus Dart — typisiert, mit klar gekapselter nativer Schicht.

Voraussetzungen

GDAL muss als Shared Library auf dem System installiert sein:

Plattform	Paket / Befehl
Debian / Ubuntu	sudo apt-get install gdal-bin libgdal-dev
macOS (Homebrew)	brew install gdal
Windows	GDAL-Binaries von gisinternals.com oder OSGeo4W

Alternativ kann der mitgelieferte Dockerfile für eine reproduzierbare Umgebung genutzt werden.

Die Library wird automatisch über den Plattform-Standardnamen geladen (libgdal.so, libgdal.dylib, gdal.dll). Über die Umgebungsvariable GDAL_LIBRARY_PATH oder den Parameter libraryPath kann ein expliziter Pfad angegeben werden.

Quick Start

import 'package:gdal_dart/gdal_dart.dart';

void main() {
  final gdal = Gdal();

  // --- Lesen ---
  final dataset = gdal.openGeoTiff('input.tif');
  print('${dataset.width} x ${dataset.height}, ${dataset.bandCount} Bänder');
  print('CRS: ${dataset.spatialReference.authorityCode}');

  final band = dataset.band(1);
  final pixels = band.readAsUint8();
  print('Erster Pixel: ${pixels[0]}');
  dataset.close();

  // --- Koordinatentransformation ---
  final wgs84 = gdal.spatialReferenceFromEpsg(4326);
  final utm32 = gdal.spatialReferenceFromEpsg(32632);
  final ct = gdal.coordinateTransform(wgs84, utm32);
  final (x, y) = ct.transformPoint(11.58, 48.14);
  print('UTM32: $x, $y');
  ct.close();
  utm32.close();
  wgs84.close();

  // --- GeoTiffSource (Metadaten + WGS 84 Bounds) ---
  final source = gdal.openGeoTiffSource('dem.tif');
  print('CRS: ${source.fromProjection}');
  print('WGS 84 Bounds: ${source.wgs84Bounds}');
  final (lon, lat) = source.transformToWgs84(500000, 5400000);
  print('WGS 84: $lon, $lat');
  source.close();

  // --- Schreiben ---
  final writer = gdal.createGeoTiff('output.tif', width: 256, height: 256);
  writer.setGeoTransform(GeoTransform(
    originX: 10.0, pixelWidth: 0.01, rotationX: 0.0,
    originY: 50.0, rotationY: 0.0, pixelHeight: -0.01,
  ));
  final srs = gdal.spatialReferenceFromEpsg(4326);
  writer.setProjection(srs.toWkt());
  srs.close();
  writer.writeAsUint8(1, Uint8List(256 * 256));
  writer.close(); // Pflicht — schreibt Daten auf Disk

  // --- Vektor-Daten lesen ---
  final ds = gdal.openVector('places.geojson');
  final layer = ds.layer(0);
  print('Layer: ${layer.name}, ${layer.featureCount} Features');

  for (final f in layer.features) {
    final geom = f.geometry as Point;
    print('${f.attributes['name']}: ${geom.x}, ${geom.y}');
  }

  // Räumlicher Filter
  layer.setSpatialFilterRect(11.0, 47.0, 12.0, 49.0);
  for (final f in layer.features) {
    print('Gefiltert: ${f.attributes['name']}');
  }
  layer.clearSpatialFilter();

  // Attribut-Filter
  layer.setAttributeFilter('population > 1000000');
  for (final f in layer.features) {
    print('Großstadt: ${f.attributes['name']}');
  }
  layer.clearAttributeFilter();

  ds.close();
}

Weitere Beispiele:

• example/gdal_dart_example.dart — Lesen, Schreiben, CRS
• example/tile_processing_example.dart — Tile-Rendering mit Reprojektion, Colormaps, Elevation
• example/vector_example.dart — Vektor-Daten lesen mit Iteration, Spatial- und Attribut-Filter

API-Übersicht

Klasse	Zweck
Gdal	Einstiegspunkt — GDAL initialisieren, Dateien öffnen/erzeugen, CRS erstellen
GeoTiffDataset	Lesezugriff — Dimensionen, Projektion, GeoTransform, Bänder
GeoTiffWriter	Schreibzugriff — neues GeoTIFF erzeugen, Bänder befüllen
RasterBand	Pixeldaten lesen — typisiert (readAsUint8, readAsFloat32, …), Tile-Zugriff, Overviews
SpatialReference	CRS-Objekt — WKT1/WKT2-Export, EPSG-Code, isSame()-Vergleich
CoordinateTransform	Koordinatentransformation zwischen CRS — transformPoint(), transformPoints()
GeoTiffSource	GeoTIFF-Quelle mit vorberechneten WGS 84 Bounds und Koordinatentransformation
GeoTransform	Affine Transformation (6 Koeffizienten)
RasterDataType	GDAL-Datentyp-Enum (byte_, uint16, float32, …)
RasterWindow	Rechteckiger Raster-Ausschnitt
GeoTIFFTileProcessor	Tile-Rendering mit Triangulations-Reprojektion, Colormaps und Elevation
Triangulation	Adaptive Triangulation für effiziente Raster-Reprojektion
ColorStop / ColorMapName	Farbmapping mit vordefinierten Colormaps (viridis, terrain, turbo, …)
VectorDataset	Vektor-Lesezugriff — Layer-Zugriff (layerCount, layer(), layerByName())
OgrLayer	Feature-Iteration, Schema (fieldDefinitions), Extent, Spatial/Attribut-Filter
Feature	Immutables Feature-Objekt — fid, attributes, geometry
Geometry	Sealed class — Point, LineString, Polygon, Multi…, GeometryCollection
OgrFieldType	OGR-Feldtyp-Enum (integer, real, string, date, dateTime, …)

Exceptions

Typ	Wann
GdalException	Basis für alle GDAL-Fehler
GdalLibraryLoadException	Shared Library nicht gefunden
GdalFileException	Datei kann nicht geöffnet/erzeugt werden (mit .path)
GdalIOException	Lese-/Schreiboperation fehlgeschlagen
GdalDatasetClosedException	Zugriff auf geschlossene Ressource
OgrException	Vektor-Operation fehlgeschlagen (Layer, Feature, Filter)

Ressourcen-Lebensdauer

Folgende Klassen besitzen native Handles und müssen mit close() freigegeben werden:

• GeoTiffDataset, GeoTiffWriter, SpatialReference, CoordinateTransform, GeoTiffSource, VectorDataset
• close() ist bei allen idempotent
• GeoTiffWriter: close() ist Pflicht, da erst dort Daten auf Disk geflusht werden
• GeoTiffSource.close(): schließt alle internen Ressourcen (Dataset, Transform, SpatialReferences)

Feature und Geometry sind reine Dart-Objekte ohne native Handles und brauchen kein close().

Entwicklung

Für reproduzierbare Checks gibt es ein Dockerfile mit folgenden Stages:

docker build --target analyze .
docker build --target test .
docker build --target coverage --no-cache-filter coverage --progress=plain .

docker build --target coverage-uncovered --no-cache-filter coverage-uncovered  --progress=plain -t gdal_dart:uncov . 
docker run --rm gdal_dart:uncov # uncoverd extrahieren

docker build --target coverage-check --no-cache-filter coverage --progress=plain --build-arg COVERAGE_MIN=95 .
docker build --target doc -t gdal_dart:doc .
docker build --target bindings .
docker build --target publish-check --no-cache-filter publish-check --progress=plain .

API-Dokumentation generieren

docker build --target doc -t gdal_dart:doc .
docker run --rm gdal_dart:doc | tar -xzf -

Die HTML-Dokumentation liegt danach in doc/api/.

CI/CD

GitHub Actions decken ab:

• CI (ci.yml): Analyse, Test, Docker-Build
• Publish (publish.yml): Release über Tags im Format gdal_dart-v*.*.* auf pub.dev

Weiterführend

• Architektur — Schichtenmodell, Designentscheidungen
• Roadmap — Phasen und Meilensteine