Postcards#

A tool for creating archival and postable scans of postcards, and their metadata. The postcards CLI tool can create & convert between a number of formats suitable for the web and 3D environments. The postbox server can offer the same service over the internet.

See them in use at:

• shutup.jp

Install#

If you have Homebrew installed:

brew install jphastings/tools/postcards

You can also download compiled binaries from Github releases for Windows, Linux, macOS — each of which is provided for arm64 and amd64 architectures.

WASIp1 compatible WASM executables are also provided with a reduced feature set (notably the more efficient image encoders, WebP and JPEGli, are absent).

Usage#

To make your first postcard file you should scan both sides of your postcard, its "components".

• Use a scanner (for accurate resolution info)
• Use a black background (as black as possible, to minimise shadows)
• Save your scan as a TIFF or PNG (for high, lossless quality)

Pick a name for your postcard, eg. pyramid, and name your scans {name}-front.png and {name}-back.png (or {name}-only.png if you're only producing a single sided card).

Create a template metadata file & edit it to show the details of your postcard:

$ postcards init pyramid
⚙︎ Generating 1 postcard metadata file…
Template (Metadata) → (Metadata) pyramid-meta.yaml

$ vi pyramid-meta.yaml

$ ls
pyramid-back.png
pyramid-front.png
pyramid-meta.yaml

Now you can generate any other postcard format from this "component" format:

$ postcards -f usdz,web,html,css pyramid-meta.yaml
⚙︎ Converting 1 postcard into 4 different formats…
pyramid-meta.yaml (Component files) → (USDZ 3D model) pyramid.postcard.usdz
pyramid-meta.yaml (Component files) → (Web) pyramid.postcard.jpg
pyramid-meta.yaml (Component files) → (HTML) pyramid.html
pyramid-meta.yaml (Component files) → (CSS) postcards.css

Here we've produced:

• A USDZ 3D model of the postcard, suitable for iOS augmented reality
• A Web image of the postcard, that can be archived (as it holds all the postcard information), and can be used with…
• Some HTML suitable for displaying the postcard Web image on a website
• The CSS needed to display the HTML format in a pretty way