From f26165910da9fcfd2347a899ac4dcc3679138eda Mon Sep 17 00:00:00 2001 From: Michael Stingl <214010+michaelstingl@users.noreply.github.com> Date: Thu, 30 Nov 2023 10:07:18 +0100 Subject: [PATCH 1/5] [docs-only] Adding thumbnail query parameters to thumbnail README.md Observed with ownCloud Web UI 7.1.0 (Spaces overview): ``` scalingup: 0 preview: 1 a: 1 c: ce88e69a448ab8acf7ff554be5bb5521 x: 1000 y: 1000 ``` --- services/thumbnails/README.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/services/thumbnails/README.md b/services/thumbnails/README.md index cc8fb7dc2..258de45ae 100644 --- a/services/thumbnails/README.md +++ b/services/thumbnails/README.md @@ -39,6 +39,21 @@ If a file type was not properly assigned or the type identification failed, thum Thumbnails can either be generated as `png`, `jpg` or `gif` files. These types are hardcoded and no other types can be requested. A requestor, like another service or a client, can request one of the available types to be generated. If more than one type is required, each type must be requested individually. +## Thumbnail Query String Parameters + +Clients can request thumbnail previews for files by adding `?preview=1` to the file URL. Requests for files with thumbnail availabe respond with HTTP status `404`. + +The following query parameters are supported: + +| Parameter | Required | Default Value | Description | +| --------- | -------- | ---------------------------------------------------- | ----------------------------- | +| preview | YES | 1 | generates preview | +| x | YES | first x-value configured in `THUMBNAILS_RESOLUTIONS` | horizontal target size | +| y | YES | first y-value configured in `THUMBNAILS_RESOLUTIONS` | vertical target size | +| a | NO | 1 | aspect ratio | +| c | NO | ??? | ??? | +| processor | NO | ??? | preferred thumbnail processor | + ## Thumbnail Resolution Various resolutions can be defined via `THUMBNAILS_RESOLUTIONS`. A requestor can request any arbitrary resolution and the thumbnail service will use the one closest to the requested resolution. If more than one resolution is required, each resolution must be requested individually. From ab9893bc46f3234bf04edb808c419dc15a79609d Mon Sep 17 00:00:00 2001 From: Michael Stingl Date: Mon, 4 Dec 2023 17:01:30 +0100 Subject: [PATCH 2/5] =?UTF-8?q?clarified=20thumbnail=20=E2=80=9Cc=E2=80=9D?= =?UTF-8?q?=20parameter?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- services/thumbnails/README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/services/thumbnails/README.md b/services/thumbnails/README.md index 258de45ae..36295e98e 100644 --- a/services/thumbnails/README.md +++ b/services/thumbnails/README.md @@ -45,14 +45,14 @@ Clients can request thumbnail previews for files by adding `?preview=1` to the f The following query parameters are supported: -| Parameter | Required | Default Value | Description | -| --------- | -------- | ---------------------------------------------------- | ----------------------------- | -| preview | YES | 1 | generates preview | -| x | YES | first x-value configured in `THUMBNAILS_RESOLUTIONS` | horizontal target size | -| y | YES | first y-value configured in `THUMBNAILS_RESOLUTIONS` | vertical target size | -| a | NO | 1 | aspect ratio | -| c | NO | ??? | ??? | -| processor | NO | ??? | preferred thumbnail processor | +| Parameter | Required | Default Value | Description | +| --------- | -------- | ---------------------------------------------------- | ------------------------------------------------------------------------------- | +| preview | YES | 1 | generates preview | +| x | YES | first x-value configured in `THUMBNAILS_RESOLUTIONS` | horizontal target size | +| y | YES | first y-value configured in `THUMBNAILS_RESOLUTIONS` | vertical target size | +| a | NO | 1 | aspect ratio | +| c | NO | Caching string | Clients should send the etag, so they get a fresh thumbnail after a file change | +| processor | NO | ??? | preferred thumbnail processor | ## Thumbnail Resolution From a87eeda1cd67e0ee32130bfe15daad0fa1a50cbf Mon Sep 17 00:00:00 2001 From: Michael Stingl Date: Mon, 4 Dec 2023 17:18:05 +0100 Subject: [PATCH 3/5] clarify thumbnail processor default in table --- services/thumbnails/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/services/thumbnails/README.md b/services/thumbnails/README.md index 36295e98e..0d7b4d388 100644 --- a/services/thumbnails/README.md +++ b/services/thumbnails/README.md @@ -52,7 +52,7 @@ The following query parameters are supported: | y | YES | first y-value configured in `THUMBNAILS_RESOLUTIONS` | vertical target size | | a | NO | 1 | aspect ratio | | c | NO | Caching string | Clients should send the etag, so they get a fresh thumbnail after a file change | -| processor | NO | ??? | preferred thumbnail processor | +| processor | NO | `resize` for gif's and `thumbnail` for all others | preferred thumbnail processor | ## Thumbnail Resolution From 478960455f060c9d377d6bb9947fc70ed20fff7f Mon Sep 17 00:00:00 2001 From: Michael Stingl Date: Mon, 4 Dec 2023 17:28:54 +0100 Subject: [PATCH 4/5] Explain processor behavior Based on: https://pkg.go.dev/github.com/disintegration/imaging --- services/thumbnails/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/services/thumbnails/README.md b/services/thumbnails/README.md index 0d7b4d388..7de40ce4f 100644 --- a/services/thumbnails/README.md +++ b/services/thumbnails/README.md @@ -69,10 +69,10 @@ Returned: 15x10 Normally, an image might get cropped when creating a preview, depending on the aspect ratio of the original image. This can have negative impacts on previews as only a part of the image will be shown. When using an _optional_ processor in the request, cropping can be avoided by defining on how the preview image generation will be done. The following processors are available: -* `resize` -* `fit` -* `fill` -* `thumbnail` +* `resize` resizes the image to the specified width and height and returns the transformed image. If one of width or height is 0, the image aspect ratio is preserved. +* `fit` scales down the image to fit the specified maximum width and height and returns the transformed image. +* `fill`: creates an image with the specified dimensions and fills it with the scaled source image. To achieve the correct aspect ratio without stretching, the source image will be cropped. +* `thumbnail` scales the image up or down, crops it to the specified width and hight and returns the transformed image. To apply one of those, a query parameter has to be added to the request, like `?processor=fit`. If no query parameter or processor is added, the default behaviour applies which is `resize` for gif's and `thumbnail` for all others. From 72825ddae477ca3b7cb6dd90d6971f93efb76b53 Mon Sep 17 00:00:00 2001 From: Michael Stingl Date: Mon, 4 Dec 2023 17:35:59 +0100 Subject: [PATCH 5/5] Added scalingup thumbnail parameter (used by web + iOS app) --- services/thumbnails/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/services/thumbnails/README.md b/services/thumbnails/README.md index 7de40ce4f..47a9939e3 100644 --- a/services/thumbnails/README.md +++ b/services/thumbnails/README.md @@ -50,6 +50,7 @@ The following query parameters are supported: | preview | YES | 1 | generates preview | | x | YES | first x-value configured in `THUMBNAILS_RESOLUTIONS` | horizontal target size | | y | YES | first y-value configured in `THUMBNAILS_RESOLUTIONS` | vertical target size | +| scalingup | NO | 0 | prevents upscaling of small images | | a | NO | 1 | aspect ratio | | c | NO | Caching string | Clients should send the etag, so they get a fresh thumbnail after a file change | | processor | NO | `resize` for gif's and `thumbnail` for all others | preferred thumbnail processor |