From f834a8235e3a43434a2bdf3a5c419be3b30c5a34 Mon Sep 17 00:00:00 2001 From: Moritz Ruth Date: Sat, 19 Apr 2025 21:52:13 +0200 Subject: [PATCH] Update README.md --- README.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 6d6b6ed..8a6f4a4 100644 --- a/README.md +++ b/README.md @@ -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. ### 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`. \ No newline at end of file + A 100×100 WebP version could then, for example, be fetched from `/pictures/CONVERTED_UPLOAD_ID/100x100.webp`. \ No newline at end of file