Overview

The philiosophy

Modules

Pacakge pystacia is divided into several submodules of which pystacia.image and pystacia.color are of most interest to readers. For convenience reasons symbols from pystacia.image are imported directly into pystacia and pystacia.color is accessible as pystacia.color attribute under pystacia.

For quick experiments in a console you can perform from pystacia import *. Several attributes got pulled into your namespace including:

• pystacia.image.read(), pystacia.image.read_blob() and pystacia.image.read_raw() image factories
• pystacia.image.composite, pystacia.image.types, pystacia.image.filters, pystacia.image.colorspaces, pystacia.image.axes lazy enumerations
• pystacia.lena() and pystacia.magick_logo() sample image factories

Classes and factories

Pystacia is an object oriented imaging library. It uses factory functions to create objects representing concepts like pystacia.image.Image or pystacia.color.Color. You don’t typically use class constructors to create objects and generally you shouldn’t unless you really know what you are doing. You should rely on factories instead.

"""Create an image object from read factory"""

from pystacia import read
image = read('example.jpg')


"""Create a color object from from_string factory"""

from pystacia import color
red = color.from_string('red')

Constants

Many Pystacia methods take C enum-like mnemonics. For example to specify which axis to perform transformation along you can use axes.x. These names are symbolic representation of underlying C constants. They are lazily resolved during runtime to their integral value.

"""Skew an image by 5 pixels along Y axis"""

image.skew(5, axes.y)

There are several lazy enums defined. Most of them inside pystacia.image but they are also for you convenience imported into main pystacia module. Some of them are listed below:

• pystacia.image.types: image types such as types.bilevel for monochrome image, types.pallette, types.grayscale and types.truecolor
• pystacia.image.colorspace: color-spaces such as colorspaces.rgb or colorspaces.ycbcr.
• pystacia.image.filters: sampling filters used typically in rescaling algorithms including popular filters.point, filters.bilinear or filters.sinc typically used in pystacia.image.Image.rescale().
• pystacia.image.composites: composite.over or composite.hue used with pystacia.image.Image.overlay().
• pystacia.image.axes: axes.x and axes.y axes

Method chaining

By default methods of pystacia.image.Image are chainable i.e. you can construct code using long string of methods forming a chain such as:

from pystacia import read
read('example.jpg').denoise().rescale(256, 256).rotate(45).write('output.png')

This style of programming is used a lot in some communities e.g. jQuery and some Java and PHP projects. This is unusual in Python and not entirely clear if appropriate. Instead a Python programmer could typically code like that:

from pystacia import read
image = read('example.jpg')
image.denoise()
image.rescale(256, 256)
image.rotate(45)
image.write('output.png')

Pystacia allows both styles or mixture of them. By default all methods that can be chained are chainable. It’s up to you what you choose. One of the down sides of chaining is that when an exception occurs it can be not immediately clear where it comes from when you call one method several times on one line. If you want to explicitly forbid chaining you can do so by injection environment variable PYSTACIA_NO_CHAINS with non-false value before importing pystacia. When you do so methods that were previously chainable return None:

from os import environ
environ['PYSTACIA_NO_CHAINS'] = '1'

from pystacia import read
# chaining explicitely disabled above

image = read('example.jpg')
image.blur(3).rotate(45)  # this raises an Exception

or from shell:

$ PYSTACIA_NO_CHAINS=1 python helloworld.py

Behind the scenes

Pystcia uses ImageMagick DLL to perform its operation. Specifically MagickWand API is used which is contained in libMagickWand.so, libMagickWand.dylib or libMagickWand.dll depending on the platform used. Pystacia searches for the library in several places starting from the place where bundled binaries are normally stored and ending with system-wide locations. The details of search algorithms are detailed in Skipping binary install. Resolved library is loaded through ctypes and all Pystacia API calls are translated into their several C API low-level counterparts abstracting details for you. Pystacia can work with ImageMagick version 6.5.9.0 or later but more recent versions are bundled and advised to use.