Skip to main content

GeoTIFF Reader

Read GeoTIFFs into the shared (source, tile) schema. The lightweight gtiff_gbx reader (the raster_gbx catch-all with the GeoTIFF driver preset, rasterio-backed, JAR-free) and the heavyweight gtiff_gdal reader are interchangeable — see Choosing an Execution Tier.

Benchmark & tradeoff

The lightweight (*_gbx) and heavyweight readers emit the same schema, but your compute usually decides the tier: the lightweight tier needs no JAR or init script and is the only option on Serverless, standard (shared), and ARM clusters. The heavyweight tier requires a classic x86 cluster (JAR + GDAL init script); where it is available it uses native GDAL on the JVM and tends to pull ahead on large workloads. See the Benchmarking page for light-vs-heavy timings and methodology.

Options​

Both named readers preset the GeoTIFF driver and inherit their respective generic raster reader's options.

Lightweight (gtiff_gbx)​

Inherits the lightweight raster_gbx options. Key options:

OptionDefaultDescription
virtualTiles"true"Default. Emit bytes-free virtual tiles — each row carries the source path + pixel window instead of raster bytes; pixels are read lazily when an operation needs them (the ingest-OOM-dissolving default for the light tier). Set "false" to materialize raster bytes into each row. See Virtual Tiles.
splitStrategy"none"When to split large rasters: none (default — one tile per file), auto, serverless, classic. See Raster Options.
sizeInMB"-1"Power-user budget override in MiB (positive value). -1 = use splitStrategy.
clipPolygonsnoneArea(s) of interest: one WKT/EWKT string, or a JSON-array string for a list. One tile per intersecting polygon; mutually exclusive with windows/tileSize. See Raster Options.
windowsnonePixel window(s): JSON 4-int array "[col,row,w,h]", or a JSON array of them. Mutually exclusive with clipPolygons/tileSize.
clipCrsnoneCRS for clipPolygons lacking an embedded SRID (embedded SRID → clipCrs → raster CRS).
tileSizenoneRegular fixed-size grid: "w,h" or a single "n" (square). One tile per cell; mutually exclusive with clipPolygons/windows. Materialized cells guarded to ~2 GB; virtual unguarded. See Raster Options.
overlapPercent0Overlap % between tileSize cells (tileSize-only). See Raster Options.
filterRegex".*"When loading a directory, keep files whose full path matches this regex.
Virtual tiles are the default

Light raster readers now emit virtual tiles by default (virtualTiles=true) — bytes-free (path, window) references that read pixels lazily. Previously the reader materialized raster bytes into every row. To restore materialized reads, pass .option("virtualTiles", "false"). A virtual tile passed to a heavyweight function must be materialized first — see Virtual Tiles.

COG output is a writer concern

The tileFormat, cogBlockSize, and cogOverviewResampling reader options are removed. COG creation belongs to the cog_gbx writer — see COG Writer. The gtiff_gbx writer still accepts cog=true to re-encode a tile DataFrame as COG.

Heavyweight (gtiff_gdal)​

Inherits all heavyweight gdal reader options. Common options include:

OptionDefaultDescription
readSubdatasets"false"Read subdatasets if present
rasterAsGrid"false"Read as grid instead of tiles
retile"false"Retile rasters for optimal processing
tileSize"256"Tile size in pixels (if retiling)

Example — reading with options set:

# Read GeoTIFF with options (sample-data Volumes path)
df = spark.read.format("gtiff_gdal") \
    .option("readSubdatasets", "false") \
    .load("/Volumes/main/default/geobrix_samples/geobrix-examples/nyc/sentinel2/nyc_sentinel2_red.tif")
df.show()
Example output
+--------------------------------------------------+-----+
|path                                              |tile |
+--------------------------------------------------+-----+
|/Volumes/.../nyc_sentinel2_red.tif                |{...}|
+--------------------------------------------------+-----+

gtiff_gbx is the raster_gbx catch-all reader with the GeoTIFF driver preset — use it to make GeoTIFF reads explicit. It is pure-Python (no JAR) and emits the same (source, tile) schema as the other readers.

Register the lightweight DataSources first (see Lightweight Raster Readers → Register).

# Named lightweight GeoTIFF reader (preset for GeoTIFF)
df = spark.read.format("gtiff_gbx").load("{SAMPLE_RASTER_PATH}")

It is the lightweight counterpart of the heavyweight gtiff_gdal reader, supporting Python and SQL bindings (not Scala).

Next Steps​

Common functions: used vs excluded​

See GBX Common Functions for the full catalog of shared file-access primitives. The table below shows which are active in this reader and which are not, and why.

Common capabilityUsed here?How / why
list_local_files (session-free enumeration)UsedAll directory reads — recursive, include_hidden, extensions, path_glob_filter options are routed through this shared predicate.
enumerate_files (FILE-tier enumeration)Not in the DataSourceThe DataSource is session-less on Connect and does not call enumerate_files; FILE-tier enumeration is only available through gbx_file_read at the function layer.
gbx_file_read / gbx_file_write (FILE tier)Not in the DataSourceThe DataSource is FUSE-only (session-less on Connect); FILE reads go through gbx_file_read → rst_fromfile at the function layer.
Shared file-access layer

Lightweight readers use the shared file_gbx file-access base for FILE / FUSE routing and enumeration — capability tiers, the no-gating rule, and layout options are described there.