feat(IBA) scale

[antond-weta]

Description

Implements IBA::scale, an algo which takes two images, one of which is required to be a single channel image, each channel of the other image gets multiplied by that single channel, per pixel.

Tests

I have added tests for the C++ code, python code, oiiotool, and the documentation examples

Checklist:

• I have read the contribution guidelines.
• I have updated the documentation, if applicable. (Check if there is no
  need to update the documentation, for example if this is a bug fix that
  doesn't change the API.)
• I have ensured that the change is tested somewhere in the testsuite
  (adding new test cases if necessary).
• If I added or modified a C++ API call, I have also amended the
  corresponding Python bindings (and if altering ImageBufAlgo functions, also
  exposed the new functionality as oiiotool options).
• My code follows the prevailing code style of this project. If I haven't
  already run clang-format before submitting, I definitely will look at the CI
  test that runs clang-format and fix anything that it highlights as being
  nonconforming.

[lgritz]

This is a behaviour changes for mul(). Maybe that's fine, but we should certainly document it, and maybe think hard about if we want it.

Are we prepared to say that any time somebody multiplies an n-channel image by a 1-channel image, they mean to scale all channels by that one value? Is there ever a case where people would not want that? (I honestly don't know.)

[antond-weta]

I don't have a strong opinion on that one. Happy to omit that bit and just go with the new algo.

[antond-weta]

I does look weird when the alpha is scaled, as you mentioned, but on the other hand this behaviour is consistent with mul() used with a single scalar.

[lgritz]

I think that's fine.

I wonder... if maybe we should get in the habit of adding a KWArgs parameter to all new IBA functions (and, slowly, adding them to exiting ones when the occasion pops up that we have to modify them for other reasons), even if we don't have any keyword args to respond to at this moment, as a placeholder for future expansion without needing to alter the ABIs or add more functions. In this case, that would make it more palatable to pick a reasonable default behavior (just scale all channels) for now and then in the future, we can very easily accommodate an option that would cause the alpha to not be scaled.

[antond-weta]

We could add a KWArgs parameter to scale(), ignored for now; and another one to mult(), with an option to override the existing behaviour when the second (or any?) argument is single channel. I'm happy to make this change and update the docs if you think this is worth doing now.

[lgritz]

Let's not add it to mul (which would either break compatibility, or cause yet another set of mul versions to be added) until we have a desired use.

But let's add it to scale() now -- it costs nothing and has no compatibility issues for a "new" IBA function, and future-proofs the API.

[antond-weta]

I've added a KWArgs parameter to scale(), and removed the changes from mul() for now.

[lgritz]

So is your opinion that this scaling is a purely mathematical operation? No semantic meaning to the channels, including alpha? So if you have one image with RGBA=(1.0,1.0,1.0,1.0) and the scale image is 0.5, you should get (0.5,0.5,0.5,0.5), and definitely not (0.5,0.5,0.5,1.0)?

I think that's reasonable, I just want us to be clear about the assumptions we're making. I guess if somebody doesn't want alpha to be scaled, they could use the ROI to limit the scale to just the first 3 channels?

[antond-weta]

Yes, that was the idea. I guess, we could introduce an option to treat the alpha channel differently, if needed. I'm not sure if that would be more convenient than using the ROI.

[antond-weta]

This should be ready for review now