fix(IBA): reorient() cases for transpose and transverse

[luna-y-kim]

Orientations 5 and 7 were swapped: case 5 produced transverse and case 7 produced transpose. Fix both cases.

Also, fix the orientation labels for 6 and 8 in the metadata conventions docs.

Fixes #4661

Checklist:

• I have read the guidelines on contributions and code review procedures.
• I have read the Policy on AI Coding Assistants
  and if I used AI coding assistants, I have an Assisted-by: TOOL / MODEL
  line in the pull request description above.
• I have updated the documentation if my PR adds features or changes
  behavior.
• I am sure that this PR's changes are tested in the testsuite.
• I have run and passed the testsuite in CI before submitting the
  PR, by pushing the changes to my fork and seeing that the automated CI
  passed there. (Exceptions: If most tests pass and you can't figure out why
  the remaining ones fail, it's ok to submit the PR and ask for help. Or if
  any failures seem entirely unrelated to your change; sometimes things break
  on the GitHub runners.)
• My code follows the prevailing code style of this project and I
  fixed any problems reported by the clang-format CI test.
• (N/A) If I added or modified a public C++ API call, I have also amended the
  corresponding Python bindings. If altering ImageBufAlgo functions, I also
  exposed the new functionality as oiiotool options.

[lgritz]

Are you sure this description is correct?

If this is default orientation 1:

    0--->
    1--->
    2--->

and this is orientation 6, rows right to left and columns top to bottom:

   2 1 0
   | | |
   v v v

Wouldn't you say that the second pattern is rotated clockwise from the default?

[lgritz]

The orientation codes are so inherently confusing to think about in words.
I really think that ultimately, we should illustrate this with a picture as well as the words (not necessarily on you to do in this PR).

I also think, if we don't have it, we really need a testsuite verification of reorient for EACH of the 8 values. I guess we don't, or the code change you made would either be failing tests, or be accompanied by updated reference images? I have to admit I'm afraid to accept this change in behavior without a visual test that proves that the new code definitely does the right thing.

[luna-y-kim]

The orientation codes are so inherently confusing to think about in words.
I really think that ultimately, we should illustrate this with a picture as well as the words (not necessarily on you to do in this PR).

Yes, the wording is super confusing. A visual illustration sounds good. That'd be helpful.

Also, the intro paragraph in the display hints docs does define the ordering convention, but still it requires some eyeballing for me. For values like 6 and 8, I couldn't tell which part of '(right to left, top to bottom)' described what.

[lgritz]

It feels like the right order of operations is:

1. Create an orientation=0 image that is small but clearly and visually shows the orientation. Then transform it to each of the 7 other orientations. We look at them and agree that we are all confident that all 8 exactly match what the TIFF spec says the orientation values mean.
2. Make a testsuite test that, for each of those 8, does a reorient() and ensures that the result exactly matches the orientation 0 we started with.
3. Use that testsuite to validate this PR and merge it.
4. Use those same images to produce a figure that augments the description of orientation in the stdmetadata.rst.

Without the visual example (and multiple people looking it over), I honestly don't trust myself to get this right just using the words and my head. It's really easy to make mistakes when reasoning about it.

[lgritz]

Maybe something that looks like this:

+------------------------+
| O -------------------> |
| |               cols   |
| |                      |
| |r                     |
| |o      [LOGO]         |
| |w                     |
| |s                     |
| |                      |
| v                (1,1) |
+------------------------+

[lgritz]

oh no, did I already mix up rows and columns?

[lgritz]

It's even confusing visually :-)

Does "cols" mean "this line is an example of a column" or does it mean "column indices increase in this direction?"

[lgritz]

Better?

+------------------------+
| O ---row 0-----------> |
| |                width |
| |                      |
| |c                     |
| |o      [LOGO]         |
| |l                     |
| |0                     |
| |                      |
| v height         (1,1) |
+------------------------+

[lgritz]

I want to make something that nobody could possibly look at and still be confused. :-)

[luna-y-kim]

Does "cols" mean "this line is an example of a column" or does it mean "column indices increase in this direction?"

That is exactly what confused me.

                   Top
        +------------------------+
        | <--- col 0 --------- O |
        |                      | |
        |                      r |
        |                      o |
Left    |                      w |    Right
        |                      0 |
        |                      | |
        |                      | |
        |                      ↓ |
 (1,1)  +------------------------+
                 Bottom

An example of Orientation 6.
In addition to your sketch, top/bottom/left/right tags could be helpful.

[luna-y-kim]

It feels like the right order of operations is:

1. Create an orientation=0 image that is small but clearly and visually shows the orientation. Then transform it to each of the 7 other orientations. We look at them and agree that we are all confident that all 8 exactly match what the TIFF spec says the orientation values mean.
2. Make a testsuite test that, for each of those 8, does a reorient() and ensures that the result exactly matches the orientation 0 we started with.
3. Use that testsuite to validate this PR and merge it.
4. Use those same images to produce a figure that augments the description of orientation in the stdmetadata.rst.

Without the visual example (and multiple people looking it over), I honestly don't trust myself to get this right just using the words and my head. It's really easy to make mistakes when reasoning about it.

I think I should've done this before opening the PR. I thought I understood it correctly. Lesson learned. I'm going to work on step 1 and share soon!

[lgritz]

In addition to your sketch, top/bottom/left/right tags could be helpful.

But not IN the image. If we're showing how each one should display, top is always top, etc. but the contents of the image rotate.

OH, I just realized I described the process incorrectly. (See? Confusing!) I think the correct description is:

1. Create a single small image that clearly shows origin, direction of rows and columns, etc., and make 7 more copies with the same pixel order but each of the other 7 "Orientation" metadata values. Shown in iv or some other viewer that tries to honor Orientation, we should clearly see each one in a different orientation and agree that they match what the TIFF spec describes.
2. Make a testsuite test that, for each of those 8 images, does a reorient() that results in an image with Orientation 0, but the pixels have actually been changed so that it matches what we saw in the viewer in (1). (The correct versions of this should be checked in as reference images.)
3. Use that testsuite to validate this PR and merge it.
4. Use those same reference images to produce a figure that augments the description of orientation in the stdmetadata.rst.