Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: Improve IB::nsubimages and other related fixes #4228

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

lgritz
Copy link
Collaborator

@lgritz lgritz commented Apr 14, 2024

Background: Some formats that support multi-image files know as soon as they are opened and read the header what the total subimage count is. Others (I'm looking at you, TIFF) can't know without reading each subimage in succession until you hit the end of the file. Format readers who can easily figure it out open first opening are supposed to set attribute "oiio:subimages" to the number of subimages, or 0 / unset if it can't be cheaply or immediately determined.

ImageBuf has a nsubimages() method that you'd think would give you the right count, and it did when all IBs were read through the ImageCache (which fully inventories the subimages of any file it reads). But when OIIO 2.5 changed IB behavior to only be backed by IC when explicitly requested, we effectively lost this functionality most of the time, and instead returned 0 ("don't know yet"). This was confusing. And also silly, because it reported 0 even for files whose formats don't permit multiple images (so you know the count is 1).

This patch does the following:

  • Changes the behavior and documentation of ImageBuf::nsubimages() to the following return values:
    • 1, for formats that are always a single subimage. (Or for ImageBufs that are not direct reads of a file.)
    • n>=1 for files that permit multiple subimages and the count is known.
    • 0 for files that permit multiple subimages, but the count is not known because it's one of the formats where it can't easily be determined upon opening the file.
  • Add a new ImageInput::supports("multiimage") that says if the input file format permits multiple images, and ensure that it returns true for all formats where this is the case.
  • Ensure that formats permitting multiimage and can easily know the count up front set the "oiio:subimages" attribute (not all did).
  • Document in the built-in format section of the docs the formats that are expected to set this attribute.

Fixes #4225

Background: Some formats that support multi-image files know as soon
as they are opened and read the header what the total subimage count
is.  Others (I'm looking at you, TIFF) can't know without reading each
subimage in succession until you hit the end of the file. Format
readers who can easily figure it out open first opening are supposed
to set attribute "oiio:subimages" to the number of subimages, or 0 /
unset if it can't be cheaply or immediately determined.

ImageBuf has a `nsubimages()` method that you'd think would give you
the right count, and it did when all IBs were read through the
ImageCache (which fully inventories the subimages of any file it
reads). But when OIIO 2.5 changed IB behavior to only be backed by IC
when explicitly requested, we effectively lost this functionality most
of the time, and instead returned 0 ("don't know yet"). This was
confusing. And also silly, because it reported 0 even for files whose
formats don't permit multiple images (so you know the count is 1).

This patch does the following:

* Changes the behavior and documentation of `ImageBuf::nsubimages()`
  to the following return values:
    - 1, for formats that are always a single subimage. (Or for
      ImageBufs that are not direct reads of a file.)
    - n>=1 for files that permit multiple subimages and the count is
      known.
    - 0 for files that permit multiple subimages, but the count is not
      known because it's one of the formats where it can't easily be
      determined upon opening the file.
* Add a new ImageInput::supports("multiimage") that says if the input
  file format permits multiple images, and ensure that it returns true
  for all formats where this is the case.
* Ensure that formats permitting multiimage and can easily know the count
  up front set the "oiio:subimages" attribute (not all did).
* Document in the built-in format section of the docs the formats that
  are expected to set this attribute.

Fixes 4225

Signed-off-by: Larry Gritz <lg@larrygritz.com>
@lgritz
Copy link
Collaborator Author

lgritz commented Apr 20, 2024

Any comments about this one?

@lgritz
Copy link
Collaborator Author

lgritz commented Apr 30, 2024

Will merge this tomorrow if nobody objects.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[BUG] OIIO::ImageBuf::nsubimages returns zero for existing image
1 participant