Skip to content

Commit cb1eee1

Browse files
dgovilmeshula
dgovil
authored and
meshula
committed
Initial Profiles proposal
1 parent 07362da commit cb1eee1

File tree

1 file changed

+274
-0
lines changed

1 file changed

+274
-0
lines changed

‎proposals/profiles/README.md‎

Lines changed: 274 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,274 @@
1+
# Profiles
2+
3+
This document proposes the addition of `profiles` as metadata to USD documents.
4+
Profiles are short, structured descriptions of potentially non-standard features
5+
used within the stage such that a runtime or human can know of their existence ahead of time.
6+
7+
Profiles are not meant to change runtime parsing behaviour, and are essentially just
8+
informational hints.
9+
10+
A proposed example would be:
11+
12+
```
13+
(
14+
profile = {
15+
string name = "org.openusd.core"
16+
string version = "1.2.3"
17+
dictionary compatibility = {
18+
string com.apple.realitykit = "4.3.2"
19+
}
20+
dictionary required = {
21+
dictionary fileFormats = {
22+
string org.aom.vvm = "1.0.0"
23+
}
24+
}
25+
dictionary optional = {
26+
dictionary schemas = {
27+
string com.apple.realitykit.components = "1.0.0"
28+
}
29+
}
30+
}
31+
)
32+
```
33+
34+
## Problem Statement
35+
36+
USD documents can be pretty wide in terms of the features supported such as custom schemas, textures, audio or geometry
37+
formats. Some of these are important to be
38+
represented, while others are not meant to be portable.
39+
40+
This makes it difficult for an application runtime to know what it should let a user
41+
know about, when it can't represent something. It also means that the application
42+
needs to analyze every element before telling the user something may be amiss.
43+
44+
Conversely, USDZ packages focus on portability and are much stricter about the resource types
45+
they may include (though it omits the same rigidity for schemas).
46+
However, this strictness can also prevent the use of new features until they've
47+
been standardized. While this is great for inter-ecosystem sharing, it can be an
48+
issue for use within more limited scopes.
49+
50+
Profiles aim to solve this by providing metadata so that USD documents and packages
51+
may express what non-standard features they use. This would allow runtimes to flag
52+
concerns to a user faster for unsupported features, and allow USDZ documents to use
53+
features prior to standardization.
54+
55+
## Glossary
56+
57+
N/A
58+
59+
## Details
60+
61+
We propose the addition of a dictionary metadata that stores a structured mapping
62+
of profile identifiers to their corresponding versions.
63+
64+
### Profile Identifiers
65+
66+
We suggest that profiles identify themselves with
67+
a [Reverse Domain Name Notation](https://en.wikipedia.org/wiki/Reverse_domain_name_notation)**.
68+
69+
This is a very standard registration type across multiple systems, and has the
70+
advantage of allowing namespacing, while reducing the risk of name squatting.
71+
72+
E.g `com.apple.text.preliminary` would allow pointing to the use of a preliminary
73+
text schema, that is attributed to Apple. This would allow disambiguation with
74+
something like `com.autodesk.text.preliminary` if Autodesk would want to release
75+
a preliminary version of their schema too.
76+
77+
While there should be other forms of delineation within the schema, and potentially its name, this allows the
78+
application runtime to alert the user before traversing
79+
the scene and running heuristics.
80+
81+
It also allows the application to direct the user to the relevant developers site
82+
where they can ask for more information.
83+
84+
Lastly, it also prevents name collisions.
85+
For example, in the future, [aswf.com](https://www.aswf.com) may want to make schemas for window
86+
film parameters. This would then conflict with [aswf.io](https://www.aswf.io)'s schemas.
87+
Treating the domain identifier as ownership has proven to be quite resilient.
88+
89+
#### Why not a URL?
90+
91+
It may be preferable to some to use a URL like `https://www.openusd.org/profiles/core/v1.2.3`.
92+
93+
However, this has been problematic in past systems where URL's bitrot, and require
94+
that everyone align on one website structure, or that runtimes have many parsers.
95+
96+
A standardized reverse domain name notation is therefore considered a good middleg round.
97+
Users may still have to search for the specific feature, but they'll
98+
at least know who to ask.
99+
100+
### Profile Versioning
101+
102+
We propose that versions of profiles use [semantic versioning](https://semver.org)
103+
compatible strings. We recognize that many projects, including OpenUSD, do not use
104+
semver. However, there is benefit in using a string that can be parsed by
105+
semver parsers even if the semantic meanings of the tokens aren't the same.
106+
107+
For example, one application may support a specific version of an extension but not older or newer versions of it.
108+
109+
### Profile Augmentation
110+
111+
Our proposal for profiles includes the concept of a base profile and augmentations
112+
beyond that.
113+
114+
The base profile should be a well known base level understanding of what features are
115+
standardized under it.
116+
117+
For example, `org.openusd.core = 0.25.8` to represent a core profile of USD that
118+
aligns with OpenUSD 25.8.
119+
120+
Features beyond this base profile may be specified as well in a similar way,
121+
augmenting it. Therefore, profiles are always additive.
122+
123+
`com.apple.realitykit.components = 1.2.3` could augment the base profile, as one
124+
example.
125+
126+
### Dictionary Overview
127+
128+
We propose the dictionary have the following top level keys:
129+
130+
- **name** : The identifier of the base profile
131+
- **version** : The version of the base profile
132+
133+
Beyond that, there are sub-dictionaries of augmentations. Each of these two are
134+
further subdivided into categories as described in the next section:
135+
136+
- **required** : A set of profile augmentations that are
137+
required to present this USD stage. For example, if using geometry compressed
138+
file format plugins, the stage would not represent in a usable form without
139+
their availability.
140+
141+
- **optional** : A set of profile augmentations that are
142+
not required to portably represent this stage. For example, Reality Kit or other
143+
runtimes may include many runtime specific schemas for behaviour etc... which
144+
are not expected to be used by a DCC.
145+
146+
Finally, it may also be beneficial to share what versions of runtimes the document
147+
has been intended for or tested with. This is a mapping of identifiers to
148+
their versions.
149+
150+
- **compatibility** : A map of which versions of a DCC or runtime the document has
151+
been tested for or is intended to be used with. e.g `com.sidefx.houdini = "12.4""`.
152+
These should not be used to prevent loading of the file in mismatched versions, but
153+
provide a standardized way to warn a user if compatibility might be an issue.
154+
155+
### Augmentation Dictionary Categories
156+
157+
Both the required and optional augmentation dictionaries are further subdivided
158+
into categories.
159+
160+
Categories help organize the augmentations into their respective domains.
161+
This further allows a runtime to decide what to present to a user.
162+
163+
For example,a runtime that is not rendering need not bother with augmentations
164+
that are meant for visualization.
165+
166+
Additionally, this allows for better, standardized reporting structures to users
167+
in whatever manner the runtime or app chooses. e.g Maya and Blender would inherently
168+
have different UIs, but wouldn't have to necessarily provide their own categorization.
169+
170+
We propose the following categories:
171+
172+
- **imaging** : features that a renderer would need to support this document.
173+
For example, Gaussian Splat rendering `com.adobe.splats`.
174+
- **fileFormats** : data plugins that are needed to be read by USD to recreate a hierarchy. e.g `org.aswf.materialx`
175+
- **assetFormats** : Asset formats for textures or audio that may be required.
176+
e.g `org.aswf.vdb`
177+
- **schemas** : Schemas that may be required for correct parsing of this scene.
178+
e.g `com.apple.realitykit.components`
179+
- **features** : A list of USD features that may not be supported by a given runtime.
180+
e.g a USD file may use relocates, but an older runtime won’t understand them even
181+
if it can parse them. e.g `org.openusd.relocates`
182+
- **general** : Extensions that don’t fit in a predetermined category
183+
184+
## Profiles vs Extensions
185+
186+
Other formats like glTF have extension facilities as described
187+
in [glTF 2.0 Extension Registry](https://github.com/KhronosGroup/glTF/blob/main/extensions/README.md).
188+
189+
Unlike extensions, profiles (as described here) do not add new functionality.
190+
Instead, profiles are a complement to OpenUSD's existing extension system by allowing
191+
up front declaration of which extensions are in use.
192+
193+
Profiles are intended to have no runtime side effects beyond their declaration.
194+
195+
## Runtime Analysis
196+
197+
A concern about profiles is that they are just hints, and are taken at face value.
198+
199+
The real truth is of course always in the actual data stored, whether thats the schemas or asset formats used.
200+
201+
However, this requires runtimes to analyze everything in the scene, and have an
202+
understanding what they may not support ahead of time.
203+
This is difficult in several scenarios, especially when combined with composition
204+
to analyze ahead of time. Additionally, this can help reduce the need to parse
205+
multiple file formats ahead of time to know if they're supported.
206+
207+
As such, profiles are simply hints that should be truthful from the content creation
208+
pipeline to the consuming application/runtime. They are not meant to be taken
209+
as absolute truth.
210+
211+
## Metadata Location
212+
213+
One question is where is best to store the metadata. Especially when it comes to the
214+
use of multiple layers composing a stage.
215+
Does the root layer need to describe the sum of all profile information of the rest
216+
of the stage?
217+
218+
Therefore, it may be preferable to store the metadata on the individual top level prims.
219+
220+
This would allow the metadata to compose together, at the expense of a little more
221+
complexity in where to look for the metadata.
222+
223+
## Suggested Core Profile
224+
225+
We propose the addition of an OpenUSD base profile that corresponds to the USD version.
226+
227+
This would be a well recognized base profile to use for systems in the form of
228+
`org.openusd.core` where the version would be `0.24.5` etc...
229+
230+
Future base profiles could be managed by well known bodies in the industry like the
231+
AOUSD. For example if there was a more limited set of USD for the web without
232+
features like volumetrics, it could be `org.aousd.web` with a requisite version.
233+
234+
## Suggested Augmentation Profiles
235+
236+
The following profiles are examples of hypothetical augmentation profiles.
237+
238+
- **org.aom.vvm** : Use of
239+
the [Volumetric Visual Media](https://aomedia.org/press%20releases/call-for-proposals-on-static-polygonal-mesh-coding-technology/)
240+
compression
241+
- **org.aom.avif** : Use of the AVIF media encoder, since USD files may need to be
242+
used in older runtime versions that do not include the AV1 decoder.
243+
- **com.apple.realitykit.components** : Components that describe RealityKit specific runtime behaviour.
244+
- **org.aswf.materialx** : Requires usdMtlx be built for a specific version of MaterialX to load the data
245+
- **org.aswf.openvdb** : Requires VDB to be available to load volumetric data
246+
247+
## Validation
248+
249+
The addition of profiles could open up the opportunity for more granular validation.
250+
e.g a file that doesn't claim to use RealityKit components could surface a warning
251+
if those components are encountered.
252+
253+
Specific additions to validation are considered out of scope for this proposal, but
254+
the idea as an abstract is one that could be useful.
255+
256+
There are a few ways that profiles can help with validation of USD files:
257+
258+
1. An application may present warnings on load when it load a USD file that uses an unsupported extension. This would be
259+
similar to when Maya loads a ma file using unknown plugins , or when Keynote loads a file that makes use of unknown
260+
fonts.
261+
2. Asset deliveries could have very quick validation to make sure that the assets aren’t using undesirable extensions,
262+
prior to parsing the files themselves. The list of e compatibility information could be provided to asset vendors to
263+
check against in a normative way.
264+
3. An asset library could choose to only show USD files that have extension versions compatible with the current
265+
application
266+
4. Command line tools (like the macOS fork of usdchecker) could validate whether a given set of extensions would work on
267+
the current versions of RealityKit etc...
268+
269+
## Alternate Solutions
270+
271+
When proposing this addition, no other alternate approaches were suggested
272+
beforehand by contributors and evaluators.
273+
274+

0 commit comments

Comments
 (0)