xarray-contrib / xarray-spatial

Latest Release Downloads License People Build Status Coverage ------- ------- :round_pushpin: Fast, Accurate Python library for Raster Operations :zap: Extensible with Numba :fast_forward: Scalable with Dask :confetti_ball: Free of GDAL / GEOS Dependencies :earth_africa: General-Purpose Spatial Processing, Geared Towards GIS Professionals ------- Xarray-Spatial implements common raster analysis functions using Numba and provides an easy-to-install, easy-to-extend codebase for raster analysis. Installation Downloading our starter examples and data Once you have xarray-spatial installed in your environment, you can use one of the following in your terminal (with the environment active) to download our examples and/or sample data into your local directory. : Download the examples notebooks and the data used. : Download the examples notebooks but not the data. Note: you won't be able to run many of the examples. : Download just the data and not the notebooks. In all the above, the command will download and store the files into your current directory inside a folder named 'xrspatial-examples'. | | | | | | |:-------------------------:|:-------------------------:|:-------------------------:|:-------------------------:|:-------------------------:| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | grew out of the Datashader project, which provides fast rasterization of vector data (points, lines, polygons, meshes, and rasters) for use with xarray-spatial. does not depend on GDAL / GEOS, which makes it fully extensible in Python but does limit the breadth of operations that can be covered. xarray-spatial is meant to include the core raster-analysis functions needed for GIS developers / analysts, implemented independently of the non-Python geo stack. Our documentation is still under construction, but docs can be found here. Raster-huh? Rasters are regularly gridded datasets like GeoTIFFs, JPGs, and PNGs. In the GIS world, rasters are used for representing continuous phenomena (e.g. elevation, rainfall, distance), either directly as numerical values, or as RGB images created for humans to view. Rasters typically have two spatial dimensions, but may have any number of other dimensions (time, type of measurement, etc.) Supported Spatial Functions with Supported Inputs ✅ = native backend    🔄 = accepted (CPU fallback) Classification · Diffusion · Focal · Morphological · Fire · Multispectral · Multivariate · Pathfinding · Proximity · Reproject / Merge · Raster / Vector Conversion · Surface · Hydrology · Flood · Interpolation · Dasymetric · Zonal · Utilities ------- **GeoTIFF / COG I/O** Native GeoTIFF and Cloud Optimized GeoTIFF reader/writer. No GDAL required. | Name | Description | NumPy | Dask | CuPy GPU | Dask+CuPy GPU | Cloud | |:-----|:------------|:-----:|:----:|:--------:|:-------------:|:-----:| | read_geotiff | Read GeoTIFF / COG / VRT | ✅️ | ✅️ | ✅️ | ✅️ | ✅️ | | write_geotiff | Write DataArray as GeoTIFF / COG | ✅️ | ✅️ | ✅️ | ✅️ | ✅️ | | write_vrt | Generate VRT mosaic from GeoTIFFs | ✅️ | | | | | and auto-dispatch to the correct backend: **Compression codecs:** Deflate, LZW (Numba JIT), ZSTD, PackBits, JPEG (Pillow), uncompressed **GPU codecs:** Deflate and ZSTD via nvCOMP; LZW via Numba CUDA; JPEG via nvJPEG **Features:** • Tiled, stripped, BigTIFF, multi-band (RGB/RGBA), sub-byte (1/2/4/12-bit) • Predictors: horizontal differencing (pred=2), floating-point (pred=3) • GeoKeys: EPSG, WKT/PROJ (via pyproj), citations, units, ellipsoid, vertical CRS • Metadata: nodata masking, palette colormaps, DPI/resolution, GDALMetadata XML, arbitrary tag preservation • Cloud storage: S3 ( ), GCS ( ), Azure ( ) via fsspec • GPUDirect Storage: SSD→GPU direct DMA via KvikIO (optional) • Thread-safe mmap reads, atomic writes, HTTP connection reuse (urllib3) • Overview generation: mean, nearest, min, max, median, mode, cubic • Planar config, big-endian byte swap, PixelIsArea/PixelIsPoint **Read performance** (real-world files, A6000 GPU): | File | Format | xrspatial CPU | rioxarray | GPU (nvCOMP) | |:-----|:-------|:------------:|:---------:|:------------:| | render_demo 187x253 | uncompressed | **0.2ms** | 2.4ms | 0.7ms | | Landsat B4 1310x1093 | uncompressed | **1.0ms** | 6.0ms | 1.7ms | | Copernicus 3600x3600 | deflate+fp3 | 241ms | 195ms | 872ms | | USGS 1as 3612x3612 | LZW+fp3 | 275ms | 215ms | 747ms | | USGS 1m 10012x10012 | LZW | **1.25s** | 1.80s | **990ms** | **Read performance** (synthetic tiled, GPU shines at scale): | Size | Codec | xrspatial CPU | rioxarray | GPU (nvCOMP) | |:-----|:------|:------------:|:---------:|:------------:| | 4096x4096 | deflate | 265ms | 211ms | **158ms** | | 4096x4096 | zstd | **73ms** | 159ms | **58ms** | | 8192x8192 | deflate | 1.06s | 859ms | **565ms** | | 8192x8192 | zstd | **288ms** | 668ms | **171ms** | **Write performance** (synthetic tiled): | Size | Codec | xrspatial CPU | rioxarray | GPU (nvCOMP) | |:-----|:------|:------------:|:---------:|:------------:| | 2048x2048 | deflate | 424ms | 110ms | **135ms** | | 2048x2048 | zstd | 49ms | 83ms | 81ms | | 4096x4096 | deflate | 1.68s | 447ms | **302ms** | | 8192x8192 | deflate | 6.84s | 2.03s | **1.11s** | | 8192x8192 | zstd | 847ms | 822ms | 1.03s | **Consistency:** 100% pixel-exact match vs rioxarray on all tested files (Landsat 8, Copernicus DEM, USGS 1-arc-second, USGS 1-meter). ----------- **Reproject / Merge** | Name | Description | Source | NumPy xr.DataArray | Dask xr.DataArray | CuPy GPU xr.DataArray | Dask GPU xr.DataArray | |:----------:|:------------|:------:|:----------------------:|:--------------------:|:-------------------:|:------:| | Reproject | Reprojects a raster to a new CRS using an approximate transform and numba JIT resampling | Standard (inverse mapping) | ✅️ | ✅️ | ✅️ | ✅️ | | Merge | Merges multiple rasters into a single mosaic with configurable overlap strategy | Standard (mosaic) | ✅️ | ✅️ | 🔄 | 🔄 | -------…