view release on metacpan or  search on metacpan

pod/Prima/Image.pod  view on Meta::CPAN

C<ict::Optimized> ( by default ) and C<ict::Posterization>. This syntax 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 C<palette> property, C<colormap> can also be used.

=head2 Data access

The pixel values can be accessed in I<Prima::Drawable> style, via C<::pixel>
property. However, I<Prima::Image> introduces several helper functions on its own.

The C<::data> 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

  $lineSize = int(( $image->width * ( $image-> type & im::BPP) + 31) / 32) * 4;

or returned from the read-only property C<::lineSize>.

This is the line size for the data as lined up internally in memory, however
C<::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 C<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 C<::data>, it is not advisable unless the speed
does not matter. Standalone PDL package with help of L<PDL::PrimaImage>
package, and Prima-derived IPA package provide routines for data and image
analysis.  Also, L<Prima::Image::Magick> connects L<ImageMagick> with Prima.
I<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.

=head2 Standalone usage

Some of image functionality can be used standalone, with all other parts of the
toolkit being uninitialized. The functionality is limited to loading and
saving files, and reading and writing pixels (outside begin_paint only).
All other calls are ignored. Example:

   my $i = Prima::Image->new( size => [5,5]);
   $i->color(cl::Red);
   $i->bar(0,0,$i->size);
   $i->save('1.bmp');

This feature is useful in non-interactive programs, running in environments
with no GUI 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 GUI part by explicitly operating system-dependent options. To do
so, invoke

  use Prima::noX11;

in the beginning of your program. See L<Prima::noX11> for more.

Generally the standalone methods support all the OS-specific functions (i.e.
color, region, etc), plus the primitives and C<put_image> methods support
drawing using Porter-Duff operators from C<rop> property (i e rop::SrcOver and
above).

See individual methods and properties in L<API> that support standalone usage,
and how they differ from system-dependent implementation.

=head2 Prima::Icon

I<Prima::Icon> inherits all properties of I<Prima::Image>, and it also provides
a transparency mask of either 1 or 8 bits.  This mask can also be loaded
and saved into image files, if the format supports transparency information.

Similar to I<Prima::Image::data> property, I<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 C<::autoMasking> and
C<::maskColor>/C<::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 C<::rop>,
different from C<rop::CopyPut>, usually fail.

=head2 Layering

The term I<layered window> is borrowed from Windows world, and means a window
with transparency. In Prima, the property L<layered> is used to select this
functionality. The call to C<< $::application->get_system_value(sv::LayeredWidgets) >>

pod/Prima/Image.pod  view on Meta::CPAN

=item split

Returns two new I<Prima::Image> objects of same dimension.
Pixels in the first is are duplicated from C<::data> storage,
in the second - from C<::mask> storage.

=item translate matrix => [a,b,c,d,x,y]

Same as the C<translate> method from C<Prima::Image> except that it also
rotates the mask, and ignores C<fill> option - all new pixels are filled with
zeros.

=item ui_scale %OPTIONS

Same as C<ui_scale> from C<Prima::Image>, but with few exceptions: It tries to
use C<ist::Quadratic> only when the system supports ARGB layering. Otherwise,
falls back on C<ist::Box> scaling algorithm, and also limits the zoom factor to
integers (2x, 3x etc) only, because when displayed, the smooth-scaled color
plane will not match mask plane downgraded to 0/1 mask, and because box-scaling
with non-integer zooms looks ugly.

=back

=head2 Prima::DeviceBitmap methods

=over

=item dup

Returns a duplicate of the object, a newly created I<Prima::DeviceBitmap>, with all
information copied to it. Does not preserve graphical properties (color etc).

=item icon

Returns a newly created I<Prima::Icon> object instance, with the
pixel information copied from the object. If the bitmap is layered,
returns icons with maskType set to C<im::bpp8>.

=item image

Returns a newly created I<Prima::Image> object instance, with the
pixel information copied from the object.

=item get_handle

Returns a system handle for a system bitmap object.

=back

=head1 AUTHOR

Dmitry Karasik, E<lt>dmitry@karasik.eu.orgE<gt>.

=head1 SEE ALSO

L<Prima>, L<Prima::Drawable>, L<Prima::image-load>, L<Prima::codecs>.

L<PDL>, L<PDL::PrimaImage>, L<IPA>

L<ImageMagick>, L<Prima::Image::Magick>