byjp.me
A tool for archiving & converting scans of postcards, and information about them.
1# Universal Scene Description (zip) format
2
3[USDZ](https://en.wikipedia.org/wiki/Universal_Scene_Description) is a 3D modelling format used extensively by Pixar and Apple. Postcards are created with the correct physical dimensions for augmented reality usage.
4
5For postcards with only one side stored in the file the produced model will (by default) have the same image on both sides.
6
7Alongside the 3D model data the zip file that is the produced USDZ holds the [web](web.md) format postcard in JPEG form. This is used directly as the texture file for the 3D model — it can be extracted manually if needed, but this tool will do this while performing consistency checks.
8
9> [!NOTE]
10> The USD contains Apple ARKit-specific extensions that flip the postcard (along the correct axis) when it is tapped. Those these extensions won't work on other platforms, they won't cause any problems either.
11
12> [!WARNING]
13> Postcards with transparent borders (like those created with the `-B` flag) don't work well with the USDZ format (yet). The transparency is ignored, and the postcard will look a little odd, particularly if it isn't rectangular.
14>
15> Eventually I'd like to alter the 3D model's geometry to match the outermost opaque pixels of a transparent-border postcard, but that's a complex operation I've not yet got around to.
16
17## Example
18
19```sh
20$ postcards -f usdz pyramids-front.jpg
21⚙︎ Converting 1 postcard into 1 different format…
22pyramids-front.jpg (Component files) → (USDZ 3D model) pyramids.postcard.usdz
23```