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