{
  "schemaVersion": "1.0",
  "canonicalPage": "https://fileformat.co/ext/usdz",
  "inspectorUrl": "https://fileformat.co/inspect",
  "spec": {
    "slug": "usdz",
    "extension": ".usdz",
    "aliases": [],
    "name": "USDZ Spatial 3D Archive (Pixar / Apple VisionOS)",
    "shortName": "USDZ",
    "category": "media-3d",
    "tier": 1,
    "summary": "Zero-compression, 64-byte mmap-aligned PKZIP package created by Pixar & Apple for AR QuickLook and VisionOS spatial scenes, beginning with a root `.usdc` (`PXR-USDC`) or `.usda` stage.",
    "technicalNotes": "Standard ZIP tools break USDZ! Every member MUST use `ZIP_STORED` (method 0) AND start its payload at an exact multiple of 64 bytes (padded via ZIP extra fields).",
    "mimeTypes": [
      "model/vnd.usdz+zip"
    ],
    "identifiers": {
      "specUrl": "https://openusd.org/release/spec_usdz.html"
    },
    "binarySignature": {
      "endianness": "little",
      "magicBytes": [
        {
          "offset": 0,
          "hex": "50 4B 03 04",
          "ascii": "PK..",
          "description": "Uncompressed 64-byte aligned ZIP containing PXR-USDC layer at offset 0x40"
        }
      ],
      "containerFamily": "zip",
      "headerLayout": [
        {
          "offset": "0x00 - 0x1D",
          "byteOffset": 0,
          "byteLength": 30,
          "lengthLabel": "30 B",
          "dataType": "zip_lfh",
          "fieldName": "local_header",
          "description": "ZIP header with compression_method == 0 (Store)"
        },
        {
          "offset": "0x1E - 0x3F",
          "byteOffset": 30,
          "byteLength": 34,
          "lengthLabel": "var",
          "dataType": "name+pad",
          "fieldName": "alignment_pad",
          "description": "Filename + extra field padding to 64-byte boundary"
        },
        {
          "offset": "0x40 - 0x47",
          "byteOffset": 64,
          "byteLength": 8,
          "lengthLabel": "8 B",
          "dataType": "char[8]",
          "fieldName": "usdc_magic",
          "description": "'PXR-USDC' Crate binary stage header"
        }
      ]
    },
    "securityProfile": {
      "riskLevel": "low",
      "allowsArbitraryCodeOrMacros": false,
      "xxeRisk": false,
      "polyglotPrependRisk": true,
      "pickleDeserializationRisk": false,
      "uploadValidationNotes": "Verify method==0 (uncompressed), data_offset % 64 == 0 for every entry, and first entry extension in {.usdc, .usda, .usd}."
    },
    "codeSnippets": {
      "python": "import struct, sys\nwith open(sys.argv[1], \"rb\") as f:\n    hdr = f.read(30)\n    sig, ver, flags, method = struct.unpack(\"<IHHH\", hdr[:10])\n    fn_len, ex_len = struct.unpack(\"<HH\", hdr[26:30])\n    data_off = 30 + fn_len + ex_len\n    assert sig == 0x04034B50 and method == 0 and data_off % 64 == 0\n    print(f\"Valid 64B-aligned USDZ: first data_offset=0x{data_off:X}\")",
      "typescript": "export async function checkUsdzAlignment(file: File) {\n  const dv = new DataView(await file.slice(0, 30).arrayBuffer());\n  const method = dv.getUint16(8, true);\n  const dataOffset = 30 + dv.getUint16(26, true) + dv.getUint16(28, true);\n  return { uncompressed: method === 0, aligned64: dataOffset % 64 === 0 };\n}",
      "rust": "use std::{fs::File, io::Read};\nfn main() -> std::io::Result<()> {\n    let mut h = [0u8; 30];\n    File::open(std::env::args().nth(1).expect(\"usage: <prog> <file>\"))?.read_exact(&mut h)?;\n    let off = 30 + u16::from_le_bytes([h[26], h[27]]) + u16::from_le_bytes([h[28], h[29]]);\n    println!(\"USDZ first data offset={} (aligned={})\", off, off % 64 == 0);\n    Ok(())\n}",
      "go": "package main\nimport (\"encoding/binary\"; \"fmt\"; \"io\"; \"os\")\nfunc main() {\n    f, err := os.Open(os.Args[1])\n    if err != nil {\n        fmt.Fprintln(os.Stderr, \"open:\", err)\n        os.Exit(1)\n    }\n    defer f.Close()\n    h := make([]byte, 30)\n    if _, err := io.ReadFull(f, h); err != nil {\n        fmt.Fprintln(os.Stderr, \"read:\", err)\n        os.Exit(1)\n    }\n    off := 30 + binary.LittleEndian.Uint16(h[26:28]) + binary.LittleEndian.Uint16(h[28:30])\n    fmt.Printf(\"USDZ offset=%d aligned=%v\\n\", off, off%64 == 0)\n}"
    },
    "relatedFormats": [
      "glb",
      "ipa",
      "png"
    ],
    "verifiedAt": "2026-11-14T16:09:03Z"
  },
  "samples": [
    {
      "id": "usdz-minimal",
      "filename": "minimal-64b-aligned.usdz",
      "variant": "minimal",
      "title": "64-Byte Aligned Zero-Compression USDZ (PXR-USDC)",
      "description": "Apple VisionOS / QuickLook compliant uncompressed ZIP with 64-byte mmap alignment and `PXR-USDC` Crate root layer.",
      "localPath": "/fixtures/v1/usdz/minimal-64b-aligned.usdz",
      "cdnUrl": "https://fileformat.co/fixtures/v1/usdz/minimal-64b-aligned.usdz",
      "sizeBytes": 206,
      "sha256": "84ed4c279742f4c9aa8557034806427c40d29fb91d3415def454b5371035f3bf",
      "expectValid": true
    },
    {
      "id": "usdz-realistic",
      "filename": "spatial-stage-textured.usdz",
      "variant": "realistic",
      "title": "Multi-Asset USDZ Stage + Embedded PNG Texture",
      "description": "64-byte aligned USDZ archive bundling both a `PXR-USDC` binary stage and an uncompressed RGBA PNG texture.",
      "localPath": "/fixtures/v1/usdz/spatial-stage-textured.usdz",
      "cdnUrl": "https://fileformat.co/fixtures/v1/usdz/spatial-stage-textured.usdz",
      "sizeBytes": 483,
      "sha256": "30477e3f8aaf315b7f84c5950a266a44d86d615dd8ad087d49825eb2b6a35f1e",
      "expectValid": true
    },
    {
      "id": "usdz-edge-case",
      "filename": "unaligned-violation.usdz",
      "variant": "edge-case",
      "title": "Misaligned USDZ Entry (Fails 64-Byte mmap Requirement)",
      "description": "Valid ZIP containing `scene.usdc`, but entry data starts at non-64B-aligned offset—catches subtle USDZ packager bugs.",
      "localPath": "/fixtures/v1/usdz/unaligned-violation.usdz",
      "cdnUrl": "https://fileformat.co/fixtures/v1/usdz/unaligned-violation.usdz",
      "sizeBytes": 182,
      "sha256": "1b5d09db530a3b47b91227c552a243fc0a0debb7e2e757ad2d6988a07e86cdae",
      "expectValid": false,
      "edgeCaseTag": "64-Byte Alignment Violation"
    }
  ]
}