fix for rt 62855

[imager.git] / lib / Imager / Cookbook.pod

diff --git a/lib/Imager/Cookbook.pod b/lib/Imager/Cookbook.pod
index aa5a6dc3d28051caf25aa2931af9ce2cc1a8b268..cb1c4ffcdbbe75ea1119dc820dbdcf49404ede3f 100644 (file)
--- a/lib/Imager/Cookbook.pod
+++ b/lib/Imager/Cookbook.pod
@@ -22,7 +22,7 @@ See L<Imager::Files>.
 
   $image->write(file=>$filename) or die $image->errstr;
 
-=head2 Write an animated gif.
+=head2 Write an animated GIF
 
   # build an array of images to use in the gif
   my  @images;
@@ -44,6 +44,53 @@ the L<read_multi()|Imager::Files> method to read them:
   my @images = Imager->read_multi(file=>$filename)
     or die Imager->errstr;
 
+=head2 Converting from one file format to another
+
+This is as simple as reading the original file and writing the new
+file, for single images:
+
+  my $image = Imager->new;
+  # Imager auto-detects the input file type
+  $image->read(file => $input_filename)
+    or die $image->errstr;
+  # Imager derives the output file format from the filename
+  $image->write(file => $output_filename)
+    or die $image->errstr;
+
+  # or you can supply a type parameter:
+  $image->write(file => $output_filename, type => 'gif')
+    or die $image->errstr;
+
+The main issue that can occur with this is if the input file has
+transparency and the output file format doesn't support that.  This
+can be a problem when converting from GIF files to JPEG files for
+example.
+
+To work around that you can compose the source image onto a background
+color:
+
+  if ($image->getchannels == 4 or $image->getchannels == 2) {
+    my $back = Imager->new(xsize => $image->getwidth, 
+                           ysize => $image->getheight);
+    # grey background for grayscale images, red for color
+    my $back_color = $image->getchannels == 2 ? [ 128 ] : 'red';
+    $back->box(filled => 1, color => $back_color);
+    $back->rubthrough(src => $image);
+    $image = $back;
+  }
+  # now we can write safely to jpeg or pnm
+
+Some formats support multiple files, so if you want to convert from
+say TIFF to JPEG, you'll need multiple output files:
+
+  my @images = Imager->read_multi(file => 'input.tif')
+    or die Imager->errstr;
+  my $index = 1;
+  for my $image (@images) {
+    $image->write(file => sprintf('output%02d.jpg', $index++))
+      or die $image->errstr;
+  }
+
 =head1 IMAGE SYNTHESIS
 
 =head2 Creating an image
@@ -57,11 +104,11 @@ If you also want an alpha channel:
 
   my $rgb_alpha = Imager->new(xsize=>$width, ysize=>$height, channels=>4);
 
-To make a grayscale image:
+To make a gray-scale image:
 
   my $gray = Imager->new(xsize=>$width, ysize=>$height, channels=>1);
 
-and a grayscale image with an alpha channel:
+and a gray-scale image with an alpha channel:
 
   my $gray_alpha = Imager->new(xsize=>$width, ysize=>$height, channels=>2);
 
@@ -255,7 +302,7 @@ Then paste the source image into the new image:
 
 Whether you draw the border before or after pasting the original image
 depends on whether you want the border to overlap the image, for
-example a semi-tranparent border drawn after pasting the source image
+example a semi-transparent border drawn after pasting the source image
 could overlap the edge without hiding it.
 
 If you want a solid border you could just fill the image before
@@ -279,8 +326,8 @@ pasting the source for simplicity:
 
 =head2 Shearing (slanting) or Rotating text
 
-This requires that you have Imager installed with Freetype 2.x support
-installed, and that the font be created using the Freetype 2.x driver,
+This requires that you have Imager installed with FreeType 2.x support
+installed, and that the font be created using the FreeType 2.x driver,
 for example:
 
   my $font = Imager::Font->new(file=>$fontfile, type=>'ft2');
@@ -320,13 +367,23 @@ transformed text into.
 
 =head2 Shearing an image
 
+=head2 Convert to gray-scale
+
+To convert an RGB image to a gray-scale image, use the convert method:
+
+  my $grey = $image->convert(preset => 'gray');
+
+convert() returns a new image.
+
+See: L<Imager::Transformations/"Color transformations">
+
 =head1 METADATA
 
 =head2 Image format
 
 When Imager reads a file it does a magic number check to determine the
-file type, so "foo.png" could actually be a GIF image, and Imager will
-read it anyway.
+file type, so C<foo.png> could actually be a GIF image, and Imager
+will read it anyway.
 
 You can check the actual format of the image by looking at the
 C<i_format> tag.