Thumbor

https://thumbor.readthedocs.io/en/latest/
Admin
Thumbor is a smart imaging service that enables on-demand image crop, resizing, flipping, and...
Tokens:35,004
Snippets:566
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Dependencies with Make

Source: https://thumbor.readthedocs.io/en/latest/hacking_on_thumbor.html

Use the 'make setup' command to download all necessary Python packages for Thumbor development. This command should be run after initializing your virtual environment and ensuring Poetry is installed.

```bash
$ make setup

```

--------------------------------

### Install Thumbor from the latest repository source

Source: https://thumbor.readthedocs.io/en/latest/installing.html

Commands to install directly from the GitHub repository.

```bash
pip install git+git://github.com/thumbor/thumbor.git
```

```bash
git clone git://github.com/thumbor/thumbor.git

cd thumbor

python setup.py install
```

--------------------------------

### Example Configuration File

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

A template showing various configuration options for logging and imaging.

```python
################################### Logging ####################################

## Logging configuration as json
## Defaults to: None
#THUMBOR_LOG_CONFIG = None

## Log Format to be used by thumbor when writing log messages.
## Defaults to: '%(asctime)s %(name)s:%(levelname)s %(message)s'
#THUMBOR_LOG_FORMAT = '%(asctime)s %(name)s:%(levelname)s %(message)s'

## Date Format to be used by thumbor when writing log messages.
## Defaults to: '%Y-%m-%d %H:%M:%S'
#THUMBOR_LOG_DATE_FORMAT = '%Y-%m-%d %H:%M:%S'

################################################################################


################################### Imaging ####################################

## Max width in pixels for images read or generated by thumbor
## Defaults to: 0
#MAX_WIDTH = 0

## Max height in pixels for images read or generated by thumbor
## Defaults to: 0
#MAX_HEIGHT = 0

## Max pixel count for images read by thumbor
## Defaults to: 75000000.0
#MAX_PIXELS = 75000000.0

## Min width in pixels for images read or generated by thumbor
## Defaults to: 1
#MIN_WIDTH = 1

## Min width in pixels for images read or generated by thumbor
## Defaults to: 1
#MIN_HEIGHT = 1

## Allowed domains for the http loader to download. These are regular
## expressions.
## Defaults to: [
#]

#ALLOWED_SOURCES = [
#]


## Quality index used for generated JPEG images
```

--------------------------------

### Start Thumbor Locally

Source: https://thumbor.readthedocs.io/en/latest/hosting.html

Launch the Thumbor service in a local development environment.

```bash
thumbor
```

--------------------------------

### Start Thumbor in Production

Source: https://thumbor.readthedocs.io/en/latest/hosting.html

Launch Thumbor with specific port and configuration file path.

```bash
thumbor --port=8888 --conf="~/mythumbor.conf"
```

--------------------------------

### Configure MixedStorage in Thumbor

Source: https://thumbor.readthedocs.io/en/latest/image_storage.html

Example configuration for setting up MixedStorage with file and Redis backends.

```python
MIXED_STORAGE_FILE_STORAGE = 'thumbor.storages.file_storage'
MIXED_STORAGE_CRYPTO_STORAGE = 'thumbor.storages.redis_storage'
MIXED_STORAGE_DETECTOR_STORAGE = 'thumbor.storages.redis_storage'

FILE_STORAGE_ROOT_PATH = '/tmp/mypath'

REDIS_STORAGE_SERVER_HOST = 'localhost'
REDIS_STORAGE_SERVER_PORT = 6379
REDIS_STORAGE_SERVER_DB = 0
```

--------------------------------

### Run Thumbor via Docker

Source: https://thumbor.readthedocs.io/en/latest/getting_started.html

Command to start a Thumbor instance using Docker if local installation is not preferred.

```bash
$ docker run -p 8888:80 ghcr.io/minimalcompact/thumbor:latest
```

--------------------------------

### Install Thumbor via pip or easy_install

Source: https://thumbor.readthedocs.io/en/latest/installing.html

Use these commands to install the latest stable version from the Python Package Index.

```bash
pip install thumbor
```

```bash
easy_install thumbor
```

--------------------------------

### Watermark Resizing Examples

Source: https://thumbor.readthedocs.io/en/latest/watermark.html

Examples demonstrating how the watermark filter handles resizing based on width and height ratios.

```text
watermark(imageUrl, 30, 10, 50, 20)
```

```text
watermark(imageUrl, 30, 10, 50, none, 15)
```

```text
watermark(imageUrl, 30, 10, 50, 30, 30)
```

--------------------------------

### Example Image URL

Source: https://thumbor.readthedocs.io/en/latest/getting_started.html

The source URL for the sample image used throughout the documentation.

```text
https://github.com/thumbor/thumbor/raw/master/example.jpg
```

--------------------------------

### Verify Thumbor Installation

Source: https://thumbor.readthedocs.io/en/latest/hosting.html

Check the installed version of Thumbor.

```bash
thumbor --version
```

--------------------------------

### Supervisor Configuration for Thumbor

Source: https://thumbor.readthedocs.io/en/latest/hosting.html

Example configuration for managing multiple Thumbor processes with Supervisor.

```ini
[supervisord]
logfile = /home/thumbor/logs/supervisord.log
logfile_maxbytes = 50MB
logfile_backups=10
loglevel = info
pidfile = /home/thumbor/supervisord.pid
user = thumbor

[program:thumbor]
command=thumbor --port=800%(process_num)s --conf=/etc/thumbor800%(process_num)s.conf
process_name=thumbor800%(process_num)s
numprocs=4
user=thumbor
directory=/home/thumbor/
autostart=true
autorestart=true
startretries=3
stopsignal=TERM
stdout_logfile=/home/thumbor/logs/thumbor800%(process_num)s.stdout.log
stdout_logfile_maxbytes=1MB
stdout_logfile_backups=10
stderr_logfile=/home/thumbor/logs/thumbor800%(process_num)s.stderr.log
stderr_logfile_maxbytes=1MB
stderr_logfile_backups=10
```

--------------------------------

### Install Thumbor from a stable source release

Source: https://thumbor.readthedocs.io/en/latest/installing.html

Execute these commands within the decompressed directory of a downloaded source release.

```bash
pip install .
```

```bash
python setup.py install
```

--------------------------------

### Example of a Secure Thumbor URL

Source: https://thumbor.readthedocs.io/en/latest/security.html

This is an example of a fully formed secure URL for Thumbor, including the generated authentication code.

```text
http://thumbor-server/1234567890123456789012345678/300x200/smart/path/to/image.jpg
```

--------------------------------

### Apply fill filter with transparency handling

Source: https://thumbor.readthedocs.io/en/latest/filling.html

Examples demonstrating the use of the fill_transparent argument to control how transparent areas are processed.

```text
http://localhost:8888/unsafe/fit-in/300x225/filters:fill(blue,1)/https://github.com/thumbor/thumbor/wiki/dice_transparent_background.png
```

```text
http://localhost:8888/unsafe/fit-in/300x225/filters:fill(f00,true)/https://github.com/thumbor/thumbor/wiki/dice_transparent_background.png
```

```text
http://localhost:8888/unsafe/fit-in/300x225/filters:fill(add8e6,1)/https://github.com/thumbor/thumbor/wiki/dice_transparent_background.png
```

```text
http://localhost:8888/unsafe/fit-in/300x225/filters:fill(auto,true)/https://github.com/thumbor/thumbor/wiki/dice_transparent_background.png
```

```text
http://localhost:8888/unsafe/fit-in/300x225/filters:fill(blur,true)/https://github.com/thumbor/thumbor/wiki/dice_transparent_background.png
```

--------------------------------

### HMAC-SHA1 Signing Process Example

Source: https://thumbor.readthedocs.io/en/latest/security.html

This outlines the steps to create a secure URL using HMAC-SHA1 signing. It involves signing the image path and options, encoding the signature using urlsafe_b64encode, and appending it to the URL.

```text
1. Generate a `signature` of that part using HMAC-SHA1 with the **SECURITY_KEY**.
2. Encode the `signature` as base64. thumbor uses `urlsafe_b64encode` method of the native python’s base64 module. This method replaces some characters in the base64 string so it becomes more url friendly.
3. Append the `encoded_signature` to the beginning of the URL, like: `/1234567890123456789012345678/300x200/smart/path/to/image.jpg`.
```

--------------------------------

### Check Poetry Version

Source: https://thumbor.readthedocs.io/en/latest/hacking_on_thumbor.html

Verify that Poetry is installed and accessible in your environment. This is a prerequisite for setting up the Thumbor development environment.

```bash
$ poetry --version
Poetry version 1.0.3

```

--------------------------------

### Accessing an image with a secure URL

Source: https://thumbor.readthedocs.io/en/latest/index.html

Example of an image URL using a security token for authorized access.

```text
http://thumbor-server/K97LekICOXT9MbO3X1u8BBkrjbu5/300x200/smart/https%3A%2F%2Fgithub.com%2Fthumbor%2Fthumbor%2Fraw%2Fmaster%2Fexample.jpg
```

--------------------------------

### GET /filters:contrast(amount)

Source: https://thumbor.readthedocs.io/en/latest/contrast.html

Applies a contrast adjustment to an image via the Thumbor filter pipeline.

```APIDOC
## GET /filters:contrast(amount)

### Description
This filter increases or decreases the image contrast.

### Method
GET

### Parameters
#### Path Parameters
- **amount** (integer) - Required - The amount (in %) to change the image contrast. Range: -100 to 100. Positive numbers increase contrast and negative numbers decrease contrast.

### Request Example
http://localhost:8888/unsafe/filters:contrast(40)/https%3A%2F%2Fgithub.com%2Fthumbor%2Fthumbor%2Fraw%2Fmaster%2Fexample.jpg
```

--------------------------------

### Apply Sharpen Filter via URL

Source: https://thumbor.readthedocs.io/en/latest/sharpen.html

Example of applying the sharpen filter to an image URL with specific parameters for amount, radius, and luminance processing.

```text
http://localhost:8888/unsafe/filters:sharpen(2,1.0,true)/https%3A%2F%2Fgithub.com%2Fthumbor%2Fthumbor%2Fraw%2Fmaster%2Fexample.jpg
```

--------------------------------

### Apply Proportion Filter to Image URL

Source: https://thumbor.readthedocs.io/en/latest/proportion.html

This example demonstrates how to use the proportion filter by appending it to a Thumbor image URL. The filter is applied with a proportion of 0.5, meaning the image will be resized to 50% of its original dimensions.

```url
http://localhost:8888/unsafe/filters:proportion(0.5)/https%3A%2F%2Fgithub.com%2Fthumbor%2Fthumbor%2Fraw%2Fmaster%2Fexample.jpg
```

--------------------------------

### Set Storage Expiration Time

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

Configure the default expiration time in seconds for cached storage. Example sets it to 60 seconds (1 minute).

```python
STORAGE_EXPIRATION_SECONDS = 60  # 1 minute
```

--------------------------------

### Example of Focal Filter Usage in Thumbor URL

Source: https://thumbor.readthedocs.io/en/latest/focal.html

This URL demonstrates how to apply the focal filter to an image. Note that using this filter with detectors or extract focal points filter may lead to unexpected behavior.

```url
http://localhost:8888/unsafe/400x100/filters:focal(146x206:279x360)/https%3A%2F%2Fgithub.com%2Fthumbor%2Fthumbor%2Fraw%2Fmaster%2Fexample.jpg
```

--------------------------------

### GET /filters:proportion(percentage)

Source: https://thumbor.readthedocs.io/en/latest/proportion.html

Applies a proportion filter to an image to scale its height and width based on a provided percentage.

```APIDOC
## GET /filters:proportion(percentage)

### Description
This filter applies the specified proportion to the image’s height and width when cropping.

### Method
GET

### Parameters
#### Path Parameters
- **percentage** (float) - Required - The float percentage of the proportion (0.0 to 1.0).

### Request Example
http://localhost:8888/unsafe/filters:proportion(0.5)/https%3A%2F%2Fgithub.com%2Fthumbor%2Fthumbor%2Fraw%2Fmaster%2Fexample.jpg
```

--------------------------------

### Apply fill filter with various color options

Source: https://thumbor.readthedocs.io/en/latest/filling.html

Examples of using the fill filter with different color arguments including named colors, hex codes, auto-detection, and blur effects.

```text
http://localhost:8888/unsafe/fit-in/300x300/filters:fill(blue)/https%3A%2F%2Fgithub.com%2Fthumbor%2Fthumbor%2Fraw%2Fmaster%2Fexample.jpg
```

```text
http://localhost:8888/unsafe/fit-in/300x300/filters:fill(f00)/https%3A%2F%2Fgithub.com%2Fthumbor%2Fthumbor%2Fraw%2Fmaster%2Fexample.jpg
```

```text
http://localhost:8888/unsafe/fit-in/300x300/filters:fill(add8e6)/https%3A%2F%2Fgithub.com%2Fthumbor%2Fthumbor%2Fraw%2Fmaster%2Fexample.jpg
```

```text
http://localhost:8888/unsafe/fit-in/300x300/filters:fill(auto)/https%3A%2F%2Fgithub.com%2Fthumbor%2Fthumbor%2Fraw%2Fmaster%2Fexample.jpg
```

```text
http://localhost:8888/unsafe/fit-in/300x300/filters:fill(blur)/https%3A%2F%2Fgithub.com%2Fthumbor%2Fthumbor%2Fraw%2Fmaster%2Fexample.jpg
```

--------------------------------

### Retrieve Image Metadata JSON

Source: https://thumbor.readthedocs.io/en/latest/usage.html

Example of the JSON structure returned by the Thumbor metadata endpoint, detailing source image properties and applied operations.

```json
{
    thumbor: {
        source: {
            url: "path/to/my/nice/image.jpg",
            width: 800,
            height: 600
        },
        operations: [
            {
                type: "crop",
                left: 10,
                top: 10,
                right: 300,
                bottom: 200
            },
            {
                type: "resize",
                width: 300,
                height: 200
            },
            { type: "flip_horizontally" },
            { type: "flip_vertically" }
        ]
    }
}
```

--------------------------------

### Run Tests with Make

Source: https://thumbor.readthedocs.io/en/latest/hacking_on_thumbor.html

Execute the 'make test' command to run the project's test suite. Ensure all tests pass after making changes to confirm your contributions do not break existing functionality.

```bash
$ make test

```

--------------------------------

### Display Thumbor Help

Source: https://thumbor.readthedocs.io/en/latest/running.html

Use this command to view all available arguments for the Thumbor server.

```bash
thumbor --help

```

--------------------------------

### GET /filters:quality(amount)

Source: https://thumbor.readthedocs.io/en/latest/quality.html

Applies a quality compression filter to JPEG images.

```APIDOC
## GET /filters:quality(amount)

### Description
This filter changes the overall quality of the JPEG image. It does not affect PNG or GIF formats.

### Method
GET

### Parameters
#### Path Parameters
- **amount** (integer) - Required - The quality level (0 to 100) in percentage.

### Request Example
http://localhost:8888/unsafe/filters:quality(40)/https%3A%2F%2Fgithub.com%2Fthumbor%2Fthumbor%2Fraw%2Fmaster%2Fexample.jpg
```

--------------------------------

### Configure Docker with Environment Variables

Source: https://thumbor.readthedocs.io/en/latest/hosting.html

Set Thumbor configuration options using the THUMBOR_ prefix.

```bash
docker run -p 8888:8888 \
  -e THUMBOR_SECURITY_KEY=my-secret-key \
  -e THUMBOR_QUALITY=85 \
  ghcr.io/thumbor/thumbor:latest
```

--------------------------------

### GET /filters:focal

Source: https://thumbor.readthedocs.io/en/latest/focal.html

Applies a focal point to an image for use in later transformations.

```APIDOC
## GET /filters:focal(leftxtop:rightxbottom)

### Description
This filter adds a focal point to the image, which is used in later transforms.

### Method
GET

### Parameters
#### Path Parameters
- **left** (integer) - Required - The left coordinate of the focal point.
- **top** (integer) - Required - The top coordinate of the focal point.
- **right** (integer) - Required - The right coordinate of the focal point.
- **bottom** (integer) - Required - The bottom coordinate of the focal point.

### Request Example
http://localhost:8888/unsafe/400x100/filters:focal(146x206:279x360)/https%3A%2F%2Fgithub.com%2Fthumbor%2Fthumbor%2Fraw%2Fmaster%2Fexample.jpg
```

--------------------------------

### GET /filters:rotate(angle)

Source: https://thumbor.readthedocs.io/en/latest/rotate.html

Applies a rotation filter to an image based on the provided angle.

```APIDOC
## GET /filters:rotate(angle)

### Description
This filter rotates the given image according to the angle value passed. For the PIL engine, the rotation is performed counter-clockwise.

### Method
GET

### Endpoint
/filters:rotate(angle)

### Parameters
#### Path Parameters
- **angle** (integer) - Required - The euler angle to rotate the image by (0 to 359). Values >= 360 are normalized.

### Request Example
http://localhost:8888/unsafe/filters:rotate(90)/https%3A%2F%2Fgithub.com%2Fthumbor%2Fthumbor%2Fraw%2Fmaster%2Fexample.jpg
```

--------------------------------

### GET /filters:autojpg()

Source: https://thumbor.readthedocs.io/en/latest/autojpg.html

Applies the autojpg filter to an image request to override the AUTO_PNG_TO_JPG configuration.

```APIDOC
## GET /filters:autojpg()

### Description
This filter overrides the AUTO_PNG_TO_JPG config variable for a specific image request.

### Method
GET

### Parameters
#### Query Parameters
- **enabled** (boolean) - Optional - Passing True (default) overrides the AUTO_PNG_TO_JPG config variable; False keeps the default behavior.

### Request Example
http://localhost:8888/unsafe/300x300/filters:autojpg()/https%3A%2F%2Fgithub.com%2Fthumbor%2Fthumbor%2Fraw%2Fmaster%2Fexample.jpg
```

--------------------------------

### Display Thumbor URL Builder Help

Source: https://thumbor.readthedocs.io/en/latest/running.html

Type this command to see all available options for the thumbor-url utility, which helps in creating signed URLs.

```bash
thumbor-url -h

```

--------------------------------

### Accessing an image with unsafe URL

Source: https://thumbor.readthedocs.io/en/latest/index.html

Example of an image URL using the unsafe flag for on-demand processing.

```text
http://thumbor-server/unsafe/300x200/smart/https%3A%2F%2Fgithub.com%2Fthumbor%2Fthumbor%2Fraw%2Fmaster%2Fexample.jpg
```

--------------------------------

### Run Thumbor with Docker

Source: https://thumbor.readthedocs.io/en/latest/hosting.html

Execute the official Thumbor Docker image.

```bash
docker run -p 8888:8888 ghcr.io/thumbor/thumbor:latest
```

--------------------------------

### GET /filters:round_corner

Source: https://thumbor.readthedocs.io/en/latest/round_corners.html

Applies rounded corners to an image using a specified radius and background color.

```APIDOC
## GET /filters:round_corner(a|b,r,g,b,[transparent])

### Description
This filter adds rounded corners to the image using the specified color as background.

### Parameters
#### Path Parameters
- **a|b** (string) - Required - Amount of pixels to use as radius. The argument b is optional and specifies the second value for the ellipsis used for the radius.
- **r** (integer) - Required - Red component of the background color.
- **g** (integer) - Required - Green component of the background color.
- **b** (integer) - Required - Blue component of the background color.
- **transparent** (boolean/integer) - Optional - If set to true or 1, the background will be transparent.

### Request Example
http://localhost:8888/unsafe/filters:round_corner(20,255,255,255)/https%3A%2F%2Fgithub.com%2Fthumbor%2Fthumbor%2Fraw%2Fmaster%2Fexample.jpg
```

--------------------------------

### Enable gifv optimizer in configuration

Source: https://thumbor.readthedocs.io/en/latest/gifv.html

Add the gifv optimizer to the OPTIMIZERS list in your Thumbor configuration file.

```python
OPTIMIZERS = [
  'thumbor.optimizers.gifv',
]
```

--------------------------------

### GET /unsafe/filters:no_upscale()/{image_url}

Source: https://thumbor.readthedocs.io/en/latest/no_upscale.html

Applies the no_upscale filter to a requested image URL to prevent upscaling.

```APIDOC
## GET /unsafe/filters:no_upscale()/{image_url}

### Description
This filter tells thumbor not to upscale your images. If an original image is smaller than the requested dimensions, thumbor will return the image at its original size.

### Method
GET

### Endpoint
/unsafe/filters:no_upscale()/{image_url}

### Parameters
#### Path Parameters
- **image_url** (string) - Required - The URL of the image to be processed.

### Request Example
http://localhost:8888/unsafe/filters:no_upscale()/https%3A%2F%2Fgithub.com%2Fthumbor%2Fthumbor%2Fraw%2Fmaster%2Fexample.jpg
```

--------------------------------

### Build and Publish Test Docker Image

Source: https://thumbor.readthedocs.io/en/latest/hacking_on_thumbor.html

Update and publish the testing Docker image after introducing a new dependency. Ensure you are logged into Docker Hub and have the necessary permissions for the thumbororg repository.

```bash
make test-docker-build test-docker-publish

```

--------------------------------

### GET /filters:brightness(amount)

Source: https://thumbor.readthedocs.io/en/latest/brightness.html

Applies a brightness adjustment to an image via the Thumbor filter pipeline.

```APIDOC
## GET /filters:brightness(amount)

### Description
This filter increases or decreases the image brightness.

### Method
GET

### Parameters
#### Path Parameters
- **amount** (integer) - Required - The amount (-100 to 100) in % to change the image brightness. Positive numbers make the image brighter and negative numbers make the image darker.

### Request Example
http://localhost:8888/unsafe/filters:brightness(40)/https%3A%2F%2Fgithub.com%2Fthumbor%2Fthumbor%2Fraw%2Fmaster%2Fexample.jpg
```

--------------------------------

### Configure MongoDB Loader

Source: https://thumbor.readthedocs.io/en/latest/plugins.html

Settings for using MongoDB as an image loader in Thumbor.

```text
LOADER = 'thumbor_mongodb.loader'
MONGO_LOADER_CNX_STRING = 'mongodb://mongodbserver01,mongodbserver02:27017'
MONGO_LOADER_SERVER_DB = 'thumbor'
MONGO_LOADER_SERVER_COLLECTION = 'images'
MONGO_LOADER_DOC_FIELD = 'content'
```

--------------------------------

### Library testing scenarios

Source: https://thumbor.readthedocs.io/en/latest/libraries.html

Pseudo-code BDD-style scenarios for verifying URL signing and encryption logic.

```text
Given
    A security key of 'my-security-key'
    And an image URL of "my.server.com/some/path/to/image.jpg"
    And a width of 300
    And a height of 200
When
    I ask my library for a signed url
Then
    I get '/8ammJH8D-7tXy6kU3lTvoXlhu4o=/300x200/my.server.com/some/path/to/image.jpg' as url
```

```text
Given
    A security key of 'my-security-key'
    And an image URL of "my.server.com/some/path/to/image.jpg"
    And a width of 300
    And a height of 200
When
    I ask my library for an encrypted URL
Then
    I get the proper url (/8ammJH8D-7tXy6kU3lTvoXlhu4o=/300x200/my.server.com/some/path/to/image.jpg)
```

--------------------------------

### Configure Redis Sentinel Instances

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

Provide a comma-separated string of Redis Sentinel server instances for the queued detector.

```python
REDIS_QUEUE_SENTINEL_INSTANCES = 'localhost:23679,localhost:23680'
```

--------------------------------

### Using the Upscale Filter in Thumbor

Source: https://thumbor.readthedocs.io/en/latest/upscale.html

This URL demonstrates how to use the upscale filter with the 'fit-in' mode to resize an image. Ensure the image URL is correctly formatted.

```url
http://localhost:8888/unsafe/fit-in/600x500/filters:upscale()/https://raw.githubusercontent.com/thumbor/thumbor/e86324e49d7e53acc2a8057e43f3fdd2ca5cea75/docs/images/dice_transparent_background.png
```

--------------------------------

### GET /filters:fill

Source: https://thumbor.readthedocs.io/en/latest/filling.html

Applies the fill filter to an image, typically used in conjunction with fit-in or adaptive-fit-in operations.

```APIDOC
## GET /filters:fill(color[,fill_transparent])

### Description
This filter returns an image sized exactly as requested independently of its ratio. It will fill the missing area with the specified color. It is usually combined with the “fit-in” or “adaptive-fit-in” options.

### Parameters
#### Query Parameters
- **color** (string) - Required - The color name (HTML) or hexadecimal RGB expression without the '#' character. Special values include 'transparent', 'auto' (smartly chosen), and 'blur' (blurred original image).
- **fill_transparent** (boolean) - Optional - Specifies whether transparent areas of the image should be filled. Accepted values: true, false, 1, 0. Default is false.

### Request Example
http://localhost:8888/unsafe/fit-in/300x300/filters:fill(blue)/image.jpg
```

--------------------------------

### Generate Thumbor Configuration File

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

Use this command to generate a commented Thumbor configuration file.

```bash
thumbor-config > ./thumbor.conf
```

--------------------------------

### GET /unsafe/filters:cover()/{image_url}

Source: https://thumbor.readthedocs.io/en/latest/cover.html

Applies the cover filter to an image URL to extract the first frame of a GIF.

```APIDOC
## GET /unsafe/filters:cover()/{image_url}

### Description
This filter is used in GIFs to extract their first frame as the image to be used as cover. Note that this filter will only function when USE_GIFSICLE_ENGINE is set to True in thumbor.conf.

### Method
GET

### Endpoint
/unsafe/filters:cover()/{image_url}

### Request Example
http://localhost:8888/unsafe/filters:cover()/http://server.my/animated_static.gif
```

--------------------------------

### Configure DigitalOcean Spaces Result Storage

Source: https://thumbor.readthedocs.io/en/latest/plugins.html

Set the result storage engine to use DigitalOcean Spaces and provide the necessary credentials and bucket details in thumbor.conf.

```python
# Use DigitalOcean Spaces for result storage.
# For more info on result storage: https://github.com/thumbor/thumbor/wiki/Result-storage
RESULT_STORAGE = 'thumbor_spaces.result_storages.spaces_storage'

SPACES_REGION='xxx'

SPACES_ENDPOINT='xxx'

SPACES_KEY='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'

SPACES_SECRET='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'

SPACES_BUCKET='your-bucket-name'
```

--------------------------------

### GET /filters:watermark

Source: https://thumbor.readthedocs.io/en/latest/watermark.html

Applies a watermark to an image using the specified URL, position, transparency, and optional resizing ratios.

```APIDOC
## GET /filters:watermark(imageUrl, x, y, alpha [, w_ratio [, h_ratio]])

### Description
Adds a watermark to the image. It can be positioned inside the image with the alpha channel specified and optionally resized based on the image size.

### Method
GET

### Parameters
#### Query Parameters
- **imageUrl** (string) - Required - Watermark image URL. Must be URL encoded if it contains parentheses.
- **x** (string) - Required - Horizontal position. Positive/negative numbers, 'center', 'repeat', or percentage (e.g., 20p).
- **y** (string) - Required - Vertical position. Positive/negative numbers, 'center', 'repeat', or percentage (e.g., 20p).
- **alpha** (number) - Required - Transparency level between 0 (opaque) and 100 (transparent).
- **w_ratio** (number/string) - Optional - Percentage of the image width the watermark should fit in.
- **h_ratio** (number/string) - Optional - Percentage of the image height the watermark should fit in.

### Request Example
http://thumbor-server/filters:watermark(http://my.site.com/img.png,-10,-10,50)/some/image.jpg
```

--------------------------------

### Apply sequential filters in a Thumbor URL

Source: https://thumbor.readthedocs.io/en/latest/filters.html

Demonstrates chaining multiple filters like watermark, blur, fill, and upscale in a single request URL.

```text
http://localhost:8888/fit-in/100x100/filters:watermark(..):blur(..):fill(red,1):upscale()/https%3A%2F%2Fgithub.com%2Fthumbor%2Fthumbor%2Fraw%2Fmaster%2Fexample.jpg
```

--------------------------------

### Apply Watermark Filter to Image URL

Source: https://thumbor.readthedocs.io/en/latest/watermark.html

Examples of applying the watermark filter to a Thumbor image URL with absolute and percentage-based positioning.

```text
http://thumbor-server/filters:watermark(http://my.site.com/img.png,-10,-10,50)/some/image.jpg
```

```text
http://thumbor-server/filters:watermark(http://my.site.com/img.png,10p,-20p,50)/some/image.jpg
```

--------------------------------

### Run Linting and Formatting Checks

Source: https://thumbor.readthedocs.io/en/latest/hacking_on_thumbor.html

Before committing, run 'make flake pylint' to ensure your code adheres to the project's linting and formatting standards. This helps maintain code quality and consistency.

```bash
$ make flake pylint

```

--------------------------------

### Apply Rotate Filter via URL

Source: https://thumbor.readthedocs.io/en/latest/rotate.html

Example of using the rotate filter in a Thumbor image URL to rotate an image by 90 degrees.

```text
http://localhost:8888/unsafe/filters:rotate(90)/https%3A%2F%2Fgithub.com%2Fthumbor%2Fthumbor%2Fraw%2Fmaster%2Fexample.jpg
```

--------------------------------

### Use Smart Cropping with Thumbor

Source: https://thumbor.readthedocs.io/en/latest/enabling_detectors.html

Append `/smart` to your Thumbor URLs to utilize the enabled detectors for intelligent image cropping. Ensure Thumbor has been restarted after configuration changes.

```http
http://localhost:8888/unsafe/200x400/smart/https%3A%2F%2Fgithub.com%2Fthumbor%2Fthumbor%2Fraw%2Fmaster%2Fexample.jpg
```

--------------------------------

### Configure Prometheus Metrics

Source: https://thumbor.readthedocs.io/en/latest/plugins.html

Enable the Prometheus metrics collector and optionally specify the scrape port in thumbor.conf.

```python
################################# Extensibility #################################
METRICS = 'tc_prometheus.metrics.prometheus_metrics'

# optional with defaults
PROMETHEUS_SCRAPE_PORT = 8000 # Port the prometheus client should listen on
```

--------------------------------

### Configure Video Engine

Source: https://thumbor.readthedocs.io/en/latest/plugins.html

Set the imaging engine to the video engine and register required filters for transcoding and still frame extraction in thumbor.conf.

```python
ENGINE = 'thumbor_video_engine.engines.video'
FILTERS = [
    # Enables transcoding between video formats (in addition to the image
    # formats already supported by thumbor.filters.format)
    'thumbor_video_engine.filters.format',
    # Allows outputting a still frame from a video as an image
    'thumbor_video_engine.filters.still',
]

# optional, if you are already using a custom image engine
IMAGING_ENGINE = 'opencv_engine'
```

--------------------------------

### Configure Thumbor Detectors

Source: https://thumbor.readthedocs.io/en/latest/enabling_detectors.html

Add this configuration to your `thumbor.conf` file to enable face and feature detectors. Note that these detectors are mutually exclusive.

```python
DETECTORS = [
    'thumbor.detectors.face_detector',
    'thumbor.detectors.feature_detector',
]
```

--------------------------------

### GET /image - Retrieve Image

Source: https://thumbor.readthedocs.io/en/latest/how_to_upload_images.html

Retrieves an uploaded image from Thumbor storage. The URI for this operation is typically obtained from the 'Location' header of a successful POST or PUT request.

```APIDOC
## GET /image

### Description
Retrieves an uploaded image from Thumbor storage.

### Method
GET

### Endpoint
/image

### Parameters
#### Query Parameters
- **image_uri** (string) - Required - The URI of the image to retrieve. This is typically the path returned in the Location header after an upload or update.

### Response
#### Success Response (200 OK)
- **image_data** (binary) - The image content.

#### Error Response
- **404 Not Found** - The specified image URI does not exist.
```

--------------------------------

### Set Browser Cache Expiration (Max Age)

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

Configure the number of seconds images should remain cached in the browser. This directly affects Expires and Cache-Control headers. Example sets to one day.

```python
MAX_AGE = 24 * 60 * 60  # A day of caching
```

--------------------------------

### Mount Configuration File in Docker

Source: https://thumbor.readthedocs.io/en/latest/hosting.html

Use a local configuration file within a Docker container.

```bash
docker run -p 8888:8888 \
  -v /path/to/thumbor.conf:/etc/thumbor/thumbor.conf \
  ghcr.io/thumbor/thumbor:latest
```

--------------------------------

### Configure Gifsicle Engine

Source: https://thumbor.readthedocs.io/en/latest/cover.html

Set this configuration in thumbor.conf to enable the cover filter functionality.

```python
USE_GIFSICLE_ENGINE = True
```

--------------------------------

### Build and Run Thumbor Apps

Source: https://thumbor.readthedocs.io/en/latest/running.html

This advanced usage allows specifying a custom application class for Thumbor. The format is 'namespace1.namespace2.class_name'.

```bash
thumbor -a myproj.thumbor_support.MyProjThumborApp

```

--------------------------------

### Run Tests in Docker

Source: https://thumbor.readthedocs.io/en/latest/hacking_on_thumbor.html

Execute tests using the Thumbor Docker image to avoid configuring dependencies locally. This provides a clean and isolated testing environment.

```bash
make test-docker-run

```

--------------------------------

### Set Temporary Image Cache Expiration

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

Configure a shorter cache expiration time for images with detection errors or deferred processing. This ensures the browser requests updated images more frequently. Example sets to one minute.

```python
MAX_AGE_TEMP_IMAGE = 60  # A minute of caching
```

--------------------------------

### Enable Automatic PNG to JPG Conversion

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

Set AUTO_PNG_TO_JPG to True to automatically convert PNG images to JPEG if the numpy dependency is installed and the image is a PNG without transparency. Evaluate use cases carefully as this may cause distortions or increase image size.

```python
AUTO_PNG_TO_JPG = True
```

--------------------------------

### Enable Automatic WebP Conversion

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

If True, Thumbor will automatically serve WebP images if the client's 'Accept' header indicates support for 'image/webp'.

```python
AUTO_WEBP = True
```

--------------------------------

### Enable Animated GIF Support

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

Set to True to enable support for animated GIFs. Defaults to False.

```python
ALLOW_ANIMATED_GIFS = True
```

--------------------------------

### Configure Glasses Detector Cascade File

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

Specify the cascade (XML) file path for OpenCV to detect glasses.

```python
## The cascade file that opencv will use to detect glasses.
GLASSES_DETECTOR_CASCADE_FILE = 'haarcascade_eye_tree_eyeglasses.xml'
```

--------------------------------

### Configure Detectors

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

Specify the detectors that should run on an image to check for focal points. Each item must be a full namespace module that Python can import.

```python
DETECTORS = [
   'thumbor.detectors.face_detector',
   'thumbor.detectors.feature_detector'
]
```

--------------------------------

### Configure Logging Format

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

Defines the format string for log messages.

```python
THUMBOR_LOG_FORMAT = '%(asctime)s %(name)s:%(levelname)s %(message)s'

```

--------------------------------

### POST /image

Source: https://thumbor.readthedocs.io/en/latest/posting_putting_deleting.html

Uploads a new image to the Thumbor server. This is the only method enabled by default.

```APIDOC
## POST /image

### Description
Uploads a new image to the server. If the image already exists, it will return a 409 Conflict error to prevent overwriting.

### Method
POST

### Endpoint
http://{thumbor-server}/image

### Request Body
- **media** (file) - Required - The image file to be uploaded via multi-part form.

### Response
#### Success Response (201)
- **Status** (201) - Image created successfully.

#### Error Responses
- **409 Conflict** - Image already exists.
- **412 Precondition Failed** - Image is too small or not a valid image file.
```

--------------------------------

### Configure Redis Queue Server Database

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

Specify the database index for the queued Redis detector server.

```python
REDIS_QUEUE_SERVER_DB = 0
```

--------------------------------

### Thumbor Image Resizing with Proportional Dimensions

Source: https://thumbor.readthedocs.io/en/latest/usage.html

Resize an image to `ExF`. Use a minus sign to flip horizontally or vertically. Omit a dimension or use zero to maintain proportionality to the original image.

```text
-Ex-F
```

```text
300x0
```

```text
0x200
```

```text
0x0
```

--------------------------------

### Configure Redis Queue Server Host

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

Specify the host for the queued Redis detector server.

```python
REDIS_QUEUE_SERVER_HOST = 'localhost'
```

--------------------------------

### Configure HBase Storage

Source: https://thumbor.readthedocs.io/en/latest/plugins.html

Settings for connecting Thumbor to an HBase backend for image storage.

```text
HBASE_STORAGE_SERVER_HOST = "localhost"
HBASE_STORAGE_SERVER_PORT = 9000
HBASE_STORAGE_TABLE = "storage-table"
HBASE_STORAGE_FAMILY = "storage-family"
```

```text
LOADER = "thumbor_hbase.loader"
```

```text
STORAGE = "thumbor_hbase.storage"
```

--------------------------------

### Configure Custom Error Handling

Source: https://thumbor.readthedocs.io/en/latest/custom_error_handlers.html

Enable custom error handling and specify the module path in the thumbor.conf file.

```python
USE_CUSTOM_ERROR_HANDLING = True
ERROR_HANDLER_MODULE = 'mylib.error_handling'
```

--------------------------------

### Configure Riak Storage

Source: https://thumbor.readthedocs.io/en/latest/plugins.html

Settings for using Riak as a backend storage provider.

```text
# Use riak for storage.
STORAGE = 'thumbor_riak.storage'

# Put the url for your riak install here
RIAK_STORAGE_BASEURL = "http://my-riak-install-base-url"
```

--------------------------------

### Configure Face Detector Cascade File

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

Specify the cascade (XML) file path for OpenCV to detect faces.

```python
## The cascade file that opencv will use to detect faces.
FACE_DETECTOR_CASCADE_FILE = 'haarcascade_frontalface_alt.xml'
```

--------------------------------

### Define Allowed Image Sources for HttpLoader

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

Configure the list of allowed domains from which Thumbor can load images when using the HttpLoader. Supports exact domains and regular expressions for wildcard matching.

```python
ALLOWED_SOURCES=['http://s.glbimg.com']
```

```python
ALLOWED_SOURCES=['.+\.globo\.com', '.+\.glbimg\.com']
```

--------------------------------

### Enable Thumbor Debug Mode for Detectors

Source: https://thumbor.readthedocs.io/en/latest/enabling_detectors.html

Use the `/debug` option in your Thumbor URLs to visualize the focal points detected by the smart cropping feature. This helps in understanding why an image was cropped in a specific way.

```http
http://localhost:8888/unsafe/debug/200x400/smart/https%3A%2F%2Fgithub.com%2Fthumbor%2Fthumbor%2Fraw%2Fmaster%2Fexample.jpg
```

--------------------------------

### Configure Redis Sentinel Master Instance

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

Specify the name of the master instance for the Redis Sentinel detector.

```python
REDIS_QUEUE_SENTINEL_MASTER_INSTANCE = 'masterinstance'
```

--------------------------------

### Enable Automatic AVIF Conversion

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

If True, Thumbor will automatically serve AVIF images if the client's 'Accept' header indicates support for 'image/avif' and the pillow-avif-plugin is enabled.

```python
AUTO_AVIF = True
```

--------------------------------

### Enable jpegtran optimizer in Thumbor

Source: https://thumbor.readthedocs.io/en/latest/jpegtran.html

Add the jpegtran optimizer to the OPTIMIZERS list in your thumbor.conf file.

```python
OPTIMIZERS = [
  'thumbor.optimizers.jpegtran'
]
```

--------------------------------

### Configure Rackspace Result Storage

Source: https://thumbor.readthedocs.io/en/latest/plugins.html

Settings for using Rackspace Cloud Files for result storage.

```text
# Use rackspace for result storage.
# For more info on result storage: https://github.com/thumbor/thumbor/wiki/Result-storage
RESULT_STORAGE = 'thumbor_rackspace.result_storages.cloudfile_storage'

# Pyrax Rackspace configuration file location
RACKSPACE_PYRAX_CFG = /var/thumbor/.pyrax.cfg

# Result Storage options
RACKSPACE_RESULT_STORAGE_EXPIRES = True # Set TTL on cloudfile objects
RACKSPACE_RESULT_STORAGES_CONTAINER = "cloudfile-container-name"
RACKSPACE_RESULT_STORAGES_CONTAINER_ROOT = "/"
```

--------------------------------

### Configure Mixed Storage File Storage

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

When using Thumbor's mixed storage, specify the storage module for images. This must be a full namespace module that Python can import.

```python
MIXED_STORAGE_FILE_STORAGE = 'thumbor.storages.file_storage'
```

--------------------------------

### POST /image

Source: https://thumbor.readthedocs.io/en/latest/how_to_upload_images.html

Uploads an image to the Thumbor server. Supports binary data with a Slug header or multipart form uploads.

```APIDOC
## POST /image

### Description
Uploads an image to the server. The image can be sent as binary data or via a multipart form.

### Method
POST

### Endpoint
/image

### Parameters
#### Request Headers
- **Content-Type** (string) - Required - The MIME type of the image (e.g., image/jpeg).
- **Slug** (string) - Optional - The filename to use for the uploaded image.

#### Request Body
- **media** (file) - Optional - Used in multipart form uploads to specify the image file and filename.

### Response
#### Success Response (201)
- **Location** (string) - The URI of the created image.

#### Response Example
HTTP/1.1 201 Created
Location: /image/05b2eda857314e559630c6f3334d818d/photo.jpg
```

--------------------------------

### Configure Redis Sentinel Master Database

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

Specify the database index for the Redis Sentinel master instance.

```python
REDIS_QUEUE_SENTINEL_MASTER_DB = 0
```

--------------------------------

### Configure File Storage Path

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

Defines the root directory for Thumbor's built-in file storage.

```python
FILE_STORAGE_ROOT_PATH = '/home/thumbor/storage'

```

--------------------------------

### Configure Upload Size Limit

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

Sets the maximum allowed size in bytes for uploaded images.

```python
UPLOAD_MAX_SIZE = 0

```

--------------------------------

### Configure Mixed Storage Detector Storage

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

When using Thumbor's mixed storage, specify the storage module for facial and feature detection results. This must be a full namespace module that Python can import.

```python
MIXED_STORAGE_DETECTOR_STORAGE = 'thumbor.storages.file_storage'
```

--------------------------------

### Set HTTP Loader Default User Agent

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

Define the default User-Agent string that Thumbor sends when requesting images via the HTTP Loader. Defaults to 'thumbor/' followed by the version.

```python
HTTP_LOADER_DEFAULT_USER_AGENT = 'thumbor/7.0.0'
```

--------------------------------

### Configure Logging Date Format

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

Defines the date format string for log messages.

```python
THUMBOR_LOG_DATE_FORMAT = '%Y-%m-%d %H:%M:%S'

```

--------------------------------

### Set Security Key for URL Signing

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

Configure the SECURITY_KEY used by Thumbor to sign secure URLs. This is a required security measure.

```text
1234567890123456
```

--------------------------------

### Configure Imaging Engine

Source: https://thumbor.readthedocs.io/en/latest/configuration.html

Specify the module responsible for image transformations. This must be a full namespace module that Python can import. The default is 'thumbor.engines.pil'.

```python
ENGINE = 'thumbor.engines.pil'
```
Tokens:
Raw