pymagery — python imagery

1.7.0 Documentation

What's New?

1.7.0 adds the __add__, __sub__, __mul__, __div__, and __eq__ plugins.

Supported File Formats

All input and output files use the Netpbm format:

Monochrome/black-and-white/1-bit — portable bitmap file format (PBM)
Grayscale — portable graymap file format (PGM)
RGB — portable pixmap file format (PPM)

These formats are easy to read/write and are lossless. Netpbm is a cross-platform package that can convert from the more common formats (JPEG, PNG, GIF, etc.) into PPM, PGM, and PBM.

Basic Read/Write Example

import pymagery i = pymagery.image('foo.ppm') i.save('bar.ppm')

Plugins

All plugins are loaded in dynamically and assigned to the image class. Thus image.crop executes the crop plugin on that image.

A distinct/unusual feature is the use of capitalization on plugin function names. Uppercase functions return the image instance, always. Lowercase functions return whatever the function normally returns. The point of this is to allow collapsing functions into a string of method calls. For example, the following options A and B produce identical results:

import pymagery # Option A pymagery.image('foo.png').ROT_90CW().save('bar.png') # Option B i = pymagery.image('foo.png') i.rot_90cw() i.save('bar.png')

The immediate advantage is removal of unnecessary lines of code without really sacrificing clarity. This could have immediate use in list comprehensions. If the uppercase function ROT_90CW were not available then two operations of instantiation of the image class and calling of the rotate function would have to be done on separate lines otherwise the image instance itself would not be retrievable since rotate function does not return an image.

image class properties

The primary means to use pymagery is the image class. At load-time the plugins are copied as properties of the image, thus the plugins become methods of the image. Other that plugins the image class has the following properties:

width — width of image in pixels
height — height of image in pixels
mode — indicates if the image is monochrome, grayscale, or RGB
comment — a file comment
pixels — pixel data as a list (rows) of lists (columns) thus pixels[0][10] is the 10th pixel from the left of the top row

The following intrinsic methods are available:

new(width, height, mode) — clears all image data and creates a black image of specified size and mode
load(fname) — clears all image data and loads in data from the specified file
save(fname, mode=None) — save image data into the specified file (if mode is supplied then the file saved file is saved as that mode)
sameas — returns True if the mode and pixels data are identical to the supplied image (changed in 1.7.0)

The origin of the image is considered to be the top-left corner. Thus, the corners of the image are at the following:

top-left — pixels[0][0]
top-right — pixels[0][width-1]
bottom-right — pixels[height-1][width-1]
bottom-left — pixels[height-1][0]

Image modes

There are three modes currently supported: monochrome, 8-bit grayscale, and 24-bit RGB. See the mode_convert plugin for mode conversion.

Monochrome

Each pixel is a zero or one for black and white, respectively.

Grayscale

Each pixel is a number from 0 to 255 (8-bit grayscale).

RGB

Each pixel is a 3-tuple of red, green, and blue 8-bit values. To be memory efficient the pixel value is concatenated into a single 24-bit integer. The upper 8-bits are red, middle 8-bits are green, and lower 8-bits are blue. The following are examples of extracting the colors and combining them:

r,g,b = (val >> 16)&255, (val >> 8)&255, val&255 val = ((r&255) << 16) + ((g&) << 8) + (b&255)

Be careful of the operator precendence of shift and bitwise AND. Packing and unpacking the color components would be a lot easier if python had macros to avoid the performance cost of function calls.