The pildriver Utility

The pildriver tool gives access to most PIL functions from your operating system’s command-line interface.

$ pildriver program

When called as a script, the command-line arguments are passed to a PILDriver instance (see below). If there are no command-line arguments, the module runs an interactive interpreter, each line of which is split into space-separated tokens and passed to the execute method.

The pildriver tool was contributed by Eric S. Raymond.

Examples #

The following example loads test.png, crops out a portion of its upper-left-hand corner and displays the cropped portion:

$ pildriver show crop 0 0 200 300 open test.png

The following example loads test.tiff, rotates it 30 degrees, and saves the result as rotated.png (in PNG format):

$ pildriver save rotated.png rotate 30 open test.tiff

The PILDriver Class #

The pildriver module provides a single class called PILDriver.

An instance of the PILDriver class is essentially a software stack machine (Polish-notation interpreter) for sequencing PIL image transformations. The state of the instance is the interpreter stack.

The only method one will normally invoke after initialization is the execute method. This takes an argument list of tokens, pushes them onto the instance’s stack, and then tries to clear the stack by successive evaluation of PILdriver operators. Any part of the stack not cleaned off persists and is part of the evaluation context for the next call of the execute method.

PILDriver doesn’t catch any exceptions, on the theory that these are actually diagnostic information that should be interpreted by the calling code.

Methods #

In the method descriptions below, each line lists a command token, followed by <>-enclosed arguments which describe how the method interprets the entries on the stack. Each argument specification begins with a type specification: either int, float, string, or image.

All operations consume their arguments off the stack (use dup to keep copies around). Use verbose 1 to see the stack state displayed before each operation.

add <image:pic1> <image:pic2> <int:offset> <float:scale>

Pop the two top images, produce the scaled sum with offset.

blend <image:pic1> <image:pic2> <float:alpha>

Replace two images and an alpha with the blended image.

brightness <image:pic1>

Enhance brightness in the top image.

clear

Clear the stack.

color <image:pic1>

Enhance colour in the top image.

composite <image:pic1> <image:pic2> <image:mask>

Replace two images and a mask with their composite.

contrast <image:pic1>

Enhance contrast in the top image.

convert <string:mode> <image:pic1>

Convert the top image to the given mode.

copy <image:pic1>

Make and push a true copy of the top image.

crop <int:left> <int:upper> <int:right> <int:lower> <image:pic1>

Crop and push a rectangular region from the current image.

darker <image:pic1> <image:pic2>

Pop the two top images, push an image of the darker pixels of both.

difference <image:pic1> <image:pic2>

Pop the two top images, push the difference image

draft <string:mode> <int:xsize> <int:ysize>

Configure the loader for a given mode and size.

dup

Duplicate the top-of-stack item.

filter <string:filtername> <image:pic1>

Process the top image with the given filter.

format <image:pic1>

Push the format of the top image onto the stack.

getbbox

Push left, upper, right, and lower pixel coordinates of the top image.

extrema

Push minimum and maximum pixel values of the top image.

invert <image:pic1>

Invert the top image.

lighter <image:pic1> <image:pic2>

Pop the two top images, push an image of the lighter pixels of both.

merge <string:mode> <image:pic1> [<image:pic2> [<image:pic3> [<image:pic4>]]]

Merge top-of stack images in a way described by the mode.

mode <image:pic1>

Push the mode of the top image onto the stack.

multiply <image:pic1> <image:pic2>

Pop the two top images, push the multiplication image.

new <int:xsize> <int:ysize> <int:color>:

Create and push a greyscale image of given size and colour.

offset <int:xoffset> <int:yoffset> <image:pic1>

Offset the pixels in the top image.

open <string:filename>

Open the indicated image, read it, push the image on the stack.

paste <image:figure> <int:xoffset> <int:yoffset> <image:ground>

Paste figure image into ground with upper left at given offsets.

pop

Discard the top element on the stack.

resize <int:xsize> <int:ysize> <image:pic1>

Resize the top image.

rotate <int:angle> <image:pic1>

Rotate image through a given angle

save <string:filename> <image:pic1>

Save image with default options.

save2 <string:filename> <string:options> <image:pic1>

Save image with specified options.

screen <image:pic1> <image:pic2>

Pop the two top images, superimpose their inverted versions.

sharpness <image:pic1>

Enhance sharpness in the top image.

show <image:pic1>

Display and pop the top image.

size <image:pic1>

Push the image size on the stack as (y, x).

subtract <image:pic1> <image:pic2> <int:offset> <float:scale>

Pop the two top images, produce the scaled difference with offset.

swap

Swap the top-of-stack item with the next one down.

thumbnail <int:xsize> <int:ysize> <image:pic1>

Modify the top image in the stack to contain a thumbnail of itself.

transpose <string:operator> <image:pic1>

Transpose the top image.

verbose <int:num>

Set verbosity flag from top of stack.