---
name: "Gimp::Pixel"
section: "3pm"
platform: "linux"
package: "libgimp-perl"
version: "2.0.dfsg+2.2pre1.dfsg-5"
release: "Debian 5.0 (Lenny)"
platforms: ["linux"]
url: "https://new.carta.tech/Gimp::Pixel"
---

# Gimp::Pixel(3pm)

how to operate on raw pixels. \*\*\*WARNING\*\*\* this manpage is no longer up-to-date. See "examples/map\_to\_gradient" for a simple raw-pixel-manipulating plug-in. If you bug me enough I'll rewrite this document.

## NAME

Gimp::Pixel - how to operate on raw pixels.

\*\*\*WARNING\*\*\* this manpage is no longer up-to-date. See `"examples/map_to_gradient"` for a simple raw-pixel-manipulating plug-in. If you bug me enough I'll rewrite this document.

## SYNOPSIS

```
  use Gimp;
  use PDL;              # to make sensible things with the pixels
  # Gimp::GimpDrawable  - The GimpDrawable structure
  # Gimp::Tile          - The Tile family of functions.
  # Gimp::PixelRgn      - The PixelRgn family of functions.
```

## DESCRIPTION

You can access the pixels in a drawable through tiles or pixel regions. This manpage explains how this is done in perl. All classes (Gimp::GimpDrawable, `"Gimp::Tile"`, `"Gimp::PixelRgn"`) are available with and without the `"Gimp::"` prefix.

## GDRAWABLES

Well, you know drawables? (also known as PARAM\_DRAWABLE or Gimp::Drawable)? In the Gimp, drawables are things you can draw on: layers, channels or whole images. While most functions named `"gimp_drawable_something"` operate on `"drawable_ID"`s, some functions (notably the ones operating on raw pixel data!) need a `"GimpDrawable"` instead. Every drawable has a corresponding `"GimpDrawable"`, you can get it with the `"gimp_drawable_get"` function:

```
 my $gdrawable = $drawable->get;
```

When the `$gdrawable` is destroyed, it is automatically flushed & detached, so you don't need to do this yourself.

## TILES

Tiles are the basic building blocks of all drawables. Each drawable consists of a "grid" of tiles, each tile having the same size. The size of a tile is always the same (it's hardcoded in your Gimp program).

The `"gimp_tile_width"` and `"gimp_tile_height"` functions return the current width/height of a tile (at the moment, this is 64x64).

How do I get a tile? First, you have to grab a GimpDrawable structure. You can get one from any drawable, by calling the `"get"` function:

```
 my $gdrawable = $drawable->get;
```

in a sense, \<$gdrawable\> contains all tiles. Changes you make to them might not be reflected in the image until you destroy this variable. (Thats the reason I used "my" int he above example. Once `$gdrawable` gets out of scope, the drawable in the gimp automatically gets updated).

To get access to a tile, you have to call `"get_tile"` or `"get_tile2"`. `"get_tile"` expects row/column numbers of the tile, while `"get_tile2"` expects pixel coordinates and will return the tile that pixel is in:

```
 my $tile = $gdrawable->get_tile2(1,75,60);
```

The `"data"` method returns and sets the raw pixel data.

```
 $piddle = $tile->data; # get the tile data as a piddle
 $piddle *= 0.5;        # do sth. with the pixels
 $tile->data($piddle);  # and modify the tile
```

## PIXELREGIONS

`"PixelRgn"`s are rectangular parts of a drawable. You can access single pixels, rows, columns and rectangles within these regions. Don't expect me to explain everything now, I don't understand the mechanism too well myself..

How do I create a pixel region? First, you have to grab a GimpDrawable structure. You can get one from any drawable, by calling the `"get"` function:

```
 my $gdrawable = $drawable->get;
```

Now you can create as many PixelRgn structures as you want from the `"GimpDrawable"`:

```
 my $region = new PixelRgn($gdrawable,0,0,50,30,1,0);   # with "new"
 my $region = $gdrawable->pixel_rgn(0,0,50,30,1,0);     # or from a drawable
```

which method you choose is purely a question of style...

The following functions return packed pixel data (see Gimp::PDL for an easier way to manipulate on image data):

```
 $piddle = $region->get_pixel(45,60);           # return the pixel at (45|60)
 $piddle = $region->get_row(45,60,10);          # return ten horizontal pixels
 $piddle = $region->get_col(45,60,10);          # same but vertically
 $piddle = $region->get_rect(45,60,10,12);      # a 10x12 rectangle
```

To modify pixels, the dirty bit of the region must be set (I believe, but I don't see the reason what the dirty bit in a region is for so I might be wrong), and you can write pixel data to the region with the following functions, each one corresponding to a get-function:

```
 $region->set_pixel($piddle,45,60);             # set pixel at (45|60)
 $region->set_row($piddle,45,60);               # set a row
 $region->set_col($piddle,45,60);               # set a column
 $region->set_rect($piddle,45,60);              # set a whole rectangle
```

Please note that (unlike the C functions they call), the size arguments (width and/or height) are missing, they can be calculated from the piddle.

## AUTHOR

Marc Lehmann \<pcg@goof.com\>

## SEE ALSO

[*perl*(1)](/perl/1.md), *Gimp*(1).