byjp.me
A tool for archiving & converting scans of postcards, and information about them.
1# XMP Metadata
2
3Postcard metadata can be stored in [XMP format](https://en.wikipedia.org/wiki/Extensible_Metadata_Platform). Usually this is stored inside the images produced with the [web](web.md) output format.
4
5> [!WARNING]
6> Some features of metadata (particularly the location of secrets) assumes that the image being described is laid out like a Web format postcard — the front above the back, and the back rotated as in the Web format.
7
8> [!TIP]
9> When output directly with `-f xmp` a file `{name}-meta.xmp` will be produced — you may need to rename it to match the name of the postcard file (`{name}.postcard.xmp`) for other tools to recognise the association.
10
11## Structure
12
13The following XMP fields are used to store Postcard metadata. Some of them don't match _perfectly_ semantically (eg. the time the postcard was sent being represented by the tag usually used for when a photo was taken, or the GPS coordinates for the location the postcard references) — but they're close enough for human use. Postcard-specific machine uses should convert them according to the following guide:
14
15Note that the TIFF schema fields (relating to image size) are omitted for XMP output directly (with `postcards -f xmp`), as image size information is only relevant when attached to a specific image.
16
17| XMP field | Schema | Postcard metadata | Use |
18|-----------------------------|----------------|-----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
19| ImageWidth | TIFF | (from source images) | The pixel width of the combined image. |
20| ImageLength | TIFF | (from source images) | The pixel height of the combined image |
21| XResolution | TIFF | (from source images) | The cm width of the combined image (always the width of the front of the postcard) |
22| YResolution | TIFF | (from source images) | The cm height of the combined image (always twice the height of the front of the postcard) |
23| ResolutionUnit | TIFF | (from source images) | Always "3", the indicator for centimetres |
24| Description | DC | - | Always "Both sides of a postcard, stored in the '.postcard' format (https://dotpostcard.org)" |
25| DateTimeOriginal | Exif | sentOn | The date the postcard was sent |
26| GPSAreaInformation | Exif | location.name | The name of the location the postcard references |
27| GPSLatitude | Exif | location.latitude | The latitude of that location |
28| GPSLongitude | Exif | location.longitude | The longitude of that location |
29| AltTextAccessibility | IPTC4 XMP Core | front.description, back.transcription | Generated text suitable to be used as alt text for the postcard |
30| Transcript | IPTC4 XMP Ext | back.transcription, front.transcription | The transcript of any writing on the the postcard. A § character will divide the back and the front (in that order), if needed |
31| ImageRegionName | IPTC4 XMP Ext | - | Always "Private information" for secrets |
32| ImageRegionBoundaryVertices | IPTC4 XMP Ext | front.secrets, back.secrets | The (normalized) x, y positions of the edges of the secret region |
33| ImageRegionBoundaryUnit | IPTC4 XMP Ext | - | Always "relative" (the vertex values are normalized to the width and height of the **image**, not the side) |
34| Flip | Postcard | flip | Which way the postcard should flip (book, calendar, left-hand, right-hand). **This field should be the one used to detect a postcard image** |
35| Sender | Postcard | sender | The name (and possibly URL) of the sender of the postcard |
36| Recipient | Postcard | recipient | The name (and possibly URL) of the recipient of the postcard |
37| Context | Postcard | context.description | Any context provided about the postcard. Always has `xml:lang` attribute, which is the `locale` of the metadata for the postcard. |
38| ContextAuthor | Postcard | context.author | The name (and possibly URL) of the author of the context |
39| ThicknessMM | Postcard | physical.thickness_mm | The thickness of the postcard, if different to the standard 0.4mm |
40| DescriptionFront | Postcard | front.description | An alt-text style description of the front of the postcard |
41| DescriptionBack | Postcard | back.description | An alt-text style description of the back of the postcard |
42| TranscriptionFront | Postcard | front.transcription | The JSON blob representing the transcription of the front of the postcard (with annotations) |
43| TranscriptionBack | Postcard | back.transcription | The JSON blob representing the transcription of the back of the postcard (with annotations) |