s4u.image

This package implements the data a basic image library. It has three basic tasks:

  1. manage a database of images, with image date stored on the filesystem and image metadata stored in a relational database.
  2. scale image to a given width or height or weight & height, but without and with cropping.
  3. store image scales so images never have to be scaled more than use.

Usage

Before you can use s4u.image you need tell it where it can store image data on disk. This is done by calling s4u.image.configure().

from s4u.image import configure

configure('/var/lib/photos/fullsize', '/var/lib/photos/scaled')

If you are using Pyramid application you can also configure s4u.image using Pyramid’s Configurator object. When doing this the paths will be taken from the application settings using the keys fs.images.original and fs.images.scaled.

from pyramid.config import Configurator

config = Configurator()
config.include('s4u.image')

Images stored using s4u.image.model.Image objects. When creating an image you need to pass in the raw image data, and optionally a filename. The filename is only used determine the extension for the image file that will be created.

from s4u.sqlalchemy import meta
from s4u.image.model import Image

def load_image(filename):
    session = meta.Session()
    image = Image(open(filename).read(), filename)
    session.add(image)
    return image

An image has two useful properties: path which contains the filename for the image relative to the directories where all images are stored, and filesystem_path which contains the full filesystem path of the image.

Most of the time you do not want to use the full size image, but scaled to a specific width or height. This is handled by the scale method.

image = load_image('mugshot.png')
# Scale to maximum of 50x100 pixels
scale = image.scale(width=50, height=100)

This will return a ImageScale object which contains a scaled version of the image. Scaled images are stored automatically, so an image will never be scaled twice to the same dimensions.

API reference

Configuration

s4u.image.configure(original_path, scale_path)

Configure the filesystem paths used to store image files.

Parameters:
  • original_path – filesystem path used for full size images.
  • scale_path – filesystem path used for scaled images.
s4u.image.includeme(config)

Configure s4u.image using a Pyramid Configurator object. This will take the filesystem paths from the application settings using the keys fs.images.original and fs.images.scaled.

s4u.image.initialise_filesystem()

Create required filesystem.

This function requires that s4u.image is already configured.

It is safe to call this function multiple times: it will notice if a directory already exists.

Scaling functions

s4u.image.scale.scale_image(image, width=None, height=None, crop=False, strip_whitespace=False)

Scale the given image data to another size and return the result as a string or optionally write in to the file-like result object.

Parameters:
  • image (file) – open file for image to scale
  • width (int) – desired maximum image width
  • height (int) – desired maximum image width
  • crop (bool) – allow cropping image to fill full width and height
  • strip_whitespace (bool) – crop surrounding whitespace before processing the image

The return value is a tuple with the new image, the image format and a size-tuple.

The width, height, direction parameters will be passed to scale_pil_image(), which performs the actual scaling.

s4u.image.scale.correct_colour_mode(image)

Make sure an image uses a colour handling scheme which allows for high quality scaling and can be rendered by web browsers.

s4u.image.scale.crop_surrounding_whitespace(image)

Remove surrounding empty space around an image.

This implemenation assumes that the surrounding space has the same colour as the top leftmost pixel.

Parameters:image – PIL image
Return type:PIL image
s4u.image.scale.center_crop(image, width, height)

Crop an image to the desired width and height. The crop is made from the middle of the image.

Parameters:
  • image – PIL image
  • width (int) – maximum width, or None of width is unrestrained
  • height (int) – maximum height, or None of height is unrestrained
Return type:

PIL image

s4u.image.scale.scale_pil_image(image, width=None, height=None, crop=False)

Scale a PIL image to another size.

Parameters:
  • image – PIL Image instance
  • width (int) – desired maximum image width
  • height (int) – desired maximum image width
  • crop (bool) – allow cropping image to fill full width and height
Return type:

PIL Image

The generated image is a JPEG image, unless the original is a GIF or PNG image. This is needed to make sure alpha channel information is not lost, which JPEG does not support.

Image model

class s4u.image.model.Image(data=None, filename=None, url=None)

A source image.

filesystem_path

Return the (absolute) filesystem path for the image data.

scale(width=None, height=None, crop=False, strip_whitespace=False)

Return a scaled version of this image. If a matching ImageScale is found it is returned directly. Otherwise the image will be scaled and a new ImageScale instance is created.

See scale_image for more information on the scaling parameters.

Return type:ImageScale
class s4u.image.model.ImageScale(image, width=None, height=None, crop=False, strip_whitespace=False)

A scaled version of image. Each Image can have many different scaled versions. The final dimensions of the image are stored to allow efficient creation of HTML img tags.

width

The width in pixels of the scaled image.

height

The heighy in pixels of the scaled image.

filesystem_path

Return the (absolute) filesystem path for the image data.

Changelog

2.4.1 - Unreleased

  • ...

2.4.0 - September 1, 2014

  • Use pyramid_sqlalchemy instead of s4u.sqlalchemy.

2.3.2 - May 2, 2014

  • Fix error in image scaling: open source image in read-mode, not write mode.

2.3.1 - April 30, 2014

  • Swallow errors when trying to delete a missing file.

2.3.0 - December 20, 2013

  • Add support for Python 3

2.2.0 - December 5, 2013

  • Add API to initialise filesystem paths.

2.1.0 - November 29, 2013

  • Add a delete method to the Image class.
  • Add a replace_content method to the Image class, which can be used to modify the image.
  • Fix URL for pyramid documentation.
  • Use tempfile.gettempdir() to get the temporary directory for tests instead of hardcoding /tmp/.

2.0.1 - January 8, 2013

  • First public release.

2.0 - September 14, 2012

  • Add a new URL column to images and extend API to support remote images.
  • Use Pillow instead of PIL.

2.0a3 - August 3, 2012

  • Fix bug in image scale generation which ignored the whitespace option. Thanks to Jason for catching this.

2.0a2 - August 3, 2012

  • Fix error in storing image scale parameters.

2.0a1 - August 3, 2012

  • Add option to remove whitespace surrounding an image.

1.4 - February 28, 2012

  • Add support for hosting images via a separate URL.

1.3 - November 30, 2011

  • Add a better index for index for the image scale table.

1.2 - October 14, 2011

  • Add support for s4u.upgrade: add an upgrade step to create the image directories.
  • Only use 16 top-level directories; 256 was a bit too much.

1.1 - September 28, 2011

  • Move minimal image data to s4u.image.testing to promote reuse by other packages.
  • Register a static view for Pyramid to serve image data.

1.0 - August 8, 2011

  • First version.

Indices and tables