Reference an OCIO Import or Export Transform using a single string syntax

まず、issueで言及されているConfig APIの提案と、既存のColorSpaceTransform、DisplayViewTransform、FileTransform、NamedTransform、Processor、Contextの各概念を確認してください。実装の前に、サポートする構文、方向の扱い、コンテキスト変数、シリアライズ規則、エラー動作について議論で明確にしてください; 完了条件は、このたたき台に基づくパッチではなく、合意されたAPIおよび構文仕様です。

Problem Statement

There are three primary means for applications to use OCIO to transform colors to or from a working color space: ColorSpaceTransform, DIsplayViewTransform, and FileTransform.

Sometimes it's convenient to be able to specify the arguments for doing that as a single string. Many applications do this already to support the ColorSpaceTransfom case. That string is simple, it's just the color space of the incoming media.

In fact some applications or frameworks are setup so that they would like to always have just a single string to hold this information (particularly applications that were designed in the OCIO v1 era). This came up recently during the OpenTimelineIO color management discussions. It would be nice to have a single string that could be associated with a piece of media that would describe to OCIO how to convert it to a working color space.

In the case of OTIO, the use-case was primarily around converting into a working space on import. But there are other use-cases where this would be helpful to convert from a working space on export. It would be helpful if the syntax could support both directions. Though typically, it will be clear from the context which direction is involved, so it might not need to be explicitly stated.

One complication for such a syntax is that OCIO is very flexible in terms of how it allows color spaces to be named. The only characters that are disallowed are the ones used to define context variables. What characters should be used to break the string into tokens? Another complication are context variables themselves, should the syntax allow specifying an arbitrary set of string/value context variable pairs?

It might be nice if the syntax was essentially invisible for the simple cases. In other words, if it is just a color space name, then that's the complete string "<colorSpaceName>". Similarly, the DisplayViewTransform arguments could be "<view> (<display>)", which is already a common way of combining the display and view into a single string. And as long as the FileTranform has an extension, the LUT file name could typically be disambiguated from the other cases without any additional syntax.

Of course, while that is nice and simple, there are potential ways it could fail. For example, a color space could use parentheses so that it looks like a "view (display)" combination. It is unlikely that both of those possibilities would exist in a single config, however, there is probably a need for a more verbose but flexible syntax that could be used in cases where the intent might not be clear, even within the context of a given config. And it might be helpful to allow specifying other information.

Proposal

Here is a proposal for a single-string syntax that applications could use to with OCIO to import to a working color space or export from a working color space. There is a both a "simple syntax" and a "flexible syntax".

Simple Syntax

ColorSpaceTransform: This is simply the color space name.
DisplayViewTransform: This uses parentheses to separate the tokens "<view> (<display>)".
FileTransform: The string is simply the name of the LUT file. If a relative path is provided, the config search_path could be used, along with whatever other information the application might have, to resolve the path.

Flexible Syntax

ColorSpaceTransform: "ociocolorspace: <colorSpaceName>"
DisplayViewTranform: "ociodisplayview: <viewName> {<displayName>}"
FileTransform: "ociofile: <filePath>"
NamedTransform: "ocionamedtransform: <transformName>"

In the DisplayView case, if either the display or view name use the "{" or "}" characters, they would need to be escaped with a backslash.

Any of these could then be followed with context variable tokens as follows: "| <cvName1>=<cvValue1> | <cvName2>=<cvValue2> |"

For the FileTransform case, additional parameters such as CCCId, CDLStyle, and Interpolation could be specified similarly to context variables. For example: "| Interpolation=tetrahedral |".

The working color space for the transform may be added similarly: "| workingSpace=<colorSpaceName> |". This would be helpful to invalidate the string if the working space later has changed.

The inverse direction would be added as: "| direction=inverse |". Note that this could be relevant for DisplayViewTransform as well as obviously FileTransform and NamedTransform.

The parser will strip extra white space such as spaces and newlines, if that is helpful to keep the flexible syntax human readable.

API

We would add a function to the API as a method of the Config class that would accept a working color space name, a direction (forward/inverse), and the string (either simple or flexible syntax) and return an OCIO Processor object of the necessary type. It would throw if the string could not be interpreted. (If we don't want to support context variables, it could return a Transform object rather than a Processor, which would be more useful in some cases.)

We would add the inverse function that would take an enum to choose between Simple or Flexible syntax, a ColorSpaceTransform, DisplayViewTransform, or FileTransform, working color space, and a Context object (which could be null) and return the string. If Simple syntax is requested but not supported, it would throw. We would add a similar function that takes a NamedTransform (since it is not a Transform).

Limitations & Assumptions

One assumption is that a config file would need to be provided along with the string, it's not intended to be meaningful on its own (except in the case of a FileTransform).

Another assumption is that the direction (to or from working space) will be clear from the context.

Another assumption is that when this string is generated, the desired working space that the transform converts to (or from) is known. Furthermore, if the working space is later changed, any existing strings would potentially be invalidated. Certainly that would be true for FileTransform, but it could be true in other cases too, for example, if the the image state of the working space changes from scene-referred to display-referred, or vice versa.

Conclusion

That's a rough strawman to start the conversation. Let's start the discussion around what functionality is desired first, before getting into details of the syntax, which I'm sure could be improved later.

For reference, here is a related request in the ColorInterop issues.