ACES Metadata Spec Draft

Tags: #<Tag:0x00007f117cb30710>

Hi Alex/Chris,

Off to a good start! I wanted to get you some initial feedback, although TBH I’m finding the document a bit difficult to navigate. The Use Case / Workflow examples are great but after that one is thrown into a bit of a puzzle to decipher a huge list of type/element definitions. Some ideas:

  • Perhaps add a section between the Use Case and Data Model sections to introduce the way AMF works at a basic level, ideally using an example XML with some of the less important parts omitted for clarity.
  • Perhaps make an alternate version of the data model diagram that trades off UML precision in order to be a little easier to read.
  • Perhaps add a table of contents entry to the PDF for each element to make it easier to jump back and forth between elements.
  • You might want to consider whether each element really needs to take up almost a full page.

My main feedback at this point is mostly relative to the Look file. I started a thread called “LMT color space tags” on Sept. 9th to discuss the to/from Look working space transforms. I’d like to reiterate my proposal that the <toLookTransformWorkingSpace> tag be dropped and only the <fromLookTransformWorkingSpace> be kept. (I’ll refer you to that thread for the motivation.) If that fails to convince, perhaps just make the “toLook” one optional?

Also, it would be helpful if the spec would clarify what is allowed with respect to user-supplied transforms and how that is supposed to work. For example:

  • User transforms are allowed for Looks but are they also allowed for Look Working Spaces? It seemed the decision was “no” during one of the meetings, but the spec simply says that they must be Color Space Conversion transforms and then refers people to S-2014-002. Looking there it seems that CSCs may only be provided by the Academy. So it seems it is still a “no” but it is a lot of detective work required for such a crucial point – it seems like it should be spelled out more clearly.
  • For LookFileType the spec says that “Valid transforms for this element are Look Transforms” and says to use a transformID and refers again to S-2014-002. But I suspect many readers will still be left wondering if user-supplied transforms are really allowed and if so how that will work.
  • I believe the argument was that transformIDs are superior to a simple file name, but it is also less obvious how they are meant to be utilized. Clearly applications will need to associate the transformID with the file that contains the user look transform but there seems to be no discussion about how. Again this seems like a crucial topic and will undoubtedly be the basis for many of the interop problems encountered. Probably there is a desire to let people make this association in different ways, but to leave it totally as “an exercise for the reader” seems like asking for trouble.

I have not done a careful read at this point, but I did notice a few typo issues:

  • In the UML diagram, I guess red means required and blue means optional but is that stated anywhere?
  • In the UML diagram, the first instance of lookTransformWorkingSpace seems to use the wrong type (aces:fromLookTransformWorkingSpaceType rather than aces:lookTransformWorkingSpaceType).

@doug_walker, Thanks for the feedback … I really appreciate the in depth look at the document. Below are a few thoughts.

I think this makes a lot of sense. I agree the document can be a bit much to parse. I’ll see what I can do here once we have more feedback from the group.

Also agree … that was the goal of the diagram @CClark added.

This can easily be done and I actually had to figure out a way to remove them. They make the TOC very long but if that’s useful I’m fine with it.

The issue here is the diagrams and their visibility. They take up a lot of room but let me see if I can make them smaller and still legible.

I’m not sure we ever came to consensus on this point. I think the major concern here is under-specification. I agree there’s implementation details to work out here. Just as there’s a concern that the forward/inverse transform pair may not match, or may not be suitable accurate, I think there’s a concern that a lack of specification of one direction might lead to difference in implementation when the second direction needs to be calculated by the implementation. There’s obviously some systems out there that could handle this but others may not be able to match the results. I don’t know what the answer is here …

I think the decision was actually “yes” in the meeting around the 47-54, particularly at the 53:07 mark. I’ve created a draft of the Versioning Document that extends the CSCs to Vendor/User supplied here : https://www.overleaf.com/read/nkyjwnqbzbtx

I’ll see if I can clarify this

I think a lot of the issue around usage and association of the transformID with a particular file is workf or the implementation group, however, I believe the inclusion of a uuid was an attempt to provide another tool to make that association.

Yes, that’s the intention but I’ll add a legend.

Thanks for catching this … I think it was a search and replace bomb.

Thanks for the detailed reply Alex!

Regarding the proposed diagram, I was thinking it would help to have something at a level in between the one Chris did and the UML one. Reading the Use Cases and looking at Chris’s figure 1 gave me a clear impression of what AMF is, but not how it works at a syntactical level. In other words, I would keep figure 1 as is and consider adding something that is detailed enough to use the actual element names, but less comprehensive than the UML. Perhaps the diagram could just be an annotated XML file with the optional details abbreviated for clarity.

Regarding my suggestion about the table of contents, I was referring to the column on the left of PDF browsers, not the TOC on page 4 of the spec – I agree it would not be helpful to have them on pg 4. (Does OverLeaf allows them to be different?)

Of course, feel free to ignore my readability comments – just my 2 cents. My main concern is clarifying how the User Look stuff will work. I’ll look forward to your next draft.

Thanks for the updated Versioning spec. I noticed it does still have some references to ACESclip that should be updated too!

Doug

Hello,

Copy-pasting verbatim, and for the public record, the AMF Review notes that I sent, as a TAC member, to the ACES Leadership:


Hi,

Another batch of congratulations for the hard work! I have barely followed the AMF working group but this is really good looking so far. The document authoring style is sharp albeit hard to go through because of the sheer density of information.

I have rejected the proposal because of two minor things to correct and one that might require a little bit more work, all are super important to me though, hence my vote. Beside that and a question, most of the comments are stylistic and pedantic but they are striving to improve the consistency of the document, quite like my Review notes for CLF in that sense :slight_smile:

Academy Color Encoding System Metadata File (AMF) Specification - Review - S-2019-001-AMF_DRAFT_2019.11.26.pdf

Summary

  • [ Rejection Source ] I would really like to see an extra type added to support authors. We are often doing archeology of super old shows and knowing who did what is critical, see 7.1.
  • [ Rejection Source ] Some elements such aces:archivedPipeline or aces:lookTransforms have a maximum number of occurrences. The specification should not impose such limitations without good reasons. We do not know all the possible usages the specification will be subjected to and such premature optimizations are the root of all evil. I really mean it, never limit the system if you don’t have to, see 9.1 and 10.2.
  • [ Rejection Source ] Why a minimum of 1 RRT? If one is using the new SSTS based Output Transforms, the RRT should not be required or am I overlooking something? See 16.2.
  • I would like to discuss about the aces:lookTransforms, I would prefer having an element that is singular, like all the others, i.e. aces:lookTransform, and simply rely on inlining in-between the inputTransform and outputTransform elements. The lookTransformStackPosition attribute could then be dropped because XML is order preserving, see 10.1.
  • Reading the document was actually quite hard and I don’t think I did it a thoroughly as required, the short deadline does not help. That being said, I think that I would have preferred to see small XML snippets of every elements rather than the UML diagrams. They are not trivial to read.

Notes

  1. 5 Use Cases (Page 7):
    1. the application of “show LUT” LMTs: Missing spaces around “show LUT”.
  2. 5.2 On Set (Page 7):
    1. as a “look template” for use: Missing spaces around ”look template”.
  3. 5.6 Archival (Page 8):
    1. would allow you to link: Unneeded you reference in a technical document.
  4. 6.2.1.2 aces:tnToLookTransformWorkingSpace (Page 10):
    1. xs:pattern value="(ACEScsc\.\S +\.a\d {1}\.\d {1}\.\d {1})": Any reason for a capturing group in the Regex? Note that the patterns as formatted in the PDF document are invalid, e.g. spaces after \S, etc…
  5. 6.2.2.4 aces:cdlType (Page 13):
    1. ASC-CDL: Reaching the pedantry summit here but the CLF specification uses ASC CDL without a dash :slight_smile:
  6. 6.2.2.5 aces:clipIdType (Page 13):
    1. about the essence associated with the AMF: What is the essence here? Might be worth defining.
  7. 6.2.2.6 aces:dateTimeType (Page 13):
    1. [ Rejection Source ] Information about creation and modification date and time can be added but nowhere the creator nor its contact can be given. It can be critical information, even more so than the date and time depending on the context, especially when you dig things, 15 or 20 years after they have been done. I would really like to see an extra type added, maybe as follows:
      • aces:authors an array of strings: ["Foo Bar <foobar@onset.com>", "John Doe <johndoe@onset.com>"]
  8. 6.2.2.\d aces:\w+ (Page 13-14):
    1. Description:: Missing line breaks here.
    2. As I’m going through this, I wish there were some minimal XML element examples even if invalid because incomplete. I’m trying to infer how the XML structure will be, and it takes quite some effort.
  9. 6.3.3 aces:archivedPipeline (Page 20):
    1. [ Rejection Source ] Why a maximum of 10 occurrences? Premature optimisations and limitations such as this one should be avoided if not necessary.
  10. 6.3.7 aces:lookTransforms (Page 24):
    1. Most of the elements are singular, is there a reason why using aces:lookTransforms over aces:lookTransform? I understand that one might stack many of them, but why not having them simply inlined/sandwiched between the inputTransform and outputTransform elements? XML is ordered so you could get rid of the lookTransformStackPosition attribute. I can also see 2 probably erroneous references to aces:lookTransform, singular in the document.
    2. [ Rejection Source ] Why a maximum of 5 children? Premature optimisations and limitations such as this one should be avoided if not necessary.
  11. 6.3.16 aces:file (Page 33):
    1. How are the paths expected to be expressed? Relative, absolute?
    2. Choice of aces:file, aces:sequence or aces:uuid is required: Typo on sequence.
  12. 6.3.18 aces:clipIdType / aces:uuid (Page 35):
    1. Choice of aces:file, aces:sequence or aces:uuid is required: Typo on sequence.
  13. 6.3.23 aces:lookFileType / aces:transformId (Page 40):
    1. The diagram is inconsistently extremely large.
  14. 6.3.28 aces:asc-cdl (Page 46):
    1. See 10.1 with respect to having singular, inlined aces:lookTransform elements.
  15. 6.3.32 aces:lookFile (Page 49):
    1. See 10.1 with respect to having singular, inlined aces:lookTransform elements.
  16. 6.3.37 aces:referenceRenderingTransformType (Page 54):
    1. Valid transforms for this element are Reference Rendering Transform (RRT).: So it is an interesting case here, Transform is singular, there is only one RRT, the current but should not it be Transforms when accounting for past versions?
    2. [ Rejection Source ] Why the minimum of 1? If one is using the new SSTS based Output Transforms, the RRT should not be required right? I’m rejecting because I might have overlooked something but I would like a definitive answer :slight_smile:
  17. Samples (Pages 62-68):
    1. Oscar Winning Movie: I find that kind of humour a tad mis-placed in a technical document, I know, this is pure pedantry… :slight_smile:

Cheers,

Thomas

Hi Alex.
Thanks for clarifying about the multiplicity of <archivedAcesPipeline> elements. I didn’t understand beforehand and I’m fine with the XML hierarchy you just explained.

As regards the manufacturer table (let me clarify: just one global, 2-columns table – not a table per each manufacturer), this is a workflow requirement.

Currently, AMF links to footage via either filename (too loose) and <clipID> (ClipID). However, which exact camera-native metadata corresponds to the ClipID of AMF is still undefined.

While some cameras and file formats have, at most, one unique clip identifier, that may be implicilty mapped to AMF ClipID, many professional cameras (and other file-formats) have potentially multiple identifiers, like:

  • absolute TimeCode,
  • ToD timecode,
  • EdgeCode,
  • reel name,
  • short clip name,
  • long clip name,
  • UUID,
  • KeyKode,
  • file hash / digest,
  • etc.

If we don’t provide indication as to which camera-native metadata maps to ClipID, several production workflow ambiguities may arise.
For example:

During DI, an online conforming software B parses an AMF’s <ClipID> by looking for footage matching it vs the short–clip–name metadata, whereas the on-set department’s off-loading software A had been generating the ClipIDs based upon the camera files’ UUID-v4 metadata. Result: no automated color pipeline would be expected out of this scenario.

Therefore, at least identifying one metadata per camera-native format would be necessary.

The further proposal for an optional <metadata> element is due to the requirement to provide a ClipID that can be flexibly assigned to different camera metadata, according to the specific on-set / production workflow.

If we don’t allow this flexibility, we are constraining production workflows to conform or associate ClipIDs to metadata that may change according to production pipelines that may not be color-related (e.g. location-based).

Happy to briefly discuss further via chat, if needed.

Plese note that nested XML ements may be used, within <metadata>, in place of XML attributes, if the latter are to be avoided. This can be trivially specified.

Thomas raised a number of interesting points, but I wanted to second his criticism of the lookTransformStackPosition. I had also raised this point during one of the meetings.

For implementors it is always a bit of a hassle to have a file format provide a given piece of information in more than one way. It means that the code needs to handle more than one path for obtaining it and also handle the case where a given file provides contradictory information. It also adds additional QA and testing work.

In this case one could argue that the lookTransformStackPosition is in fact the only official way to specify the order but the problem is that the ordering of the XML file itself is the more “natural” order both to human readers and in terms of what is returned from an XML parser.

I would advise the implementation VWG to add that case to their test plan – namely, where the two orderings disagree.

Doug

During preparation for work in the AMFImp VWG a few questions came up here in our team when reading the current version of the AMF specification. These topics probably have been discussed in the AMF VWG already, so my appologies for rising that again.

1. “applied” attribute

The amf:asc-cdl and amf:lookFile have an “applied” attribute. As far as I understand this means, that the look transform is “baked in” the footage already.

What would be a typical use case for using the “applied” attribute?

In my understanding if the look transform is baked in, also the input transform will be “applied”. Does the input transform to be marked as “applied” then as well? Or is this attribute indicating that the clip is even rendered with certain output transform (such as “dailies in Rec.709 with look applied”)?

2. “amf:hash”

I think this is clear for example for a referenced ASC-CDL file, but what is hashed when it’s used in the context of for example an input or output transform? The underlying CTL file?

Any insights would be appreciated. Thank you!

The questions have been answered in the AMFImp VWG meeting, thanks to everyone. Here are the short versions (as far is I understood):

  1. “applied” is used for example with an input transform for footage that originally had been in a camera native color space, but has been transferred to OpenEXR in ACES color space. Then the IDT is already applied, but carried in the AMF for reference.

  2. amf:hash is an optional tag, that you would probably not use for “standard” input and output transforms, but is intended rather for custom transforms.

@Thomas_Mansencal @CClark
I’ve added an <aces:author> element with subelements for <aces:name> and <aces:emailAddress>. From what I can tell XML does not support array formats as in @Thomas_Mansencal example.

@CClark @doug_walker
I’ve removed the lookTransformStackPosition attribute from aces:lookTransformType.
The order in which the lmts is applied shall be based on the order they appear in the AMF XML.

@CClark
I’ve removed the restriction on the number of lookFile or asc-cdl elements that can occur in the aces:lookTransforms element. Also, I’ve removed the restriction on the number of aces:archivedPipeline elements.

@CClark

Changed the movie names in the descriptions used in the examples.

@CClark

changed example file extensions from .xml to .amf

@Thomas_Mansencal I’m open to this … makes sense to me. FYI … there’s a lookTransformsType and a lookTransformType this is intentional with the current structure.

Now that we’ve decided to remove the lookTransformStackPosition and rely on the order in the XML I believe it might make sense to move each Look Transform to the top level.

That raises a question though that I haven’t fully thought through the implications of … should I then eliminate the <asc-cdl> and <lookFile> nodes underneath <lookTransform> and perhaps indicate the if it’s a CDL or a file via an attribute on <lookTransform>
(e.g. <lookTransform type='cdl' applied='false'>)

It looks like I can’t restrict the children of an element based on the attribute of the parent element …

So … I’ve added a choice under lookTransform where lookTransform will either contain the contents of what what previously in asc-cdl or lookFile plus the other common elements (e.g. description).

Let me know what you think …

All,

Per @dtatut comment at the meeting … I’ve updated the algorithm attribute of the hash tag to use the standard URIs.

Hi Patrick.
I think your raised bullet question #2 has not been completely aswered yet.
It’s true that the <hash> is mostly for custom transforms, but it may still be useful to have it in Academy-provided transforms to make sure that a particular implementation of a project doesn’t override standard transforms (for example, the Academy RRT) with “tweaked” ones.

The specification should clearly state the order of precedence by which the hash is computed (digested) on. I would propose this ordered set of alternatives:

  1. if the transform is specified by, at least, a <filename> element (for example, a LUT file), then the value is the hash of the whole external file; otherwise,
  2. if the transform is specified by a <transformId> element, then there should be a reference CTL for that TransformID, that the hash is computed against.

Please note that, in case of non-Academy provided transforms, the corresponding CTL does not need to be public – just the hash is. That also works with vendor-supplied transforms, that can be at least referenced by TransformID (and whose conformance is checked by means of a hash), even if the CTL is not publicly available to users.

Currently this is specified as a string. Does it make sense to change this to anyURI and offer guidance in the spec? I’m not sure about relative vs. absolute. Any thoughts here?

Hi Alex,

This is great! Only caveat here though is that there is only a single author possible, it might be enough for practical purposes but quite certain that the question about multiple authors will come :slight_smile: Alternative would be a single authors string like that: "Foo Bar <foobar@onset.com>, John Doe <johndoe@onset.com>".

I quite like it from initial perusal, feels much more elegant! Here is the AMF file with both CDL and LMT nodes I was looking at: https://github.com/aforsythe/amf/blob/70443b306a92b72e950e130b784e70d7fd8f8cc9/example3.amf

Good idea, if adopting anyURI, it would be like that:

../path/to/aces.amf
file:///C:/path/to/aces.amf
file:///Users/John/path/to/aces.amf

Cheers,

Thomas

I set that there could be an unlimited number of author tags. See the example :

This would be much more easily parsed by software too.

I agree!

Sounds good