byjp.me
A tool for archiving & converting scans of postcards, and information about them.
Enhance help docs
+2
-1
docs/formats/css.md
+2
-1
docs/formats/css.md
···
2
3
This output format produces the same `postcards.css` file every time, which can be used in conjunction with the [html](html.md) format to display [web.md] format postcards beautifully on the web.
4
5
-
The CSS is modern, and makes use of [nesting](https://caniuse.com/css-nesting), so you may need to do some extra work if your target audience uses older browsers.
6
7
## Example
8
···
2
3
This output format produces the same `postcards.css` file every time, which can be used in conjunction with the [html](html.md) format to display [web.md] format postcards beautifully on the web.
4
5
+
> [!WARNING]
6
+
> The CSS is modern, and makes use of [nesting](https://caniuse.com/css-nesting), so you may need to do some extra work if your target audience uses older browsers.
7
8
## Example
9
+4
-2
docs/formats/html.md
+4
-2
docs/formats/html.md
···
2
3
Used in conjunction with the [css](css.md) and [web](web.md) formats, this output format creates a sample `{name}.html` file with an HTML fragment that's suitable to display the postcard being converted.
4
5
-
The HTML fragment produced has two sections separated by `\n\n` (the only `\n\n` in the file). The first of these sections can be discarded if you're injecting the HTML into an already established postcards page.
6
7
-
In the unlikely even that the CSS being produced by the [css](css.md) format changes in a backwards incompatible way (which will only happen after a breaking change release of this tool) then any HTML previously produced by this format may also need to be updated. Details on how to manually make the needed changes will be in the release notes for this tool.
8
9
## Example
10
···
2
3
Used in conjunction with the [css](css.md) and [web](web.md) formats, this output format creates a sample `{name}.html` file with an HTML fragment that's suitable to display the postcard being converted.
4
5
+
> [!TIP]
6
+
> The HTML fragment produced has two sections separated by `\n\n` (the only `\n\n` in the file). The first of these sections can be discarded if you're injecting the HTML into an already established postcards page.
7
8
+
> [!NOTE]
9
+
> In the unlikely even that the CSS being produced by the [css](css.md) format changes in a backwards incompatible way (which will only happen after a breaking change release of this tool) then any HTML previously produced by this format may also need to be updated. Details on how to manually make the needed changes will be in the release notes for this tool.
10
11
## Example
12
+4
-1
docs/formats/usd.md
+4
-1
docs/formats/usd.md
···
1
# Universal Scene Description 3D format
2
3
+
An ASCII formatted USD file, and its texture. The components of a compiled [USDZ file](usdz.md).
4
+
5
+
> [!TIP]
6
+
> If you meet the requirements of `usdz` output (you have the `usdzip` tool installed) then you probably want that format, not this one!
7
8
## Example
9
+8
docs/formats/usdz.md
+8
docs/formats/usdz.md
···
6
7
Alongside 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
## Requirements
10
11
USDZ creation requires that the `usdzip` tool is installed on yours system (see [OpenUSD](https://openusd.org/) for information). If you don't have access to that tool, you can still export in the `usd` format, which produces both the unzipped (and text-formatted) version of USD and the necessary texture file.
···
6
7
Alongside 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
## Requirements
18
19
USDZ creation requires that the `usdzip` tool is installed on yours system (see [OpenUSD](https://openusd.org/) for information). If you don't have access to that tool, you can still export in the `usd` format, which produces both the unzipped (and text-formatted) version of USD and the necessary texture file.
+2
-1
docs/formats/web.md
+2
-1
docs/formats/web.md
···
4
5
If the postcard is 'heteroriented' (the back and front have different orientations) then the lower half will be rotated 90º clockwise (for left-hand flip postcards), or 90º anti-clockwise (for right-hand flip postcards), so that a Web format postcard is always the same width as the front of the postcard, and twice the height of the front.
6
7
-
By default this format uses lossy JPEGli compression and resizing to make a small but high quality image. If your input images use transparency, or if you request an 'archival' quality postcard, then it will produce a WebP format image that can support what you've requested.
8
9
## Example
10
···
4
5
If the postcard is 'heteroriented' (the back and front have different orientations) then the lower half will be rotated 90º clockwise (for left-hand flip postcards), or 90º anti-clockwise (for right-hand flip postcards), so that a Web format postcard is always the same width as the front of the postcard, and twice the height of the front.
6
7
+
> [!TIP]
8
+
> By default this format uses lossy JPEGli compression and resizing to make a small but high quality image. If your input images use transparency, or if you request an 'archival' quality postcard, then it will produce a WebP format image that can support what you've requested.
9
10
## Example
11
+5
-1
docs/formats/xmp.md
+5
-1
docs/formats/xmp.md
···
2
3
Postcard 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
-
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. 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.
6
7
## Structure
8
···
2
3
Postcard 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