pdfimage.java

Java生成PDF Java生成PDF Java生成PDF

// $Id: PDFImage.java,v 1.5 2003/11/04 17:16:01 mike Exp $

package org.faceless.pdf;

import java.util.*;
import java.io.*;
import java.awt.*;

/**
 * <p>
 * The PDFImage class encapsulates a bitmap image, like a JPEG or PNG file,
 * which can be inserted directly into the PDF document. Since version 1.1.13
 * the TIFF image format is supported too.
 * </p>
 *
 * <b>Example</b>
 * <pre>
 *   PDFPage page = pdf.newPage(PAGESIZE_A4);
 *   PDFImage img = new PDFImage(new FileInputStream("mypicture.jpg"));
 *   page.drawImage(img, 100, 100, i.getWidth(), i.getHeight());
 * </pre>
 *
 * <p>
 * Images embedded into the document can be stretched to any size, but it's important
 * to remember that there is a loss in quality as they're stretched. A thumbnail-size
 * image scaled to full page will look bad on a 72dpi screen, and worse on a 600dpi
 * printer.
 * </p>
 * <p>
 * Since 1.1.17, simple "mask" transparency is supported. This allows one or more colors to
 * be set to transparent, and is a useful feature of the GIF and PNG file formats. Please
 * note that support for this feature in Adobe Acrobat is <i>printer dependent</i> - it
 * requires PostScript level 3 support to print correctly (earlier PostScript levels
 * will print without transparency). In addition, Acrobat 4.0 will ignore the transparency
 * information if the image is too large (for indexed images like GIF and some PNG, this
 * means <code><i>width</i>*<i>height</i> > 1MB</code>. For TrueColor PNG images, the limit
 * is 340Kb).
 * </p><p>
 * Alpha channel transparency (the kind used in some PNG and TIFF images) is not supported.
 * </p><p>
 * Since 1.2, JPEG images are no longer all a uniform 72dpi, but have their DPI set to the
 * value specified in the file. This may cause images to be resized from those upgrading
 * from version 1.1.x of the library - for those in this situation, the {@link #getDPIX}
 * and {@link #getDPIY} methods may help to migrate their code.
 * </p>
 * @version $Revision: 1.5 $
 */
public class PDFImage extends PeeredObject
{
    final org.faceless.pdf2.PDFImage image;
    
    Object getPeer()
    {
        return image;
    }

    PDFImage(org.faceless.pdf2.PDFImage image)
    {
        this.image=image;
    }

    /**
     * Create a new PDFimage from the specified <code>java.awt.Image</code>.
     * The image must be fully loaded, i.e. the Width and Height are known,
     * otherwise an <code>IllegalArgumentException</code> is thrown.
     *
     * @param img the image to load
     *
     * @throws InterruptedException if the library is unable to read the pixels from
     * the image before being interrupted
     *
     * @throws IllegalArgumentException if the image is invalid - ie. the width or height
     * is zero or not defined, or if the image is not an embeddable image type
     */
    public PDFImage(Image img)
        throws InterruptedException, IllegalArgumentException
    {
	image = new org.faceless.pdf2.PDFImage(img);
    }

    /**
     * Load a PDFimage from an InputStream. The image can be either a JPEG,
     * PNG, GIF or TIFF file. PDF documents can embed these types of images
     * with the following restrictions:
     * <ul>
     * <li>PNG images must be either indexed or specify 8 or less bitplanes per color.</li>
     * <li>Progressive JPEGs can't be rendered in viewers earlier than Acrobat 4.0.</li>
     * <li>If the GIF is animated, only the first frame is embedded.</li>
     * <li>TIFF images (since 1.1.13) - currently JPEG, ThunderScan and NeXT variations
     * are not supported.</li>
     * <li>The library only supports "simple" transparency - the kind available in GIF and
     * certain types of PNG image. Full alpha transparency, of the kind supported in some
     * PNG and TIFF images, is not supported.</li>
     * </ul>
     * @param in the <code>InputStream</code> to read the image from
     * @throws IOException if the method is unable to read or parse the image
     * @throws IllegalArgumentException if the image is invalid or can't be embedded.
     */
    public PDFImage(InputStream in)
        throws IOException, IllegalArgumentException
    {
	image = new org.faceless.pdf2.PDFImage(in);
    }

    /**
     * Load a PDFimage from a byte array. This method is identical to
     * the <code>InputStream</code> constructor, but takes a byte array
     * containing the image as a parameter instead
     * @since 1.2
     */
    public PDFImage(byte[] in)
        throws IOException, IllegalArgumentException
    {
	image = new org.faceless.pdf2.PDFImage(in);
    }

    /**
     * <p>
     * Return the width in points of the original bitmap image.
     * </p><p>
     * Prior to version 1.1.13 this returned the width in pixels,
     * but as every image prior to 1.1.13 was at 72dpi there's no
     * practical difference.
     * </p>
     */
    public int getWidth()
    {
	return (int)image.getWidth();
    }

    /**
     * <p>
     * Return the height in points of the original bitmap image.
     * </p><p>
     * Prior to version 1.1.13 this returned the height in pixels,
     * but as every image prior to 1.1.13 was at 72dpi there's no
     * practical difference.
     * </p>
     */
    public int getHeight()
    {
	return (int)image.getHeight();
    }

    /**
     * Return the dots-per-inch of the image in the X direction (horizontally)
     * @since 1.2
     */
    public double getDPIX()
    {
	return image.getDPIX();
    }

    /**
     * Return the dots-per-inch of the image in the Y direction (vertically)
     * @since 1.2
     */
    public double getDPIY()
    {
	return image.getDPIY();
    }

    /**
     * Set the ColorSpace that the image uses. The specified
     * ColorSpace must have the same number of components as
     * the images default <tt>ColorSpace</tt>, or an
     * <tt>IllegalArgumentException</tt> is thrown.
     * </p><p>
     * Note that all <tt>java.awt.Image</tt> and some PNG and TIFF
     * images contain an embedded <tt>ColorSpace</tt> already, and
     * overriding it may result in an effect the artist didn't
     * anticipate.
     * </p>
     * @since 1.1.5
     */
    public void setColorSpace(java.awt.color.ColorSpace space)
    {
        // NOOP
    }

    /**
     * Set the XML metadata associated with this object. See
     * {@link PDF#setMetaData PDF.setMetaData} for more information.
     * @param xmldata the XML data to embed into the document, or <tt>null</tt>
     * to clear any existing metadata. No validation is performed on this input.
     * @since 1.1.12
     */
    public void setMetaData(String xmldata)
    {
	image.setMetaData(xmldata);
    }

    /**
     * Return any XML metadata associated with this object. See the
     * {@link PDF#getMetaData} for more information
     * @return a {@link java.io.Reader} containing the source of the XML or
     * <tt>null</tt> if no metadata is available.
     * @throws IOException if the metadata can't be extracted
     * @since 1.1.12
     */
    public Reader getMetaData()
        throws IOException
    {
	return image.getMetaData();
    }
}