minna/minna-pima
1
0
Fork 0
Code Releases Activity Actions

Update README.md

Browse source
This commit is contained in:
Moritz Ruth 2025-04-19 21:52:13 +02:00
parent e01d249c8e
commit f834a8235e
Signed by: moritzruth
GPG key ID: C9BBAB79405EE56D
1 changed files with 18 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

36
README.md
View file

@ -2,7 +2,7 @@
> Picture manager intended for usage with Minna. > Picture manager intended for usage with Minna.
**`minna-pima`** integrates with [`minna-caos`](https://git.moritzruth.de/minna/minna-caos) to provide picture management features. **minna-pima** integrates with [minna-caos](https://git.moritzruth.de/minna/minna-caos) to provide picture management features.
Similarly to the latter, it is intended as a companion to a single application (“the app”) that has full authority. Similarly to the latter, it is intended as a companion to a single application (“the app”) that has full authority.
@ -24,20 +24,20 @@ Similarly to the latter, it is intended as a companion to a single application (
### Pictures are not cached ### Pictures are not cached
`minna-pima` does not cache the pictures it generates on-demand. minna-pima does not cache the pictures it generates on-demand.
This is by design: Caching is hard and better left to tools designated for this purpose. This is by design: Caching is hard and better left to tools designated for this purpose.
It is therefore recommended to use a caching reverse-proxy in front of **minna-pima**. It is therefore recommended to use a caching reverse-proxy in front of minna-pima.
<!-- TODO: example configuration for Caddy with https://github.com/darkweak/souin#caddy-module --> <!-- TODO: example configuration for Caddy with https://github.com/darkweak/souin#caddy-module -->
### Example picture upload flow ### Example picture upload flow
1. The _client_ uploads a PNG file to _`minna-caos`_ in cooperation with the _app_. 1. The client uploads a PNG file to minna-caos in cooperation with the app.
2. Because _`minna-caos`_ detected that the file is a PNG image, the _app_ decides to use `minna-pima`. 2. Because minna-caos detected that the file is a PNG image, the app decides to use minna-pima.
3. The _app_ sends a `GET /objects/ORIGINAL_UPLOAD_HASH/similar` request to _`minna-pima`_: 3. The app sends a `GET /objects/ORIGINAL_UPLOAD_HASH/similar` request to minna-pima:
1. _`minna-pima`_ fetches the object’s content and media type from _`minna-caos`_. 1. minna-pima fetches the object’s content and media type from minna-caos.
2. _`minna-pima`_ computes a perceptual hash of the picture and uses it to search its database for similar pictures. 2. minna-pima computes a perceptual hash of the picture and uses it to search its database for similar pictures.
3. It finds two matching pictures and returns the following result: 3. It finds two matching pictures and returns the following result:
```json ```json
{ {
@ -45,13 +45,13 @@ It is therefore recommended to use a caching reverse-proxy in front of **minna-p
} }
``` ```
4. The _app_ notifies the _client_ that there are similar pictures. 4. The app notifies the client that there are similar pictures.
5. The _user_ decides that… 5. The user decides that…
1. the first picture is unrelated, and 1. the first picture is unrelated, and
2. the second picture is a lower-quality version of the uploaded picture and should be replaced by the higher-quality version. 2. the second picture is a lower-quality version of the uploaded picture and should be replaced by the higher-quality version.
6. The _client_ notifies the _app_ of the user’s decision. 6. The client notifies the app of the user’s decision.
7. The _app_ creates a new upload through _`minna-caos`_. It’s ID is `CONVERTED_UPLOAD_ID`. 7. The app creates a new upload through minna-caos. Its ID is `CONVERTED_UPLOAD_ID`.
8. The _app_ sends a `POST /pictures/` request to _`minna_pima`_ with the following payload: 8. The app sends a `POST /pictures/` request to _`minna_pima`_ with the following payload:
```json ```json
{ {
"hash": "ORIGINAL_UPLOAD_HASH", "hash": "ORIGINAL_UPLOAD_HASH",
@ -59,10 +59,10 @@ It is therefore recommended to use a caching reverse-proxy in front of **minna-p
"replaces": ["def456"] "replaces": ["def456"]
} }
``` ```
1. _`minna-pima`_ fetches the content and the media type of the object from _`minna-caos`_. 1. minna-pima fetches the content and the media type of the object from minna-caos.
2. _`minna-pima`_ generates a ThumbHash and converts the picture to AVIF because PNG is not in the list of allowed source formats. 2. minna-pima generates a ThumbHash and converts the picture to AVIF because PNG is not in the list of allowed source formats.
3. _`minna-pima`_ uploads the picture to _`minna-caos`_ using `PATCH /uploads/CONVERTED_UPLOAD_ID`. 3. minna-pima uploads the picture to minna-caos using `PATCH /uploads/CONVERTED_UPLOAD_ID`.
9. The _app_ waits for the `CONVERTED_UPLOAD_ID` upload to finish. The new picture’s ID is also `CONVERTED_UPLOAD_ID`. 9. The app waits for the `CONVERTED_UPLOAD_ID` upload to finish. The new picture’s ID is also `CONVERTED_UPLOAD_ID`.
A 100×100 WebP version can be fetched from `/pictures/CONVERTED_UPLOAD_ID/100x100.webp`. A 100×100 WebP version could then, for example, be fetched from `/pictures/CONVERTED_UPLOAD_ID/100x100.webp`.