bug: `oiiotool --attrib` apply beyond the top image when `--dup` is used

[DevilishSpirits]

Describe the bug

The oiiotool --attrib documentation state that it applies only to the top image.
However I had issues where it applied accross the whole image stack and it's a problem for me.

I believe that --dup does not clone the metadata so write attribute operations on the duplicated image go through the source images as well.

OpenImageIO version and dependencies

Happens on both ArchLinux version and fresh Git compiled version:

$ ./bin/oiiotool --buildinfo
OIIO 3.2.0.2dev | Linux/x86_64
    Build compiler: gcc 16.2 | C++17/201703
    HW features enabled at build: sse2
    No CUDA support (disabled / unavailable at build time)
Dependencies: BZip2 1.0.8, DCMTK NONE, FFmpeg 8.0, fmt 12.2.0, Freetype 2.14.3, GIF 6.1.3, Imath 3.2.3, JXL 0.12.0, libdeflate 1.26, Libheif 1.23.2,
    libjpeg-turbo 3.2.0, LibRaw 0.22.2, libuhdr NONE, nanobind 2.13.0, OpenColorIO 2.5.1, OpenCV 5.0.0, OpenEXR 3.4.15, OpenGL, OpenJPEG 2.5.4, openjph
    0.31.0, OpenVDB 13.0.0, PNG 1.6.58, Ptex 2.5, Python3 3.14.7, Qt6 6.11.2, Robinmap 1.4.1, TBB 2023.1.0, TIFF 4.7.2, WebP 1.6.0, ZLIB 1.3.2

To Reproduce

$ oiiotool \
	--create 256x256 1 \
	--create 256x256 4 \
	--dup \
	--sattrib 'Dummy' 'attribute' \
	--ch R,G,B \
	--siappendall \
	--printinfo:allsubimages=1

This output :

 256 x  256, 1 channel, float 
    3 subimages: 256x256 [f], 256x256 [f,f,f,f], 256x256 [f,f,f]
 subimage  0:  256 x  256, 1 channel, float 
    channel list: Y
 subimage  1:  256 x  256, 4 channel, float 
    channel list: R, G, B, A
    Dummy: "attribute"
 subimage  2:  256 x  256, 3 channel, float 
    channel list: R, G, B
    Dummy: "attribute"

The Dummy attribute should only be on the last subimage but it went through the previous image as well. If you play around you see that --dup seem to don't clone the metadata :

$ oiiotool \
	--create 256x256 1 \
	--create 256x256 4 \
	--dup \
	--dup \
	--sattrib 'Dummy' 'attribute' \
	--ch R,G,B \
	--siappendall \
	--printinfo:allsubimages=1

Output:

 256 x  256, 1 channel, float 
    4 subimages: 256x256 [f], 256x256 [f,f,f,f], 256x256 [f,f,f,f], 256x256 [f,f,f]
 subimage  0:  256 x  256, 1 channel, float 
    channel list: Y
 subimage  1:  256 x  256, 4 channel, float 
    channel list: R, G, B, A
    Dummy: "attribute"
 subimage  2:  256 x  256, 4 channel, float 
    channel list: R, G, B, A
    Dummy: "attribute"
 subimage  3:  256 x  256, 3 channel, float 
    channel list: R, G, B
    Dummy: "attribute"

And a last one with stack reordering reinforce the hypothesis that --dup doesn't duplicate metadata :

oiiotool \
	--create 256x256 1 \
	--create 256x256 4 \
	--dup \
	--dup \
	--create 256x256 2 \
	--stackextract 1 \
	--sattrib 'Dummy' 'attribute' \
	--ch R,G,B \
	--siappendall \
	--printinfo:allsubimages=1

Output:

 256 x  256, 1 channel, float 
    5 subimages: 256x256 [f], 256x256 [f,f,f,f], 256x256 [f,f,f,f], 256x256 [f,f], 256x256 [f,f,f]
 subimage  0:  256 x  256, 1 channel, float 
    channel list: Y
 subimage  1:  256 x  256, 4 channel, float 
    channel list: R, G, B, A
    Dummy: "attribute"
 subimage  2:  256 x  256, 4 channel, float 
    channel list: R, G, B, A
    Dummy: "attribute"
 subimage  3:  256 x  256, 2 channel, float 
    channel list: R, G
 subimage  4:  256 x  256, 3 channel, float 
    channel list: R, G, B
    Dummy: "attribute"

[lgritz]

Aha, I see what is happening, and it's subtle. The gist is that --dup doesn't make a copy, it makes a second reference, and that operations that only alter metadata (like --sattrib) just alter the top image and do not make NEW images. Almost all operations that alter pixels create new images to do it, though there are a few exceptions that operate in-place even though they touch pixels, such as --text.

• --create 256x256 1 : puts one image is on the stack, 256x256 x1 channel.
• --create 256x256 4 : pushes another new image, so now the stack has the 256x256 x4 at the top, then underneath the 256x256 x1.
• --dup : the stack has 3 items, and the top TWO are actually references to the first image
• --sattrib 'Dummy' 'attribute' changes the attribute of the top image, but remember, the next image is really the same image! Because --sattrib changes an image in place, it does not make a whole new image.
• --ch R,G,B : pops the top image (4 channels) and creates a new image with only 3 channels (and whatever metadata the source image had) and pushes that. At this point the stack is (top to bottom), the 3-channel (with Dummy), the 4-channel (with Dummy), then the 1-channel (no Dummy). And each image has only a single reference.
• --siappendall mashes them together into a single, 3-subimage image having parts of 1-chan NO dummy, 4-chan dummy, 3-chan dummy.

So that's how we get into this pickle. I'm going to let you linger with this explanation, then in a separate comment, will discuss possible fixes.

[lgritz]

I can think of a few ways to fix this, possibly with different tradeoffs for performance, and the potential of altering the meaning of people's existing scripts that call oiiotool. Everybody please think carefully about this and discuss below. (And they aren't necessarily mutually exclusive.)

Issue A: --dup

Are there circumstances in which --dup should definitely make a full copy? (Expensive! Especially if it is a very large resolution image.)

Choices:

1. Leave as-is: unconditional duplicate reference to the same image. (Status quo.)
2. Unconditional full duplicate. (Could turn --dup from essentially free to possibly very expensive.)
3. Make an optional modifier to fully duplicate, such as --dup:copy=1. Pros: no surprise expense, users get full control. Cons: users in full control and I bet often will not know which they should do. The fact that this issue is the first to report this means that people are almost never bitten by the fact that it's a cheap reference, that's almost always ok, so will they know when it needs to be a full copy?

(Interlude: it really burns me up that GitHub Markdown doesn't let you start a numbered list with 0, which is natural for computer scientists, and also is especially apt when the first choice you want to list is "keep it the way it is". I digress)

Issue B: --attrib

(I'm using this as a stand-in for all oiiotool ops that just alter metadata, including --sattrib.)

Choices:

1. Leave as-is: alter the top image in place (and any other references).
2. Make a copy (ugh, very expensive, and imagine how common it probably is to have several --attrib commands in a row, you definitely don't want every one to do a full image copy!).
3. Make a copy IF AND ONLY IF the top image has a reference count > 1. In other words, operate in-place on a unique image, make a copy if it's a shared image. Question: are there workflows that this will break? Are there times when people intentionally have multiple references and want --attrib to change it, knowing it will be reflected in all the copies?
4. Make an optional modifier to explicitly cause it to make a copy, like --attrib:copy=1 foo bar. Same tendency for users to not know when to use it, either forgetting or making needless copies.

Issue C: those stray pixel-altering operations like --text

The "in-place" nature of these operations is probably on purpose for efficiency. An operation like --ch changes the whole "shape" of the image, so of course you need a new one. An operation like --colorconvert changes (ROI notwithstanding) all the pixels, so making a new copy is really not more expensive, so we do it. But --text, I can picture myself having thought, "do I really want to copy the whole image to change a few pixels where the letters are? Let's operate in-place."

But now I am inclined to think that these are the problematic and that it's probably better to change them so that they make a new copy if the top image has multiple references -- making it as cheap before if it's the only copy, but semantically behaves the same as all the other pixel-altering operations that make a copy. In fact, maybe the general rule is that all operations that can be done in-place SHOULD be done in-place, but only if it's a unique image and not a shared reference; if it's shared, make a copy so that the alteration only affects the one image.

Issue D: But what about --label?

Don't forget --label which creates a reference and attaches a name to it, so you can refer to it later. For example,

oiiotool a.exr --label John b.exr c.exr --attrib ImageDescription "{John.ImageDescription}"

This copies a.exr's ImageDescription metadata to c.exr (well, assuming you save it). But what do we believe this should do:

oiiotool a.exr --label John --attrib ImageDescription "hello" --echo "{John.ImageDescription}"

Does this, or doesn't it, print "hello"? Remember that the sequence is

• read a.exr
• make a second reference, not on the stack, but in the "name dictionary" associated with the key "John".
• change the top image's ImageDescription metadata to "hello"

Now, at this point, what about "John"? If --attrib made and altered a COPY because the TOP image was not unique, then the image at the top of the stack has "hello" but the image labeled "John" does not.

So what I'm demonstrating is that changing any operations that currently operate on all references to make copies if the top image is a non-unique reference has the possibility of having a behavior change that maybe isn't always what you want.

Possibility of a single, most consistent rule

Now, we could just establish a rule that image references within oiiotool (created by --dup or --label or anything else we've forgotten) are always copy on write, let all operations that alter the image (pixels or metadata) operate freely in place on uniquely-referenced images but make copies before altering images with multiple references. That means you need to be careful with --label, as it can diverge if the image you labeled is subsequently modified, the labeled one is always the original one from the time you labeled it.

I'm leaning toward this a a comprehensive solution, but I would like to hear others' opinions, and I'm really not sure if it has the potential to break existing scripts.

[DevilishSpirits]

I think I understand the data model now : labeled and stack slots are pointers to reference counted mutable images and while most operations erase the TOP image, some does not erase it and cause what appear to be mutations in other images.

After your analysis @lgritz I believe that the data model should not be changed but be more documented.
My comments reggarding the other routes you presented :

• The systematic full-copy approach is undesirable as it will break for users handling huge or massively multi-layers images in my case. Between sticking with an outdated OIIO version and buying RAM these days the choice is quick 💸️.
• The copy-on-write approach seem viable to me but that is a breaking change and some users may have relied on it.

My bug does not justify breaking the current behavior of OIIO. Though a way to perform a deep copy via --dup:copy=1 makes sense. A use case is for repeated use of --text with different captions. Alternatively a --make-unique command that makes the TOP image unique.

What I was using OIIO for when encountering this issue is that I am baking textures of a 3D model using Blender and output everything in a single multi-part OpenEXR file. OIIO is used to extract the individual textures into PNGs and perform channel packing such as setting the roughness as Alpha channel of the albedo for use in Unity and I used --dup for that.

Ultimately I believe that the actual bug I have encountered is a lack of documentation regarding this behavior. I suggest updating the documentation for example with :

--dup

Push a new reference of the current image on the stack. Note that this results in both the current and the next image being the same image. While most operations takes and replaces the current image with a new one, operations that does not such as --text and --attrib will affect both the current and the next image until an operation replaces the current image.

Also remove the following as it is wrong when --dup is used and the documentation already states that it affects the current image :

Only the current (i.e., top of stack) image is affected, not any images further down the stack.

And finally makes sure that the wording of options makes it clears if the top is replaced or altered, most options are already clear but for example what --powc does is unclear.

What do you think ?