Usdz File Format Specification

Copyright © 2018, Pixar Animation Studios, version 1.2

Purpose

USD provides multiple features that could make it a compelling choice for 3D content delivery, including:

  • Robust schemas for interchange of geometry, shading, and skeletal deformation

  • High performance data retrieval and rendering, including powerful instancing features

  • The ability to package user-selectable content variations, natively

  • A sound architecture that is flexible enough to adapt to future needs

However, part of USD’s appeal is its ability to create a 3D scene by “composing” many modular data sources (files) together into successively larger and larger aggregations. While very useful within content creation pipelines, this aspect can be a very large hindrance to using USD to deliver assets in the form that they have been built up. In particular, even though USD does provide several means of “flattening” multiple USD files into a single file, there is, by design, no mechanism for representing images/textures as the “scene description” encodable in USD files. Content delivery is simplified and useful on a broader range of platforms when the content is:

  1. A single object, from marshaling and transmission perspectives

  2. Potentially streamable

  3. Usable without unpacking to a filesystem

We believe we can address these concerns by leveraging USD’s FileFormat plugin mechanism to design an archive format that contains and proxies for files of other formats embedded within the archive. This document provides the specification for such a format, for which we will assign the . usdz extension; we refer to the format as “the usdz format”, as we similarly refer to the usda and usdc file formats; only when forming the start of a sentence or word in a class name do we capitalize it, such as UsdUsdzFileFormat. We refer to usdz files as packages, and the design rests on a new Ar-level abstraction of a package, of which the UsdUsdzFileFormat is the first implementation, but we retain the architecture required to easily add others in the future, if needed.

Usdz Specification

A usdz package is an uncompressed zip archive that is allowed to contain the following file types:

Kind

Allowed File Types

USD

usda, usdc, usd

Image

png, jpeg, exr

Audio

M4A, MP3, WAV

The rest of the section goes into more detail about the specification.

Foundation

A usdz package is a zip archive .

Zip Constraints

A usdz package is a zero compression, unencrypted zip archive. We reserve the ability to relax this constraint in the future, but consider it unlikely.

Layout

The only absolute layout requirement a usdz package makes of files within the package is that the data for each file begin at a multiple of 64 bytes from the beginning of the package.

However, if you wish the package to be presentable on a UsdStage “as is”, or be able to target the package with a simple reference to the package itself, then the first file in the package must be a native usd file , but otherwise, there are no constraints on the number or layout of other files in the package. We refer to this “first USD file” as the Default Layer , in analogy to the defaultPrim metadata used to allow layer referencers to elide a prim target.

Clients wishing to deliver “streamable content” may wish to consider other layout constraints , as well.

File Types

A usdz package can contain only file types whose data can be consumed by the USD runtime via mmap, pointer to memory, or threadsafe access to a FILE * (i.e. solely pread-like access). This excludes, for example, Alembic files, currently. Allowable file types are currently:

  • usda, usdc, usd files (Apple’s current usdz implementation allows only a single usdc file, but this restriction will be lifted in future OS updates)

  • png, jpeg (any of the multiple common extensions for jpeg), and OpenEXR files for images/textures. See Working With Image File Formats for more details on supported image file formats.

  • M4A, MP3, WAV files for embedded audio (given in order of preferred format)

USD Constraints

To make usdz packages maximally useful within production pipelines, we impose no further constraints on the allowable content within a package. Of particular note:

  • it is possible to reference individual files within a package from outside the package

  • packages can themselves contain other packages.

When the key intention of a package is to provide perfectly reproducible results in arbitrary consuming environments, it may be useful to enforce restrictions on the kinds of asset paths encoded in USD files within the package. We explore this further in For Reproducible Results, Encapsulate Using Anchored Asset Paths , and imagine that adherence to such protocols may be something useful to encode in package metadata (see next item).

Editability

A usdz file is read-only - editing its contents requires first unpacking the package and editing its constituent parts using appropriate tools. Since usdz is a “core” USD file format, one can use usdcat and usdedit on packages:

  • If the package contains a Default Layer, usdcat will print its contents, otherwise, it prints nothing.

  • If the package contains a Default Layer file, usdedit will populate an editor with its contents, but with the –noeffect option in force, preventing the saving of any changes; otherwise, it will show an empty layer.

Accessibility

Although not required, if creators of usdz packages use SdfLayer::SetDocumentation to add a documentation string to the Default Layer, then consumers of usdz packages can retrieve the textual description using SdfLayer::GetDocumentation on the Default Layer.

Packaging Considerations for Streaming and Encapsulation

File Ordering Within Package for Streaming

There are many interpretations and possible implementations/encodings of “streaming usd context”, and we feel it is, at this time, beyond the scope of USD’s concerns to dictate how streaming must be achieved. We limit our concern in this matter to the already-stated “Default Layer” semantics, which dictates the first file in the package must be a usd file for the package to be imageable directly on a stage. This means that a consumer app can, using the zip (or wrapper, provided by the usdz file format) API, determine the size of the first file and therefore know when it has been fully delivered, and display the contents of that file in its “default state”, while waiting for subsequent files (described in the layer’s metadata) to be delivered. This enables many kinds of streaming; to suggest just a few:

  • LOD, in which the first file contains low-complexity geometry, with a variantSet that can bring in higher quality LOD’s in other files, when switched

  • LOD, in which the first file binds no or simple materials, with a variantSet that binds texture-driven Materials when the textures are available

  • Animation, in which the first file contains a static pose, with a payload arc to another file containing animation.

It is important to note that the USD runtime has no knowledge or consideration of streaming: it will be the responsibility of the client application to manage the scene it is streaming, and ensuring not to ask the USD runtime to consume any part of the package that has not yet been delivered. In particular, it must use the provided API’s to construct an SdfLayer directly using offsets into an incompletely downloaded usdz package, rather than trying to point a UsdStage directly at the incomplete usdz package, as the UsdzFileFormat will assume and require that the package it is consuming is complete and intact.

For Reproducible Results, Encapsulate Using Anchored Asset Paths

To insure uniform consumption of assets shipped to clients via usdz, we feel it is prudent to curtail the power of USD’s asset resolution system, so that the asset references within a package resolve uniformly on any consuming system, regardless of how that system’s USD ArResolver is configured. Rather than make restrictions within the FileFormat itself, we propose that such “encapsulation” of packages be achieved by restricting the content to only use anchored paths (paths that begin with “./” or “../”, both of which are interpreted in the virtual filesystem described by the package’s internal layout.

This does not prevent one from overriding the textures or other non-USD assets contained in an “encapsulated” package, by specifically overriding the attributes that name the assets, in a layer stronger than the package in a composition.

MIME Type

Usdz is registered with IANA, with a media type name of model and a subtype name of vnd.usdz+zip . For full details, see Usdz’s IANA registration page.

Toolset

The UsdzFileFormat includes helper API’s for introspecting and extracting data from a package, as well as tailored wrappings of the zip API functions for creating and adding files to an package that satisfy the usdz layout constraints. The toolset also includes:

  • usdzip - a command-line program that accepts either an explicit list of files to package, or when provided the --asset or --arkitAsset options, will “localize” the named USD file, discovering all (recursively) referenced files, updating the references to point to their new, package-relative locations, and create a new usdz package. The reason for a --arkitAsset option separate from --asset is that usdz files intended for transmission to iOS devices support a more limited subset of USD functionality. usdzip can also list the contents of a package file, and optionally validate the contents as they are being packaged. Usdz files can be unpacked using any zip/unzip program.

  • usdcat, usdedit - as described above, these utilities will operate on the defaultLayer of a usdz package.

  • usdchecker - will validate the contents of a package (or any other USD format) ; for usdz files specifically, the usdchecker option --arkit will make usdchecker enforce stricter “web-compliant” rules that disallow certain advanced USD features that web-browsers do not yet support.