Skip to content

Commit 2bbbdb8

Browse files
committed
merge work-in-progress branch 'update-docs' into dev
* update-docs: add placeholder "intro" pages for AMF and CLF lots of reorganization of directory structure and ordering/layout in nav update transformId page add to acronyms add gitignore and hide .cache files update html to add pattern restrictions for 2.0 transformId fix typo in specification header link schema to raw schema file on github segment AMF doc into smaller pages for more granulated sidebar nav; add schema docs html
2 parents f410838 + d75d60d commit 2bbbdb8

File tree

77 files changed

+695
-130
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

77 files changed

+695
-130
lines changed

.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
1+
12
.vscode
23
.DS_Store
4+
.cache/

LaTeX/typesetacesdocs.sh

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
#!/bin/bash
2+
3+
function usage
4+
{
5+
echo "typesetacesdocs - typesets each of the ACES documents using pdflatex"
6+
echo " The result is a PDF in each of the document folders"
7+
echo ""
8+
echo "usage:"
9+
echo " typsetacesdocs [ -k ]"
10+
echo ""
11+
echo "options:"
12+
echo " -k | --keep-logs Preserves the log files from the typesetting"
13+
echo " (by default, extra files are cleaned up)"
14+
}
15+
16+
### MAIN
17+
K=0
18+
19+
while [ "$1" != "" ]; do
20+
case $1 in
21+
-k | --keep-logs ) shift
22+
K=1
23+
;;
24+
-h | --help ) usage
25+
exit
26+
;;
27+
* ) usage
28+
exit 1
29+
esac
30+
shift
31+
done
32+
33+
for d in */ ; do
34+
FILENAME=${d%/}
35+
36+
# if [ "$FILENAME" != "template" ]
37+
# if [ "$FILENAME" == "S-2014-006" ]
38+
if [ "$FILENAME" == "ACES-Document-Manifest" ]
39+
then
40+
echo $FILENAME
41+
42+
cd $FILENAME
43+
pdflatex $FILENAME.tex
44+
pdflatex $FILENAME.tex
45+
46+
if [ !$K ]
47+
then
48+
rm ${FILENAME}.aux
49+
rm ${FILENAME}.log
50+
rm ${FILENAME}.out
51+
rm ${FILENAME}.toc
52+
fi
53+
54+
# cp ${FILENAME}.pdf /Users/scott/Dropbox/work/ACES/Internal/Documents/dev/
55+
# cp ${FILENAME}.pdf /Users/scott/Dropbox/work/ACES/Public/aces-dev/docs/
56+
# cp ${FILENAME}.pdf /Users/scott/Dropbox\ \(Academy\)/work/ACES/Public/aces-dev/docs
57+
# cp ${FILENAME}.pdf /Users/scott/tmp/docs/
58+
59+
cd ..
60+
fi
61+
62+
done
63+
64+
# FILEPATH=${FILE%/*}
65+
# FILENAME=${FILE##*/}
66+
# FILENAME=${FILENAME%%.*}
67+
68+
# pdflatex /Users/scott/Documents/ampas/iif/aces-dev/documents/P-2013-001/P-2013-001.tex
File renamed without changes.
Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
Specification
2+
==========
3+
4+
This section describes the data intended for use within the ACES Metadata file.
5+
6+
## Namespace
7+
8+
All top level structures shall be tagged as being within the `aces` namespace with urn `urn:ampas:aces:amf:v2.0`
9+
10+
## UML Diagram
11+
The following UML diagrams are segments of the complete UML diagram which is not included in this document due to space constraints. To view the entire UML diagram in SVG format visit [https://aces.mp/amf\_uml](https://aces.mp/amf\_uml).
12+
13+
### acesMetadataFile
14+
<figure align="center" markdown>
15+
![diagram](./uml_diagrams/uml_amf.svg)
16+
</figure>
17+
18+
### amfInfo
19+
<figure align="center" markdown>
20+
![amfDiagram ](./uml_diagrams/uml_amfInfo.svg)
21+
</figure>
22+
23+
### clipId
24+
<figure align="center" markdown>
25+
![amfDiagram ](./uml_diagrams/uml_clipId.svg)
26+
</figure>
27+
28+
### pipeline
29+
<figure align="center" markdown>
30+
![amfDiagram ](./uml_diagrams/uml_pipeline.svg)
31+
</figure>
32+
33+
### pipelineInfo
34+
<figure align="center" markdown>
35+
![amfDiagram ](./uml_diagrams/uml_piplineInfo.svg)
36+
</figure>
37+
38+
### inputTransform
39+
<figure align="center" markdown>
40+
![amfDiagram ](./uml_diagrams/uml_inputTransform.svg)
41+
</figure>
42+
43+
### lookTransform
44+
<figure align="center" markdown>
45+
![amfDiagram ](./uml_diagrams/uml_lookTransform.svg)
46+
</figure>
47+
48+
### outputTransform
49+
<figure align="center" markdown>
50+
![amfDiagram ](./uml_diagrams/uml_outputTransform.svg)
51+
</figure>
52+
53+
54+
<!-- Include section numbering -->
55+
<style>
56+
/* @import "../../stylesheets/sections.css" */
57+
body {
58+
counter-reset : h2 3;
59+
}
60+
h2 {
61+
counter-reset : h3;
62+
}
63+
h3 {
64+
counter-reset : h4;
65+
}
66+
h4 {
67+
counter-reset : h5;
68+
}
69+
h5 {
70+
counter-reset : h6;
71+
}
72+
article h2:before {
73+
content : counter(h2,decimal) ". ";
74+
counter-increment : h2;
75+
}
76+
article h3:before {
77+
content : counter(h2,decimal) "." counter(h3,decimal) ". ";
78+
counter-increment : h3;
79+
}
80+
article h4:before {
81+
content : counter(h2,decimal) "." counter(h3,decimal) "." counter(h4,decimal) ". ";
82+
counter-increment : h4;
83+
}
84+
article h5:before {
85+
content : counter(h2,decimal) "." counter(h3,decimal) "." counter(h4,decimal) "." counter(h5,decimal) ". ";
86+
counter-increment : h5;
87+
}
88+
article h6:before {
89+
content : counter(h2,decimal) "." counter(h3,decimal) "." counter(h4,decimal) "." counter(h5,decimal) "." counter(h6,decimal) ". ";
90+
counter-increment : h6;
91+
}
92+
h2.nocount:before, h3.nocount:before, h4.nocount:before, h5.nocount:before, h6.nocount:before {
93+
content : "";
94+
counter-increment : none;
95+
}
96+
</style>
97+
Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
Introduction
2+
============
3+
4+
## Why is metadata needed for ACES?
5+
6+
ACES establishes a standard color color encoding (SMPTE ST 2065-1) for exchange of images. It also defines Input Transforms to convert different image sources to ACES and Output Transforms to display ACES files across different types of displays.
7+
8+
However, during production, critical information required to fully define the viewing pipeline or the "creative intent" of an image is often missing. Examples of such essential details include:
9+
10+
* ACES Version – _Which version of ACES was used?_
11+
* Look Transform – _Was a creative look applied?_
12+
* Output Transform – _How was the image viewed on a display?_
13+
14+
Transporting this information is vital for maintining consistent color appearance throughtout the production process. Moreover, it serves as an unambiguous archive of the creative intent.
15+
16+
## What is AMF
17+
The ACES Metadata File (“AMF”) is a sidecar XML file intended to exchange the metadata required to recreate ACES viewing pipelines. It describes the transforms necessary to configure an ACES viewing pipeline for a collection of related image files.
18+
19+
An AMF may have a specified association with a single frame or clip. Alternatively, it may exist without any association to an image, and one may apply it to an image. An application of an AMF to an image would translate its viewing pipeline to the target image.
20+
21+
Images are formed at several stages of production and post-production, including:
22+
23+
* Digital cameras
24+
* Film scanners
25+
* Animation and VFX production
26+
* Virtual production
27+
* Editorial and color correction systems
28+
29+
AMF can be compatible with any digital image, and is not restricted to those encoded in the ACES (SMPTE ST 2065-1). They may be camera native file formats or other encodings if they have associated Input Transforms (IDTs) (using the `<inputTransform>` element) so they may be displayed using an ACES viewing pipeline.
30+
31+
AMFs may also embed creative look adjustments as one or more LMTs (using the `<lookTransform>` elements). These looks may be in the form of ASC CDL values, or a reference to an external look file, such as a CLF (Common LUT Format). Multiple `<lookTransform>` elements are allowed, and the order of operations in which they are applied shall be the order in which they appear in the AMF.
32+
33+
AMFs can also serve as effective archival elements. When paired with finished ACES image files, they form a complete archival record of how image content is intended to be viewed (for example, using the `<outputTransform>` and `<systemVersion>` elements).
34+
35+
AMFs do not contain “timeline” metadata such as edit points. Timeline management files such as Edit Decision Lists (EDLs) or Avid Log Exchange files (ALEs) may reference AMFs, attaching them to editing events and thus enable standardized color management throughout all stages of production.
36+
37+
<figure align="center" markdown>
38+
![amfDiagram](./images/amfDiagram.png)
39+
<figcaption align="center">
40+
<b>Figure 1.</b> Overall structure of an AMF in simplified form.
41+
</figcaption>
42+
</figure>
Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
Use Cases
2+
=========
3+
4+
ACES Metadata Files (AMFs) are intended to contain the minimum required metadata for transferring information about ACES viewing pipelines during production, post-production, and archival.
5+
6+
Typical use cases for AMF files are the application of “show LUT” LMTs in cameras and on-set systems,the capture of shot-to-shot looks generated on-set using ASC-CDL, and communication of both to dailies,editorial, VFX, and post-production mastering facilities.
7+
8+
AMF supports the transfer of looks by embedding ASC-CDL values within the AMF file or by referencingsidecar look files containing LMTs, such as CLF (Common LUT Format) files.
9+
10+
## Look Development
11+
The development of a creative look before the commencement of production is common. Production uses this look to produce a pre-adjusted reference for on-set monitoring. The creative look may be a package of files containing a viewing transform (also known as a “Show LUT”), CDL grades, or more. There are no consistent standards specifying how to produce them, and exchanging them is complex due to a lack of metadata.
12+
13+
AMF contains the ability to completely specify the application of a creative look. This automates the exchange of these files and the recreation of the look when applying the AMF. In an ACES workflow, one specifies the creative look as one or more Look Modification Transforms (LMT). AMF can include references to any number of these transforms, and maintains their order of operations.
14+
15+
The input and output of an LMT is always a triplet of ACES RGB relative exposure values, as defined in SMPTE ST 2065-1. This will likely need a robust transform, such as CLF, that can handle linear input data and output data.
16+
17+
AMF offers an unambiguous description of the full ACES viewing pipeline for on-set look management software to load and display images as intended.
18+
19+
## On Set
20+
Before production begins, an AMF may be created and shared with production as a "look template" for use during on-set monitoring or look management.
21+
22+
Cameras with AMF support can load or generate AMFs to configure or communicate the viewing pipeline of images viewed out of the camera's live video signal.
23+
24+
On-set color grading software can load or generate AMFs, allowing the communication of the color adjustments created on set.
25+
26+
## Dailies
27+
Dailies can apply AMFs from production to the camera files to reproduce the same images seen on set. There is no single method of exchange between production and dailies. AMFs should be agnostic to the given exchange method.
28+
29+
It is possible, or even likely, that one will update AMFs in the dailies stage. For example, a dailies colorist may choose to balance shots at this stage and update the look. Another example could be that dailies uses a different ODT than the one used in on-set monitoring.
30+
31+
This specification does not define how one should transport AMFs between stages. Existing exchange formats may reference them, or image files themselves may embed them. One may also transport AMFs independently of any other files.
32+
33+
## VFX
34+
The exchange of shots for VFX work requires perfect translation of each shot’s viewing pipeline, or ‘color recipe’. If the images cannot be accurately reproduced from VFX plates, effects will be created with an incorrect reference.
35+
36+
AMF provides a complete and unambiguous translation of ACES viewing pipelines. If they travel with VFX plates, they can describe how to view each plate along with any associated looks.
37+
38+
VFX software should have the ability to read AMF to configure its internal viewing pipeline. Or, AMF will inform the configuration of third party color management software, such as OpenColorIO.
39+
40+
## Finishing
41+
In finishing, the on-set or dailies viewing reference can be automatically recreated upon reading an AMF. This stage typically uses a higher quality display, which may warrant the use of a different ODT than one specified in an ingested AMF.
42+
43+
AMF can seamlessly provide the colorist a starting point that is consistent with the creative intent of the filmmakers on-set. This removes any necessity to recreate a starting look from scratch.
44+
45+
## Archival
46+
AMF enables the ability to establish a complete ACES archive, and effectively serves as a snapshot of creative intent for preservation and remastering purposes. All components required to recreate the look of an ACES archive are meaningfully described and preserved within the AMF.
47+
48+
One possible method for this could be the utilization of SMPTE standards such as ST.2067-50 (IMF App \#5) -- commonly referred to as "ACES IMF" -- and SMPTE RDD 47 (ISXD) -- a virtual track file containing XML data -- in order to form a complete and flexible ACES archival package.
49+
50+
Another method could be to use SMPTE ST.2067-9 (Sidecar Composition Map) which would allow linking of a single AMF to a CPL (Composition Playlist) in the case where there is a single AMF for an entire playlist.

docs/amf/specification/index.md

Lines changed: 15 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ This document specifies the ACES Metadata File (“AMF”), a ‘sidecar’ XML
1313
This specification supersedes "TB-2014-009 – Academy Color Encoding System – (ACES) Clip-level Metadata File Format Definition and Usage (“ACESclip”)". TB-2014-009 is now considered obsolete.
1414

1515

16+
17+
1618
Introduction
1719
----------------
1820
### Why is metadata needed for ACES?
@@ -21,7 +23,7 @@ ACES establishes a standard color color encoding (SMPTE ST 2065-1) for exchange
2123

2224
However, during production, critical information required to fully define the viewing pipeline or the "creative intent" of an image is often missing. Examples of such essential details include:
2325

24-
* ACES Version – _Shich version of ACES was used?_
26+
* ACES Version – _Which version of ACES was used?_
2527
* Look Transform – _Was a creative look applied?_
2628
* Output Transform – _How was the image viewed on a display?_
2729

@@ -55,6 +57,9 @@ AMFs do not contain “timeline” metadata such as edit points. Timeline manage
5557
</figcaption>
5658
</figure>
5759

60+
61+
62+
5863
Use Cases
5964
----------------
6065
ACES Metadata Files (AMFs) are intended to contain the minimum required metadata for transferring information about ACES viewing pipelines during production, post-production, and archival.
@@ -106,19 +111,22 @@ One possible method for this could be the utilization of SMPTE standards such as
106111
Another method could be to use SMPTE ST.2067-9 (Sidecar Composition Map) which would allow linking of a single AMF to a CPL (Composition Playlist) in the case where there is a single AMF for an entire playlist.
107112

108113

114+
115+
109116
Data Model
110117
----------------
111118
This section describes the data intended for use within the ACES Metadata file.
112119

113-
All top level structures shall be tagged as being within the `aces` namespace with urn `urn:acesMetadata:acesMetadataFile:v1.0`
120+
121+
### Namespace
122+
All top level structures shall be tagged as being within the `aces` namespace with urn `urn:ampas:aces:amf:v2.0`.
114123

115124
### UML Diagram
116125
The following UML diagrams are segments of the complete UML diagram which is not included in this document due to space constraints. To view the entire UML diagram in SVG format visit [https://aces.mp/amf\_uml](https://aces.mp/amf\_uml).
117126

118127
#### acesMetadataFile
119128
<figure align="center" markdown>
120-
![diagram](https://www.plantuml.com/plantuml/svg/TLDDRzim33rBlu8r4Y16qY0PDWm8qA9RUybXbwx1pgfDnrfioPEeRSNG_pxARXtFStE8HVAznmzADvwKer1NiiA2W2muVIm9Skqm8ssDz2Tj6kLK3NyalFm-g-nqT3QO_DPMrW4vPJo3q90KbJP8Jms2TLHQARwMAhU_j3b2eIgFKdpHvhPItd_JEPNmxkC7AOpDqMC3suqKh7MAv_SR-IpbHJ0_WYNCeN4smpmuxD8LrjMBcV8hc96vIXB-AYB7frGA-_WTCuA4umae3_nTEsk9Un1YxibnEOj4PUXt2InZcF-J1wuwiiLwpNyNke08hT0iMkaKhc730T5Q4O4cruKKp-U4t4RcT1CdroSU-Dhyl_qEkXAwL4D-gNpP4wFHCjf2enKhVArl2QewMgUfh647FUGJEplOG3O4dVUoqMXbywokTeV3_cuWEo0LkiAU58tNwfLvEjpl_oVqUzcVamryJ1zDbSnvfcHY5DiRmeTPun2keDiHcQHpPgfXvpmq3Rh5t8T7LcelmMQrJTCNelN4e65qkpelqaVS-HAqUPOGbUCdajD-jNsBKlGtwFBoUhpLYMZSn8GxZdx27OSxSezc9xcWmHEOVXSsK1FeOVWwk1Twq-xmT_XJPzYp_a4uBD2XoV2UqsCSs00tgdXIhGsFW9EYG_Yurt5V8pkLDqm8TVKN#only-light)
121-
![diagram](https://www.plantuml.com/plantuml/dsvg/TLDDRzim33rBlu8r4Y16qY0PDWm8qA9RUybXbwx1pgfDnrfioPEeRSNG_pxARXtFStE8HVAznmzADvwKer1NiiA2W2muVIm9Skqm8ssDz2Tj6kLK3NyalFm-g-nqT3QO_DPMrW4vPJo3q90KbJP8Jms2TLHQARwMAhU_j3b2eIgFKdpHvhPItd_JEPNmxkC7AOpDqMC3suqKh7MAv_SR-IpbHJ0_WYNCeN4smpmuxD8LrjMBcV8hc96vIXB-AYB7frGA-_WTCuA4umae3_nTEsk9Un1YxibnEOj4PUXt2InZcF-J1wuwiiLwpNyNke08hT0iMkaKhc730T5Q4O4cruKKp-U4t4RcT1CdroSU-Dhyl_qEkXAwL4D-gNpP4wFHCjf2enKhVArl2QewMgUfh647FUGJEplOG3O4dVUoqMXbywokTeV3_cuWEo0LkiAU58tNwfLvEjpl_oVqUzcVamryJ1zDbSnvfcHY5DiRmeTPun2keDiHcQHpPgfXvpmq3Rh5t8T7LcelmMQrJTCNelN4e65qkpelqaVS-HAqUPOGbUCdajD-jNsBKlGtwFBoUhpLYMZSn8GxZdx27OSxSezc9xcWmHEOVXSsK1FeOVWwk1Twq-xmT_XJPzYp_a4uBD2XoV2UqsCSs00tgdXIhGsFW9EYG_Yurt5V8pkLDqm8TVKN#only-dark)
129+
![diagram](./uml_diagrams/uml_amf.svg)
122130
</figure>
123131

124132
#### amfInfo
@@ -156,22 +164,19 @@ The following UML diagrams are segments of the complete UML diagram which is not
156164
![amfDiagram ](./uml_diagrams/uml_outputTransform.svg)
157165
</figure>
158166

167+
### Schema
168+
The XSD for AMF is maintained on Github in the repository [[ampas/aces-amf](https://raw.githubusercontent.com/ampas/aces-amf/refs/heads/main/schema/acesMetadataFile.xsd)]
159169

160170
### Types
161-
The following types are defined for use within the AMF XML file and are validated with the XSD schema included in Appendix A. The types are used as the basis to form the elements listed in section X in the schema.
162-
163-
\input{sec-types.tex}
171+
Data types defined by the AMF schema can be explored interactively [[Explore Types](amf/specification/schema-docs/acesMetadataFile.html)]
164172

165173

166-
### Elements (by type)
167-
The following elements are defined for use with the AMF XML file and are validated with the XSD schema included in Appendix A.
168174

169175

170176
References
171177
----------
172178
The following standards, specifications, articles, presentations, and texts are referenced in this text:
173179

174-
* [Academy S-2014-002, Academy Color Encoding System - Versioning System](https://www.dropbox.com/s/cnrak5pvu4agfk4/S-2014-002.pdf?dl=0)
175180
* [SMPTE ST 2065-1:2021, Academy Color Encoding Specification (ACES)](https://doi.org/10.5594/SMPTE.ST2065-1.2021)
176181
* [SMPTE ST 2065-4:2013, ACES Image Container File Layout](https://doi.org/10.5594/SMPTE.ST2065-4.2013)
177182
* [Academy TB-2014-010, Design, Integration and Use of ACES Look Modification Transforms (LMTs)](https://www.dropbox.com/s/grjoi885tv78e70/TB-2014-010.pdf?dl=0)

docs/amf/specification/schema-docs/acesMetadataFile_xsd_Simple_Type_aces_tnColorSpaceConversionTransform.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -354,6 +354,7 @@ <h3>Showing:</h3>
354354
<td width="100%"><pre><span class="tEl">&lt;xs:simpleType</span><span class="tAN"> name=</span><span class="tAV">"tnColorSpaceConversionTransform"</span><span class="tEl">&gt;</span><span class="tI">
355355
</span><span class="tEl">&lt;xs:restriction</span><span class="tAN"> base=</span><span class="tAV">"xs:string"</span><span class="tEl">&gt;</span><span class="tI">
356356
</span><span class="tEl">&lt;xs:pattern</span><span class="tAN"> value=</span><span class="tAV">"urn:ampas:aces:transformId:v1.5:(ACEScsc\.\S+\.\S+\.a\d+\.v\d+|ACEScsc\.Academy\.\S+\.a\d+\.\d+\.\d+)"</span><span class="tEl">/&gt;</span><span class="tI">
357+
</span><span class="tEl">&lt;xs:pattern</span><span class="tAN"> value=</span><span class="tAV">"urn:ampas:aces:transformId:v2.0:CSC\.\S+\.\S+\.a\d+\.v\d+"</span><span class="tEl">/&gt;</span><span class="tI">
357358
</span><span class="tEl">&lt;/xs:restriction&gt;</span><span class="tI">
358359
</span><span class="tEl">&lt;/xs:simpleType&gt;</span></pre></td>
359360
</tr>

docs/amf/specification/schema-docs/acesMetadataFile_xsd_Simple_Type_aces_tnInputTransform.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -354,6 +354,7 @@ <h3>Showing:</h3>
354354
<td width="100%"><pre><span class="tEl">&lt;xs:simpleType</span><span class="tAN"> name=</span><span class="tAV">"tnInputTransform"</span><span class="tEl">&gt;</span><span class="tI">
355355
</span><span class="tEl">&lt;xs:restriction</span><span class="tAN"> base=</span><span class="tAV">"xs:string"</span><span class="tEl">&gt;</span><span class="tI">
356356
</span><span class="tEl">&lt;xs:pattern</span><span class="tAN"> value=</span><span class="tAV">"urn:ampas:aces:transformId:v1.5:(IDT\.\S+\.\S+\.a\d+\.v\d+|ACEScsc\.\S+\.a\d+\.\d+\.\d+)"</span><span class="tEl">/&gt;</span><span class="tI">
357+
</span><span class="tEl">&lt;xs:pattern</span><span class="tAN"> value=</span><span class="tAV">"urn:ampas:aces:transformId:v2.0:(Input\.\S+\.\S+\.a\d+\.v\d+|CSC\.\S+\.a\d+\.v\d+)"</span><span class="tEl">/&gt;</span><span class="tI">
357358
</span><span class="tEl">&lt;/xs:restriction&gt;</span><span class="tI">
358359
</span><span class="tEl">&lt;/xs:simpleType&gt;</span></pre></td>
359360
</tr>

0 commit comments

Comments
 (0)