From: Tony Cook <tony@develop=help.com>
Date: Tue, 11 Jul 2006 13:21:31 +0000 (+0000)
Subject: add some examples using the i_xres and i_yres tags
X-Git-Tag: Imager-0.52~21
X-Git-Url: http://git.imager.perl.org/imager.git/commitdiff_plain/c2d1dd1300da10ea73f24b445c17be251d928c98

add some examples using the i_xres and i_yres tags
---

diff --git a/Imager.pm b/Imager.pm
index 1c2f11e1..396f7ce8 100644
--- a/Imager.pm
+++ b/Imager.pm
@@ -3778,13 +3778,14 @@ cropping - L<Imager::Transformations/crop>
 
 C<diff> images - L<Imager::Filter/"Image Difference">
 
-dpi - L<Imager::ImageTypes/i_xres>
+dpi - L<Imager::ImageTypes/i_xres>, 
+L<Imager::Cookbook/"Image spatial resolution">
 
 drawing boxes - L<Imager::Draw/box>
 
 drawing lines - L<Imager::Draw/line>
 
-drawing text - L<Imager::Font/string>, L<Imager::Font/align>
+drawing text - L<Imager::Draw/string>, L<Imager::Draw/align_string>
 
 error message - L<"Basic Overview">
 
@@ -3802,8 +3803,8 @@ flood fill - L<Imager::Draw/flood_fill>
 
 fonts - L<Imager::Font>
 
-fonts, drawing with - L<Imager::Font/string>, L<Imager::Font/align>,
-L<Imager::Font::Wrap>
+fonts, drawing with - L<Imager::Draw/string>,
+L<Imager::Draw/align_string>, L<Imager::Font::Wrap>
 
 fonts, metrics - L<Imager::Font/bounding_box>, L<Imager::Font::BBox>
 
diff --git a/lib/Imager/Cookbook.pod b/lib/Imager/Cookbook.pod
index 87f9e848..aa5a6dc3 100644
--- a/lib/Imager/Cookbook.pod
+++ b/lib/Imager/Cookbook.pod
@@ -322,8 +322,44 @@ transformed text into.
 
 =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.
+
+You can check the actual format of the image by looking at the
+C<i_format> tag.
+
+  my $format = $image->tags(name=>'i_format');
+
 =head2 Image spatial resolution
 
+Most image file formats store information about the physical size of
+the pixels, though in some cases that information isn't useful.
+
+Imager stores this information in the tags C<i_xres> and C<i_yres>,
+and this is always stored in dots per inch.
+
+Some formats, including TIFF and JPEG allow you to change the units
+spatial resolution information is stored in, if you set the tag that
+changes this the Imager will convert C<i_xres> and C<i_yres> to those
+units when it writes the file.
+
+For example to set the resolution to 300 dpi:
+
+  $image->settag(name => 'i_xres', value => 300);
+  $image->settag(name => 'i_yres', value => 300);
+
+If you want the file format to store the resolution in some other
+unit, for example you can write a TIFF file that stores the resolution
+in pixels per centimeter, you would do:
+
+  # 150 pixels/cm
+  $image->settag(name => 'i_xres', value => 150 * 2.54);
+  $image->settag(name => 'i_yres', value => 150 * 2.54);
+  $image->settag(name => 'tiff_resolutionunit', value => 3);
+
 Keywords: DPI
 
 =head1 AUTHOR
diff --git a/lib/Imager/ImageTypes.pod b/lib/Imager/ImageTypes.pod
index 488f80b6..cb67145c 100644
--- a/lib/Imager/ImageTypes.pod
+++ b/lib/Imager/ImageTypes.pod
@@ -683,6 +683,16 @@ The spatial resolution of the image in pixels per inch.  If the image
 format uses a different scale, eg. pixels per meter, then this value
 is converted.  A floating point number stored as a string.
 
+  # our image was generated as a 300 dpi image
+  $img->settag(name => 'i_xres', value => 300);
+  $img->settag(name => 'i_yres', value => 300);
+
+  # 100 pixel/cm for a TIFF image
+  $img->settag(name => 'tiff_resolutionunit', value => 3); # RESUNIT_CENTIMETER
+  # convert to pixels per inch, Imager will convert it back
+  $img->settag(name => 'i_xres', value => 100 * 2.54);
+  $img->settag(name => 'i_yres', value => 100 * 2.54);
+
 =item i_aspect_only
 
 If this is non-zero then the values in i_xres and i_yres are treated