Prev Next
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.