Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ioppermann/modjpeg-nginx

NGINX filter module for adding overlays and logos to JPEGs on-the-fly without degrading the quality of the image.
https://github.com/ioppermann/modjpeg-nginx

filter jpeg libmodjpeg module nginx

Last synced: 6 days ago
JSON representation

NGINX filter module for adding overlays and logos to JPEGs on-the-fly without degrading the quality of the image.

Host: GitHub
URL: https://github.com/ioppermann/modjpeg-nginx
Owner: ioppermann
License: bsd-2-clause
Created: 2015-01-07T17:33:28.000Z (almost 10 years ago)
Default Branch: master
Last Pushed: 2020-09-09T16:34:36.000Z (about 4 years ago)
Last Synced: 2024-08-03T21:02:54.730Z (3 months ago)
Topics: filter, jpeg, libmodjpeg, module, nginx
Language: C
Homepage:
Size: 43.9 KB
Stars: 19
Watchers: 3
Forks: 3
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

awesome-nginx - modjpeg-nginx - Filter module for adding overlays and logos to JPEGs on-the-fly without degrading the quality of the image. (Third Party Modules / C Modules)

README

# modjpeg-nginx

Nginx filter module for adding overlays on JPEGs on-the-fly with [libmodjpeg](https://github.com/ioppermann/libmodjpeg).

> With libmodjpeg you can overlay a (masked) image onto an existing JPEG as lossless as possible. Changes in the JPEG only
> take place where the overlayed image is applied. All modifications happen in the DCT domain, thus the JPEG is decoded and
> encoded losslessly.

- [Typical Uses](#typical-uses)
- [Try it out](#try-it-out)
- [Installation](#installation)
- [Compatibility](#compatibility)
- [Synopsis](#synopsis)
- [Directives](#directives)
- [jpeg_filter](#jpeg_filter)
- [jpeg_filter_max_pixel](#jpeg_filter_max_pixel)
- [jpeg_filter_buffer](#jpeg_filter_buffer)
- [jpeg_filter_optimize](#jpeg_filter_optimize)
- [jpeg_filter_progressive](#jpeg_filter_progressive)
- [jpeg_filter_arithmetric](#jpeg_filter_arithmetric)
- [jpeg_filter_graceful](#jpeg_filter_graceful)
- [jpeg_filter_effect](#jpeg_filter_effect)
- [jpeg_filter_dropon_align](#jpeg_filter_dropon_align)
- [jpeg_filter_dropon_offset](#jpeg_filter_dropon_offset)
- [jpeg_filter_dropon_file](#jpeg_filter_dropon_file)
- [jpeg_filter_dropon_memory](#jpeg_filter_dropon_memory)
- [Notes](#notes)
- [License](#license)
- [Acknowledgement](#acknowledgement)

## Typical Uses

This filter module can add overlays (e.g. a logo, visual watermark) on JPEGs when they are requested.

A few ideas:

- Consider you are a photographer and have a image gallery on your website. Without hardcoding your logo (brand, watermark, ...) into these images you can apply it the moment the image is requested. Whenever you update your logo, just update the nginx configuration and it's done. No need to re-process all your images.
- You have an online shop with thousands of product images. With just configuring nginx you can add your logo to all of the product images. You don't have to process all product images.
- You have a paid service. Add a watermark to all images if the user is not subscribed. If the user is subscribed, don't apply the watermark or put just a small logo on the images without touching the original images.
- On your website, registered users can upload images. Add the avatar of the user to the image who uploaded the image without processing it after the upload. If the user changes her avatar, all her images will automatically have the new avatar on them.

## Try it out

In order to try out this filter module, pull the docker image

```bash
docker pull ioppermann/modjpeg-nginx:latest
```

The docker container exposes TCP port 80 and expects a directory with images mounted on `/images`, e.g.

```bash
docker run -it --rm --name=modjpeg-nginx \
--mount type=bind,src=$PWD/images,dst=/images,readonly \
-p 8080:80 \
ioppermann/modjpeg-nginx:latest
```

Now you can browse to [http://localhost:8080/](http://localhost:8080/) and click on the listed images. The modjpeg logo will be applied in the top left corner. By default
only images that are smaller than 10MB are processed by the filter. Stop the container by pressing `Ctrl-c`.

The filter can be controlled by these environment variables:

| Name | Default | Description |
| ---------------- | ---------------------------------- | ----------------------------------------------------------- |
| MJ_GRACEFUL | on | See [jpeg_filter_graceful](#jpeg_filter_graceful) |
| MJ_BUFFER | 10M | See [jpeg_filter_buffer](#jpeg_filter_buffer) |
| MJ_MAX_PIXEL | 0 | See [jpeg_filter_max_pixel](#jpeg_filter_max_pixel) |
| MJ_DROPON_ALIGN | "top left" | See [jpeg_filter_dropon_align](#jpeg_filter_dropon_align) |
| MJ_DROPON_OFFSET | "0 0" | See [jpeg_filter_dropon_offset](#jpeg_filter_dropon_offset) |
| MJ_DROPON_FILE | "/usr/local/nginx/conf/dropon.png" | See [jpeg_filter_dropon_file](#jpeg_filter_dropon_file) |

The following example will allow images with up to 150 megapixel (`MJ_MAX_PIXEL`) and 100MB in file size (`MJ_BUFFER`). The logo will be placed in bottom right corner (`MJ_DROPON_ALIGN`)
with an offset of -15px horizontally and vertically (`MJ_DROPON_OFFSET`).

```bash
docker run -it --rm --name=modjpeg-nginx \
--mount type=bind,src=$PWD/images,dst=/images,readonly \
-p 8080:80 \
-e MJ_MAX_PIXEL=150000000 \
-e MJ_BUFFER=100M \
-e MJ_DROPON_ALIGN="bottom right" \
-e MJ_DROPON_OFFSET="-15 -15" \
ioppermann/modjpeg-nginx:latest
```

In order to change the logo, you can mount an additional volume or put it into the directory you already mount, e.g.

```bash
docker run -it --rm --name=modjpeg-nginx \
--mount type=bind,src=$PWD/images,dst=/images,readonly \
-p 8080:80 \
-e MJ_DROPON_FILE="/images/logo.png" \
ioppermann/modjpeg-nginx:latest
```

## Installation

### CentOS / RedHat 7 packages

An easy way to use the module in CentOS or RedHat 7, is to use precompiled dynamic nginx module. It is built for nginx stable. The [repository](https://www.getpagespeed.com/redhat) includes latest stable nginx, the jpeg module, libmodjpeg and libpng16 dependencies:

yum -y install https://extras.getpagespeed.com/release-el7-latest.rpm
yum install nginx nginx-module-jpeg

### Compilation

For using the modjpeg-nginx filter module, follow these steps:

1. Clone and install [libmodjpeg](https://github.com/ioppermann/libmodjpeg) (libjpeg and cmake are required)
2. Clone this repository
3. Download and extract the [latest nginx](http://nginx.org/en/download.html)
4. Configure, compile, and install nginx

```bash
# Clone and install libmodjpeg
git clone https://github.com/ioppermann/libmodjpeg.git
cd libmodjpeg
cmake .
make
make install
cd ..

# Clone modjpeg-nginx
git clone https://github.com/ioppermann/modjpeg-nginx.git

# Download and install nginx
wget 'http://nginx.org/download/nginx-1.19.2.tar.gz'
tar -xvzf nginx-1.19.2.tar.gz
cd nginx-1.19.2

# Configure as static module, or ...
./configure --add_module=../modjpeg-nginx

# ... configure as dynamic module (as of nginx 1.9.11)
./configure --add_dynamic_module=../modjpeg-nginx

# If the libmodjpeg library is not found, add e.g. '--with-ld-opt=-L/usr/local/lib' to
# the configure options if it was installed to /usr/local/lib

# You may want to use the other './configure' options that are used
# in your current nginx build. Check the output of 'nginx -V'.

make
make install
```

If you configured modjpeg-nginx as dynamic module, you have to load the module in the beginning of the config

```nginx
...
load_module modules/ngx_http_jpeg_filter_module.so;
...
```

## Compatibility

This module has been tested with the following versions of nginx:

- 1.26.2
- 1.24.0
- 1.22.1
- 1.20.2
- 1.19.2
- 1.18.0
- 1.17.6
- 1.16.1
- 1.15.3
- 1.14.0
- 1.13.10
- 1.12.2
- 1.10.3
- 1.8.1 (only as static module)

## Synopsis

```nginx
...

location /gallery {
# enable jpeg filter module
jpeg_filter on;

# limit image sizes to 9 megapixel
jpeg_filter_max_pixel 9000000;

# limit image file size to 5 megabytes
jpeg_filter_buffer 5M;

# deliver the images unmodified if one of the limits apply
jpeg_filter_graceful on;

# pixelate the image
jpeg_filter_effect pixelate;

# add a masked logo in the bottom right corner
# with a distance of 10 pixel from the border
jpeg_filter_dropon_align bottom right;
jpeg_filter_dropon_offset -10 -10;
jpeg_filter_dropon_file /path/to/logo.jpg /path/to/mask.jpg;
}

...
```

Or use it with [OpenResty's ngx_http_lua_module](https://github.com/openresty/lua-nginx-module) and a PNG logo:

```nginx
...

location /gallery {
set_by_lua_block $valign {
local a = { 'top', 'center', 'bottom' }
return a[math.random(#a)]
}

set_by_lua_block $halign {
local a = { 'left', 'center', 'right' }
return a[math.random(#a)]
}

# enable jpeg filter module
jpeg_filter on;

# limit image sizes to 9 megapixel
jpeg_filter_max_pixel 9000000;

# limit image file size to 5 megabytes
jpeg_filter_buffer 5M;

# deliver the images unmodified if one of the limits apply
jpeg_filter_graceful on;

# pixelate the image
jpeg_filter_effect pixelate;

# add a logo in a random position
jpeg_filter_dropon_align $valign $halign;
jpeg_filter_dropon_file /path/to/logo.png;
}

...
```

Or generate a logo with [Lua-GD](http://ittner.github.io/lua-gd/):

```nginx
http {
...
lua_package_cpath '/usr/local/lib/lua/5.1/?.so;;';
...
server {
...
location /gallery {
set_by_lua_block $logobytestream {
local gd = require "gd"

local im = gd.create(210, 70)
local white = im:colorAllocate(255, 255, 255)
local black = im:colorAllocate(0, 0, 0)
im:filledRectangle(0, 0, 140, 80, white)
im:string(gd.FONT_LARGE, 10, 10, "Hello modjpeg", black)
im:string(gd.FONT_LARGE, 10, 40, os.date("%c"), black);
return im:jpegStr(85)
}

# enable jpeg filter module
jpeg_filter on;

# limit image sizes to 9 megapixel
jpeg_filter_max_pixel 9000000;

# limit image file size to 5 megabytes
jpeg_filter_buffer 5M;

# deliver the images unmodified if one of the limits apply
jpeg_filter_graceful on;

# pixelate the image
jpeg_filter_effect pixelate;

# add a generated logo in the bottom right corner
# with a distance of 10 pixel from the border
jpeg_filter_dropon_align bottom right;
jpeg_filter_dropon_offset -10 -10;
jpeg_filter_dropon_memory $logobytestream;
}
...
}
...
}
```

## Directives

- [jpeg_filter](#jpeg_filter)
- [jpeg_filter_max_pixel](#jpeg_filter_max_pixel)
- [jpeg_filter_buffer](#jpeg_filter_buffer)
- [jpeg_filter_optimize](#jpeg_filter_optimize)
- [jpeg_filter_progressive](#jpeg_filter_progressive)
- [jpeg_filter_arithmetric](#jpeg_filter_arithmetric)
- [jpeg_filter_graceful](#jpeg_filter_graceful)
- [jpeg_filter_effect](#jpeg_filter_effect)
- [jpeg_filter_dropon_align](#jpeg_filter_dropon_align)
- [jpeg_filter_dropon_offset](#jpeg_filter_dropon_offset)
- [jpeg_filter_dropon_file](#jpeg_filter_dropon_file)
- [jpeg_filter_dropon_memory](#jpeg_filter_dropon_memory)
- [Notes](#notes)

### jpeg_filter

**Syntax:** `jpeg_filter on | off`

**Default:** `jpeg_filter off`

**Context:** `location`

Enable the jpeg filter module.

This directive is turned off by default.

### jpeg_filter_max_pixel

**Syntax:** `jpeg_filter_max_pixel pixel`

**Default:** `0`