view release on metacpan or  search on metacpan

lib/Image/Base.pm  view on Meta::CPAN

The attributes for C<new()>, C<get()> and C<set()> are up to the subclasses,
but the common settings, when available, include

=over

=item C<-width> (integers)

=item C<-height>

The size of the image.  These might be create-only with C<new()> taking a
size which is then fixed.  If the image can be resized then C<set()> of
C<-width> and/or C<-height> does a resize.

=item C<-file> (string)

Set by C<new()> reading a file, or C<load()> or C<save()> if passed a
filename, or just by C<set()> ready for a future C<load()> or C<save()>.

=item C<-file_format> (string)

The name of the file format loaded or to save as.  This is generally an
abbreviation like "XPM", set by C<load()> or C<set()> and then used by
C<save()>.

=item C<-hotx> (integers, or maybe -1 or maybe C<undef>)

=item C<-hoty>

The coordinates of the "hotspot" position.  Images which can be a mouse
cursor or similar have a position within the image which is the active pixel
for clicking etc.  For example XPM and CUR (cursor form of ICO) formats have
hotspot positions.

=item C<-zlib_compression> (integer -1 to 9, or C<undef>)

The compression level for images which use Zlib, such as PNG.  0 is no
compression, 9 is maximum compression.  -1 is the Zlib compiled-in default
(usually 6).  C<undef> means no setting to use an image library default if
it has one, or the Zlib default.

For reference, PNG format doesn't record the compression level used in the
file, so for it C<-zlib_compression> can be C<set()> to control a C<save()>,
but generally won't read back from a C<load()>.

=item C<-quality_percent> (integer 0 to 100, or C<undef>)

The quality level for saving lossy image formats such as JPEG.  0 is the
worst quality, 100 is the best.  Lower quality should mean a smaller file,
but fuzzier.  C<undef> means no setting which gives some image library
default.

=back

=head1 ALGORITHMS

=head2 Lines

Sloping lines are drawn by a basic Bressenham line drawing algorithm with
integer-only calculations.  It ends up drawing the same set of pixels no
matter which way around the two endpoints are passed.

Would there be merit in rounding odd numbers of pixels according to which
way around line ends are given?  Eg. a line 0,0 to 4,1 might do 2 pixels on
y=0 and 3 on y=1, but 4,1 to 0,0 the other way around.  Or better to have
consistency either way around?  For reference, in the X11 drawing model the
order of the ends doesn't matter for "wide" lines, but for
implementation-dependent "thin" lines it's only encouraged, not required.

=head2 Ellipses

Ellipses are drawn with the midpoint ellipse algorithm.  This algorithm
chooses between points x,y or x,y-1 according to whether the position
x,y-0.5 is inside or outside the ellipse (and similarly x+0.5,y on the
vertical parts).

The current ellipse code ends up with 0.5's in the values, which means
floating point, but is still exact since binary fractions like 0.5 are
exactly representable.  Some rearrangement and factors of 2 could make it
all-integer.  The "discriminator" in the calculation may exceed 53-bits of
float mantissa at around 160,000 pixels wide or high.  That might affect the
accuracy of the pixels chosen, but should be no worse than that.

=head2 Diamond

The current code draws a diamond with the Bressenham line algorithm along
each side.  Just one line is calculated and is then replicated to the four
sides, which ensures the result is symmetric.  Rounding in the line (when
width not a multiple or height, or vice versa) is biased towards making the
pointier vertices narrower.  That tends to look better, especially when the
diamond is small.

=head2 Image Libraries

The subclasses like GD or PNGwriter which are front-ends to other drawing
libraries don't necessarily use these base algorithms, but can be expected
to something sensible within the given line endpoints or ellipse bounding
box.  (Among the image libraries it's surprising how variable the quality of
the ellipse drawing is.)

=head1 SEE ALSO

L<Image::Xpm>,
L<Image::Xbm>,
L<Image::Pbm>,
L<Image::Base::GD>,
L<Image::Base::Imager>,
L<Image::Base::Imlib2>,
L<Image::Base::Magick>,
L<Image::Base::PNGwriter>,
L<Image::Base::SVG>,
L<Image::Base::SVGout>,
L<Image::Base::Text>,
L<Image::Base::Multiplex>

L<Image::Base::Gtk2::Gdk::Drawable>,
L<Image::Base::Gtk2::Gdk::Image>,
L<Image::Base::Gtk2::Gdk::Pixbuf>,
L<Image::Base::Gtk2::Gdk::Pixmap>,
L<Image::Base::Gtk2::Gdk::Window>

L<Image::Base::Prima::Drawable>,
L<Image::Base::Prima::Image>

L<Image::Base::Tk::Canvas>,
L<Image::Base::Tk::Photo>

L<Image::Base::Wx::Bitmap>,
L<Image::Base::Wx::DC>,
L<Image::Base::Wx::Image>

L<Image::Base::X11::Protocol::Drawable>,
L<Image::Base::X11::Protocol::Pixmap>,
L<Image::Base::X11::Protocol::Window>

C<http://user42.tuxfamily.org/image-base/index.html>

=head1 AUTHOR

Mark Summerfield. I can be contacted as <summer@perlpress.com> -
please include the word 'imagebase' in the subject line.

=head1 COPYRIGHT

Copyright (c) Mark Summerfield 2000. All Rights Reserved.

Copyright (c) Kevin Ryde 2010, 2011, 2012.

This module may be used/distributed/modified under the LGPL. 

=cut

# Local variables:
# cperl-indent-level: 4
# End: