=item *
-2 samples per color - gray scale image with alpha channel.
+2 samples per color - gray scale image with alpha channel, allowing
+transparency.
=item *
=item *
-4 samples per color - RGB image with alpha channel.
+4 samples per color - RGB image with alpha channel, allowing
+transparency.
=back
=over
-=item new
+=item new()
+X<new(), Imager methods>
$img = Imager->new();
$img->read(file=>"alligator.ppm") or die $img->errstr;
=item *
+C<model> - this overrides the value, if any, supplied for C<channels>.
+This can be one of C<gray>, C<graya>, C<rgb> or C<rgba>.
+
+=item *
+
C<bits> - The storage type for samples in the image. Default: 8.
Valid values are:
=item *
-C<file>, C<fh>, C<fd>, C<callback>, C<readcb> - specify a file name,
-filehandle, file descriptor or callback to read image data from. See
-L<Imager::Files> for details. The typical use is:
+C<file>, C<fh>, C<fd>, C<callback>, C<readcb>, or C<io> - specify a
+file name, filehandle, file descriptor or callback to read image data
+from. See L<Imager::Files> for details. The typical use is:
my $im = Imager->new(file => $filename);
my $img = Imager->new(file => $filename)
or die Imager->errstr;
+If none of C<xsize>, C<ysize>, C<file>, C<fh>, C<fd>, C<callback>,
+C<readcb>, C<data>, C<io> is supplied, and other parameters I<are> supplied
+C<< Imager->new >> will return failure rather than returning an empty
+image object.
+
=item img_set()
+X<img_set>
img_set destroys the image data in the object and creates a new one
with the given dimensions and channels. For a way to convert image
$img->img_set(xsize=>500, ysize=>500, channels=>4);
-This takes exactly the same parameters as the new() method.
+This takes exactly the same parameters as the new() method, excluding
+those for reading from files.
=back
print "Image height: ", $img->getheight(), "\n";
-Same details apply as for L<getwidth>.
+Same details apply as for L</getwidth()>.
=item getchannels()
+X<getchannels() method>X<methods, getchannels()>
print "Image has ",$img->getchannels(), " channels\n";
-To get the number of channels in an image C<getchannels()> is used.
+Returns the number of channels in an image.
+
+Note: previously the number of channels in an image mapped directly to
+the color model of the image, ie a 4 channel image was always RGBA.
+This may change in a future release of Imager.
+
+Returns an empty list if the image object is not initialized.
+
+=item colorchannels()
+X<colorchannels() method>X<methods, colorchannels()>
+
+Returns the number of color channels.
+
+Currently this is always 1 or 3, but may be 0 for some rare images in
+a future version of Imager.
+
+Returns an empty list if the image object is not initialized.
+
+=item colormodel()
+X<colormodel method>X<methods, colormodel>
+
+Returns the color model of the image, including whether there is an
+alpha channel.
+
+By default this is returned as a string, one of C<unknown>, C<gray>,
+C<graya>, C<rgb> or C<rgba>.
+
+If you call C<colormodel()> with a true numeric parameter:
+
+ my $model = $img->colormodel(numeric => 1);
+
+then the color model is returned as a number, mapped as follows:
+
+ Numeric String
+ ------- ------
+ 0 unknown
+ 1 gray
+ 2 graya
+ 3 rgb
+ 4 rgba
+
+=item alphachannel()
+X<alphachannel() method>X<methods, alphachannel()>
+
+Returns the channel index of the alpha channel of the image.
+This is 1 for grayscale images with alpha, 3 for RGB images with alpha
+and will return C<undef> for all other images.
+
+Returns an empty list if the image object is not initialized.
=item bits()
# slower but more precise
}
+Returns an empty list if the image object is not initialized.
+
=item type()
The type() method returns either 'direct' for direct color images or
}
}
+Returns an empty list if the image object is not initialized.
+
=item virtual()
The virtual() method returns non-zero if the image contains no actual
If a real bi-level organization image is ever added to Imager, this
function will return true for that too.
+Returns an empty list if the image object is not initialized.
+
=back
=head2 Direct Type Images
$img->setmask(mask=>$mask); # restore previous mask
C<setmask()> is used to set the channel mask of the image. See
-L<getmask> for details.
+L</getmask()> for details.
=back
=over
-=item to_paletted
+=item to_paletted()
You can create a new paletted image from an existing image using the
to_paletted() method:
$palimg = $img->to_paletted(\%opts)
-where %opts contains the options specified under L<Quantization options>.
+where %opts contains the options specified under L</Quantization options>.
# convert to a paletted image using the web palette
# use the closest color to each pixel
=item to_rgb16()
-You can convert a paletted image (or any image) to an 16-bit/channel
-RGB image with:
+Convert a paletted image (or any image) to a 16-bit/channel RGB image.
$rgbimg = $img->to_rgb16;
No parameters.
-=item masked
+=item to_rgb_double()
+
+Convert a paletted image (or any image) to an double/channel direct
+color image.
+
+ $rgbimg = $img->to_rgb_double;
+
+No parameters.
+
+=item masked()
Creates a masked image. A masked image lets you create an image proxy
object that protects parts of the underlying target image.
my $maskedimg = $img->masked(left => 100, top=>100,
right=>200, bottom=>200);
+=item make_palette()
+
+This doesn't perform an image conversion, but it can be used to
+construct a common palette for use in several images:
+
+ my @colors = Imager->make_palette(\%opts, @images);
+
+You must supply at least one image, even if the C<make_colors>
+parameter produces a fixed palette.
+
+On failure returns no colors and you can check C<< Imager->errstr >>.
+
=back
=head2 Tags
get all of the tags in an image, as a list of array references, with
the code or name of the tag followed by the value of the tag.
+Imager's support for fairly limited, for access to pretty much all
+image metadata you may want to try L<Image::ExifTool>.
+
=over
=item tags()
set this as a tag you will need to format it like
C<color(>I<red>C<,>I<green>C<,>I<blue>C<)>, eg color(255,0,0).
+=item *
+
+X<i_comment>C<i_comment> - used when reading or writing several image
+formats. If the format has only one text field it will be read into
+the C<i_comment> tag or written to the file.
+
=back
=head2 Quantization options
These options can be specified when calling
-L<Imager::ImageTypes/to_paletted>, write_multi() for GIF files, when
+L<Imager::ImageTypes/to_paletted()>, write_multi() for GIF files, when
writing a single image with the C<gifquant> option set to C<gen>, or for
direct calls to i_writegif_gen() and i_writegif_callback().
C<mono>, C<monochrome> - a fixed black and white palette, suitable for
producing bi-level images (eg. facsimile)
+=item *
+
+C<gray>, C<gray4>, C<gray16> - make fixed gray palette with 256, 4 or
+16 entries respectively.
+
=back
Other methods may be added in the future.
=item *
-C<giflib> - the C<giflib> native quantization function is used.
+C<giflib> - this is a historical equivalent for C<closest> that also
+forces C<make_colors> to C<mediancut>.
=item *
=item *
-C<errdiff> - an error diffusion dither is performed.
+C<errdiff> - an error diffusion dither is performed. If the supplied
+(or generated) palette contains only grays the source colors are
+converted to gray before error diffusion is performed.
=back
=item *
-C<log> - name of a log file to log Imager's actions to. Not all actions
-are logged, but the debugging memory allocator does log allocations
-here. Ignored if Imager has been built without logging support.
+C<log> - name of a log file to log Imager's actions to. Not all
+actions are logged, but the debugging memory allocator does log
+allocations here. Ignored if Imager has been built without logging
+support. Preferably use the open_log() method instead.
=item *
=back
-=head1 REVISION
+=head1 LOGGING METHODS
+
+Imager can open an internal log to send debugging information to.
+This log is extensively used in Imager's tests, but you're unlikely to
+use it otherwise.
+
+If Imager has been built with logging disabled, the methods fail
+quietly.
+
+=over
+
+=item open_log()
+
+Open the Imager debugging log file.
-$Revision$
+=over
+
+=item *
+
+C<log> - the file name to log to. If this is undef logging information
+is sent to the standard error stream.
+
+=item *
+
+C<loglevel> the level of logging to produce. Default: 1.
+
+=back
+
+Returns a true value if the log file was opened successfully.
+
+ # send debug output to test.log
+ Imager->open_log(log => "test.log");
+
+ # send debug output to stderr
+ Imager->open_log();
+
+=item close_log()
+
+Close the Imager debugging log file and disable debug logging.
+
+No parameters.
+
+ Imager->close_log();
+
+=item log()
+
+ Imager->log($message)
+ Imager->log($message, $level)
+
+This method does not use named parameters.
+
+The default for C<$level> is 1.
+
+Send a message to the debug log.
+
+ Imager->log("My code got here!");
+
+=item is_logging()
+
+Returns a true value if logging is enabled.
+
+=back
-=head1 AUTHORS
+=head1 AUTHOR
-Tony Cook, Arnar M. Hrafnkelsson
+Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
=head1 SEE ALSO
projects / imager.git / blobdiff