Making USDZ files for iPhone AR Quick Look: scale, materials, file size, testing
AR Quick Look needs a USDZ in metres, with PBR materials, under about 25 MB, and will refuse or mis-scale anything else without saying why.
Updated 27 October 2026 · 8 min read
What AR Quick Look expects
AR Quick Look is the viewer built into iOS and iPadOS since version 12. Tap a USDZ link in Safari, Messages, Mail or Files and the system opens it in a full-screen viewer with an Object mode (turntable) and an AR mode that places the model on a detected surface at real-world scale. No app is required, which is why product pages use it.
USDZ is a zip archive, stored uncompressed and 64-byte aligned, containing a USD scene (.usdc binary or .usda text) plus textures. Quick Look reads a specific subset of USD: triangle and quad meshes, UsdPreviewSurface materials, PNG and JPEG textures, simple transform and skeletal animation, and a few AR-specific schemas. Anything outside that subset is ignored or causes the file to fail silently. The requirements that catch most people are units, material type, texture size and overall file size.
Units: USD is in centimetres by default, Quick Look places in metres
USD has a stage-level metersPerUnit attribute. The USD default is 0.01 (centimetres); most exporters write 1.0 (metres) for USDZ, and Quick Look honours the value. A model that comes out ten or a hundred times too large or too small in AR almost always has either the wrong metersPerUnit or geometry authored in the wrong unit for the value declared.
The simplest rule: author the geometry in metres and set metersPerUnit to 1. A 300 mm vase has coordinates spanning 0.3. If you are converting from STL, which slicers treat as millimetres, divide by 1000. Also note that USD is Y-up by default and Quick Look expects Y-up; a Z-up STL or OBJ needs a -90° rotation about X or it lies on its back on the floor.
| Source | Typical units | Factor to metres | Axis change |
|---|---|---|---|
| STL from slicer or CAD | mm, Z-up | ×0.001 | Rotate -90° about X |
| OBJ from Blender (default scene) | m, exported Y-up if option set | ×1 | Usually none |
| GLB / glTF | m, Y-up | ×1 | None |
| FBX from Maya, Unity | cm, Y-up | ×0.01 | None |
| STEP from CAD | mm, Z-up usually | ×0.001 | Rotate -90° about X |
Check in the GLB viewer or STL viewer what the bounding box reads before converting; a bounding box of 300 units from an STL means millimetres and a factor of 0.001. The GLB to USDZ converter keeps metres and Y-up as they are in the glTF, which is why GLB is the easiest source. Converting STL directly through STL to USDZ applies the millimetre-to-metre factor and axis rotation on the way.
Materials: UsdPreviewSurface only
Quick Look renders one material model, UsdPreviewSurface, which is a metallic-roughness PBR shader similar to glTF's. Inputs that work: diffuseColor, metallic, roughness, normal, occlusion, emissiveColor, opacity and clearcoat, either as constants or as textures connected through UsdUVTexture nodes. Anything else (MaterialX, Arnold, Blender Principled BSDF directly) is dropped and the model renders in flat grey or white.
Practical rules:
- Converting from glTF maps almost one-to-one: baseColor to diffuseColor, metallicRoughness to metallic and roughness (split channels), normal to normal, occlusion to occlusion. This is why GLB to USDZ is the most reliable path.
- From Blender, use File > Export > Universal Scene Description with Materials: USD Preview Surface and Export Textures ticked (Blender 3.x and 4.x). Blender writes USDZ directly if the file name ends in .usdz.
- Textures must be PNG or JPEG. No TIFF, no EXR, no KTX2, no WebP. 8-bit only.
- Keep textures at 2048 × 2048 or smaller. Quick Look will load 4096 textures but memory pressure on older devices causes crashes, and the file size grows four times.
- Unlit or emissive-only looks (for scans with baked lighting) work by setting diffuseColor to black and emissiveColor to the baked texture, or more simply by leaving diffuseColor as the baked texture and accepting the added lighting.
- Transparency: set opacity below 1 and, for cut-out leaves and grilles, set opacityThreshold. Glass looks poor in Quick Look; a slightly tinted opacity of 0.3 to 0.5 with roughness 0.05 is the usual compromise.
- An STL has no material at all, so a converter assigns a default. Set a colour and roughness that match the physical product if the file comes from a print.
File size and geometry limits
Apple does not publish a hard limit, but in practice:
- Under 10 MB loads instantly over mobile data; 10 to 25 MB is acceptable; above 50 MB users abandon the download and older iPhones may fail to open it.
- Keep triangle counts under about 100,000 for product models and under 500,000 in any case. A 1-million-triangle scan will open on a recent iPhone but will stutter in AR mode.
- Textures are usually the bulk of the file. A 2048 PNG base colour is 3 to 6 MB; as JPEG at quality 85 it is 400 to 800 KB. Use JPEG for base colour and PNG only where alpha is needed or for normal maps (JPEG artefacts on normal maps are visible as lighting noise).
- Because USDZ is stored without compression, there is no gain from compressing the archive. Reduce what goes in it instead.
Decimate before converting: the reduce tool brings a scan to a target count while preserving the silhouette. For textured GLB, decimate in Blender with the Decimate modifier and keep UVs (Collapse mode preserves them adequately at ratios above 0.2).
Embedding on a web page
Safari opens a USDZ in Quick Look when the link has rel="ar" and contains exactly one image child:
<a rel="ar" href="chair.usdz"><img src="chair.jpg" alt="Chair"></a>
Safari overlays an AR badge on the image. The server must send the file with content type model/vnd.usdz+zip; a wrong MIME type is the most common reason a link downloads the file instead of opening it. Add it to the server configuration (Nginx: types { model/vnd.usdz+zip usdz; }; Apache: AddType model/vnd.usdz+zip .usdz; most CDNs have a custom-header setting).
Optional fragment parameters on the URL control the viewer: #allowsContentScaling=0 stops the user pinch-scaling the model (correct for products meant to be shown at true size), #canonicalWebPageURL= sets the share link, and #applePayButtonType=, #checkoutTitle= and related parameters add a purchase banner.
For a single page that serves both platforms, use <model-viewer> with src pointing to a GLB and ios-src pointing to the USDZ; it shows the AR button on each device for the right file. Android uses the GLB with Scene Viewer.
Testing
- On a Mac: Quick Look in Finder (select the file, press Space) uses the same renderer as iOS. If the file does not preview here, it will not open on the phone. The Reality Converter app (free from Apple's developer site) opens USDZ, shows materials, reports problems and can re-export; Reality Composer can also open it and shows errors in the console.
- On the device: AirDrop the file to the iPhone, or put it in iCloud Drive and open it from Files. Tap it; it should open in Quick Look directly. Check AR mode on a real floor or table and compare the size to a physical reference.
- Through the web: host the file and open the page in Safari on the phone. Confirm the AR badge appears on the image and the tap opens the viewer rather than downloading the file.
- usdchecker: Apple's USD tools (usdzconvert and usdchecker from the USDPython package, or Pixar's USD build) validate structure: usdchecker --arkit file.usdz reports every ARKit compatibility problem by name.
Common errors and what they mean
| Symptom | Cause | Fix |
|---|---|---|
| Safari downloads the file instead of opening it | Wrong MIME type, or the link lacks rel="ar" and an image child | Set model/vnd.usdz+zip; use the exact link structure |
| Quick Look opens then shows "Unsupported file" | Archive is compressed (deflate) or not 64-byte aligned, or contains an unsupported USD feature | Re-export with a USDZ-aware tool; never re-zip by hand |
| Model is huge or tiny in AR | Wrong metersPerUnit or geometry in mm/cm with metersPerUnit 1 | Scale geometry to metres |
| Model lies flat on the floor | Z-up source without axis conversion | Rotate -90° about X before export |
| Everything is white or grey | Material not UsdPreviewSurface, or texture paths broken | Export with Preview Surface; textures must be inside the archive |
| Model is black | Normals inverted or missing; or diffuse texture is 16-bit | Recalculate normals; convert textures to 8-bit |
| Model floats above or sinks into the surface | Origin not at the base of the object | Move the model so its lowest point is at Y = 0 |
| Crashes on open on older devices | Textures too large or too many; triangle count too high | 2048 max textures, decimate |
| Parts missing | Instanced or referenced prims not flattened; n-gons with more than 4 sides | Flatten the stage; triangulate on export |
A typical pipeline
Product in CAD, exported as STEP. Convert to STL at fine tolerance (STEP to STL), decimate to about 80,000 triangles, convert to GLB with a colour and roughness that match the product (STL to GLB), check scale and appearance in the GLB viewer, then convert to USDZ (GLB to USDZ). Open the result in Finder Quick Look, then on a phone. If the product needs real textures, do the UV and texturing step in Blender between STL and GLB. The AR on iPhone and Android guide covers the Android side and viewer embedding in more detail.
FAQ
What units should a USDZ file use?
Author geometry in metres with metersPerUnit set to 1. Quick Look places the model at that scale in AR. Millimetre geometry from STL must be divided by 1000.
How big can a USDZ be for AR Quick Look?
There is no documented limit, but keep it under 25 MB and ideally under 10 MB. Textures at 2048 pixels or smaller and JPEG base colour maps keep most product models well under that.
Why does my USDZ show in grey with no texture?
The material is not UsdPreviewSurface, the texture is not PNG or JPEG, or the texture file is referenced outside the archive. Re-export with Preview Surface materials and embedded textures.
Can I convert STL to USDZ?
Yes. Scale from millimetres to metres, rotate from Z-up to Y-up, assign a material, then package as USDZ. The STL to USDZ converter does these steps in the browser; the result will be a single-colour model since STL has no texture.
Why does Safari download the USDZ instead of opening it?
The server is sending the wrong content type. It must be model/vnd.usdz+zip. The link also needs rel="ar" with a single image child for the AR badge and direct opening.