Gimp-Python implements a number of special object types that represent the different types of parameters you can pass to a PDB procedure. Rather than just making these place holders, I have added a number of members and methods to them that allow a lot of configurability without directly calling PDB procedures.
There are also a couple of extra objects that allow low level manipulation of images. These are tile objects (working) and pixel regions (not quite finished).
This is the object that represents an open image. In this section, image represents a generic image object.
This is the active channel of the image. You can also assign to this member, or None if there is no active channel.
This is the active layer of the image. You can also assign to this member, or None if there is no active layer.
This is the type of the image (eg RGB, INDEXED).
This is a list of the channels of the image. Altering this list has no effect, and you can not assign to this member.
This is the colour map for the image.
This is the filename for the image. A file load or save handler might assign to this.
This is the height of the image. You can't assign to this member.
The floating selection layer, or None if there is no floating selection.
This is a list of the layers of the image.
The selection mask for the image.
This is the width of the image. You can't assign to this member.
Adds channel to image in position position.
Adds layer to image in position position.
Adds the mask mask to layer.
Unsets the dirty flag on the image.
Disables undo for image.
Enables undo for image. You might use these commands round a plugin, so that the plugin's actions can be undone in a single step.
Returns the resulting layer after merging all the visible layers, discarding non visible ones and stripping the alpha channel.
Returns true if component (one of the *_CHANNEL constants) is active.
Returns true if component is visible.
Sets the activeness of component.
Sets the visibility of component.
Lowers channel.
Lowers layer.
Merges the visible layers of image using the given merge type.
Returns the layer that is visible at the point (x,y), or None if no layer matches.
Raises channel.
Raises layer.
Removes channel from image.
Removes layer from image.
Removes the mask from layer, with the given mode (either APPLY or DISCARD).
Resizes the image to size (width, height) and places the old contents at position (x,y).
These objects represent a Gimp Image's colour channels. In this section, channel will refer to a generic channel object.
The colour of the channel.
The height of the channel.
The width of the channel.
The image the channel belongs to, or None if it isn't attached yet.
The channel's layer (??) or None if one doesn't exist.
Non zero if the channel is a layer mask.
The name of the channel.
The opacity of the channel.
The show_masked value of the channel.
Non-zero if the channel is visible.
returns a copy of the channel.
Layer objects represent the layers of a Gimp image. In this section I will refer to a generic layer called layer.
The apply mask setting. (non zero if the layer mask is being composited with the layer's alpha channel).
The number of bytes per pixel.
The edit mask setting. (non zero if the mask is active, rather than the layer).
The height of the layer.
The image the layer is part of, or None if the layer isn't attached.
Non zero if this layer is the image's floating selection.
The layer's mask, or None if it doesn't have one.
The mode of the layer.
The name of the layer.
The opacity of the layer.
The layer's preserve transparency setting.
Adds an alpha component to the layer.
Creates a copy of the layer, optionally with an alpha layer.
Creates a layer mask of type type.
Resizes the layer to (w, h), positioning the original contents at (x,y).
Scales the layer to (w, h), using the specified origin (local or image).
Sets the offset of the layer, relative to the image's origin
Moves the layer to (x, y) relative to its current position.
Both layers and channels are drawables. Hence there are a number of operations that can be performed on both objects. They also have some common attributes and methods. In the description of these attributes, I will refer to a generic drawable called drawable.
The number of bytes per pixel.
Non zero if the drawable is colour.
Non zero if the drawable is greyscale.
Non zero if the drawable has an alpha channel.
The height of the drawable.
The image the drawable belongs to.
Non zero if the drawable uses an indexed colour scheme.
The bounds of the drawable's selection.
The name of the drawable.
The offset of the top left hand corner of the drawable.
The type of the drawable.
Non zero if the drawable is visible.
The width of the drawable.
Fills the drawable with given fill_type (one of the *_FILL constants).
Flush the changes to the drawable.
Creates a pixel region for the drawable. It will cover the region with origin (x,y) and dimensions w x h. The dirty argument sets whether any changes to the pixel region will be reflected in the drawable (default is TRUE). The shadow argument sets whether the pixel region acts on the shadow tiles or not (default is FALSE). If you draw on the shadow tiles, you must call drawable.merge_shadow() for changes to take effect.
Get a tile at (row, col). Either on or off the shadow buffer.
Get the tile that contains the pixel (x, y).
Merge the shadow buffer back into the drawable.
Update the given portion of the drawable.
Tile objects represent the way Gimp stores information. A tile is basically just a 64x64 pixel region of the drawable. The reason Gimp breaks the image into small pieces like this is so that the whole image doesn't have to be loaded into memory in order to alter one part of it. This becomes important with larger images.
In Gimp-Python, you would use Tiles if you wanted to perform some low level operation on the image, instead of using procedures in the PDB. This type of object gives a Gimp-Python plugin the power of a C plugin, rather than just the power of a Script-Fu script. Tile objects are created with either the drawable.get_tile() or drawable.get_tile2() functions. In this section, I will refer to a generic tile object named tile.
All tile members are read only.
The number of bytes per pixel.
If there have been changes to the tile since it was last flushed.
The drawable that the tile is from.
The actual height of the tile.
The actual width of the tile.
The reference count of the tile. (this is independent of the Python object reference count).
Non zero if the tile is part of the shadow buffer.
Flush any changes in the tile. Note that the tile is automatically flushed when the Python object is deleted from memory.
Tile objects also act as a mapping, or sequence. You can access the pixels in the tile in one of two ways. You can either access them with a single number, which refers to its position in the tile (eg. tile[64] refers to the first pixel in the second row of a 64x64 pixel tile). The other way is with a tuple, representing the coordinates on the tile (eg. tile[0, 1] refers to the first pixel on the second row of the tile).
The type of these subscripts is a string of length tile.bpp. When you assign to a subscript, the dirty flag is automatically set on the tile, so you don't have to explicitly set the flag, or flush the tile.
Pixel region objects give an interface for low level operations to act on large regions of an image, instead of on small 64x64 pixel tiles. In this section I will refer to a generic pixel region called pr. For an example of a pixel region's use, please see the example plugin whirlpinch.py.
The drawable this pixel region is for.
The number of bytes per pixel for the drawable.
The rowstride for the pixel region.
The x coordinate of the top left hand corner.
The y coordinate of the top left hand corner.
The width of the pixel region.
The height of the pixel region.
Non zero if changes to the pixel region will be reflected in the drawable.
Non zero if the pixel region acts on the shadow tiles of the drawable.
resize the pixel region so that it operates on the the region with corner (x, y) with dimensions w x h.
The pixel region acts as a mapping. The index is a 2-tuple with components that are either integers or slices. The subscripts may be read and assigned to. The type of the subscripts is a string containing the binary data of the requested region. Here is a description of the possible operations:
Get/Set the pixel at (x,y)
Get/Set the row starting at (x1, y), width x2 - x1.
Get/Set the column starting at (x, y1), height y2 - y1.
Get/Set the rectangle starting at (x1, y1), width x2 - x1 and height y2 - y1.