use Prima qw(Application);
# create a new image from scratch
my $i = Prima::Image-> new(
width => 32,
height => 32,
type => im::BW, # same as im::bpp1 | im::GrayScale
);
# draw something
$i-> begin_paint;
$i-> color( cl::White);
$i-> ellipse( 5, 5, 10, 10);
$i-> end_paint;
# mangle
$i-> size( 64, 64);
# file operations
$i-> save('a.gif') or die "Error saving:$@\n";
$i-> load('a.gif') or die "Error loading:$@\n";
# draw on screen
$::application-> begin_paint;
# an image is drawn as specified by its palette
$::application-> set( color => cl::Red, backColor => cl::Green);
$::application-> put_image( 100, 100, $i);
# a bitmap is drawn as specified by destination device colors
$::application-> put_image( 200, 100, $i-> bitmap);
When an object enters the enabled state, it serves as a canvas, and all Prima::Drawable operations can be performed on it. When the object is back to the disabled state, the graphic information is stored into the object associated memory, in the pixel format, supported by the toolkit. This information can be visualized by using one of "Prima::Drawable::put_image" group methods. If the object enters the enabled state again, the graphic information is presented as an initial state of a bitmap.
It must be noted, that if an implicit conversion takes place after an object enters and before it leaves the enabled state, as it is with Prima::Image and Prima::Icon, the bitmap is converted to the system pixel format. During such conversion some information can be lost, due to down-sampling, and there is no way to preserve the information. This does not happen with Prima::DeviceBitmap.
Image objects can be drawn upon images, as well as on the screen and Prima::Widget objects. This operation is performed via one of Prima::Drawable::put_image group methods ( see Prima::Drawable), and can be called with the image object disregarding the paint state. The following code illustrates the dualism of an image object, where it can serve both as a drawing surface and as a drawing tool:
my $a = Prima::Image-> create( width => 100, height => 100, type => im::RGB);
$a-> begin_paint;
$a-> clear;
$a-> color( cl::Green);
$a-> fill_ellipse( 50, 50, 30, 30);
$a-> end_paint;
$a-> rop( rop::XorPut);
$a-> put_image( 10, 10, $a);
$::application-> begin_paint;
$::application-> put_image( 0, 0, $a);
$::application-> end_paint;
It must be noted, that "put_image", "stretch_image" and "put_image_indirect" are only painting methods that allow drawing on an image that is in its paint-disabled state. Moreover, in such context they only allow "Prima::Image" descendants to be passed as a source image object. This functionality does not imply that the image is internally switched to the paint-enabled state and back; the painting is performed without switching and without interference with the system's graphical layer.
Another special case is a 1-bit ( monochrome ) DeviceBitmap. When it is drawn upon a drawable with bit depth greater than 1, the drawable's color and backColor properties are used to reflect 1 and 0 bits, respectively. On a 1-bit drawable this does not happen, and the color properties are not used.
When an image is loaded, the old bitmap memory content is discarded, and the image attributes are changed accordingly to the loaded image. Along with these, an image palette is loaded, if available, and a pixel format is assigned, closest or identical to the pixel format in the image file.
Prima::Image can also be initialized from other formats, that it does not support, but can convert data from. Currently these are represented by a set of permutations of 32-bit RGBA format, and 24-bit BGR format. These formats can only be used in conjunction with "::data" property.
The conversions can be performed between any of the supported formats ( to do so, "::type" property is to be set-called ). An image of any of these formats can be drawn on the screen, but if the system can not accept the pixel format ( as it is with non-integer or complex formats ), the bitmap data are implicitly converted. The conversion does not change the data if the image is about to be drawn; the conversion is performed only when the image is about to be served as a drawing surface. If, by any reason, it is desired that the pixel format is not to be changed, the "::preserveType" property must be set to 1. It does not prevent the conversion, but it detects if the image was implicitly converted inside "end_paint()" call, and reverts it to its previous pixel format.
There are situations, when pixel format must be changed together while down-sampling the image. One of four down-sampling methods can be selected - normal, 8x8 ordered halftoning, error diffusion, and error diffusion combined with optimized palette. These can be set to the "::conversion" property with one of "ict::XXX" constants. When there is no information loss, "::conversion" property is not used.
Another special case of conversion is a conversion with a palette. The following calls,
$image-> type( im::bpp4); $image-> palette( $palette);
and
$image-> palette( $palette); $image-> type( im::bpp4);
produce different results, but none of these takes into account eventual palette remapping, because "::palette" property does not change bitmap pixel data, but overwrites palette information. A proper call syntax here would be
$image-> set(
palette => $palette,
type => im::bpp4,
);
This call produces also palette pixel mapping. This syntax is most powerful when conversion is set to "ict::Optimized" ( by default ). It not only allows remapping or downsampling to a predefined colors set, but also can be used to limit palette size to a particular number, without knowing the actual values of the final color palette. For example, for an 24-bit image,
$image-> set( type => im::bpp8, palette => 32);
call would calculate colors in the image, compress them to an optimized palette of 32 cells and finally converts to a 8-bit format.
Instead of "palette" property, "colormap" can also be used.
$lineSize = int(( $image->width * ( $image-> type & im::BPP) + 31) / 32) * 4;
or returned from the read-only property "::lineSize".
This is the line size for the data as lined up internally in memory, however "::data" should not necessarily should be aligned like this, and can be accompanied with a write-only flag 'lineSize' if pixels are aligned differently:
$image-> set( width => 1, height=> 2);
$image-> type( im::RGB);
$image-> set(
data => 'RGB----RGB----',
lineSize => 7,
);
print $image-> data, "\n";
output: RGB-RGB-
Internally, Prima contains images in memory so that the first scanline is the farthest away from the memory start; this is consistent with general Y-axis orientation in Prima drawable terminology, but might be inconvenient when importing data organized otherwise. Another write-only boolean flag "reverse" can be set to 1 so data then are treated as if the first scanline of the image is the closest to the start of data:
$image-> set( width => 1, height=> 2, type => im::RGB);
$image-> set(
data => 'RGB-123-',
reverse => 1,
);
print $image-> data, "\n";
output: RGB-123-
Although it is possible to perform all kinds of calculations and modification with the pixels, returned by "::data", it is not advisable unless the speed does not matter. Standalone PDL package with help of PDL::PrimaImage package, and Prima-derived IPA package provide routines for data and image analysis. Also, Prima::Image::Magick connects ImageMagick with Prima. Prima::Image itself provides only the simplest statistic information, namely: lowest and highest pixel values, pixel sum, sum of square pixels, mean, variance, and standard deviation.
use Prima::noX11;
in the beginning of your program. See Prima::noX11 for more.
Similar to Prima::Image::data property, Prima::Icon::mask property provides access to the binary mask data. The mask can be updated automatically, after an icon object was subject to painting, resizing, or other destructive change. The auxiliary properties "::autoMasking" and "::maskColor"/"::maskIndex" regulate mask update procedure. For example, if an icon was loaded with the color ( vs. bitmap ) transparency information, the binary mask will be generated anyway, but it will be also recorded that a particular color serves as a transparent indicator, so eventual conversions can rely on the color value, instead of the mask bitmap.
If an icon is drawn upon a graphic canvas, the image output is constrained to the mask. On raster displays it is typically simulated by a combination of and- and xor- operation modes, therefore attempts to put an icon with "::rop", different from "rop::CopyPut", usually fail.
See also "palette".
ict::None - no dithering ict::Halftone - 8x8 ordered halftone dithering ict::ErrorDiffusion - error diffusion dithering with static palette ict::Optimized - error diffusion dithering with optimized palette
As an example, if a 4x4 color image with every pixel set to RGB(32,32,32), converted to a 1-bit image, the following results occur:
ict::None:
[ 0 0 0 0 ]
[ 0 0 0 0 ]
[ 0 0 0 0 ]
[ 0 0 0 0 ]
ict::Halftone:
[ 0 0 0 0 ]
[ 0 0 1 0 ]
[ 0 0 0 0 ]
[ 1 0 0 0 ]
ict::ErrorDiffusion, ict::Ordered:
[ 0 0 1 0 ]
[ 0 0 0 1 ]
[ 0 0 0 0 ]
[ 0 0 0 0 ]
See also "colormap".
is::RangeLo - minimum pixel value is::RangeHi - maximum pixel value is::Mean - mean value is::Variance - variance is::StdDev - standard deviation is::Sum - sum of pixel values is::Sum2 - sum of squares of pixel values
The values are re-calculated on request and cached. On set-call VALUE is stored in the cache, and is returned on next get-call. The cached values are discarded every time the image data changes.
These values are also accessible via set of alias properties: "::rangeLo", "::rangeHi", "::mean", "::variance", "::stdDev", "::sum", "::sum2".
Bit-depth constants provide size of pixel is bits. Their actual value is same as number of bits, so "im::bpp1" value is 1, "im::bpp4" - 4, etc. The valid constants represent bit depths from 1 to 128:
im::bpp1 im::bpp4 im::bpp8 im::bpp16 im::bpp24 im::bpp32 im::bpp64 im::bpp128
The following values designate the pixel format category:
im::Color im::GrayScale im::RealNumber im::ComplexNumber im::TrigComplexNumber
Value of "im::Color" is 0, whereas other category constants represented by unique bit value, so combination of "im::RealNumber" and "im::ComplexNumber" is possible.
There also several mnemonic constants defined:
im::Mono - im::bpp1 im::BW - im::bpp1 | im::GrayScale im::16 - im::bpp4 im::Nibble - im::bpp4 im::256 - im::bpp8 im::RGB - im::bpp24 im::Triple - im::bpp24 im::Byte - gray 8-bit unsigned integer im::Short - gray 16-bit unsigned integer im::Long - gray 32-bit unsigned integer im::Float - float im::Double - double im::Complex - dual float im::DComplex - dual double im::TrigComplex - dual float im::TrigDComplex - dual double
Bit depths of float- and double- derived pixel formats depend on a platform.
The groups can be masked out with the mask values:
im::BPP - bit depth constants im::Category - category constants im::FMT - extra format constants
The extra formats are the pixel formats, not supported by "::type", but recognized within the combined set-call, like
$image-> set(
type => im::fmtBGRI,
data => 'BGR-BGR-',
);
The data, supplied with the extra image format specification will be converted to the closest supported format. Currently, the following extra pixel formats are recognized:
im::fmtBGR im::fmtRGBI im::fmtIRGB im::fmtBGRI im::fmtIBGR
am::None - no mask update performed am::MaskColor - mask update based on ::maskColor property am::MaskIndex - mask update based on ::maskIndex property am::Auto - mask update based on corner pixel values
The "::maskColor" color value is used as a transparent color if TYPE is "am::MaskColor". The transparency mask generation algorithm, turned on by "am::Auto" checks corner pixel values, assuming that majority of the corner pixels represents a transparent color. Once such color is found, the mask is generated as in "am::MaskColor" case.
"::maskIndex" is the same as "::maskColor", except that it points to a specific color index in the palette.
When image "::data" is stretched, "::mask" is stretched accordingly, disregarding the "::autoMasking" value.
See Prima::image-load for details.
This method can be called without object instance.
my $x = Prima::Image-> create(); die "$@" unless $x-> load( ... );
and
my $x = Prima::Image-> load( ... ); die "$@" unless $x;
See Prima::image-load for details.
NB! When loading from streams on win32, mind "binmode".
"rop::NoOper" type can be used for color masking.
Examples:
width => 4, height => 1, data => [ 1, 2, 3, 4] color => 10, backColor => 20, rop => rop::CopyPut rop2 => rop::CopyPut input: map(2) output: [ 20, 10, 20, 20 ] rop2 => rop::NoOper input: map(2) output: [ 1, 10, 3, 4 ]
$image-> resample( $image-> rangeLo, $image-> rangeHi, 0, 255);
Note that when saving to a stream, "codecID" must be explicitly given in %PARAMETERS.
See Prima::image-load for details.
NB! When saving to streams on win32, mind "binmode".
PDL, PDL::PrimaImage, IPA
ImageMagick, Prima::Image::Magick