PDFImage


1   // $Id: PDFImage.java,v 1.5 2003/11/04 17:16:01 mike Exp $
2   
3   package org.faceless.pdf;
4   
5   import java.util.*;
6   import java.io.*;
7   import java.awt.*;
8   
9   /**
10   * <p>
11   * The PDFImage class encapsulates a bitmap image, like a JPEG or PNG file,
12   * which can be inserted directly into the PDF document. Since version 1.1.13
13   * the TIFF image format is supported too.
14   * </p>
15   *
16   * <b>Example</b>
17   * <pre>
18   *   PDFPage page = pdf.newPage(PAGESIZE_A4);
19   *   PDFImage img = new PDFImage(new FileInputStream("mypicture.jpg"));
20   *   page.drawImage(img, 100, 100, i.getWidth(), i.getHeight());
21   * </pre>
22   *
23   * <p>
24   * Images embedded into the document can be stretched to any size, but it's important
25   * to remember that there is a loss in quality as they're stretched. A thumbnail-size
26   * image scaled to full page will look bad on a 72dpi screen, and worse on a 600dpi
27   * printer.
28   * </p>
29   * <p>
30   * Since 1.1.17, simple "mask" transparency is supported. This allows one or more colors to
31   * be set to transparent, and is a useful feature of the GIF and PNG file formats. Please
32   * note that support for this feature in Adobe Acrobat is <i>printer dependent</i> - it
33   * requires PostScript level 3 support to print correctly (earlier PostScript levels
34   * will print without transparency). In addition, Acrobat 4.0 will ignore the transparency
35   * information if the image is too large (for indexed images like GIF and some PNG, this
36   * means <code><i>width</i>*<i>height</i> > 1MB</code>. For TrueColor PNG images, the limit
37   * is 340Kb).
38   * </p><p>
39   * Alpha channel transparency (the kind used in some PNG and TIFF images) is not supported.
40   * </p><p>
41   * Since 1.2, JPEG images are no longer all a uniform 72dpi, but have their DPI set to the
42   * value specified in the file. This may cause images to be resized from those upgrading
43   * from version 1.1.x of the library - for those in this situation, the {@link #getDPIX}
44   * and {@link #getDPIY} methods may help to migrate their code.
45   * </p>
46   * @version $Revision: 1.5 $
47   */
48  public class PDFImage extends PeeredObject
49  {
50      final org.faceless.pdf2.PDFImage image;
51      
52      Object   getPeer()
53      {
54          return image;
55      }
56  
57      PDFImage(org.faceless.pdf2.PDFImage image)
58      {
59          this.image=image;
60      }
61  
62      /**
63       * Create a new PDFimage from the specified <code>java.awt.Image</code>.
64       * The image must be fully loaded, i.e. the Width and Height are known,
65       * otherwise an <code>IllegalArgumentException</code> is thrown.
66       *
67       * @param img the image to load
68       *
69       * @throws InterruptedException if the library is unable to read the pixels from
70       * the image before being interrupted
71       *
72       * @throws IllegalArgumentException if the image is invalid - ie. the width or height
73       * is zero or not defined, or if the image is not an embeddable image type
74       */
75      public PDFImage(Image img)
76          throws InterruptedException  , IllegalArgumentException  
77      {
78      image = new org.faceless.pdf2.PDFImage(img);
79      }
80  
81      /**
82       * Load a PDFimage from an InputStream. The image can be either a JPEG,
83       * PNG, GIF or TIFF file. PDF documents can embed these types of images
84       * with the following restrictions:
85       * <ul>
86       * <li>PNG images must be either indexed or specify 8 or less bitplanes per color.</li>
87       * <li>Progressive JPEGs can't be rendered in viewers earlier than Acrobat 4.0.</li>
88       * <li>If the GIF is animated, only the first frame is embedded.</li>
89       * <li>TIFF images (since 1.1.13) - currently JPEG, ThunderScan and NeXT variations
90       * are not supported.</li>
91       * <li>The library only supports "simple" transparency - the kind available in GIF and
92       * certain types of PNG image. Full alpha transparency, of the kind supported in some
93       * PNG and TIFF images, is not supported.</li>
94       * </ul>
95       * @param in the <code>InputStream</code> to read the image from
96       * @throws IOException if the method is unable to read or parse the image
97       * @throws IllegalArgumentException if the image is invalid or can't be embedded.
98       */
99      public PDFImage(InputStream in)
100         throws IOException, IllegalArgumentException  
101     {
102     image = new org.faceless.pdf2.PDFImage(in);
103     }
104 
105     /**
106      * Load a PDFimage from a byte array. This method is identical to
107      * the <code>InputStream</code> constructor, but takes a byte array
108      * containing the image as a parameter instead
109      * @since 1.2
110      */
111     public PDFImage(byte[] in)
112         throws IOException, IllegalArgumentException  
113     {
114     image = new org.faceless.pdf2.PDFImage(in);
115     }
116 
117     /**
118      * <p>
119      * Return the width in points of the original bitmap image.
120      * </p><p>
121      * Prior to version 1.1.13 this returned the width in pixels,
122      * but as every image prior to 1.1.13 was at 72dpi there's no
123      * practical difference.
124      * </p>
125      */
126     public int getWidth()
127     {
128     return (int)image.getWidth();
129     }
130 
131     /**
132      * <p>
133      * Return the height in points of the original bitmap image.
134      * </p><p>
135      * Prior to version 1.1.13 this returned the height in pixels,
136      * but as every image prior to 1.1.13 was at 72dpi there's no
137      * practical difference.
138      * </p>
139      */
140     public int getHeight()
141     {
142     return (int)image.getHeight();
143     }
144 
145     /**
146      * Return the dots-per-inch of the image in the X direction (horizontally)
147      * @since 1.2
148      */
149     public double getDPIX()
150     {
151     return image.getDPIX();
152     }
153 
154     /**
155      * Return the dots-per-inch of the image in the Y direction (vertically)
156      * @since 1.2
157      */
158     public double getDPIY()
159     {
160     return image.getDPIY();
161     }
162 
163     /**
164      * Set the ColorSpace that the image uses. The specified
165      * ColorSpace must have the same number of components as
166      * the images default <tt>ColorSpace</tt>, or an
167      * <tt>IllegalArgumentException</tt> is thrown.
168      * </p><p>
169      * Note that all <tt>java.awt.Image</tt> and some PNG and TIFF
170      * images contain an embedded <tt>ColorSpace</tt> already, and
171      * overriding it may result in an effect the artist didn't
172      * anticipate.
173      * </p>
174      * @since 1.1.5
175      */
176     public void setColorSpace(java.awt.color.ColorSpace   space)
177     {
178         // NOOP
179     }
180 
181     /**
182      * Set the XML metadata associated with this object. See
183      * {@link PDF#setMetaData PDF.setMetaData} for more information.
184      * @param xmldata the XML data to embed into the document, or <tt>null</tt>
185      * to clear any existing metadata. No validation is performed on this input.
186      * @since 1.1.12
187      */
188     public void setMetaData(String   xmldata)
189     {
190     image.setMetaData(xmldata);
191     }
192 
193     /**
194      * Return any XML metadata associated with this object. See the
195      * {@link PDF#getMetaData} for more information
196      * @return a {@link java.io.Reader} containing the source of the XML or
197      * <tt>null</tt> if no metadata is available.
198      * @throws IOException if the metadata can't be extracted
199      * @since 1.1.12
200      */
201     public Reader getMetaData()
202         throws IOException
203     {
204     return image.getMetaData();
205     }
206 }
207
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags