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.
**`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.
@ -24,20 +24,20 @@ Similarly to the latter, it is intended as a companion to a single application (
### 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.
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 -->
### Example picture upload flow
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`.
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`_.
2. _`minna-pima`_ computes a perceptual hash of the picture and uses it to search its database for similar pictures.
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.
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.
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:
```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.
5. The _user_ decides that…
4. The app notifies the client that there are similar pictures.
5. The user decides that…
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.
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`.
8. The _app_ sends a `POST /pictures/` request to _`minna_pima`_ with the following payload:
6. The client notifies the app of the user’s decision.
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:
```json
{
"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"]
}
```
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.
3. _`minna-pima`_ uploads the picture to _`minna-caos`_ using `PATCH /uploads/CONVERTED_UPLOAD_ID`.
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.
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`.