.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "pod::Prima::Image 3" .TH pod::Prima::Image 3 "2009-02-24" "perl v5.14.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Prima::Image \- Bitmap routines .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& 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(\*(Aqa.gif\*(Aq) or die "Error saving:$@\en"; \& $i\-> load(\*(Aqa.gif\*(Aq) or die "Error loading:$@\en"; \& \& # 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); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fIPrima::Image\fR, \fIPrima::Icon\fR and \fIPrima::DeviceBitmap\fR are classes for bitmap handling, including file and graphic input and output. \fIPrima::Image\fR and \fIPrima::DeviceBitmap\fR are descendants of \fIPrima::Drawable\fR and represent bitmaps, stored in memory. \fIPrima::Icon\fR is a descendant of \fIPrima::Image\fR and contains a transparency mask along with the regular data. .SH "USAGE" .IX Header "USAGE" Images usually are represented as a memory area, where pixel data are stored row-wise. The Prima toolkit is no exception, however, it does not assume that the \s-1GUI\s0 system uses the same memory format. The implicit conversion routines are called when \fIPrima::Image\fR is about to be drawn onto the screen, for example. The conversions are not always efficient, therefore the \&\fIPrima::DeviceBitmap\fR class is introduced to represent a bitmap, stored in the system memory in the system pixel format. These two basic classes serve the different needs, but can be easily converted to each other, with \f(CW\*(C`image\*(C'\fR and \&\f(CW\*(C`bitmap\*(C'\fR methods. \fIPrima::Image\fR is a more general bitmap representation, capable of file and graphic input and output, plus it is supplied with number of conversion and scaling functions. The \fIPrima::DeviceBitmap\fR class has almost none of additional functionality, and is targeted to efficient graphic input and output. .SS "Graphic input and output" .IX Subsection "Graphic input and output" As descendants of \fIPrima::Drawable\fR, all \fIPrima::Image\fR, \fIPrima::Icon\fR and \&\fIPrima::DeviceBitmap\fR objects are subject to three-state painting mode \- normal ( disabled ), painting ( enabled ) and informational. \&\fIPrima::DeviceBitmap\fR is, however, exists only in the enabled state, and can not be switched to the other two. .PP When an object enters the enabled state, it serves as a canvas, and all \&\fIPrima::Drawable\fR 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 \f(CW\*(C`Prima::Drawable::put_image\*(C'\fR group methods. If the object enters the enabled state again, the graphic information is presented as an initial state of a bitmap. .PP 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 \fIPrima::Image\fR and \fIPrima::Icon\fR, 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 \&\fIPrima::DeviceBitmap\fR. .PP Image objects can be drawn upon images, as well as on the screen and Prima::Widget objects. This operation is performed via one of \&\fIPrima::Drawable::put_image\fR 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: .PP .Vb 11 \& 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; .Ve .PP It must be noted, that \f(CW\*(C`put_image\*(C'\fR, \f(CW\*(C`stretch_image\*(C'\fR and \f(CW\*(C`put_image_indirect\*(C'\fR are only painting methods that allow drawing on an image that is in its paint-disabled state. Moreover, in such context they only allow \f(CW\*(C`Prima::Image\*(C'\fR 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. .PP 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. .SS "File input and output" .IX Subsection "File input and output" Depending on the toolkit configuration, images can be read and written in different formats. This functionality in accessible via \f(CW\*(C`load()\*(C'\fR and \f(CW\*(C`save()\*(C'\fR methods. Prima::image\-load is dedicated to the description of loading and saving parameters, that can be passed to the methods, so they can handle different aspects of file format-specific options, such as multi-frame operations, auto conversion when a format does not support a particular pixel format etc. In this document, \f(CW\*(C`load()\*(C'\fR and \f(CW\*(C`save()\*(C'\fR methods are illustrated only in their basic, single-frame functionality. When called with no extra parameters, these methods fail only if a disk I/O error occurred or an unknown image format was used. .PP 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. .SS "Pixel formats" .IX Subsection "Pixel formats" \&\fIPrima::Image\fR supports a number of pixel formats, governed by the \f(CW\*(C`::type\*(C'\fR property. It is reflected by an integer value, a combination of \f(CW\*(C`im::XXX\*(C'\fR constants. The whole set of pixel formats is represented by colored formats, like, 16\-color, 256\-color and 16M\-color, and by gray-scale formats, mapped to C data types \- unsigned char, unsigned short, unsigned long, float and double. The gray-scale formats are further subdivided to real-number formats and complex-number format; the last ones are represented by two real values per pixel, containing the real and the imaginary values. .PP \&\fIPrima::Image\fR 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 \s-1RGBA\s0 format, and 24\-bit \s-1BGR\s0 format. These formats can only be used in conjunction with \f(CW\*(C`::data\*(C'\fR property. .PP The conversions can be performed between any of the supported formats ( to do so, \f(CW\*(C`::type\*(C'\fR 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 \f(CW\*(C`::preserveType\*(C'\fR property must be set to 1. It does not prevent the conversion, but it detects if the image was implicitly converted inside \f(CW\*(C`end_paint()\*(C'\fR call, and reverts it to its previous pixel format. .PP 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 \f(CW\*(C`::conversion\*(C'\fR property with one of \f(CW\*(C`ict::XXX\*(C'\fR constants. When there is no information loss, \f(CW\*(C`::conversion\*(C'\fR property is not used. .PP Another special case of conversion is a conversion with a palette. The following calls, .PP .Vb 2 \& $image\-> type( im::bpp4); \& $image\-> palette( $palette); .Ve .PP and .PP .Vb 2 \& $image\-> palette( $palette); \& $image\-> type( im::bpp4); .Ve .PP produce different results, but none of these takes into account eventual palette remapping, because \f(CW\*(C`::palette\*(C'\fR property does not change bitmap pixel data, but overwrites palette information. A proper call syntax here would be .PP .Vb 4 \& $image\-> set( \& palette => $palette, \& type => im::bpp4, \& ); .Ve .PP This call produces also palette pixel mapping. This syntax is most powerful when conversion is set to \f(CW\*(C`ict::Optimized\*(C'\fR ( 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, .PP .Vb 1 \& $image\-> set( type => im::bpp8, palette => 32); .Ve .PP call would calculate colors in the image, compress them to an optimized palette of 32 cells and finally converts to a 8\-bit format. .PP Instead of \f(CW\*(C`palette\*(C'\fR property, \f(CW\*(C`colormap\*(C'\fR can also be used. .SS "Data access" .IX Subsection "Data access" The pixel values can be accessed in \fIPrima::Drawable\fR style, via \f(CW\*(C`::pixel\*(C'\fR property. However, \fIPrima::Image\fR introduces several helper functions, for different aims. The \f(CW\*(C`::data\*(C'\fR property is used to set or retrieve a scalar representation of bitmap data. The data are expected to be lined up to a 'line size' margin ( 4\-byte boundary ), which is calculated as .PP .Vb 1 \& $lineSize = int(( $image\->width * ( $image\-> type & im::BPP) + 31) / 32) * 4; .Ve .PP or returned from the read-only property \f(CW\*(C`::lineSize\*(C'\fR. .PP This is the line size for the data as lined up internally in memory, however \&\f(CW\*(C`::data\*(C'\fR should not necessarily should be aligned like this, and can be accompanied with a write-only flag 'lineSize' if pixels are aligned differently: .PP .Vb 7 \& $image\-> set( width => 1, height=> 2); \& $image\-> type( im::RGB); \& $image\-> set( \& data => \*(AqRGB\-\-\-\-RGB\-\-\-\-\*(Aq, \& lineSize => 7, \& ); \& print $image\-> data, "\en"; \& \& output: RGB\-RGB\- .Ve .PP 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 \f(CW\*(C`reverse\*(C'\fR 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: .PP .Vb 6 \& $image\-> set( width => 1, height=> 2, type => im::RGB); \& $image\-> set( \& data => \*(AqRGB\-123\-\*(Aq, \& reverse => 1, \& ); \& print $image\-> data, "\en"; \& \& output: RGB\-123\- .Ve .PP Although it is possible to perform all kinds of calculations and modification with the pixels, returned by \f(CW\*(C`::data\*(C'\fR, it is not advisable unless the speed does not matter. Standalone \s-1PDL\s0 package with help of PDL::PrimaImage package, and Prima-derived \s-1IPA\s0 package provide routines for data and image analysis. Also, Prima::Image::Magick connects ImageMagick with Prima. \&\fIPrima::Image\fR itself provides only the simplest statistic information, namely: lowest and highest pixel values, pixel sum, sum of square pixels, mean, variance, and standard deviation. .SS "Standalone usage" .IX Subsection "Standalone usage" The image functionality can be used standalone, with all other parts of the toolkit being uninitialized. This is useful in non-interactive programs, running in evnironments with no \s-1GUI\s0 access, a cgi-script with no access to X11 display, for example. Normally, Prima fails to start in such situations, but can be told not to initialize its \s-1GUI\s0 part by explicitly operating system-dependent options. To do so, invoke .PP .Vb 1 \& use Prima::noX11; .Ve .PP in the beginning of your program. See Prima::noX11 for more. .SS "Prima::Icon" .IX Subsection "Prima::Icon" \&\fIPrima::Icon\fR inherits all properties of \fIPrima::Image\fR, and it also provides a 1\-bit depth transparency mask. This mask can also be loaded and saved into image files, if the format supports a transparency information. .PP Similar to \fIPrima::Image::data\fR property, \fIPrima::Icon::mask\fR 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 \f(CW\*(C`::autoMasking\*(C'\fR and \&\f(CW\*(C`::maskColor\*(C'\fR/\f(CW\*(C`::maskIndex\*(C'\fR 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. .PP 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 \f(CW\*(C`::rop\*(C'\fR, different from \f(CW\*(C`rop::CopyPut\*(C'\fR, usually fail. .SH "API" .IX Header "API" .SS "Prima::Image properties" .IX Subsection "Prima::Image properties" .ie n .IP "colormap @PALETTE" 4 .el .IP "colormap \f(CW@PALETTE\fR" 4 .IX Item "colormap @PALETTE" A color palette, used for representing 1, 4, and 8\-bit bitmaps, when an image object is to be visualized. \f(CW@PALETTE\fR contains individual colors component triplets, in \s-1RGB\s0 format. For example, black-and-white monochrome image may contain colormap as \f(CW\*(C`0,0xffffff\*(C'\fR. .Sp See also \f(CW\*(C`palette\*(C'\fR. .IP "conversion \s-1TYPE\s0" 4 .IX Item "conversion TYPE" Selects the type of dithering algorithm to be used for pixel down-sampling. \&\s-1TYPE\s0 is one of \f(CW\*(C`ict::XXX\*(C'\fR constants: .Sp .Vb 4 \& 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 .Ve .Sp As an example, if a 4x4 color image with every pixel set to \s-1RGB\s0(32,32,32), converted to a 1\-bit image, the following results occur: .Sp .Vb 5 \& 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 ] .Ve .IP "data \s-1SCALAR\s0" 4 .IX Item "data SCALAR" Provides access to the bitmap data. On get-call, returns all bitmap pixels, aligned to 4\-byte boundary. On set-call, stores the provided data with same alignment. The alignment can be altered by submitting 'lineSize' write-only flag to set call; the ordering of scan lines can be altered by setting \&'reverse' write-only flag ( see \*(L"Data access\*(R" ). .IP "height \s-1INTEGER\s0" 4 .IX Item "height INTEGER" Manages the vertical dimension of the image data. On set-call, the image data are changed accordingly to the new height, and depending on \f(CW\*(C`::vScaling\*(C'\fR property, the pixel values are either scaled or truncated. .IP "hScaling \s-1BOOLEAN\s0" 4 .IX Item "hScaling BOOLEAN" If 1, the bitmap data will be scaled when image changes its horizontal extent. If 0, the data will be stripped or padded with zeros. .IP "lineSize \s-1INTEGER\s0" 4 .IX Item "lineSize INTEGER" A read-only property, returning the length of an image row in bytes, as represented internally in memory. Data returned by \f(CW\*(C`::data\*(C'\fR property are aligned with \f(CW\*(C`::lineSize\*(C'\fR bytes per row, and setting \f(CW\*(C`::data\*(C'\fR expects data aligned with this value, unless \f(CW\*(C`lineSize\*(C'\fR is set together with \f(CW\*(C`data\*(C'\fR to indicate another alignment. See \*(L"Data access\*(R" for more. .IP "mean" 4 .IX Item "mean" Returns mean value of pixels. Mean value is \f(CW\*(C`::sum\*(C'\fR of pixel values, divided by number of pixels. .ie n .IP "palette [ @PALETTE ]" 4 .el .IP "palette [ \f(CW@PALETTE\fR ]" 4 .IX Item "palette [ @PALETTE ]" A color palette, used for representing 1, 4, and 8\-bit bitmaps, when an image object is to be visualized. \f(CW@PALETTE\fR contains individual color component triplets, in \s-1BGR\s0 format. For example, black-and-white monochrome image may contain palette as \f(CW\*(C`[0,0,0,255,255,255]\*(C'\fR. .Sp See also \f(CW\*(C`colormap\*(C'\fR. .IP "pixel ( X_OFFSET, Y_OFFSET ) \s-1PIXEL\s0" 4 .IX Item "pixel ( X_OFFSET, Y_OFFSET ) PIXEL" Provides per-pixel access to the image data when image object is in disabled paint state. Otherwise, same as \f(CW\*(C`Prima::Drawable::pixel\*(C'\fR. .IP "preserveType \s-1BOOLEAN\s0" 4 .IX Item "preserveType BOOLEAN" If 1, reverts the image type to its old value if an implicit conversion was called during \f(CW\*(C`end_paint()\*(C'\fR. .IP "rangeHi" 4 .IX Item "rangeHi" Returns maximum pixel value in the image data. .IP "rangeLo" 4 .IX Item "rangeLo" Returns minimum pixel value in the image data. .IP "size \s-1WIDTH\s0, \s-1HEIGHT\s0" 4 .IX Item "size WIDTH, HEIGHT" Manages dimensions of the image. On set-call, the image data are changed accordingly to the new dimensions, and depending on \f(CW\*(C`::vScaling\*(C'\fR and \f(CW\*(C`::hScaling\*(C'\fR properties, the pixel values are either scaled or truncated. .IP "stats ( \s-1INDEX\s0 ) \s-1VALUE\s0" 4 .IX Item "stats ( INDEX ) VALUE" Returns one of calculated values, that correspond to \s-1INDEX\s0, which is one of the following \f(CW\*(C`is::XXX\*(C'\fR constants: .Sp .Vb 7 \& 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 .Ve .Sp The values are re-calculated on request and cached. On set-call \s-1VALUE\s0 is stored in the cache, and is returned on next get-call. The cached values are discarded every time the image data changes. .Sp These values are also accessible via set of alias properties: \f(CW\*(C`::rangeLo\*(C'\fR, \f(CW\*(C`::rangeHi\*(C'\fR, \f(CW\*(C`::mean\*(C'\fR, \f(CW\*(C`::variance\*(C'\fR, \&\f(CW\*(C`::stdDev\*(C'\fR, \f(CW\*(C`::sum\*(C'\fR, \f(CW\*(C`::sum2\*(C'\fR. .IP "stdDev" 4 .IX Item "stdDev" Returns standard deviation of the image data. Standard deviation is the square root of \f(CW\*(C`::variance\*(C'\fR. .IP "sum" 4 .IX Item "sum" Returns sum of pixel values of the image data .IP "sum2" 4 .IX Item "sum2" Returns sum of squares of pixel values of the image data .IP "type \s-1TYPE\s0" 4 .IX Item "type TYPE" Governs the image pixel format type. \s-1TYPE\s0 is a combination of \f(CW\*(C`im::XXX\*(C'\fR constants. The constants are collected in groups: .Sp Bit-depth constants provide size of pixel is bits. Their actual value is same as number of bits, so \f(CW\*(C`im::bpp1\*(C'\fR value is 1, \&\f(CW\*(C`im::bpp4\*(C'\fR \- 4, etc. The valid constants represent bit depths from 1 to 128: .Sp .Vb 8 \& im::bpp1 \& im::bpp4 \& im::bpp8 \& im::bpp16 \& im::bpp24 \& im::bpp32 \& im::bpp64 \& im::bpp128 .Ve .Sp The following values designate the pixel format category: .Sp .Vb 5 \& im::Color \& im::GrayScale \& im::RealNumber \& im::ComplexNumber \& im::TrigComplexNumber .Ve .Sp Value of \f(CW\*(C`im::Color\*(C'\fR is 0, whereas other category constants represented by unique bit value, so combination of \&\f(CW\*(C`im::RealNumber\*(C'\fR and \f(CW\*(C`im::ComplexNumber\*(C'\fR is possible. .Sp There also several mnemonic constants defined: .Sp .Vb 10 \& 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 .Ve .Sp Bit depths of float\- and double\- derived pixel formats depend on a platform. .Sp The groups can be masked out with the mask values: .Sp .Vb 3 \& im::BPP \- bit depth constants \& im::Category \- category constants \& im::FMT \- extra format constants .Ve .Sp The extra formats are the pixel formats, not supported by \f(CW\*(C`::type\*(C'\fR, but recognized within the combined set-call, like .Sp .Vb 4 \& $image\-> set( \& type => im::fmtBGRI, \& data => \*(AqBGR\-BGR\-\*(Aq, \& ); .Ve .Sp 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: .Sp .Vb 5 \& im::fmtBGR \& im::fmtRGBI \& im::fmtIRGB \& im::fmtBGRI \& im::fmtIBGR .Ve .IP "variance" 4 .IX Item "variance" Returns variance of pixel values of the image data. Variance is \f(CW\*(C`::sum2\*(C'\fR, divided by number of pixels minus square of \f(CW\*(C`::sum\*(C'\fR of pixel values. .IP "vScaling \s-1BOOLEAN\s0" 4 .IX Item "vScaling BOOLEAN" If 1, the bitmap data will be scaled when image changes its vertical extent. If 0, the data will be stripped or padded with zeros. .IP "width \s-1INTEGER\s0" 4 .IX Item "width INTEGER" Manages the horizontal dimension of the image data. On set-call, the image data are changed accordingly to the new width, and depending on \f(CW\*(C`::hScaling\*(C'\fR property, the pixel values are either scaled or truncated. .SS "Prima::Icon properties" .IX Subsection "Prima::Icon properties" .IP "autoMasking \s-1TYPE\s0" 4 .IX Item "autoMasking TYPE" Selects whether the mask information should be updated automatically with \f(CW\*(C`::data\*(C'\fR change or not. Every \&\f(CW\*(C`::data\*(C'\fR change is mirrored in \f(CW\*(C`::mask\*(C'\fR, using \s-1TYPE\s0, one of \f(CW\*(C`am::XXX\*(C'\fR constants: .Sp .Vb 4 \& 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 .Ve .Sp The \f(CW\*(C`::maskColor\*(C'\fR color value is used as a transparent color if \&\s-1TYPE\s0 is \f(CW\*(C`am::MaskColor\*(C'\fR. The transparency mask generation algorithm, turned on by \f(CW\*(C`am::Auto\*(C'\fR 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 \f(CW\*(C`am::MaskColor\*(C'\fR case. .Sp \&\f(CW\*(C`::maskIndex\*(C'\fR is the same as \f(CW\*(C`::maskColor\*(C'\fR, except that it points to a specific color index in the palette. .Sp When image \f(CW\*(C`::data\*(C'\fR is stretched, \f(CW\*(C`::mask\*(C'\fR is stretched accordingly, disregarding the \f(CW\*(C`::autoMasking\*(C'\fR value. .IP "mask \s-1SCALAR\s0" 4 .IX Item "mask SCALAR" Provides access to the transparency bitmap. On get-call, returns all bitmap pixels, aligned to 4\-byte boundary in 1\-bit format. On set-call, stores the provided transparency data with same alignment. .IP "maskColor \s-1COLOR\s0" 4 .IX Item "maskColor COLOR" When \f(CW\*(C`::autoMasking\*(C'\fR set to \f(CW\*(C`am::MaskColor\*(C'\fR, \s-1COLOR\s0 is used as a transparency value. .IP "maskIndex \s-1INDEX\s0" 4 .IX Item "maskIndex INDEX" When \f(CW\*(C`::autoMasking\*(C'\fR set to \f(CW\*(C`am::MaskIndex\*(C'\fR, INDEXth color in teh current palette is used as a transparency value. .SS "Prima::DeviceBitmap properties" .IX Subsection "Prima::DeviceBitmap properties" .IP "monochrome \s-1BOOLEAN\s0" 4 .IX Item "monochrome BOOLEAN" A read-only property, that can only be set during creation, reflects whether the system bitmap is black-and-white 1\-bit (monochrome) or not. The color depth of a bitmap can be read via \f(CW\*(C`get_bpp()\*(C'\fR method; monochrome bitmaps always have bit depth of 1. .SS "Prima::Image methods" .IX Subsection "Prima::Image methods" .IP "bitmap" 4 .IX Item "bitmap" Returns newly created \fIPrima::DeviceBitmap\fR instance, with the image dimensions and with the bitmap pixel values copied to. .IP "codecs" 4 .IX Item "codecs" Returns array of hashes, each describing the supported image format. If the array is empty, the toolkit was set up so it can not load and save images. .Sp See Prima::image\-load for details. .Sp This method can be called without object instance. .IP "dup" 4 .IX Item "dup" Returns a duplicate of the object, a newly created \fIPrima::Image\fR, with all information copied to it. .IP "extract X_OFFSET, Y_OFFSET, \s-1WIDTH\s0, \s-1HEIGHT\s0" 4 .IX Item "extract X_OFFSET, Y_OFFSET, WIDTH, HEIGHT" Returns a newly created image object with \s-1WIDTH\s0 and \s-1HEIGHT\s0 dimensions, initialized with pixel data from X_OFFSET and Y_OFFSET in the bitmap. .IP "get_bpp" 4 .IX Item "get_bpp" Returns the bit depth of the pixel format. Same as \f(CW\*(C`::type & im::BPP\*(C'\fR. .IP "get_handle" 4 .IX Item "get_handle" Returns a system handle for an image object. .ie n .IP "load (\s-1FILENAME\s0 or \s-1FILEGLOB\s0) [ %PARAMETERS ]" 4 .el .IP "load (\s-1FILENAME\s0 or \s-1FILEGLOB\s0) [ \f(CW%PARAMETERS\fR ]" 4 .IX Item "load (FILENAME or FILEGLOB) [ %PARAMETERS ]" Loads image from file \s-1FILENAME\s0 or stream \s-1FILEGLOB\s0 into an object, and returns the success flag. The semantics of \f(CW\*(C`load()\*(C'\fR is extensive, and can be influenced by \&\s-1PARAMETERS\s0 hash. \f(CW\*(C`load()\*(C'\fR can be called either in a context of an existing object, then a boolean success flag is returned, or in a class context, then a newly created object ( or \f(CW\*(C`undef\*(C'\fR ) is returned. If an error occurs, \f(CW$@\fR variable contains the error description string. These two invocation semantics are equivalent: .Sp .Vb 2 \& my $x = Prima::Image\-> create(); \& die "$@" unless $x\-> load( ... ); .Ve .Sp and .Sp .Vb 2 \& my $x = Prima::Image\-> load( ... ); \& die "$@" unless $x; .Ve .Sp See Prima::image\-load for details. .Sp \&\s-1NB\s0! When loading from streams on win32, mind \f(CW\*(C`binmode\*(C'\fR. .IP "map \s-1COLOR\s0" 4 .IX Item "map COLOR" Performs iterative mapping of bitmap pixels, setting every pixel to \f(CW\*(C`::color\*(C'\fR property with respect to \f(CW\*(C`::rop\*(C'\fR type if a pixel equals to \s-1COLOR\s0, and to \f(CW\*(C`::backColor\*(C'\fR property with respect to \f(CW\*(C`::rop2\*(C'\fR type otherwise. .Sp \&\f(CW\*(C`rop::NoOper\*(C'\fR type can be used for color masking. .Sp Examples: .Sp .Vb 2 \& 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 ] .Ve .IP "resample \s-1SRC_LOW\s0, \s-1SRC_HIGH\s0, \s-1DEST_LOW\s0, \s-1DEST_HIGH\s0" 4 .IX Item "resample SRC_LOW, SRC_HIGH, DEST_LOW, DEST_HIGH" Performs linear scaling of gray pixel values from range (\s-1SRC_LOW\s0 \- \s-1SRC_HIGH\s0) to range (\s-1DEST_LOW\s0 \- \s-1DEST_HIGH\s0). Can be used to visualize gray non\-8 bit pixel values, by the code: .Sp .Vb 1 \& $image\-> resample( $image\-> rangeLo, $image\-> rangeHi, 0, 255); .Ve .ie n .IP "save (\s-1FILENAME\s0 or \s-1FILEGLOB\s0), [ %PARAMETERS ]" 4 .el .IP "save (\s-1FILENAME\s0 or \s-1FILEGLOB\s0), [ \f(CW%PARAMETERS\fR ]" 4 .IX Item "save (FILENAME or FILEGLOB), [ %PARAMETERS ]" Stores image data into image file \s-1FILENAME\s0 or stream \s-1FILEGLOB\s0, and returns the success flag. The semantics of \f(CW\*(C`save()\*(C'\fR is extensive, and can be influenced by \&\s-1PARAMETERS\s0 hash. If error occurs, \f(CW$@\fR variable contains error description string. .Sp Note that when saving to a stream, \f(CW\*(C`codecID\*(C'\fR must be explicitly given in \f(CW%PARAMETERS\fR. .Sp See Prima::image\-load for details. .Sp \&\s-1NB\s0! When saving to streams on win32, mind \f(CW\*(C`binmode\*(C'\fR. .SS "Prima::Image events" .IX Subsection "Prima::Image events" \&\f(CW\*(C`Prima::Image\*(C'\fR\-specific events occur only from inside load call, to report image loading progress. Not all codecs (currently \s-1JPEG\s0,PNG,TIFF only) are able to report the progress to the caller. See \*(L"Loading with progress indicator\*(R" in Prima::image\-load for details, \*(L"watch_load_progress\*(R" in Prima::ImageViewer and \&\*(L"load\*(R" in Prima::ImageDialog for suggested use. .IP "HeaderReady" 4 .IX Item "HeaderReady" Called whenever image header is read, and image dimensions and pixel type is changed accordingly to accomodate image data. .IP "DataReady X, Y, \s-1WIDTH\s0, \s-1HEIGHT\s0" 4 .IX Item "DataReady X, Y, WIDTH, HEIGHT" Called whenever image data that cover area designated by X,Y,WIDTH,HEIGHT is acquired. Use \f(CW\*(C`load\*(C'\fR option \f(CW\*(C`eventDelay\*(C'\fR to limit the rate of \f(CW\*(C`DataReady\*(C'\fR event. .SS "Prima::Icon methods" .IX Subsection "Prima::Icon methods" .IP "split" 4 .IX Item "split" Returns two new \fIPrima::Image\fR objects of same dimension. Pixels in the first is are duplicated from \f(CW\*(C`::data\*(C'\fR storage, in the second \- from \f(CW\*(C`::mask\*(C'\fR storage. .IP "combine \s-1DATA\s0, \s-1MASK\s0" 4 .IX Item "combine DATA, MASK" Copies information from \s-1DATA\s0 and \s-1MASK\s0 images into \f(CW\*(C`::data\*(C'\fR and \f(CW\*(C`::mask\*(C'\fR property. \s-1DATA\s0 and \s-1MASK\s0 are expected to be images of same dimension. .SS "Prima::DeviceBitmap methods" .IX Subsection "Prima::DeviceBitmap methods" .IP "icon" 4 .IX Item "icon" Returns a newly created \fIPrima::Icon\fR object instance, with the pixel information copied from the object. .IP "image" 4 .IX Item "image" Returns a newly created \fIPrima::Image\fR object instance, with the pixel information copied from the object. .IP "get_handle" 4 .IX Item "get_handle" Returns a system handle for a system bitmap object. .SH "AUTHOR" .IX Header "AUTHOR" Dmitry Karasik, . .SH "SEE ALSO" .IX Header "SEE ALSO" Prima, Prima::Drawable, Prima::image\-load, Prima::codecs. .PP \&\s-1PDL\s0, PDL::PrimaImage, \s-1IPA\s0 .PP ImageMagick, Prima::Image::Magick