NaremitIMG is tiny Django app which enables dynamic image manipulation on the fly. This could be used, for example, in conjunction with an online image editing tool, or to create thumbnails or to serve responsive images via a CDN. This project is deliberately simple.

Example usage:

mywebsite.com/path/to/naremitimg?uri=http://mywebsite.com/images/frog.jpg&p=cropratio,1|resize,100,100|grayscale

The code takes a source image from a URL or a location on the webserver's filesystem, manipulates as per your instructions, then returns the output image.

The following assumes you have Django and either the Pillow (recommended) or PIL (not so much) imaging libraries installed and working.

Because the Pillow installation process can vary between different webserver environments, NaremitIMG does not attempt to create a dependency. Instead please just know that it won't work without one of these packages installed. See Pillow installation documentation.

Once this is done:

1. Get the code:
   pip install django-naremitimg
   
   
2. Add 'naremitimg' to your INSTALLED_APPS in your Django project's settings.py file
   
   
3. Add an entry to your urls.py file as follows:
   url(r'^path/to/naremitimg$', 'naremitimg.views.img')

There are some optional settings which can be applied (see the "domain" section below).

Once installation is complete, open a web browser and point it to (obviously substitute the path for the machine you are testing this on): http://localhost/path/to/naremitimg?uri=http://naremit.com/naremit.gif

Assuming you have a working web connection and everything in installed correctly, you should see our "N" logo in your browser window. Not very exciting, but if you've got this far, it is all working. Excellent.

All parameters are passed in via GET request in the querystring. These are:

(At least one of uri or path must be present)

• uri: (optional) The web address of the source image.
  
  
• domain: (optional) The domain from which to retrieve the source image. See the "domain" section below.
  
  
• file: (optional) The filesystem path of the source image, e.g. file=/var/www/images/dog.gif.
  
  By using the file method you do expose this path in your webserver's file structure to the outside world. If you server is secured appropriately this shouldn't be a problem but do consider this carefully on public facing systems. A chat with your friendly SysAdmin or InfoSec guy/gal is probably a good idea if you aren't 100% sure.

• format: (optional) Define the filetype you wish NaremitIMG to output, e.g. 'JPEG', 'PNG', etc. If not specified, the output image format will match that of the source image.
  
  
• p: (optional, but silly to leave out) The processing (or manipulations) you would like to perform on the image. See "Image Processing" below.

• cache: (optional) 1 (yes) or 0 (no). Stores a local copy on your server to prevent repeated downloads. By default, the temporary files are help in the /tmp folder but you can changes this by adding NAREMITIMG_TMP_FOLDER to you config (Note: paths must end with a trailing slash).

  Note: NaremitIMG does not delete old files from your specified cache folder. I suggest running a frequently scheduled task (e.g. a cronjob) which deletes old naremitimg_* files in this folder.

• optimize: (optional) Attempt to make the file as small as possible without compromising quality. Only works for JPEG and PNG images. Usage: optimize=1

NaremitIMG can chain multiple processes together to manipulate images. Processes are separated by the '|' (pipe) symbol and are processed one at a time in the order provided. Some processing commands accept additional parameters separated using commas. For example...

p=cropratio,1|resize,100,100|grayscale

...performs the following manipulations:

1. Crop the image to a square shape (using the cropratio command), then,
2. resizes the output to 100x100 pixels (using the resize command), then,
3. removes colour information (using the grayscale command).

The available commands are as follows:

See "Gaussian Blur" below for more powerful blurring options.

Example: ?p=brightness,0.75

This command accepts one floating-point number&p=colorize,%23000,%23f00 parameter. A number less than 1.0 darkens the image and a number greater than 1.0 brightens it. A value of 0 returns a completely black image.

Example: ?p=color,1.1

This command accepts one floating-point number parameter. A number less than 1.0 reduces color information from the image and a number greater than 1.0 increases it. A value of 0 removes all color information and is equivalent to the "grayscale" command below.

Examples:
    ?p=colorize,black,red
    ?p=colorize,%23000,%23f00 (note the '%23' replacement for the '#' sign when dealing with hex colors)

Colorizes the image between the provided colors. Easier for you to try it than for me to explain. :)

Example: ?p=contrast,1.2

This command accepts one floating-point number parameter. A number less than 1.0 reduces the contrast of the image and a number greater than 1.0 increases it. A value of 0 returns a completely gray image.

Example: ?p=crop,100,100,400,300

Crop the image within the coordinates (from the top left corner) specified.

Example: ?p=cropratio,1.4

Crops the image from the center to match the image ratio provided to it. Image ratio is calculated as (width / height), meaning a landscape image is greater than 1, a square image is 1 exactly, and a portrait image has a ratio of less than 1.

Use in conjuction with resize to create fixed size images, e.g. to create 80x120 thumbnails, use: ?p=cropratio,0.6666666666|resize,80,120

Example: ?p=gblur,2

Apply a Gaussian blur to the image. The second parameter is required and specifies the blur distance in pixels.

Example: ?p=posterize,2

Reduce the number of bits for each color channel.

Example: ?p=resize,600,400

Resize an image to fixed pixel dimensions. Especially useful in conjunction with cropratio.

Example: ?p=resize,0.5,0.5

Resize an image to a percentage of its original size, e.g. to make an image 25% the size of the original, use resizepc,0.25,0.25

Example: ?p=rotate,90

Rotate an image through a given number of degrees.

Example: ?p=sharpness,0.5

This command accepts one floating-point number parameter. A number less than 1.0 reduces the sharpness of the image and a number greater than 1.0 increases it.

Example: ?p=solarize,20

Invert all pixel values above the given threshold.

The domain parameter is useful if you wish to hide the domain of the source image from prying eyes. So instead of a URL such as...

mywebsite.com/path/to/naremitimg?uri=http://mysecretplace.example.com/images/dog.gif

...you code specify...

mywebsite.com/path/to/naremitimg?domain=secret&uri=dog.gif

Then, in your settings.py file, add the following:

NAREMITIMG= {
    'secret': 'http://mysecretplace.example.com/images/',
}

The code then simply appends the two strings together, e.g. "%s%s" % (domain, uri) to create the full URL. You can add as many entries to this dictionary as you like.

This project needs more testing, units tests and for the documentation to be moved to a 'readthedocs' Sphinx style format for easier use. All help is welcomed and gratefully appreciated, however big or small.

Before submitting a pull request, please ensure the docs are updated to reflect the changes you have made. We rely on your feedback so please report any bugs or comments, good or bad, via https://github.com/naremit/NaremitIMG/issues.

NaremitIMG was developed original by Naremit, a digital agency based in Bangkok, Thailand.