feat!: fetch only specific bands instead of all bands by weiji14 · Pull Request #251 · developmentseed/async-tiff

weiji14 · 2026-02-24T20:44:40Z

What I am changing

Enable fetching only specific bands from an IFD, instead of all bands, useful when data is band-interleaved and/or there are a large number of bands that don't need to be fetched
Considered a breaking change since call changes from ifd.fetch_tile(0, 0, &reader) to ifd.fetch_tile(0, 0, None, &reader)

How I did it

Initial implementation to fetch a range of bands by modifying .fetch_tile()
Refactor to allow fetching disjoint band indexes
Better handle errors when trying to fetch invalid bands (kinda done, but not ergonomic)
Propagate to .fetch_tiles() method.
Propagate to python bindings

How you can test it

Run cargo test locally.

Related Issues

Support fetching specific band only from band-interleaved TIFFs #249

kylebarron · 2026-02-24T21:23:05Z

        &self,
        x: usize,
        y: usize,
+        bands: Option<Range<usize>>,


maybe it makes sense to create an options object for cleaner forwards compatibility

This should probably be a Vec<usize> instead of a Range. There's no requirement for the bands to be contiguous.

yep, agree with 2. Can you elaborate on 1? What's an options object?

I just mean something like

struct FetchOptions { bands: Option<Vec<usize>>, }

so that we can add more options in the future if necessary without changing the primary function signature here again.

Right, I was thinking something like that with a Default impl trait (that returns all bands by default) so Option<> won't be needed (unsure if it's possible since bands are runtime determined), or using a builder pattern like .fetch_tiles(x, y, ...).with_bands(0..3).build().

Ok to go with FetchOptions, since we can reuse it for .fetch_tiles() as well.

Yeah we can implement Default for FetchOptions. But right I think we'll still need to represent bands: None to support all bands when those band indices aren't known till later.

Yes we can reuse it for fetch_tiles and I think we can ignore the niche case where someone might want to fetch different bands for each tile in fetch_tiles.

Change from passing in a Range<usize> to a Vec<usize> so specific bands can be indexed.

Create a FetchOptions struct that allows passing specific parameters (currently only `bands`) when doing a fetch_tile operation. Keep the existing option of passing only None to do the default action of fetching of all bands.

With some special handling to handle 0-based indexing.

Use the same FetchOptions struct, included another unit test using the eox_cloudless.tif data as test case.

weiji14 · 2026-03-02T05:38:18Z

        &self,
        x: usize,
        y: usize,
+        fetch_options: Option<FetchOptions>,


Continuing from #251 (comment):

Yeah we can implement Default for FetchOptions. But right I think we'll still need to represent bands: None to support all bands when those band indices aren't known till later.

Yes we can reuse it for fetch_tiles and I think we can ignore the niche case where someone might want to fetch different bands for each tile in fetch_tiles.

I went with Option<FetchOptions> here, which makes it easier to pass just None if wanting the default all bands instead of instantiating something like FetchOptions {bands: None}, but not sure how I feel about this tbh.

Almost thinking if we should just go back to plain bands: Option<Vec<usize>>. Realistically speaking, are there other fetch related configuration options we might need to handle later to require future-proofing the API like this?

Realistically speaking, are there other fetch related configuration options we might need to handle later to require future-proofing the API like this?

Rust doesn't have keyword arguments, only positional arguments. In Python, I have a set of heuristics for when I define positional vs keyword-only arguments. In particular, as much as possible (at least for public facing APIs), arguments that are allowed to be positional should be plainly obvious what they do. E.g. in fetch_tile(x, y) it can be reasonably understood what fetch_tile(1, 2) means without having to look up the function definition or documentation.

Once you get further away from that, though, it becomes hard to know what fetch_tile(1, 2, None) means, without going back to look at what the named parameter for None was.

My suggestion above is essentially applying this same heuristic to Rust. Even if we don't expect more options (which I'm not confident in), then for public APIs like this it may still be better to have an "options object" which essentially acts as Python keyword-only parameters.

I went with Option<FetchOptions> here, which makes it easier to pass just None if wanting the default all bands instead of instantiating something like FetchOptions {bands: None}, but not sure how I feel about this tbh.

I'd suggest against it. I'd rather have FetchOptions and the user can pass in Default::default() if they want default options. Then it's more readable at the callsite that you're getting the default options, instead of having to recall that None means "use default options".

I went with Option<FetchOptions> here, which makes it easier to pass just None if wanting the default all bands instead of instantiating something like FetchOptions {bands: None}, but not sure how I feel about this tbh.

I'd suggest against it. I'd rather have FetchOptions and the user can pass in Default::default() if they want default options. Then it's more readable at the callsite that you're getting the default options, instead of having to recall that None means "use default options".

Gotcha. I'll refactor this after #261. Using Option<FetchOptions> did sound weird, I need to change my Python-way of thinking that None means default 😆

kylebarron · 2026-03-02T21:27:43Z

I think after #261 this should become very simple and straightforward of just indexing into the ranges array for planar data.

kylebarron · 2026-03-03T22:03:05Z

I went ahead and updated this PR given #261... but then I realized we have to make a choice... is our band indexing 0-based or 1-based 🙈

async-geotiff has adopted 1-based indexing to match GDAL/Rasterio, but I think it may be best here in async-tiff to use 0-based indexing, since we're trying to be generic for all TIFFs. And here the band numbers are used to index into a list of offsets, which for a general computer science person would obviously be 0-based.

@weiji14 do you have any thoughts?

weiji14 · 2026-03-03T22:24:46Z

Thanks for handling the merge conflict and adding the Python-bindings!

async-geotiff has adopted 1-based indexing to match GDAL/Rasterio, but I think it may be best here in async-tiff to use 0-based indexing, since we're trying to be generic for all TIFFs. And here the band numbers are used to index into a list of offsets, which for a general computer science person would obviously be 0-based.

@weiji14 do you have any thoughts?

Yeah, would prefer 0-based here (math is easier that way). I secretly wanted to 👎 developmentseed/async-geotiff#14 but won't argue with the experts 🙈

kylebarron · 2026-03-03T22:36:29Z

I think given the geospatial ecosystem in Python is already extremely reliant on 1-based band indexing, it would be more disruptive to switch to 0-based band indexing there. But here I'm open to it.

weiji14 · 2026-03-03T22:52:06Z

    fn fetch_tile<'py>(
        &'py self,
        py: Python<'py>,
        x: usize,
        y: usize,
        z: usize,
    ) -> PyResult<Bound<'py, PyAny>> {
        let reader = self.reader.clone();
        let ifd = self
            .ifds
            .get(z)
            .ok_or_else(|| PyIndexError::new_err(format!("No IFD found for z={z}")))?
            .clone();
        future_into_py(py, async move {
            let tile = ifd
-                .fetch_tile(x, y, reader.as_ref())
+                .fetch_tile(x, y, reader.as_ref(), Default::default())


Should the TIFF.fetch_tile() method also expose specific band fetching? Or limit it to be only on the IFD level?

Yes it should expose band fetching; good catch

I'm happy to just keep it at the IFD level to be honest. But I suppose you want to align with the Typescript implementation in deck.gl-raster?

I think it makes sense to mirror the same options in both sets of fetch_tile. And it's a pretty simple option to pass along

mdsumner · 2026-03-14T01:45:39Z

I think given the geospatial ecosystem in Python is already extremely reliant on 1-based band indexing, it would be more disruptive to switch to 0-based band indexing there. But here I'm open to it.

And GDAL overview 0 is IFD level 1. I have internalized mental reminders to keep track. 🙏

kylebarron · 2026-03-14T16:44:03Z

I think given the geospatial ecosystem in Python is already extremely reliant on 1-based band indexing, it would be more disruptive to switch to 0-based band indexing there. But here I'm open to it.

And GDAL overview 0 is IFD level 1. I have internalized mental reminders to keep track. 🙏

@mdsumner you may be better served by using https://github.com/developmentseed/async-geotiff, if you're not already, because it automatically associates images with overviews and their masks, and makes it easy to access specific tiles in a geospatial context.

weiji14 added 2 commits February 24, 2026 15:38

Add band-interleaved multi-band sample TIFF

1ce8145

Fetch range of bands for a tile instead of all bands

3a5b771

weiji14 self-assigned this Feb 24, 2026

github-actions bot added feat breaking change labels Feb 24, 2026

Add specific test pulling specific band ranges from a TIFF

854a632

kylebarron reviewed Feb 24, 2026

View reviewed changes

kylebarron mentioned this pull request Feb 25, 2026

feat(wip): embeddings visualization developmentseed/deck.gl-raster#261

Draft

weiji14 added 7 commits February 24, 2026 23:46

Merge branch 'main' into specific_band_fetch

43af6fd

Enable fetching disjoint bands from a TIFF

98a63e0

Change from passing in a Range<usize> to a Vec<usize> so specific bands can be indexed.

clippy

197e46e

Check that we are not fetching bands outside the max band count

25ed9a8

With some special handling to handle 0-based indexing.

Merge branch 'main' into specific_band_fetch

5e646a1

Support fetching specific bands with fetch_tiles

7a3ca77

Use the same FetchOptions struct, included another unit test using the eox_cloudless.tif data as test case.

weiji14 force-pushed the specific_band_fetch branch from 23a18f6 to 7a3ca77 Compare March 2, 2026 05:30

weiji14 commented Mar 2, 2026

View reviewed changes

weiji14 mentioned this pull request Mar 2, 2026

feature request: tile/strip byte range lookup API #257

Closed

kylebarron added 7 commits March 3, 2026 16:33

Merge branch 'main' into specific_band_fetch

7055073

update

d566435

update python compile

4fbb671

update band selection for options

6ecec5d

fix band count

c3f7253

Rename to ReadOptions

72e1071

add to python

28e3270

fmt

33ec7d7

Merge branch 'main' into specific_band_fetch

b60a11d

weiji14 commented Mar 3, 2026

View reviewed changes

kylebarron mentioned this pull request Mar 3, 2026

Support fetching partial bands developmentseed/async-geotiff#113

Open

Conversation

weiji14 commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What I am changing

How I did it

How you can test it

Related Issues

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

weiji14 Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

weiji14 Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kylebarron commented Mar 2, 2026

Uh oh!

kylebarron commented Mar 3, 2026

Uh oh!

weiji14 commented Mar 3, 2026

Uh oh!

kylebarron commented Mar 3, 2026

Uh oh!

weiji14 Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mdsumner commented Mar 14, 2026

Uh oh!

kylebarron commented Mar 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

weiji14 commented Feb 24, 2026 •

edited

Loading

weiji14 Feb 25, 2026 •

edited

Loading

weiji14 Mar 2, 2026 •

edited

Loading

weiji14 Mar 3, 2026 •

edited

Loading