ACES Metadata Spec Draft

Discussions - ACESNext VWG – ACES Metadata File (AMF)
1

All,

Attached is a draft of the ACES Metadata File Specification that’s ready for comment.
Please have a look and tell us what you think. It’s critical we get feedback on this quickly to keep ACES 1.2 on track, so the sooner you can provide any feedback the better.

Thanks so much!

S_2019_00x_AMF_DRAFT_2019.11.14.pdf (1.4 MB)

S-2019-001-AMF_DRAFT_2019.11.25.pdf (985.9 KB)

S-2019-001-AMF_DRAFT_2019.11.26.pdf.pdf (983.6 KB)

S_2019_00x_AMF_DRAFT_2019.12.19.pdf (978.5 KB)

S_2019_001_AMF_DRAFT_2020.03.11.pdf (1010.6 KB)

The overleaf project can be found here:

The latest xsd and examples can be found here :
https://github.com/aforsythe/amf/tree/clean
https://github.com/aforsythe/aces-dev/tree/amf_modifications (moved to aces-dev repo after release of RC1)

2

Do you think it would be possible to add some sort of “outline” that isn’t the UML object model (it’s so tiny that it’s hard to read) and isn’t as dense and “code-y” as the schema. Basically just “plain text” outline/overview so that it’s easier to see the overall structure of the format before we get into the details about each type, element, etc.?
I know it’s a bit redundant but I think it would help a lot with readability and understanding.

1 Like
3

That’s a really good point Scott, and I agree with you. Maybe we can add a simpler block diagram (with required elements only, even) to show an example in a more digestible form.

4

Hey all … just wanted to let everyone know the plan is to get this to the Architecture TAC for review by the end of this week. If you have any feedback on the document, please submit it as soon as possible. The earlier the better.

Thanks
Alex

5

Hi all,

We have restructured and fleshed out the Scope & Introduction sections and polished up some of the language across the document (see Overleaf for a live view).

PDF version is attached here with today’s date:
S_2019_00x_AMF_DRAFT_2019.11.19.pdf (1.8 MB)

Also added the following diagram to show the structure of AMF in visual form:

AMF_Diagram_lowres
AMF_Diagram_lowres2228×1138 147 KB

I received a couple of comments that it would be nice to have an <author> element added next to <creationDateTime> and <modificationDateTime> to indicate who created or modified it. Thoughts?

Any other comments or suggestions on the current draft, please let us know. You can also message me or Alex directly if you prefer.

Thanks,
Chris

3 Likes
6

@CClark Thanks for posting the new version!

Does anyone have direct feedback on this version? We are really in need of some comments one way or the other.

7

Thanks for adding the overview diagram in the Introduction - I think that helps a lot for setting the basic understanding of an AMF structure. Overall, the document looks good - dense - but good. I’m not really an XML expert so I can’t validate each and every Type but here are a few thoughts on the first few sections.

General - Many instances of " facing the incorrect direction. Replace " with `` ‘’ in LaTeX to avoid this.

4.2 - Reference is a bit ambiguous - be specific. Even though I know which document you are referencing, the document is called Academy S-2014-002, Academy Color Encoding System - Versioning System (this is also how you have it listed in your references)

5.1, P2 - maybe add “while ensuring they are all applied in the correct order and in the working space for which they were designed” ?

The dense XML type sections will require some more time for me to peruse. I will try to add more comments tomorrow…

2 Likes
8

Uploaded a new version of the document … see above

9

Hi all.
So AMF seems to be now back to its original scope: an ACES-only color pipleine
So I assume wider scope like including non-ACES color pipelines too isn’t in the radar any longer.

I have three suggestions to make. I will use one topic per suggestion.

1.
Following on conversations had with Alex in Amsterdam during IBC, I strongly suggest properly using XML namespacing for all of AMF’s XML elements, instead of having most critical elements with an element name starting wtih “aces-” suffix. Either ampas or aces namespaces are good candidates (and they should be referenced in the AMF root element via an xmlns:aces attribute).
Reasons for this are:

  1. Less amiguous XML syntax (from a purely Computer Science perspective);
  2. It helps when AMF extends other XML-based files (e.g. project files from editorial, color-grading or VFX software); needless to say that apps like Apple Final Cut, Autodesk Flame, FilmLight Baselight and Foundry NUKE all have XML-based project files which may benefit from embedding AMF pieces inside.
  3. It helps when AMF is extended by non-AMF elements (ASC CDL is just one of the few).
  4. One has a “cleaner” syntax using elements like <aces:archivedPipeline> rather than <archivedAcesPipeline>.
10

2.

I think that there is a duplication of children elements among clipId and fileInfo (and, again, <aces:clipId> …), which may be merged into one clip-referencing element that uses either either filename and metadata as reference anchor(s). Currenlty, filenames can be specified in either <file> child and <clipName> and in the independent <fileInfo> elements, which is ambiguous. I think only the former of the two (file) should stay.

Most importantly, a table is needed to match the value of clipId element with one specified metadata per every major file format (OpenEXR, REDCODE, ARRIRAW, MXF, DPX, MP4, QuickTime, etc.). During recent talk with Chris I told I could produce one, which I still need to find out spare time to realize. Hope that, when it’s ready, file-format maintainers (especially those for camera-native formats) will come out and speak up to complete/fine-tune this list.

This one-to-one corresponding list is however, not enough for generic (and usually more complex) production cases, where you might want to stick an AMF to a different metadata. For example, what if your production workflows uses a clip’s starting ToD TimeCode to attach AMFs? Let’s think to a live recording scenario (e.g. sports event).

Therefore I proposed several time that a fourth element, called <metadata> is introduced, whose attribute is the file-format maintainer’s original header metadata name. Multiple istances of it may be present – not just 0-1 occurrences.

For example, a severly over-specified example for R3D would be:

<aces:filename>A012_C009_FB1119_001.R3D</aces:filename>
<aces:clipId>A012C009</aces:clipId>
<aces:uuid>723n84n238n7239nc492349823n929</aces:uuid>
<aces:metadata name="reelName">A012_C009_FB1119</aces:metadata>
<aces:metadata name="ToD">2019-11-25T12:23:48-0800</aces:metadata>
<aces:metadata name="VITC">00:01:18:24</aces:metadata>

Understandably in real-world scenarios, just any one of the above six different lines is likely sufficient to uniquely bind the AMF to a particular clip. Using more than one at the same time, however, has the advantage that when the R3D file is transcoded – during the many stages of near-set, VFX prep, editorial, online, color-grading, compositing, mastering, versioning – there’s a higher chance at least one clipId reference sticks from one conversion to the next. Therefore, there’s a higher chance that the binding between the ACES pipeline (in the AMF) and footage is not broken.
Can you see?

  • some format conversions may preserve filename;
  • some other format conversions may preserve just eihter one of the TimeCodes;
  • some other format conversions may preserve the UUID:
  • etc.

Ultimately, in an effort to preserve enough production metadata deep throughout the pipeline (from camera-natives down to finished, archived masters), the more metadata are used, the better it is.

11

3.
History / color-pedigree / archived pipelines

I think one additional level is requred here. Currently, the draft spec only allows for one archived preview, as the <archivedAcesPipeline> only hosts one inputTransform, one lookTransforms, one outputTransform, etc.

Instead, an <aces:archivedPipelines> (or <aces:history>) element should contain zero or more occurrences of an <aces:archivedPipeline> element. Such element may be complemented by optional name= or uuid= attributes to further describe the single archived pipeline. It also contains a whole replica of a previous AMF piepline inside.

This way the whole ACES footage history can be rebuilt - for either Content-Protection or workflow purposes.

12

@walter.arrighetti The fileInfo is information about the AMF file not the essence as in clipId.

fileInfo is of the type infoType and the list level children are description, dateTime, and uuid.

clipId is of the type clipIdType and the list level children are sequence, file, and uuid.

13

Ah ok sorry for that Alex, now all is clear. What do you think of the optional and flexible <metadata> (0+ instances) in the same comment ?
Also, that was the third post (3.) about my comments on the draf.
Did you get a chance to read the other two: 1. and 2. ?

14

@walter.arrighetti I don’t think this is true. You can currently have 0-10 <archivedAcesPipeline> elements. The intention here was to simply change an <acesPipeline> to <archivedAcesPipeline>. No need to imbed it in another nested tag. The group talked at length about the role of the <archivedAcesPipeline> and felt it was probably best practice to have an AMF per output device and/or essence. The group felt one monolithic AMF would become too big, too complex, and too confusing. Obviously this is a matter of perspective and opinion.

Currently we are using amf as the namespace. There isn’t any real reason we need to stick with that but your point is a good one and I’ll update the examples to explicitly use the namespace. I see your point about using aces as the namespace and shortening the element names. It’s interesting but I’d love to hear other’s opinions. Just a bunch of work to modify the documentation and we are already late in getting this to the TAC for review.

Frankly I’m not sure I understand the proposal for the per-manufacturer table. The goal of AMF isn’t to transport all camera metadata. It’s to communicate an ACES viewing pipeline. I understand there may be value in providing a standardize container to transport other camera metadata but much like the conversation around framing it just seems out of scope right now. Am I misunderstanding out this is critical to the communication of an ACES viewing pipeline? We’d also discussed trying to minimize the use of attributes which obviously your metadata element proposal utilizes heavily. That’s just an detail but the key is scope and adoption.

1 Like
15

I’ve posted the change to the examples with the explicit use of the namespace here :

I’ve created an alternate version changing the namespace from amf to aces, modifying tags to remove aces where appropriate, and changing fileInfo to amfInfo for clarity. It’s posted here :

I’d love to hear everyone’s thoughts.

16

All, I’ve posted the updated document above that reflects the changes to the namespace and element names based on the feedback.

Please take a look and let me know what you think.

17

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).
18

@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 : Overleaf, Online LaTeX Editor

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.

19

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

20

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