aswf-aces-amf-utils 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. aswf_aces_amf_utils-0.1.0/PKG-INFO +304 -0
  2. aswf_aces_amf_utils-0.1.0/README.md +293 -0
  3. aswf_aces_amf_utils-0.1.0/pyproject.toml +36 -0
  4. aswf_aces_amf_utils-0.1.0/setup.cfg +4 -0
  5. aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/__init__.py +38 -0
  6. aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/aces_amf.py +220 -0
  7. aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/builder.py +336 -0
  8. aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/bulk_generator.py +159 -0
  9. aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/cli/__init__.py +59 -0
  10. aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/cli/create.py +53 -0
  11. aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/cli/diff_cmd.py +29 -0
  12. aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/cli/edit.py +77 -0
  13. aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/cli/info.py +86 -0
  14. aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/cli/resolve.py +184 -0
  15. aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/cli/templates.py +109 -0
  16. aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/cli/transforms.py +65 -0
  17. aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/cli/validate.py +79 -0
  18. aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/diff.py +193 -0
  19. aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/factories.py +182 -0
  20. aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/placement.py +112 -0
  21. aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/template_registry.py +128 -0
  22. aswf_aces_amf_utils-0.1.0/src/aswf_aces_amf_utils.egg-info/PKG-INFO +304 -0
  23. aswf_aces_amf_utils-0.1.0/src/aswf_aces_amf_utils.egg-info/SOURCES.txt +32 -0
  24. aswf_aces_amf_utils-0.1.0/src/aswf_aces_amf_utils.egg-info/dependency_links.txt +1 -0
  25. aswf_aces_amf_utils-0.1.0/src/aswf_aces_amf_utils.egg-info/entry_points.txt +2 -0
  26. aswf_aces_amf_utils-0.1.0/src/aswf_aces_amf_utils.egg-info/requires.txt +3 -0
  27. aswf_aces_amf_utils-0.1.0/src/aswf_aces_amf_utils.egg-info/top_level.txt +1 -0
  28. aswf_aces_amf_utils-0.1.0/tests/test_acesamf_wrapper.py +397 -0
  29. aswf_aces_amf_utils-0.1.0/tests/test_builder.py +185 -0
  30. aswf_aces_amf_utils-0.1.0/tests/test_builder_placement.py +294 -0
  31. aswf_aces_amf_utils-0.1.0/tests/test_cli.py +424 -0
  32. aswf_aces_amf_utils-0.1.0/tests/test_diff.py +88 -0
  33. aswf_aces_amf_utils-0.1.0/tests/test_factories.py +97 -0
  34. aswf_aces_amf_utils-0.1.0/tests/test_template_registry.py +99 -0
@@ -0,0 +1,304 @@
1
+ Metadata-Version: 2.4
2
+ Name: aswf-aces-amf-utils
3
+ Version: 0.1.0
4
+ Summary: CLI, builder, and utilities for ACES Metadata Files (AMF)
5
+ License-Expression: Apache-2.0
6
+ Requires-Python: >=3.10
7
+ Description-Content-Type: text/markdown
8
+ Requires-Dist: aswf-aces-amf-lib>=0.1.0
9
+ Requires-Dist: aswf-aces-transforms>=0.1.0
10
+ Requires-Dist: click>=8.0.0
11
+
12
+ # aswf-aces-amf-utils
13
+
14
+ CLI, builder, and utilities for creating, modifying, validating, and analyzing ACES Metadata Files (AMF).
15
+
16
+ This package currently supports AMF v2.0 schema only. The AMF schema version is separate from the ACES system version of a given AMF, e.g. ACES v1.3 system version and transform IDs are supported in AMF v2.0.
17
+
18
+ ## Installation
19
+
20
+ ```bash
21
+ pip install aswf-aces-amf-utils
22
+ ```
23
+
24
+ This package installs the `amf` command-line utility and its runtime dependencies, including the
25
+ core library and transform registry. Python 3.10 or newer is required.
26
+
27
+ ## Quick Start
28
+
29
+ ```python
30
+ from aswf.aces.amf_lib import amf
31
+ from aswf.aces.amf_utils import ACESAMF, AMFBuilder, cdl_look_transform
32
+
33
+ # Load and inspect an existing AMF
34
+ aces_amf = ACESAMF.from_file("input.amf")
35
+ print(aces_amf.description)
36
+ print(aces_amf.input_transform)
37
+
38
+ # Build a new AMF from scratch
39
+ amf_doc = (AMFBuilder()
40
+ .with_description("My Show - Ep 1")
41
+ .with_input_transform(amf.InputTransformType(
42
+ transform_id="urn:ampas:aces:transformId:v2.0:CSC.Arri.LogC4_to_ACES.a2.v1",
43
+ applied=False))
44
+ .with_look_transform(cdl_look_transform(slope=(1.2, 1.0, 0.8), saturation=0.95))
45
+ .with_output_transform(amf.OutputTransformType(
46
+ transform_id="urn:ampas:aces:transformId:v2.0:Output.Academy.Rec709-D65_100nit_in_Rec709-D65_BT1886.a2.v1",
47
+ applied=False))
48
+ .build())
49
+ ```
50
+
51
+ ## API Design
52
+
53
+ The API follows a property-based pattern with chainable builder wrappers:
54
+
55
+ - **Properties** for Pythonic get/set using pre-built Pydantic types from `aswf.aces.amf_lib.amf`
56
+ - **`with_X()` methods** that wrap property setters and return `self` for fluent chaining
57
+ - **Factory functions** for complex type construction (e.g., CDL look transforms)
58
+
59
+ ```python
60
+ # Property access — direct get and set
61
+ aces_amf = ACESAMF.from_file("shot.amf")
62
+ it = aces_amf.input_transform # get
63
+ aces_amf.input_transform = amf.InputTransformType( # set
64
+ transform_id="urn:...", applied=False)
65
+
66
+ # Builder chaining — via with_X() wrappers
67
+ aces_amf = (ACESAMF.new()
68
+ .with_input_transform(amf.InputTransformType(transform_id="urn:...", applied=False))
69
+ .with_look_transform(amf.LookTransformType(file="grade.clf", applied=True))
70
+ .with_output_transform(amf.OutputTransformType(transform_id="urn:...", applied=False)))
71
+ ```
72
+
73
+ ## ACESAMF — High-Level Wrapper
74
+
75
+ `ACESAMF` wraps an `AcesMetadataFile` with convenient I/O and mutation methods.
76
+
77
+ ### Construction
78
+
79
+ ```python
80
+ # Create a new minimal AMF
81
+ amf = ACESAMF.new(aces_version=(2, 0, 0))
82
+
83
+ # Load an AMF v2 file
84
+ amf = ACESAMF.from_file("input.amf", validate=True)
85
+
86
+ # Load from raw bytes
87
+ amf = ACESAMF.from_data(xml_bytes, validate=True)
88
+ ```
89
+
90
+ ### I/O
91
+
92
+ ```python
93
+ amf.write("output.amf", validate=True) # write to file
94
+ xml = amf.dump(validate=True) # serialize to XML string
95
+ amf.rev_up() # update timestamps and UUIDs before saving
96
+ ```
97
+
98
+ ### Properties (get/set)
99
+
100
+ All properties accept and return pre-built Pydantic types:
101
+
102
+ | Property | Type | Description |
103
+ |----------|------|-------------|
104
+ | `description` | `str \| None` | Top-level AMF description |
105
+ | `pipeline_description` | `str \| None` | Pipeline description |
106
+ | `input_transform` | `InputTransformType \| None` | Pipeline input transform |
107
+ | `output_transform` | `OutputTransformType \| None` | Pipeline output transform |
108
+ | `clip_id` | `ClipIdType \| None` | Clip identification |
109
+ | `aces_system_version` | `VersionType \| None` | ACES system version object |
110
+
111
+ ### Read-Only Properties
112
+
113
+ | Property | Type | Description |
114
+ |----------|------|-------------|
115
+ | `clip_name` | `str \| None` | Extracted from clipId |
116
+ | `amf_uuid` | `str` | Top-level AMF UUID |
117
+ | `authors` | `list[AuthorType]` | Author list |
118
+ | `modification_date_time` | `XmlDateTime` | Last modified timestamp |
119
+ | `creation_date_time` | `XmlDateTime` | Creation timestamp |
120
+ | `has_working_location` | `bool` | Whether pipeline has a working location marker |
121
+ | `aces_version` | `tuple[int,int,int] \| None` | ACES version as tuple (ACESAMF only) |
122
+ | `aces_major_version` | `int \| None` | Major version number (ACESAMF only) |
123
+
124
+ ### Chainable `with_X()` Methods
125
+
126
+ All return `self` for fluent chaining:
127
+
128
+ | Method | Accepts |
129
+ |--------|---------|
130
+ | `with_description(text)` | `str` |
131
+ | `with_pipeline_description(text)` | `str` |
132
+ | `with_input_transform(value)` | `InputTransformType` |
133
+ | `with_output_transform(value)` | `OutputTransformType` |
134
+ | `with_look_transform(value)` | `LookTransformType` |
135
+ | `with_working_location()` | _(no args — inserts delimiter)_ |
136
+ | `with_author(author)` | `AuthorType` |
137
+ | `with_clip_id(value)` | `ClipIdType` |
138
+ | `with_aces_system_version(value)` | `VersionType` |
139
+
140
+ ## AMFBuilder — Fluent Construction
141
+
142
+ `AMFBuilder` provides the same properties and `with_X()` methods as `ACESAMF`, plus a `build()` method to extract the final `AcesMetadataFile`:
143
+
144
+ ```python
145
+ from aswf.aces.amf_lib import amf, save_amf
146
+ from aswf.aces.amf_utils import AMFBuilder
147
+ from aswf.aces.transforms import ACESTransformRegistry
148
+
149
+ amf = (AMFBuilder(aces_version=(2, 0, 0))
150
+ .with_description("DI Grade")
151
+ .with_author(amf.AuthorType(name="Colorist", email_address="color@studio.com"))
152
+ .with_input_transform(amf.InputTransformType(
153
+ transform_id="urn:ampas:aces:transformId:v2.0:CSC.Arri.LogC4_to_ACES.a2.v1",
154
+ applied=False))
155
+ .with_look_transform(amf.LookTransformType(
156
+ file="grade.clf", description="Primary grade", applied=True))
157
+ .with_working_location()
158
+ .with_look_transform(amf.LookTransformType(
159
+ file="trim.clf", description="Trim pass", applied=False))
160
+ .with_output_transform(amf.OutputTransformType(
161
+ transform_id="urn:ampas:aces:transformId:v2.0:Output.Academy.Rec709-D65_100nit_in_Rec709-D65_BT1886.a2.v1",
162
+ applied=False))
163
+ .build())
164
+
165
+ registry = ACESTransformRegistry()
166
+ save_amf(amf, "output.amf", transform_registry=registry)
167
+ ```
168
+
169
+ ## Look Stack Management
170
+
171
+ Looks are stored in a compound list that can also contain working location markers. Management methods operate on logical look indices (excluding markers):
172
+
173
+ ```python
174
+ amf = ACESAMF.from_file("input.amf")
175
+
176
+ # Read
177
+ looks = amf.get_looks() # list[LookTransformType]
178
+ look = amf.get_look(0) # by index (supports negative)
179
+ count = amf.count_looks() # int
180
+ for i, look in amf.iter_looks(): # (index, look) pairs
181
+ print(f"{i}: {look.description}")
182
+
183
+ # Mutate
184
+ amf.insert_look(0, new_look) # insert at logical index
185
+ amf.remove_look(1) # remove by logical index
186
+ amf.move_look(from_idx=0, to_idx=2) # reorder
187
+ amf.clear_looks() # remove all (preserves working location)
188
+
189
+ # Working location splits
190
+ pre = amf.get_pre_working_looks() # looks before working location
191
+ post = amf.get_post_working_looks() # looks after working location
192
+ ```
193
+
194
+ ## Factory Functions
195
+
196
+ For complex type construction:
197
+
198
+ ```python
199
+ from aswf.aces.amf_utils import cdl_look_transform, cdl_look_transform_to_dict
200
+
201
+ # Create a CDL look transform with ACEScct working space
202
+ lt = cdl_look_transform(
203
+ slope=(1.2, 1.0, 0.8),
204
+ offset=(0.01, 0.0, -0.01),
205
+ power=(1.0, 1.0, 1.0),
206
+ saturation=0.95,
207
+ )
208
+ lt.description = "Primary grade"
209
+ lt.applied = True
210
+
211
+ # Extract CDL values back to a dict
212
+ cdl_dict = cdl_look_transform_to_dict(lt)
213
+ # {"asc_sop": {"slope": [...], "offset": [...], "power": [...]}, "asc_sat": 0.95}
214
+ ```
215
+
216
+ `cdl_look_transform` defaults to ACES 2.0 and an ACEScct working space. Pass
217
+ `aces_version` matching the AMF's system version when creating a CDL for a
218
+ different ACES version. You can pass `working_space` to select another CSC
219
+ working space; the transform registry is used to find its inverse.
220
+
221
+ ## File Hashes
222
+
223
+ `ACESAMF.compute_file_hashes()` computes hashes for existing files referenced
224
+ by transforms in the AMF's pipelines, stores them on the model, and returns a
225
+ mapping from each file reference to its digest. It resolves relative file
226
+ references against `base_path`, which defaults to the current working directory.
227
+ The default algorithm is the AMF SHA-256 algorithm URI.
228
+
229
+ ```python
230
+ from aswf.aces.amf_utils import ACESAMF
231
+
232
+ amf = ACESAMF.from_file("show/shot.amf")
233
+ hashes = amf.compute_file_hashes(base_path="show")
234
+ amf.write("show/shot_with_hashes.amf")
235
+ ```
236
+
237
+ ## Diff
238
+
239
+ Compare two AMF files or objects:
240
+
241
+ ```python
242
+ from aswf.aces.amf_utils import diff_amf
243
+
244
+ result = diff_amf("a.amf", "b.amf", verbose=True)
245
+ if result.has_differences:
246
+ print(result.summary())
247
+ for d in result.differences:
248
+ print(f" {d.field}: {d.old_value} -> {d.new_value}")
249
+ ```
250
+
251
+ ## CLI
252
+
253
+ The `amf` command provides a full suite of tools. Transform ID validation uses
254
+ `aswf-aces-transforms` by default.
255
+
256
+ ```bash
257
+ # Validate AMF files
258
+ amf validate shot.amf
259
+ amf validate --schema-only shot.amf
260
+ amf validate --verbose *.amf
261
+
262
+ # Display AMF information
263
+ amf info shot.amf
264
+ amf info -v shot.amf # verbose with transform details
265
+
266
+ # Create a new AMF
267
+ amf create output.amf -d "My Show" --author "Jane Doe" \
268
+ --idt "urn:ampas:aces:transformId:v2.0:CSC.Arri.LogC4_to_ACES.a2.v1" \
269
+ --odt "urn:ampas:aces:transformId:v2.0:Output.Academy.Rec709-D65_100nit_in_Rec709-D65_BT1886.a2.v1"
270
+
271
+ # Add a CDL look transform
272
+ amf add-cdl shot.amf --slope 1.2 1.0 0.8 --saturation 0.95 -d "Primary grade" -o shot_graded.amf
273
+
274
+ # Compare two AMF files
275
+ amf diff a.amf b.amf --verbose
276
+
277
+ # Query the ACES transform registry
278
+ amf transforms list --category IDT
279
+ amf transforms info "urn:ampas:aces:transformId:v2.0:CSC.Academy.ACES_to_ACEScc.a2.v1"
280
+ amf transforms categories
281
+
282
+ # Print a checksum of the AMF document (does not modify it)
283
+ amf compute-hashes shot.amf
284
+ ```
285
+
286
+ ## Key Types
287
+
288
+ All transform and metadata types are provided by [aswf-aces-amf-lib](https://pypi.org/project/aswf-aces-amf-lib/) and imported via `aswf.aces.amf_lib.amf`:
289
+
290
+ ```python
291
+ from aswf.aces.amf_lib.amf import (
292
+ InputTransformType, # input_transform property type
293
+ OutputTransformType, # output_transform property type
294
+ LookTransformType, # look transforms and CDL
295
+ AuthorType, # author entries
296
+ ClipIdType, # clip identification
297
+ VersionType, # ACES system version
298
+ WorkingLocationType, # working location marker
299
+ )
300
+ ```
301
+
302
+ ## License
303
+
304
+ Apache-2.0
@@ -0,0 +1,293 @@
1
+ # aswf-aces-amf-utils
2
+
3
+ CLI, builder, and utilities for creating, modifying, validating, and analyzing ACES Metadata Files (AMF).
4
+
5
+ This package currently supports AMF v2.0 schema only. The AMF schema version is separate from the ACES system version of a given AMF, e.g. ACES v1.3 system version and transform IDs are supported in AMF v2.0.
6
+
7
+ ## Installation
8
+
9
+ ```bash
10
+ pip install aswf-aces-amf-utils
11
+ ```
12
+
13
+ This package installs the `amf` command-line utility and its runtime dependencies, including the
14
+ core library and transform registry. Python 3.10 or newer is required.
15
+
16
+ ## Quick Start
17
+
18
+ ```python
19
+ from aswf.aces.amf_lib import amf
20
+ from aswf.aces.amf_utils import ACESAMF, AMFBuilder, cdl_look_transform
21
+
22
+ # Load and inspect an existing AMF
23
+ aces_amf = ACESAMF.from_file("input.amf")
24
+ print(aces_amf.description)
25
+ print(aces_amf.input_transform)
26
+
27
+ # Build a new AMF from scratch
28
+ amf_doc = (AMFBuilder()
29
+ .with_description("My Show - Ep 1")
30
+ .with_input_transform(amf.InputTransformType(
31
+ transform_id="urn:ampas:aces:transformId:v2.0:CSC.Arri.LogC4_to_ACES.a2.v1",
32
+ applied=False))
33
+ .with_look_transform(cdl_look_transform(slope=(1.2, 1.0, 0.8), saturation=0.95))
34
+ .with_output_transform(amf.OutputTransformType(
35
+ transform_id="urn:ampas:aces:transformId:v2.0:Output.Academy.Rec709-D65_100nit_in_Rec709-D65_BT1886.a2.v1",
36
+ applied=False))
37
+ .build())
38
+ ```
39
+
40
+ ## API Design
41
+
42
+ The API follows a property-based pattern with chainable builder wrappers:
43
+
44
+ - **Properties** for Pythonic get/set using pre-built Pydantic types from `aswf.aces.amf_lib.amf`
45
+ - **`with_X()` methods** that wrap property setters and return `self` for fluent chaining
46
+ - **Factory functions** for complex type construction (e.g., CDL look transforms)
47
+
48
+ ```python
49
+ # Property access — direct get and set
50
+ aces_amf = ACESAMF.from_file("shot.amf")
51
+ it = aces_amf.input_transform # get
52
+ aces_amf.input_transform = amf.InputTransformType( # set
53
+ transform_id="urn:...", applied=False)
54
+
55
+ # Builder chaining — via with_X() wrappers
56
+ aces_amf = (ACESAMF.new()
57
+ .with_input_transform(amf.InputTransformType(transform_id="urn:...", applied=False))
58
+ .with_look_transform(amf.LookTransformType(file="grade.clf", applied=True))
59
+ .with_output_transform(amf.OutputTransformType(transform_id="urn:...", applied=False)))
60
+ ```
61
+
62
+ ## ACESAMF — High-Level Wrapper
63
+
64
+ `ACESAMF` wraps an `AcesMetadataFile` with convenient I/O and mutation methods.
65
+
66
+ ### Construction
67
+
68
+ ```python
69
+ # Create a new minimal AMF
70
+ amf = ACESAMF.new(aces_version=(2, 0, 0))
71
+
72
+ # Load an AMF v2 file
73
+ amf = ACESAMF.from_file("input.amf", validate=True)
74
+
75
+ # Load from raw bytes
76
+ amf = ACESAMF.from_data(xml_bytes, validate=True)
77
+ ```
78
+
79
+ ### I/O
80
+
81
+ ```python
82
+ amf.write("output.amf", validate=True) # write to file
83
+ xml = amf.dump(validate=True) # serialize to XML string
84
+ amf.rev_up() # update timestamps and UUIDs before saving
85
+ ```
86
+
87
+ ### Properties (get/set)
88
+
89
+ All properties accept and return pre-built Pydantic types:
90
+
91
+ | Property | Type | Description |
92
+ |----------|------|-------------|
93
+ | `description` | `str \| None` | Top-level AMF description |
94
+ | `pipeline_description` | `str \| None` | Pipeline description |
95
+ | `input_transform` | `InputTransformType \| None` | Pipeline input transform |
96
+ | `output_transform` | `OutputTransformType \| None` | Pipeline output transform |
97
+ | `clip_id` | `ClipIdType \| None` | Clip identification |
98
+ | `aces_system_version` | `VersionType \| None` | ACES system version object |
99
+
100
+ ### Read-Only Properties
101
+
102
+ | Property | Type | Description |
103
+ |----------|------|-------------|
104
+ | `clip_name` | `str \| None` | Extracted from clipId |
105
+ | `amf_uuid` | `str` | Top-level AMF UUID |
106
+ | `authors` | `list[AuthorType]` | Author list |
107
+ | `modification_date_time` | `XmlDateTime` | Last modified timestamp |
108
+ | `creation_date_time` | `XmlDateTime` | Creation timestamp |
109
+ | `has_working_location` | `bool` | Whether pipeline has a working location marker |
110
+ | `aces_version` | `tuple[int,int,int] \| None` | ACES version as tuple (ACESAMF only) |
111
+ | `aces_major_version` | `int \| None` | Major version number (ACESAMF only) |
112
+
113
+ ### Chainable `with_X()` Methods
114
+
115
+ All return `self` for fluent chaining:
116
+
117
+ | Method | Accepts |
118
+ |--------|---------|
119
+ | `with_description(text)` | `str` |
120
+ | `with_pipeline_description(text)` | `str` |
121
+ | `with_input_transform(value)` | `InputTransformType` |
122
+ | `with_output_transform(value)` | `OutputTransformType` |
123
+ | `with_look_transform(value)` | `LookTransformType` |
124
+ | `with_working_location()` | _(no args — inserts delimiter)_ |
125
+ | `with_author(author)` | `AuthorType` |
126
+ | `with_clip_id(value)` | `ClipIdType` |
127
+ | `with_aces_system_version(value)` | `VersionType` |
128
+
129
+ ## AMFBuilder — Fluent Construction
130
+
131
+ `AMFBuilder` provides the same properties and `with_X()` methods as `ACESAMF`, plus a `build()` method to extract the final `AcesMetadataFile`:
132
+
133
+ ```python
134
+ from aswf.aces.amf_lib import amf, save_amf
135
+ from aswf.aces.amf_utils import AMFBuilder
136
+ from aswf.aces.transforms import ACESTransformRegistry
137
+
138
+ amf = (AMFBuilder(aces_version=(2, 0, 0))
139
+ .with_description("DI Grade")
140
+ .with_author(amf.AuthorType(name="Colorist", email_address="color@studio.com"))
141
+ .with_input_transform(amf.InputTransformType(
142
+ transform_id="urn:ampas:aces:transformId:v2.0:CSC.Arri.LogC4_to_ACES.a2.v1",
143
+ applied=False))
144
+ .with_look_transform(amf.LookTransformType(
145
+ file="grade.clf", description="Primary grade", applied=True))
146
+ .with_working_location()
147
+ .with_look_transform(amf.LookTransformType(
148
+ file="trim.clf", description="Trim pass", applied=False))
149
+ .with_output_transform(amf.OutputTransformType(
150
+ transform_id="urn:ampas:aces:transformId:v2.0:Output.Academy.Rec709-D65_100nit_in_Rec709-D65_BT1886.a2.v1",
151
+ applied=False))
152
+ .build())
153
+
154
+ registry = ACESTransformRegistry()
155
+ save_amf(amf, "output.amf", transform_registry=registry)
156
+ ```
157
+
158
+ ## Look Stack Management
159
+
160
+ Looks are stored in a compound list that can also contain working location markers. Management methods operate on logical look indices (excluding markers):
161
+
162
+ ```python
163
+ amf = ACESAMF.from_file("input.amf")
164
+
165
+ # Read
166
+ looks = amf.get_looks() # list[LookTransformType]
167
+ look = amf.get_look(0) # by index (supports negative)
168
+ count = amf.count_looks() # int
169
+ for i, look in amf.iter_looks(): # (index, look) pairs
170
+ print(f"{i}: {look.description}")
171
+
172
+ # Mutate
173
+ amf.insert_look(0, new_look) # insert at logical index
174
+ amf.remove_look(1) # remove by logical index
175
+ amf.move_look(from_idx=0, to_idx=2) # reorder
176
+ amf.clear_looks() # remove all (preserves working location)
177
+
178
+ # Working location splits
179
+ pre = amf.get_pre_working_looks() # looks before working location
180
+ post = amf.get_post_working_looks() # looks after working location
181
+ ```
182
+
183
+ ## Factory Functions
184
+
185
+ For complex type construction:
186
+
187
+ ```python
188
+ from aswf.aces.amf_utils import cdl_look_transform, cdl_look_transform_to_dict
189
+
190
+ # Create a CDL look transform with ACEScct working space
191
+ lt = cdl_look_transform(
192
+ slope=(1.2, 1.0, 0.8),
193
+ offset=(0.01, 0.0, -0.01),
194
+ power=(1.0, 1.0, 1.0),
195
+ saturation=0.95,
196
+ )
197
+ lt.description = "Primary grade"
198
+ lt.applied = True
199
+
200
+ # Extract CDL values back to a dict
201
+ cdl_dict = cdl_look_transform_to_dict(lt)
202
+ # {"asc_sop": {"slope": [...], "offset": [...], "power": [...]}, "asc_sat": 0.95}
203
+ ```
204
+
205
+ `cdl_look_transform` defaults to ACES 2.0 and an ACEScct working space. Pass
206
+ `aces_version` matching the AMF's system version when creating a CDL for a
207
+ different ACES version. You can pass `working_space` to select another CSC
208
+ working space; the transform registry is used to find its inverse.
209
+
210
+ ## File Hashes
211
+
212
+ `ACESAMF.compute_file_hashes()` computes hashes for existing files referenced
213
+ by transforms in the AMF's pipelines, stores them on the model, and returns a
214
+ mapping from each file reference to its digest. It resolves relative file
215
+ references against `base_path`, which defaults to the current working directory.
216
+ The default algorithm is the AMF SHA-256 algorithm URI.
217
+
218
+ ```python
219
+ from aswf.aces.amf_utils import ACESAMF
220
+
221
+ amf = ACESAMF.from_file("show/shot.amf")
222
+ hashes = amf.compute_file_hashes(base_path="show")
223
+ amf.write("show/shot_with_hashes.amf")
224
+ ```
225
+
226
+ ## Diff
227
+
228
+ Compare two AMF files or objects:
229
+
230
+ ```python
231
+ from aswf.aces.amf_utils import diff_amf
232
+
233
+ result = diff_amf("a.amf", "b.amf", verbose=True)
234
+ if result.has_differences:
235
+ print(result.summary())
236
+ for d in result.differences:
237
+ print(f" {d.field}: {d.old_value} -> {d.new_value}")
238
+ ```
239
+
240
+ ## CLI
241
+
242
+ The `amf` command provides a full suite of tools. Transform ID validation uses
243
+ `aswf-aces-transforms` by default.
244
+
245
+ ```bash
246
+ # Validate AMF files
247
+ amf validate shot.amf
248
+ amf validate --schema-only shot.amf
249
+ amf validate --verbose *.amf
250
+
251
+ # Display AMF information
252
+ amf info shot.amf
253
+ amf info -v shot.amf # verbose with transform details
254
+
255
+ # Create a new AMF
256
+ amf create output.amf -d "My Show" --author "Jane Doe" \
257
+ --idt "urn:ampas:aces:transformId:v2.0:CSC.Arri.LogC4_to_ACES.a2.v1" \
258
+ --odt "urn:ampas:aces:transformId:v2.0:Output.Academy.Rec709-D65_100nit_in_Rec709-D65_BT1886.a2.v1"
259
+
260
+ # Add a CDL look transform
261
+ amf add-cdl shot.amf --slope 1.2 1.0 0.8 --saturation 0.95 -d "Primary grade" -o shot_graded.amf
262
+
263
+ # Compare two AMF files
264
+ amf diff a.amf b.amf --verbose
265
+
266
+ # Query the ACES transform registry
267
+ amf transforms list --category IDT
268
+ amf transforms info "urn:ampas:aces:transformId:v2.0:CSC.Academy.ACES_to_ACEScc.a2.v1"
269
+ amf transforms categories
270
+
271
+ # Print a checksum of the AMF document (does not modify it)
272
+ amf compute-hashes shot.amf
273
+ ```
274
+
275
+ ## Key Types
276
+
277
+ All transform and metadata types are provided by [aswf-aces-amf-lib](https://pypi.org/project/aswf-aces-amf-lib/) and imported via `aswf.aces.amf_lib.amf`:
278
+
279
+ ```python
280
+ from aswf.aces.amf_lib.amf import (
281
+ InputTransformType, # input_transform property type
282
+ OutputTransformType, # output_transform property type
283
+ LookTransformType, # look transforms and CDL
284
+ AuthorType, # author entries
285
+ ClipIdType, # clip identification
286
+ VersionType, # ACES system version
287
+ WorkingLocationType, # working location marker
288
+ )
289
+ ```
290
+
291
+ ## License
292
+
293
+ Apache-2.0
@@ -0,0 +1,36 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ [build-system]
3
+ requires = ["setuptools>=61.0", "wheel"]
4
+ build-backend = "setuptools.build_meta"
5
+
6
+ [project]
7
+ name = "aswf-aces-amf-utils"
8
+ version = "0.1.0"
9
+ description = "CLI, builder, and utilities for ACES Metadata Files (AMF)"
10
+ readme = "README.md"
11
+ license = "Apache-2.0"
12
+ requires-python = ">=3.10"
13
+ dependencies = [
14
+ "aswf-aces-amf-lib>=0.1.0",
15
+ "aswf-aces-transforms>=0.1.0",
16
+ "click>=8.0.0",
17
+ ]
18
+
19
+ [project.scripts]
20
+ amf = "aswf.aces.amf_utils.cli:main"
21
+
22
+ [tool.setuptools.packages.find]
23
+ where = ["src"]
24
+ include = ["aswf.aces.amf_utils*"]
25
+
26
+ [tool.uv.sources]
27
+ aswf-aces-amf-lib = { workspace = true }
28
+ aswf-aces-transforms = { workspace = true }
29
+
30
+ [[tool.uv.index]]
31
+ name = "pypi"
32
+ url = "https://pypi.org/simple"
33
+ default = true
34
+
35
+ [tool.pytest.ini_options]
36
+ testpaths = ["tests"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,38 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """CLI, builder, and utilities for ACES Metadata Files (AMF)."""
3
+
4
+ from aswf.aces.amf_utils.aces_amf import ACESAMF
5
+ from aswf.aces.amf_utils.builder import AMFBuilder
6
+ from aswf.aces.amf_utils.diff import DiffResult, FieldDiff, diff_amf
7
+ from aswf.aces.amf_utils.factories import (
8
+ cdl_look_transform,
9
+ cdl_look_transform_to_dict,
10
+ cdl_working_space,
11
+ minimal_amf,
12
+ prepare_for_write,
13
+ )
14
+ from aswf.aces.amf_utils.template_registry import (
15
+ REGISTRY,
16
+ TemplateCategory,
17
+ TemplateMetadata,
18
+ TemplateRegistry,
19
+ )
20
+
21
+ __version__ = "0.1.0"
22
+
23
+ __all__ = [
24
+ "ACESAMF",
25
+ "AMFBuilder",
26
+ "DiffResult",
27
+ "FieldDiff",
28
+ "diff_amf",
29
+ "REGISTRY",
30
+ "TemplateCategory",
31
+ "TemplateMetadata",
32
+ "TemplateRegistry",
33
+ "minimal_amf",
34
+ "cdl_look_transform",
35
+ "cdl_working_space",
36
+ "cdl_look_transform_to_dict",
37
+ "prepare_for_write",
38
+ ]