[Feature] Add UV alignment, orientation instructions in volume meta.json

[skyward7187]

What problem is your feature request solving?

Scrolls can be scanned upright or upside down, and slice ordering has two possibilities. Each combination requires inputting different --uv-align-to-axis or --uv-flip, uv-rotate operations into vc_render to orient the flattened segment properly for reading.

What is your feature request?

We should add support for volume-specific uv orientation instructions to the volume meta.json

What alternative solutions have you considered?

Edit all volumes: use the internal spiral information to rotate all volumes to be "upright and to have the same slice ordering. Downsides are the possibility of making mistakes, and the presence of uncorrected volumes already released to the public.

Is there anything else we should know that wasn't included already?

No response

Are you proposing to work on this feature yourself?

• I am willing to submit a pull request for this feature

Code of Conduct

• I agree to follow this project's Code of Conduct

[stephenrparsons]

There are a few considerations to include here, and it should be inclusive of other manuscript forms like books/codices, not just scrolls. Do these variables (names could probably be improved) cover it? vc_render could then make informed choices about UV rotation and flip, as well as normal vector orientation.

• handedness: ["right", "left"] based on whether the slices, stacked bottom-to-top from Z=0, reflect real-world geometry or whether a flip is necessary (separate from the orientation of the scanned object within the volume, which could be upside down or sideways, handled by the next variable). Informs --uv-flip
• uv-align-to-axis: ["+X", "-X", "+Y", "-Y", "+Z", "-Z", "null"] to define UV rotation (not always consistently defined, e.g. with a folded document). Informs --uv-align-to-axis
• recto-orientation: ["concave", "convex", "+X", "-X", "+Y", "-Y", "+Z", "-Z", "null"] based on which best defines the expected recto (not always consistently defined, e.g. with a folded document). Informs a now parameterized --orient-normals

[csparker247]

Internally, this functionality has been desired for a long time, and I think it would dramatically improve the interpretability of vc_render outputs. I've seen too many people tried to read "text" that would be impossible given the orientation of the UV map. I'm open to an extension of the volume metadata which provides this. I'm unlikely to work on this in the near future myself, but I'll happily review a PR for it!

An idea from years ago was to annotate the volume with landmarks which could then be used as orientation references. This has a theoretical advantage of being able to support auto-alignment for sample types beyond books and scrolls, or even just books or scrolls in a weird scan orientation. That said, it would be a complicated system, so I don't think it's necessarily worth doing at the moment unless this strikes someone's particular fancy.

I like this generally, and I haven't fully thought through edge cases for this, but some initial thoughts:

• I would like this to be opt-in functionality. Whatever the final structure ends up being, I think it should be grouped inside the volume metadata, and if the group isn't there, just do current default behavior. And as with most things in VC, command-line flags take priority over embedded configurations. Possible example:

  {
    "type" : "vol",
    "orientation": {
      "handedness" : "right"
    }
  }

• * **handedness**: ["right", "left"] based on whether the slices, stacked bottom-to-top from Z=0, reflect real-world geometry or whether a flip is necessary (separate from the orientation of the scanned object within the volume, which could be upside down or sideways, handled by the next variable). Informs `--uv-flip`
  

  Because I'm very slow, it took me a minute to realize this was a reference to the handedness of the coordinate frame, so I'm just wondering if there's a better term we can use here. But generally yes to the concept.

• * **uv-align-to-axis**: ["+X", "-X", "+Y", "-Y", "+Z", "-Z", "null"] to define UV rotation (not always consistently defined, e.g. with a folded document). Informs `--uv-align-to-axis`
  

  Sometimes I forget what this flag means. Align the +V axis to 3D axis VALUE, right? Then how about uv-up or uv-down or something more descriptive of tge part of the UV which is getting aligned. Also, supporting an arbitrary 3D vector in addition to one of these named values would be trivial and would handle objects in weird orientations w.r.t. the scan.

• * **recto-orientation**: ["concave", "convex", "+X", "-X", "+Y", "-Y", "+Z", "-Z", "null"] based on which best defines the expected recto (not always consistently defined, e.g. with a folded document). Informs a now parameterized `--orient-normals`
  

  I don't know about "recto" in non-document contexts, but I get the desire to name is something more object-centric than the "normals."

• Instead of storing null, I'd generally suggest just making these keys optional.