Pixel(3) User Contributed Perl Documentation Pixel(3)NAMEGimp::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 ALSOperl(1), Gimp(1).
perl v5.18.1 2000-08-24 Pixel(3)