byjp.me
A tool for archiving & converting scans of postcards, and information about them.
docs: Improve Readme
+15
-22
README.md
+15
-22
README.md
···
21
21
22
22
To make your first postcard file you should scan both sides of your postcard, its "components".
23
23
24
-
> [!NOTE]
25
-
> JPG, PNG and TIFF formats are all supported, but JPG may lose quality, and some scanning software's TIFF format isn't compatible with this software.
24
+
- Use a scanner (for accurate resolution info)
25
+
- Use a black background (as black as possible, to minimise shadows)
26
+
- Save your scan as a PNG (For quality, and because Go doesn't support macOS' TIFF encoding)
26
27
27
28
> [!TIP]
28
-
> Taking a photo will work, but a scanner won't produce reflections or add perspective to your postcard, and can provide accurate information about its physical size — which you'd have to add manually otherwise.
29
+
> There is an experimental web-based postcard creator at [create.dotpostcard.org](https://create.dotpostcard.org), which you may find easier.
29
30
30
-
Pick a suitable short name for your postcard, eg. `pyramid`.
31
+
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).
31
32
32
-
> [!TIP]
33
-
> Using only a-z, 0-9, hyphens, and underscores is smart as this will prevent issues moving your postcard between computers and ecosystems.
34
-
35
-
Name your two scans `{name}-front.{ext}` and `{name}-back.{ext}` (or `{name}-only.{ext}` if you're only producing a single sided card).
36
-
37
-
```sh
38
-
$ ls
39
-
pyramid-front.png
40
-
pyramid-back.png
41
-
```
42
-
43
-
Create a template metadata file & fill it out with the details of your postcard:
33
+
Create a template metadata file & edit it to show the details of your postcard:
44
34
45
35
```sh
46
36
$ postcards init pyramid
47
37
⚙︎ Generating 1 postcard metadata file…
48
38
Template (Metadata) → (Metadata) pyramid-meta.yaml
39
+
40
+
$ vi pyramid-meta.yaml
41
+
42
+
$ ls
43
+
pyramid-back.png
44
+
pyramid-front.png
45
+
pyramid-meta.yaml
49
46
```
50
47
51
-
Now generate any other postcard format from this "component" format:
48
+
Now you can generate any other postcard format from this "component" format:
52
49
53
50
```sh
54
-
$ postcards -f web,usdz,html,css pyramid-meta.yaml
51
+
$ postcards -f usdz,web,html,css pyramid-meta.yaml
55
52
⚙︎ Converting 1 postcard into 4 different formats…
56
53
pyramid-meta.yaml (Component files) → (USDZ 3D model) pyramid.postcard.usdz
57
54
pyramid-meta.yaml (Component files) → (Web) pyramid.postcard.jpg
···
68
65
69
66
> [!IMPORTANT]
70
67
> Most formats can be converted between each other (web, usdz, component). If this is likely use the `--archival` flag to turn on lossless conversion so quality remains high until the final conversion.
71
-
72
-
## Under construction
73
-
74
-
This repo is in rapid development (and migration from a previous iteration at [dotpostcard/postcards-go](https://github.com/dotpostcard/postcards-go)) — please bear with me!