Gimp Python Documentation
Prev |  | Next

# Gimp Objects

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).

## Image Object

This is the object that represents an open image. In this section, image represents a generic image object.

### Image Members

image.active_channel

  This is the active channel of the image. You can also assign to this member, or None if there is no active channel.

image.active_layer

  This is the active layer of the image. You can also assign to this member, or None if there is no active layer.

image.base_type

  This is the type of the image (eg RGB, INDEXED).

image.channels

  This is a list of the channels of the image. Altering this list has no effect, and you can not assign to this member.

image.cmap

  This is the colour map for the image.

image.filename

  This is the filename for the image. A file load or save handler might assign to this.

image.height

  This is the height of the image. You can't assign to this member.

image.floating_selection

  The floating selection layer, or None if there is no floating selection.

image.layers

  This is a list of the layers of the image.

image.selection

  The selection mask for the image.

image.width

  This is the width of the image. You can't assign to this member.

### Image Methods

image.`add_channel`(channel, position)

  Adds channel to image in position position.

image.`add_layer`(layer, position)

  Adds layer to image in position position.

image.`add_layer_mask`(layer, mask)

  Adds the mask mask to layer.

image.`clean_all`()

  Unsets the dirty flag on the image.

image.`disable_undo`()

  Disables undo for image.

image.`enable_undo`()

  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.

image.`flatten`()

  Returns the resulting layer after merging all the visible layers, discarding non visible ones and stripping the alpha channel.

image.`get_component_active`(component)

  Returns true if component (one of the *_CHANNEL constants) is active.

image.`get_component_visible`(component)

  Returns true if component is visible.

image.`set_component_active`(component, active)

  Sets the activeness of component.

image.`set_component_visible`(component, active)

  Sets the visibility of component.

image.`lower_channel`(channel)

  Lowers channel.

image.`lower_layer`(layer)

  Lowers layer.

image.`merge_visible_layers`(type)

  Merges the visible layers of image using the given merge type.

image.`pick_correlate_layer`(x, y)

  Returns the layer that is visible at the point (x,y), or None if no layer matches.

image.`raise_channel`(channel)

  Raises channel.

image.`raise_layer`(layer)

  Raises layer.

image.`remove_channel`(channel)

  Removes channel from image.

image.`remove_layer`(layer)

  Removes layer from image.

image.`remove_layer_mask`(layer, mode)

  Removes the mask from layer, with the given mode (either APPLY or DISCARD).

image.`resize`(width, height, x, y)

  Resizes the image to size (width, height) and places the old contents at position (x,y).

## Channel Objects

These objects represent a Gimp Image's colour channels. In this section, channel will refer to a generic channel object.

### Channel Members

channel.colour or channel.color

  The colour of the channel.

channel.height

  The height of the channel.

channel.width

  The width of the channel.

channel.image

  The image the channel belongs to, or None if it isn't attached yet.

channel.layer

  The channel's layer (??) or None if one doesn't exist.

channel.layer_mask

  Non zero if the channel is a layer mask.

channel.name

  The name of the channel.

channel.opacity

  The opacity of the channel.

channel.show_masked

  The show_masked value of the channel.

channel.visible

  Non-zero if the channel is visible.

### Channel Methods

channel.`copy`()

  returns a copy of the channel.

## Layer Objects

Layer objects represent the layers of a Gimp image. In this section I will refer to a generic layer called layer.

### Layer Members

layer.apply_mask

  The apply mask setting. (non zero if the layer mask is being composited with the layer's alpha channel).

layer.bpp

  The number of bytes per pixel.

layer.edit_mask

  The edit mask setting. (non zero if the mask is active, rather than the layer).

layer.height

  The height of the layer.

layer.image

  The image the layer is part of, or None if the layer isn't attached.

layer.is_floating_selection

  Non zero if this layer is the image's floating selection.

layer.mask

  The layer's mask, or None if it doesn't have one.

layer.mode

  The mode of the layer.

layer.name

  The name of the layer.

layer.opacity

  The opacity of the layer.

layer.preserve_transparency

  The layer's preserve transparency setting.

### Layer Methods

layer.`add_alpha`()

  Adds an alpha component to the layer.

layer.`copy`([alpha])

  Creates a copy of the layer, optionally with an alpha layer.

layer.`create_mask`(type)

  Creates a layer mask of type type.

layer.`resize`(w, h, x, y)

  Resizes the layer to (w, h), positioning the original contents at (x,y).

layer.`scale`(h, w, origin)

  Scales the layer to (w, h), using the specified origin (local or image).

layer.`set_offsets`(x, y)

  Sets the offset of the layer, relative to the image's origin

layer.`translate`(x, y)

  Moves the layer to (x, y) relative to its current position.

## Drawable Objects

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.

### Drawable Members

drawable.bpp

  The number of bytes per pixel.

drawable.is_colour or drawable.is_color or drawable.is_rgb

  Non zero if the drawable is colour.

drawable.is_grey or drawable.is_gray

  Non zero if the drawable is greyscale.

drawable.has_alpha

  Non zero if the drawable has an alpha channel.

drawable.height

  The height of the drawable.

drawable.image

  The image the drawable belongs to.

drawable.is_indexed

  Non zero if the drawable uses an indexed colour scheme.

drawable.mask_bounds

  The bounds of the drawable's selection.

drawable.name

  The name of the drawable.

drawable.offsets

  The offset of the top left hand corner of the drawable.

drawable.type

  The type of the drawable.

drawable.visible

  Non zero if the drawable is visible.

drawable.width

  The width of the drawable.

### Drawable Methods

drawable.`fill`(fill_type)

  Fills the drawable with given fill_type (one of the *_FILL constants).

drawable.`flush`()

  Flush the changes to the drawable.

drawable.`get_pixel_rgn`(x, y, w, h, [dirty, [shadow])

  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.

drawable.`get_tile`(shadow, row, col)

  Get a tile at (row, col). Either on or off the shadow buffer.

drawable.`get_tile2`(shadow, x, y)

  Get the tile that contains the pixel (x, y).

drawable.`merge_shadow`()

  Merge the shadow buffer back into the drawable.

drawable.`update`(x, y, w, h)

  Update the given portion of the drawable.

## Tile Objects

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.

### Tile Members

All tile members are read only.

tile.bpp

  The number of bytes per pixel.

tile.dirty

  If there have been changes to the tile since it was last flushed.

tile.drawable

  The drawable that the tile is from.

tile.eheight

  The actual height of the tile.

tile.ewidth

  The actual width of the tile.

tile.ref_count

  The reference count of the tile. (this is independent of the Python object reference count).

tile.shadow

  Non zero if the tile is part of the shadow buffer.

### Tile Methods

tile.`flush`()

  Flush any changes in the tile. Note that the tile is automatically flushed when the Python object is deleted from memory.

### Tile Mapping Behaviour

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 Regions

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`.

### Pixel Region Members

pr.drawable

  The drawable this pixel region is for.

pr.bpp

  The number of bytes per pixel for the drawable.

pr.rowstride

  The rowstride for the pixel region.

pr.x

  The x coordinate of the top left hand corner.

pr.y

  The y coordinate of the top left hand corner.

pr.w

  The width of the pixel region.

pr.h

  The height of the pixel region.

pr.dirty

  Non zero if changes to the pixel region will be reflected in the drawable.

pr.shadow

  Non zero if the pixel region acts on the shadow tiles of the drawable.

### Pixel Region Methods

pr.`resize`(x, y, w, h)

  resize the pixel region so that it operates on the the region with corner (x, y) with dimensions w x h.

### Pixel Region Mapping Behaviour

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 posible operations:

pr[x, y]

  Get/Set the pixel at (x,y)

pr[x1:x2, y]

  Get/Set the row starting at (x1, y), width x2 - x1.

pr[x, y1:y2]

  Get/Set the column starting at (x, y1), height y2 - y1.

pr[x1:x2, y1:y1]

  Get/Set the rectangle starting at (x1, y1), width x2 - x1 and height y2 - y1.

Prev | Home | Next
Gimp Module Procedures |  | Support Modules