org.faceless.pdf2

## Class PDFImage

- java.lang.Object
- - org.faceless.pdf2.PDFImage

- All Implemented Interfaces:
    Cloneable

      public final class PDFImage
      extends Object

  The PDFImage class encapsulates a bitmap image, like a JPEG or PNG file, which can be inserted directly into the PDF document.

         PDFPage page = pdf.newPage("A4");
         InputStream in = new FileInputStream("mypicture.jpg");
         PDFImage img = new PDFImage(in);
         in.close();
         page.drawImage(img, 100, 100, 100+i.getWidth(), 100+i.getHeight());

  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. See the `getWidth()` and `getPixelWidth()` methods for details.

  Embedded ICC Color Profiles will be respected, as are Transparency (supported by the GIF, PNG, TIFF and JPEG2000 file formats) and TIFF clipping paths. Note that transparency will require Acrobat 5 or later to display the PDF.

  Technical Note. The PDF does not embed the original image file, but instead stores the raw bitmap data. If the original bitmap format uses a compression scheme that is also used by PDF then it will not need to be recompressed, which will speed things up. For that reason, if you have a choice of image format to import try to choose one of the following:

  - TIFF images encoded as a single strip of CCITT Group 4 image data and msb-to-lsb FillOrder
  - JPEG
  - JPEG2000
  - TIFF images encoded using new-style JPEG compression
  - PNG other than 1-bit indexed PNG or 32-bit (= 24-bit plus alpha channel) PNG images
  Since:
    1.0

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `PDFImage(byte[] buf)` Load a PDFimage from a byte array.
    `PDFImage(Image img)` Create a new PDFimage from the specified `java.awt.Image`.
    `PDFImage(Image img, String properties)` Create a new PDFimage from the specified `java.awt.Image`.
    `PDFImage(InputStream in)` Load a PDFimage from an InputStream.
    `PDFImage(int w, int h, int bpc, double dpix, double dpiy, boolean photo, boolean alpha, ColorSpace space, InputStream[] planes)` Create a PDFImage from the raw bitmap data provided.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Compress the image and close it, preventing any further changes.
    `double` | `getDPIX()` Return the dots-per-inch of the image in the X direction (horizontally).
    `double` | `getDPIY()` Return the dots-per-inch of the image in the Y direction (vertically) Not every image contains this information (for example, it's not part of the GIF specification), in which case this method returns the default resolution of 72, which means 1 pixel = 1 point.
    `float` | `getHeight()` Return the height in points of the image.
    `Reader` | `getMetaData()` Return any XML metadata associated with this object.
    `int` | `getPixelHeight()` Get the height of the image in pixels.
    `int` | `getPixelWidth()` Get the width of the image in pixels.
    `RenderedImage` | `getRenderedImage()` Return a `RenderedImage` from this PDFImage.
    `float` | `getWidth()` Return the width in points of the image.
    `void` | `quantize()` Convert a PDFImage to an "Indexed" image, by reducing the number of colors in the image to 256 and storing each color as an index into a color table.
    `void` | `setColorSpace(ColorSpace space)` Override the stored ColorSpace in this image.
    `void` | `setMetaData(String xmldata)` Set the XML metadata associated with this object.
    `String` | `toString()`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### PDFImage

          public PDFImage(Image img)
                   throws InterruptedException

      Create a new PDFimage from the specified `java.awt.Image`. The image must be fully loaded, ie. the width and height are known, otherwise an `IllegalArgumentException` is thrown.
      Parameters:
        `img` - the image to load
      Throws:
        `InterruptedException` - if the library is unable to read the pixels from the image before being interrupted
        `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

    - #### PDFImage

          public PDFImage(Image img,
                          String properties)
                   throws InterruptedException

      Create a new PDFimage from the specified `java.awt.Image`. The image must be fully loaded, ie. the width and height are known, otherwise an `IllegalArgumentException` is thrown.
      Parameters:
        `img` - the image to load
        `properties` - properties that can be specified to modify the way the image is encoded. For now value values are "JPEG", "JPEG=nnn" (where nnn is the quality between 0 and 100), "JPX" and "JPX=nnn" (where nnn is the quality, ranging from about 0.5 to 1.5). These arguments will cause the image to be compressed using JPEG or JPEG-2000 compression respectively.
      Throws:
        `InterruptedException`
      Since:
        2.11.8

    - #### PDFImage

          public PDFImage(byte[] buf)
                   throws IOException

      Load a PDFimage from a byte array. This method is identical to the `PDFImage(InputStream)` constructor, but takes a byte array containing the image as a parameter instead
      Throws:
        `IOException`
      Since:
        1.2

    - #### PDFImage

          public PDFImage(InputStream in)
                   throws IOException

      Load a PDFimage from an InputStream. PDF documents can embed these types of images with the following restrictions:

      PNG | All except for 16 bit PNG
      JPEG | Progressive JPEG images can only be viewed in Acrobat 4 or later. Additionally, CMYK JPEG images created with Adobe tools like Photoshop may print incorrectly unless you're running Java 1.4 or later.
      GIF | If the GIF is animated, only the first frame is embedded
      TIFF | Since 2.1.1 we can handle CCITT, Flate, LZW, CMYK, alpha transparency, most YCbCr and (if you're running Java 1.4 or later) new-style JPEG images, but old-style JPEG, JBIG, SGI, 16-bit and Lab images remain unsupported. For multi-page TIFF support see the `PDFImageSet` class.
      PBM, PGM | Only standard 8-bit PBM and PGM images are supported. Support was added in version 2.0.6
      JPEG 2000 | These can only be displayed in Acrobat 6 or later. Support added in version 2.1.1

      Note the InputStream is not closed by this constructor - it should be closed by the user
      Parameters:
        `in` - the `InputStream` to read the image from
      Throws:
        `IOException` - if the method is unable to read or parse the image
        `IllegalArgumentException` - if the image is invalid or can't be embedded.

    - #### PDFImage

          public PDFImage(int w,
                          int h,
                          int bpc,
                          double dpix,
                          double dpiy,
                          boolean photo,
                          boolean alpha,
                          ColorSpace space,
                          InputStream[] planes)
                   throws IOException

      Create a PDFImage from the raw bitmap data provided. The vast majority of users will be better off either parsing an encoded image format or calling the `PDFImage(java.awt.Image)` constructor, but for special cases it's possible to use this constructor to pass the raw bitmap data in for each plane.

      Parameters:
        `w` - the width of the image in pixels
        `h` - the height of the image in pixels
        `bpc` - the number of bits for each component of the image. Must be 1, 2, 4, 8 or 16 - although 16 is only supported by Acrobat 6 or later.
        `dpix` - the horizontal dots-per-inch of the image
        `dpiy` - the vertical dots-per-inch of the image
        `photo` - for 8 bit images, whether to use JPEG compression instead of the normal Flate compression. For non 8-bit images this has no effect
        `alpha` - whether or not an alpha plane is being passed in as the last plane
        `space` - The ColorSpace this image is in. The number of components in the colorspace must match the number of planes passed in.
        `planes` - The planes of the image. Each InputStream represents a single plane (for example, a CMYK image would have four planes passed in, the first representing Cyan, the second Magenta and so on). Each InputStream must contain `w*h*bpc` bits of image data in the form of a number of horizontal scanlines starting at the top of the image. Each scanline must start on a byte boundary. Note the InputStreams are not closed by this constructor.
      Throws:
        `IOException` - if one of the InputStreams throws an IOException while being read, or if one of them returns a -1 from it's `read()` method.
      Since:
        2.2

  - ### Method Detail

    - #### getWidth

          public float getWidth()

      Return the width in points of the image. This may be different to the width in pixels, depending on whether the image contains information about it's resolution.

      See Also:
        `getDPIX()`

    - #### getHeight

          public float getHeight()

      Return the height in points of the image. This may be different to the height in pixels, depending on whether the image contains information about it's resolution.

      See Also:
        `getDPIY()`

    - #### getPixelWidth

          public int getPixelWidth()

      Get the width of the image in pixels.
      Since:
        2.11.5

    - #### getPixelHeight

          public int getPixelHeight()

      Get the height of the image in pixels.
      Since:
        2.11.5

    - #### getDPIX

          public double getDPIX()

      Return the dots-per-inch of the image in the X direction (horizontally). Not every image contains this information (for example, it's not part of the GIF specification), in which case this method returns the default resolution of 72, which means 1 pixel = 1 point.
      Since:
        1.2

    - #### getDPIY

          public double getDPIY()

      Return the dots-per-inch of the image in the Y direction (vertically) Not every image contains this information (for example, it's not part of the GIF specification), in which case this method returns the default resolution of 72, which means 1 pixel = 1 point.
      Since:
        1.2

    - #### setMetaData

          public void setMetaData(String xmldata)

      Set the XML metadata associated with this object. See `PDF.setMetaData` for more information.
      Parameters:
        `xmldata` - the XML data to embed into the document, or `null` to clear any existing metadata. No validation is performed on this input.
      Since:
        1.1.12

    - #### getMetaData

          public Reader getMetaData()
                             throws IOException

      Return any XML metadata associated with this object. See the `PDF.getMetaData()` for more information.

      Note that JPEG2000 images may have more than one MetaData stream embedded in them. If this is the case, in order to present only a single root node to the XML Parser, the XML objects are all wrapped in a single `<JPEG2000>` node

      Returns:
        a `Reader` containing the source of the XML or `null` if no metadata is available.
      Throws:
        `IOException` - if the metadata can't be extracted
      Since:
        1.1.12

    - #### close

          public void close()

      Compress the image and close it, preventing any further changes. Unless you're going to add MetaData to the image, it's always a good idea to call this method so you can claw back some memory.
      Since:
        2.0
      See Also:
        `Cache`

    - #### quantize

          public void quantize()

      Convert a PDFImage to an "Indexed" image, by reducing the number of colors in the image to 256 and storing each color as an index into a color table. This operation isn't quick, but for some types of image it can reduce the filesize with little or no loss of quality.

      For RGB source images it's typically better to do this in the image file - PNG and TIFF images can store indexed RGB data and GIF is always indexed - and for grayscale there's no benefit. However for CMYK images this method can make a significant difference.

      Since:
        2.11.22

    - #### setColorSpace

          public void setColorSpace(ColorSpace space)

      Override the stored ColorSpace in this image. This may be necessary if the image has been saved with a particular ColorSpace which doesn't match the sRGB space `used by Java`. Typically this manifests itself by a shift to red or blue in the image when the PDF containing it is opened in Acrobat (a result of the image whitepoint being hotter or colder respectively than D50).
      Parameters:
        `space` - the `ColorSpace` to set the image to. A value of `null` will cause the image to use device-dependent color, and a value of `Color.red.getColorSpace()` will set the image to sRGB. In practice this is the same thing.
      Throws:
        `IllegalArgumentException` - if the number of components in the ColorSpace doesn't match the number in the image.
      Since:
        2.11.8

    - #### getRenderedImage

          public RenderedImage getRenderedImage()
                                         throws IOException

      Return a `RenderedImage` from this PDFImage.
      Throws:
        `IOException` - if the image cannot be decoded
      Since:
        2.11.8

    - #### toString

          public String toString()

Copyright © 2001-2015 Big Faceless Organization