GeoTIFFBase.readRasters should support COGs with multiple full-res images

[rgov]

GeoTIFFBase.readRasters() attempts to find the best-fitting image (full resolution or overview) for given bounds and desired resolution.

The function assumes that the first image is the full resolution image, and that any other images with newSubfileType & 1 are downsampled overviews of this full resolution image:

      const firstImage = await this.getImage();
      // ...
      for (let i = 0; i < imageCount; ++i) {
        const image = await this.getImage(i);
        const { SubfileType: subfileType, NewSubfileType: newSubfileType } = image.fileDirectory;
        if (i === 0 || subfileType === 2 || newSubfileType & 1) {
          allImages.push(image);
        }
      }

However, the COG spec allows for multiple full resolution images, each with their own overview images. The function does not handle this case properly.

The function could take an optional principal_image_id (default 0) parameter, follow the sequence of overview images, and stop before the next full resolution image:

      const firstImage = await this.getImage(principal_image_id);
      // ...
      allImages.push(firstImage);
      for (let i = principal_image_id + 1; i < imageCount; ++i) {
        const image = await this.getImage(i);
        const { SubfileType: subfileType, NewSubfileType: newSubfileType } = image.fileDirectory;
        if (newSubfileType & 1 === 0) {
          // The chain ended, so this is a different full-res image
          break;
        }
        allImages.push(image);
      }

Note I've dropped the check for subfileType === 2, I'm not sure whether it should skip over other subfile types like thumbnails or terminate the loop. I don't think we expect them in a COG, and I'm not sure about the general case.

[constantinius]

Hey @rgov
I know that it is in principle possible to have multiple full resolution images inside a single TIFF and their overviews too, but I have never come across one in geospatial context.
Could you show me an example TIFF file? Do you have a spec that details such a use?

Regarding the ordering of the IFDs: I'm pretty sure that the order of the IFDs in the file cannot give an indication of their structuring. AFAIK this is handled via the SubIFD tag, when there are actually multiple full resolution ones.

In short: I would only implement this in geotiff.js if there is a tangible usecase.

[rgov]

That's reasonable. I have found support for creating these images similarly lacking, though it seemed like a more tractable problem to fix the viewer. I am just a passerby in the world of GeoTIFF but it seems like there could be some feedback to the COG spec editors about what subset is practical to implement...

There is one case where this may be supported by other tools: GDAL seems to support a separate full-resolution mask image when using compression that doesn't support the alpha channel:

As JPEG compression cannot include the transparency information, two TIFF IFD have to be created: one for YCbCr, and another one for alpha.

---

Regarding the ordering of IFDs, the COG spec, Requirement 3, writes,

B: An IFD with a NewSubfileType tag whose bit 0 is not set, or without a NewSubfileType tag SHALL have an offset to the next IFD that will point to an IFD with a NewSubfileType tag whose bit 0 is set (reduced-resolution image data) if there is one, or an offset to the next full-resolution image data (e.g., another band or a mask) or an offset 0 if there is no other image.

F: When no additional reduced-resolution image data is available for this image, the IFD SHALL have an offset to the next IFD pointing to the next full-resolution image data (e.g. another band or a mask) or an offset 0 if there is no other image.

This implies that taken as a linked list, the IFDs must go: FullResImage1, Overview1_1, Overview1_2, ..., FullResImage2, Overview2_1, Overview2_2, ...

This is not to say that the positional order in the stream (i.e., byte offset) has to follow this order, and Recommendation 3 suggests a different positional order for more efficient fetching.

Also, I understand you support GeoTIFFs that are not Cloud Optimized® and so this may not be a safe assumption to make unless there is a flag passed to the format parser.

---

What I am trying to achieve is a 9-band seekable, tiled image, with the three RGB channels and six others. In my testing, WEBP gives much better compression than deflate, but it is limited to 4 channels. It seems to be within the COG spec to split my channels up into 3 images of 3 channels, each WEBP compressed.

(I also have a PR #469 because 3-channel WEBP is currently broken.)