GeoIO fails to load GeoTIFFs with internal overviews (GeoTIFFImageIterator)

[marcosdanieldasilva]

Description

GeoIO.load fails when loading GeoTIFF files that contain internal overviews (multiple IFDs), which are very common in drone orthomosaics and GDAL-generated rasters.

In these cases, GeoTIFF.read returns a GeoTIFFImageIterator instead of a single GeoTIFFImage, but GeoIO assumes a single image and calls image(::GeoTIFFImage), leading to a MethodError.

As a result, many valid GeoTIFFs that load correctly in GDAL-based tools (QGIS, Rasters.jl, rasterio) cannot be loaded with GeoIO.

---

Error message

ERROR: MethodError: no method matching image(::GeoTIFF.GeoTIFFImageIterator{...})

---

Steps to reproduce

using GeoIO
GeoIO.load("imgs.tif")

(imgs.tif is a GeoTIFF with internal overviews.)

---

Observed behavior

• GeoIO.load throws a MethodError
• GeoIO.read falls back to returning raw bytes (Vector{UInt8})
• The file is a valid GeoTIFF

---

Expected behavior

GeoIO.load should load the base (full-resolution) image and ignore internal overviews, similarly to GDAL behavior.

---

Technical notes

Inspection with TiffImages.jl shows multiple IFDs (base image + overviews):

imgs = TiffImages.load("imgs.tif")
map(size, imgs)

Example result:

(16210, 16159)
(8105, 8080)
(4053, 4040)
(2027, 2020)
(1014, 1010)
(507, 505)
(254, 253)

Rasters.jl (via GDAL) loads the same file correctly and always exposes the base image.

---

Environment

• OS: Windows
• Julia Version 1.12.4
• GeoIO Version: 1.21.5

[juliohm]

Thank you Marcos! I believe we can transfer this issue to GeoIO.jl. There is a button on GitHub to transfer issues across repositories in the organization. I can do that if you can't find it. Em qua., 21 de jan. de 2026, 15:13, Marcos Daniel da Silva < ***@***.***> escreveu:

…

*marcosdanieldasilva* created an issue (JuliaEarth/GeoIO.jl#192) <#192> Description GeoIO.load fails when loading GeoTIFF files that contain internal overviews (multiple IFDs), which are very common in drone orthomosaics and GDAL-generated rasters. In these cases, GeoTIFF.read returns a GeoTIFFImageIterator instead of a single GeoTIFFImage, but GeoIO assumes a single image and calls image(::GeoTIFFImage), leading to a MethodError. As a result, many valid GeoTIFFs that load correctly in GDAL-based tools (QGIS, Rasters.jl, rasterio) cannot be loaded with GeoIO. ------------------------------ Error message ERROR: MethodError: no method matching image(::GeoTIFF.GeoTIFFImageIterator{...}) ------------------------------ Steps to reproduce using GeoIO GeoIO.load("imgs.tif") (imgs.tif is a GeoTIFF with internal overviews.) ------------------------------ Observed behavior - GeoIO.load throws a MethodError - GeoIO.read falls back to returning raw bytes (Vector{UInt8}) - The file is a valid GeoTIFF ------------------------------ Expected behavior GeoIO.load should load the base (full-resolution) image and ignore internal overviews, similarly to GDAL behavior. ------------------------------ Technical notes Inspection with TiffImages.jl shows multiple IFDs (base image + overviews): imgs = TiffImages.load("imgs.tif") map(size, imgs) Example result: (16210, 16159) (8105, 8080) (4053, 4040) (2027, 2020) (1014, 1010) (507, 505) (254, 253) Rasters.jl (via GDAL) loads the same file correctly and always exposes the base image. ------------------------------ Environment - OS: Windows - Julia Version 1.12.4 - GeoIO Version: 1.21.5 — Reply to this email directly, view it on GitHub <#192>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAZQW3P3HDE27HVVXAASERT4H66VJAVCNFSM6AAAAACSN6DQNOVHI2DSMVQWIX3LMV43ASLTON2WKOZTHAZTSNBUHE4DONQ> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[juliohm]

@marcosdanieldasilva could you please share the imgs.tif used in the MWE?

I believe we have two fixes to consider:

1. Fix GeoIO.load to only load the first image in the iterator because by default we have layer=1
2. Add a GeoIO.loadall (or similar name) that loads an iterator of geotables

Some file formats like GEOTIFF and GPKG support mulitple layers. In the case of GEOTIFF this is justifiable, because sometimes people save large images as tiles in a single file. What I think is not justifiable, and is just bad software design:

• Saving the same region in different resolutions in a single GEOTIFF file. The "overview" image and the "zoomed" images are stored in the same file for "interactive" visualization. This is not necessary as we can easily build strided views into lazy arrays.
• Saving multiple feature tables in GPKG, which represent completely different objects in the physical world. Data-science-wise it would be much better if these objects had their own separate GPKG file.