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.
- aswf_aces_amf_utils-0.1.0/PKG-INFO +304 -0
- aswf_aces_amf_utils-0.1.0/README.md +293 -0
- aswf_aces_amf_utils-0.1.0/pyproject.toml +36 -0
- aswf_aces_amf_utils-0.1.0/setup.cfg +4 -0
- aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/__init__.py +38 -0
- aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/aces_amf.py +220 -0
- aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/builder.py +336 -0
- aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/bulk_generator.py +159 -0
- aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/cli/__init__.py +59 -0
- aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/cli/create.py +53 -0
- aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/cli/diff_cmd.py +29 -0
- aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/cli/edit.py +77 -0
- aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/cli/info.py +86 -0
- aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/cli/resolve.py +184 -0
- aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/cli/templates.py +109 -0
- aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/cli/transforms.py +65 -0
- aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/cli/validate.py +79 -0
- aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/diff.py +193 -0
- aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/factories.py +182 -0
- aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/placement.py +112 -0
- aswf_aces_amf_utils-0.1.0/src/aswf/aces/amf_utils/template_registry.py +128 -0
- aswf_aces_amf_utils-0.1.0/src/aswf_aces_amf_utils.egg-info/PKG-INFO +304 -0
- aswf_aces_amf_utils-0.1.0/src/aswf_aces_amf_utils.egg-info/SOURCES.txt +32 -0
- aswf_aces_amf_utils-0.1.0/src/aswf_aces_amf_utils.egg-info/dependency_links.txt +1 -0
- aswf_aces_amf_utils-0.1.0/src/aswf_aces_amf_utils.egg-info/entry_points.txt +2 -0
- aswf_aces_amf_utils-0.1.0/src/aswf_aces_amf_utils.egg-info/requires.txt +3 -0
- aswf_aces_amf_utils-0.1.0/src/aswf_aces_amf_utils.egg-info/top_level.txt +1 -0
- aswf_aces_amf_utils-0.1.0/tests/test_acesamf_wrapper.py +397 -0
- aswf_aces_amf_utils-0.1.0/tests/test_builder.py +185 -0
- aswf_aces_amf_utils-0.1.0/tests/test_builder_placement.py +294 -0
- aswf_aces_amf_utils-0.1.0/tests/test_cli.py +424 -0
- aswf_aces_amf_utils-0.1.0/tests/test_diff.py +88 -0
- aswf_aces_amf_utils-0.1.0/tests/test_factories.py +97 -0
- 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,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
|
+
]
|