Working with Image Processing
1. Using Image Filter Module
| Directive | Description | Values | Notes |
|---|---|---|---|
| image_filter | Enables image filtering for the current location | on, off |
Must be set inside a location block |
| image_filter_buffer | Size of the buffer for image processing | size |
Default is 10M, can be increased for large images |
| image_filter_crop | Crops image to specified dimensions | widthxheight |
Example: 100x100 |
| image_filter_scale | Scales image to specified dimensions | widthxheight |
Example: 200x150 |
| image_filter_rotate | Rotates image by specified angle | 90, 180, 270 |
Rotates image clockwise |
| image_filter_sharpen | Applies sharpening filter to image | amount |
Value between 0 and 100 (default is 0) |
| image_filter_blur | Applies blur filter to image | radius |
Radius in pixels (default is 0) |
Example: Basic Image Filtering Configuration
location /images/ {
image_filter on;
image_filter_buffer 20M;
image_filter_crop 100x100;
}Example: Image Scaling and Rotation
location /scaled/ {
image_filter on;
image_filter_scale 300x200;
image_filter_rotate 90;
}
Note: The
image_filter module requires the ngx_http_image_filter_module to be compiled into Nginx. This module is not included by default in the standard Nginx build.
2. Resizing Images
| Directive | Description | Values | Notes |
|---|---|---|---|
| image_filter | Enables image filtering capabilities | resize, crop, rotate |
Must be used within a location block |
| image_filter_buffer | Size of the buffer for image processing | 10M, 50M |
Default is 10M, increase if processing large images |
| image_filter_jpeg_quality | Quality of JPEG output | 75, 90 |
Range from 1 to 100, default is 75 |
| image_filter_webp_quality | Quality of WebP output | 75, 90 |
Range from 1 to 100, default is 75 |
Example: Resizing Images
location /images/ {
image_filter resize 100x100;
image_filter_jpeg_quality 85;
image_filter_buffer 20M;
}
Note: The image_filter module requires the
ngx_http_image_filter_module to be compiled into Nginx.
Warning: Resizing large images can consume significant memory. Ensure
image_filter_buffer is set appropriately to avoid out-of-memory errors.
3. Rotating Images
| Directive | Description | Values | Notes |
|---|---|---|---|
| rotation | Rotates image by specified angle | 0 | 90 | 180 | 270 |
Applies to images processed by image_filter |
Note: The
image_filter module must be enabled for rotation to work.
4. Cropping Images
| Directive | Values | Description |
|---|---|---|
| image_filter | crop |
Enables image cropping filter |
| image_filter_crop | WIDTHxHEIGHT+X+Y |
Specifies crop dimensions and offset |
Example: Cropping an Image
location /images/crop/ {
image_filter crop 200x150+10+20;
image_filter_buffer 10M;
}
Note: The crop size is specified as
WIDTHxHEIGHT, and the offset as +X+Y. The coordinates are relative to the top-left corner of the image.
5. Adjusting Image Quality
| Directive | Description | Values | Default |
|---|---|---|---|
| image_filter | Sets the image filter to use for processing | scale, crop, rotate, sharpen |
None |
| image_filter_buffer | Specifies the buffer size for image processing | Size in bytes or with K, M, G suffixes | 10M |
| image_filter_jpeg_quality | Sets JPEG quality level (1-100) | Integer between 1 and 100 | 75 |
| image_filter_webp_quality | Sets WebP quality level (0-100) | Integer between 0 and 100 | 75 |
Example: Setting JPEG Quality
location /images/ {
image_filter_jpeg_quality 90;
image_filter_buffer 2M;
proxy_pass http://backend;
}Example: Setting WebP Quality
location /images/ {
image_filter_webp_quality 85;
proxy_pass http://backend;
}6. Setting Image Buffer Size
| Directive | Values | Description |
|---|---|---|
| image_filter_buffer | 10M |
Sets the buffer size for image processing operations. Default is 10M. |
Example: Configuring Image Buffer Size
location /images/ {
image_filter_buffer 50M;
image_filter resize 100 100;
}
Note: Increasing the buffer size allows processing of larger images but uses more memory.
7. Creating Thumbnails
| Directive | Description | Values | Notes |
|---|---|---|---|
| image_filter | Enables image filtering capabilities | thumbnail |
Must be set inside location block |
| image_filter_buffer | Size of the buffer for image processing | 10M |
Default is 10MB, can be increased for large images |
| image_filter_jpeg_quality | Quality of JPEG output (1-100) | 90 |
Higher values mean better quality but larger file size |
| image_filter_webp_quality | Quality of WebP output (0-100) | 85 |
Similar to JPEG quality setting |
Example: Thumbnail Creation
location /thumb/ {
image_filter thumbnail 100x100;
image_filter_buffer 2M;
image_filter_jpeg_quality 85;
}
Note: The
image_filter module requires the ngx_http_image_filter_module to be compiled into Nginx.
Warning: Image filtering is CPU-intensive. Consider caching results or using a dedicated image processing service for high-volume applications.
8. Testing Image Validity
| Directive | Description | Default | Notes |
|---|---|---|---|
| image_filter | Enables image filtering and validation | off | Must be set to test for validity checks |
| image_filter_buffer | Buffer size for image processing | 10M | Can be adjusted to handle large images |
| image_filter_jpeg_quality | Quality setting for JPEG output | 75 | Valid range 1-100 |
Example: Testing Image Validity
location ~* \.(jpg|jpeg|png|gif)$ {
image_filter test;
image_filter_buffer 10M;
image_filter_jpeg_quality 85;
if ($image_filter_result = "invalid") {
return 400;
}
proxy_pass http://backend;
}
Note: The
image_filter directive must be set to test to validate image format and integrity. If the image is invalid, the $image_filter_result variable will be set to invalid.
Warning: Large images may cause memory issues. Adjust
image_filter_buffer accordingly to prevent out-of-memory errors.
9. Converting Image Formats
| Format | Description | Supported in Nginx | Notes |
|---|---|---|---|
| JPEG | Joint Photographic Experts Group format for lossy compression | NEW | Can be used with image_filter directive |
| PNG | Portable Network Graphics format supporting lossless data compression | NEW | Can be used with image_filter directive |
| GIF | Graphics Interchange Format for animated images | DEPRECATED | Support removed in newer versions; use WebP or JPEG instead |
| WebP | Modern image format by Google with lossy and lossless options | NEW | Requires ngx_http_v2_module for full support |
| BMP | Bitmap image format, uncompressed | DEPRECATED | Not supported in current versions |
Example: Converting JPEG to WebP
location ~ \.jpg$ {
image_filter webp;
image_filter_buffer 10M;
image_filter_jpeg_quality 85;
}
Note: The
image_filter module must be compiled into Nginx for image conversion to work.
Warning: Large images may cause memory issues. Ensure
image_filter_buffer is set appropriately.
10. Configuring Sharpen
| Directive | Values | Description |
|---|---|---|
| image_filter | sharpen |
Enables the sharpen filter for image processing |
| image_filter_sharpen | 0-100 |
Sets the intensity of the sharpen effect (default: 0) |
Example: Basic Sharpen Configuration
location /images/ {
image_filter sharpen 50;
image_filter_buffer 10M;
}
Note: The
image_filter module requires the ngx_http_image_filter_module to be compiled into Nginx.
11. Setting Interlace Mode
| Directive | Values | Description |
|---|---|---|
| interlace_mode | off, on |
Controls whether image interlacing is enabled. Default is off. |
Note: Interlacing is primarily useful for web browsers to display images progressively. It does not affect image quality or file size significantly.
12. Handling Image Errors
| Error Type | Description | Configuration | Solution |
|---|---|---|---|
| 404 Not Found | Image file does not exist at the specified path | error_page 404 /404.html; |
Return custom 404 page or redirect to default image |
| 415 Unsupported Media Type | Unsupported image format (e.g., .tiff) | error_page 415 /unsupported.html; |
Return custom error page or fallback to default format |
| 500 Internal Server Error | Server error during image processing (e.g., memory issues) | error_page 500 /error.html; |
Log error and return user-friendly message |
| 502 Bad Gateway | Proxy or upstream server failure in image delivery | error_page 502 /bad-gateway.html; |
Retry or serve cached version if available |
Example: Custom Error Pages for Images
error_page 404 /images/missing.png;
location = /images/missing.png {
alias /var/www/images/placeholder.png;
}
error_page 500 502 /images/error.png;
location = /images/error.png {
alias /var/www/images/default-error.png;
}
Note: Ensure error pages are optimized for fast loading to avoid cascading errors.
Warning: Avoid exposing internal paths in error messages to prevent security risks.