{"id":6368,"library":"gdal","title":"GDAL (Geospatial Data Abstraction Library)","description":"GDAL (Geospatial Data Abstraction Library) is a powerful translator library for raster and vector geospatial data formats. It provides a single abstract data model for applications to interact with various data types. The `osgeo` Python bindings allow Python applications to leverage GDAL's extensive capabilities. The current version is 3.12.3, and it maintains a continuous release cycle, typically aligning with the core C++ library updates.","status":"active","version":"3.12.3","language":"en","source_language":"en","source_url":"https://github.com/OSGeo/GDAL.git","tags":["geospatial","gis","raster","vector","data processing","osgeo"],"install":[{"cmd":"pip install GDAL","lang":"bash","label":"Install Python Bindings (requires system GDAL)"}],"dependencies":[{"reason":"The `pip install GDAL` package provides Python bindings. The underlying C/C++ GDAL library and its dependencies (like PROJ, GEOS) must be installed separately on the system for full functionality. Consult GDAL documentation or OS-specific guides for installation.","package":"GDAL C/C++ library","optional":false}],"imports":[{"symbol":"gdal","correct":"from osgeo import gdal"},{"note":"For vector data operations.","symbol":"ogr","correct":"from osgeo import ogr"},{"note":"For spatial reference system operations.","symbol":"osr","correct":"from osgeo import osr"},{"note":"For GDAL constants like data types, access modes.","symbol":"gdalconst","correct":"from osgeo import gdalconst"}],"quickstart":{"code":"from osgeo import gdal, ogr, osr\n\n# Configure GDAL to raise Python exceptions for errors\ngdal.UseExceptions()\n\n# --- Raster Quickstart (using an in-memory dataset) ---\nprint(\"--- Raster Quickstart ---\")\ndriver = gdal.GetDriverByName(\"MEM\")\n# Create a 10x10, 1-band, Byte-type in-memory raster dataset\nds_raster = driver.Create(\"dummy_raster\", 10, 10, 1, gdal.GDT_Byte)\nds_raster.SetProjection(\"EPSG:4326\") # Set a dummy geographic projection\nraster_band = ds_raster.GetRasterBand(1)\nraster_band.WriteArray([[i * j for j in range(10)] for i in range(10)])\n\nprint(f\"Raster Driver: {ds_raster.GetDriver().LongName}\")\nprint(f\"Raster Size: {ds_raster.RasterXSize}x{ds_raster.RasterYSize}\")\nprint(f\"Raster Projection: {ds_raster.GetProjectionRef()[:20]}...\") # Abbreviate for brevity\nprint(f\"First pixel value: {raster_band.ReadAsArray()[0, 0]}\")\n\nds_raster = None # Release the dataset\n\n# --- Vector Quickstart (using an in-memory dataset) ---\nprint(\"\\n--- Vector Quickstart ---\")\ndriver = ogr.GetDriverByName(\"Memory\")\n# Create an in-memory vector datasource\nds_vector = driver.CreateDataSource(\"dummy_vector\")\n# Create a layer\nsrs = osr.SpatialReference()\nsrs.SetFromUserInput(\"EPSG:4326\")\nlayer = ds_vector.CreateLayer(\"points\", srs, ogr.wkbPoint)\n\n# Add a field\nfield_defn = ogr.FieldDefn(\"name\", ogr.OFTString)\nlayer.CreateField(field_defn)\n\n# Create a feature\nfeature = ogr.Feature(layer.GetLayerDefn())\nfeature.SetField(\"name\", \"Test Point\")\npoint = ogr.Geometry(ogr.wkbPoint)\npoint.AddPoint(10.0, 20.0) # Lon, Lat\nfeature.SetGeometry(point)\nlayer.CreateFeature(feature)\n\nprint(f\"Vector Layer Name: {layer.GetName()}\")\nprint(f\"Number of Features: {layer.GetFeatureCount()}\")\n# Access the first feature\nfirst_feature = layer.GetFeature(0)\nprint(f\"First Feature Name: {first_feature.GetField(\"name\")}\")\nprint(f\"First Feature Geometry: {first_feature.GetGeometryRef().ExportToWkt()}\")\n\nds_vector = None # Release the datasource","lang":"python","description":"This quickstart demonstrates basic raster and vector data handling using in-memory datasets with `osgeo.gdal` and `osgeo.ogr`. It includes setting up error handling to raise Python exceptions and ensures datasets are properly released."},"warnings":[{"fix":"Ensure the GDAL C/C++ library is installed on your system *before* attempting `pip install GDAL`.","message":"The `pip install GDAL` command only installs the Python bindings. The core GDAL C/C++ library and its dependencies (like PROJ and GEOS) must be installed separately on your operating system. Failure to do so will result in build errors during pip installation or a non-functional Python package. Consult GDAL's official documentation or OS-specific package managers (e.g., `apt`, `yum`, `brew`, `conda`) for proper system-level installation.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be mindful of axis order. For `osr.SpatialReference` objects, use `SetAxisMappingStrategy()` to explicitly control how axis order is handled (e.g., `osr.OAMS_TRADITIONAL_GIS_ORDER` for Lat/Lon or `osr.OAMS_AUTHORITY_COMPLIANT` for Lon/Lat). Test existing code paths that perform coordinate transformations.","message":"GDAL 3.0 introduced significant changes, especially regarding Coordinate Reference Systems (CRS) and axis order. It standardized on 'east/north' (longitude/latitude) axis order for geographic CRS, aligning with ISO 19111, whereas GDAL 2.x often used 'north/east'. This can lead to incorrect coordinate transformations or interpretations if not explicitly managed, especially when working with older datasets or applications.","severity":"breaking","affected_versions":"GDAL 3.0 and newer"},{"fix":"Set the dataset object to `None` (e.g., `dataset = None`) or allow it to go out of scope. For multiple datasets, ensure all are explicitly closed. Using `try...finally` blocks or context managers (if available for specific operations) can help manage this.","message":"GDAL datasets consume system resources and often hold open file handles. It is crucial to explicitly close datasets when you are finished with them to prevent resource leaks and ensure data integrity (e.g., for writing operations).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use `osr.SpatialReference.ExportToWkt(options=['VERSION=WKT1_GDAL'])` to explicitly generate WKT1 if backward compatibility is required. Otherwise, ensure consuming applications can handle WKT2.","message":"The default output of Well-Known Text (WKT) representations for spatial references changed from WKT1 to WKT2 in GDAL 3.0. While GDAL can still parse WKT1, generating WKT1 by default is no longer the standard. This can affect interoperability with older GIS software that may not fully support WKT2.","severity":"deprecated","affected_versions":"GDAL 3.0 and newer"},{"fix":"Call `gdal.UseExceptions()` at the start of your script to make GDAL raise Python exceptions for most errors, allowing for more robust error handling with `try...except` blocks. Always check return values for `None` from GDAL functions.","message":"GDAL's C++ core often uses C-style error reporting (e.g., logging to stderr, returning NULL or specific error codes) rather than throwing exceptions. While Python bindings translate some errors to exceptions, others might result in `None` being returned or a silent failure with logged warnings. This can make debugging difficult.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}