Introduction

sanpera is an image-editing library for Python, powered by ImageMagick.

While sanpera uses ImageMagick, it isn't designed as an ImageMagick wrapper; the underlying library is a mere implementation detail. The goal is to support all of ImageMagick's features with an idiomatic interface.

The examples from the ImageMagick Usage documentation are gradually being converted into unit tests in sanpera/tests/im_usage. An easy way to learn sanpera, then, is to find an example that does what you want and read the test's equivalent Python code.

Warning

This software is not production-ready. It may segfault, leak memory, eat your data, cheat on your boyfriend, or burn down your house.

Concepts

Images and frames

Somewhat unlike both PIL and ImageMagick, sanpera draws a distinction between an image and a frame. An image is a collection of metadata and zero or more frames; a frame contains the actual pixel data.

Frames can be manipulated to alter an image in-place. Image operations apply to every frame at once and produce copies.

Geometry

Sizes, offsets, and other geometric concepts are represented by small utility classes in sanpera.geometry. To avoid the minor hassle of constructing a trivial object, methods that expect Size and Vector objects also accept (x, y) tuples.

Overview

Creating images

A new image with one frame can be created with Image.new().

from sanpera.image import Image
img = Image.new((640, 480))

Note the double parentheses: that's a tuple (or a Size), not two separate arguments.

Reading and writing

Images can be read and written by filename:

img = Image.read('foo.png')
img.write('bar.png')

Or to and from bytestrings:

pngdata = img.to_buffer(format='png')
img = Image.from_buffer(pngdata)

Due to limitations in ImageMagick, sanpera cannot read to or write from arbitrary file-like objects in chunks.

Working with frames

An image is an iterable of its frames.

frame = img[0]
print len(img)

A frame may belong to only one image at a time. You can still make copies, move frames from one image to another, or extract frames into a new image.

Resizing

Resizing creates a new image.

smaller = img.resized((100, 100))

Size methods exist for adjusting sizes in various ways, including emulating any of the special symbols accepted by convert -resize.

thumbnail = img.resized(img.size.fit_inside((100, 100)))

Cropping

TODO