pdftron::PDF::Image Class Reference

Image class provides common methods for working with PDF images. More...

#include <Image.h>

List of all members.

Public Types

enum  InputFilter {
  e_none, e_jpeg, e_jp2, e_flate,
  e_g3, e_g4, e_ascii_hex
}

Public Member Functions

 Image (SDF::Obj image_xobject=0)
 Create an image from an existing image represented as a SDF/Cos object.
 Image (const Image &)
Imageoperator= (const Image &)
SDF::Obj GetSDFObj () const
bool IsValid () const
Filters::Filter GetImageData () const
int GetImageDataSize () const
Gdiplus::Bitmap * GetBitmap () const
 Convert PDF image to GDI+ Bitmap.
ColorSpace GetImageColorSpace () const
int GetImageWidth () const
int GetImageHeight () const
SDF::Obj GetDecodeArray () const
int GetBitsPerComponent () const
int GetComponentNum () const
bool IsImageMask () const
bool IsImageInterpolate () const
SDF::Obj GetMask () const
void SetMask (Image &image_mask)
 Set an Explicit Image Mask.
void SetMask (SDF::Obj mask)
 Set a Color Key Mask.
SDF::Obj GetSoftMask ()
void SetSoftMask (Image &soft_mask)
 Set a Soft Mask.
GState::RenderingIntent GetImageRenderingIntent () const
int Export (const UString &filename)
 Saves this image to a file.
int Export (Filters::FilterWriter &writer)
 Saves this image to the output stream.
void ExportAsTiff (const UString &filename)
 Saves this image to a TIFF file.
void ExportAsTiff (Filters::FilterWriter &writer)
 Saves this image to a TIFF output stream.
void ExportAsPng (const UString &filename)
 Saves this image to a PNG file.
void ExportAsPng (Filters::FilterWriter &writer)
 Saves this image to a PNG output stream.

Static Public Member Functions

static Image Create (SDF::SDFDoc &doc, const UString &filename, SDF::Obj encoder_hints=0)
 Create and embed an Image from an external file taking into account specified compression hints.
static Image Create (SDF::SDFDoc &doc, const char *image_data, size_t image_data_size, int width, int height, int bpc, ColorSpace color_space, SDF::Obj encoder_hints=0)
 Create and embed an Image.
static Image Create (SDF::SDFDoc &doc, Filters::FilterReader &image_data, int width, int height, int bpc, ColorSpace color_space, SDF::Obj encoder_hints=0)
 Create and embed an Image.
static Image Create (SDF::SDFDoc &doc, Gdiplus::Bitmap *bmp, SDF::Obj encoder_hints=0)
 Create and embed an Image from any GDI+ Bitmap taking into account specified compression hints.
static Image CreateImageMask (SDF::SDFDoc &doc, const char *image_data, size_t image_data_size, int width, int height, SDF::Obj encoder_hints=0)
 Create and embed an ImageMask.
static Image CreateImageMask (SDF::SDFDoc &doc, Filters::FilterReader &image_data, int width, int height, SDF::Obj encoder_hints=0)
 Create and embed an ImageMask.
static Image CreateSoftMask (SDF::SDFDoc &doc, const char *image_data, size_t image_data_size, int width, int height, int bpc, SDF::Obj encoder_hints=0)
 Create and embed a Soft Mask.
static Image CreateSoftMask (SDF::SDFDoc &doc, Filters::FilterReader &image_data, int width, int height, int bpc, SDF::Obj encoder_hints=0)
 Create and embed a Soft Mask.
static Image Create (SDF::SDFDoc &doc, const char *image_data, size_t image_data_size, int width, int height, int bpc, ColorSpace color_space, InputFilter input_format)
 Directly embed the image that is already compressed using the Image::InputFilter format.
static Image Create (SDF::SDFDoc &doc, Filters::FilterReader &image_data, int width, int height, int bpc, ColorSpace color_space, InputFilter input_format)
 Embed the raw image data taking into account specified compression hints.


Detailed Description

Image class provides common methods for working with PDF images.

Note:
PDF::Element contains a similar interface used to access image data. To create the Image object from image PDF::Element, pass the Element's SDF/Cos dictionary to Image constructor (i.e. Image image(element->GetXObject()) )

Member Enumeration Documentation

Enumerator:
e_none 
e_jpeg 
e_jp2 
e_flate 
e_g3 
e_g4 
e_ascii_hex 


Constructor & Destructor Documentation

pdftron::PDF::Image::Image ( SDF::Obj  image_xobject = 0  ) 

Create an image from an existing image represented as a SDF/Cos object.

Note:
To create the Image object from image PDF::Element, pass the Element's SDF/Cos dictionary to Image constructor (i.e. Image image(element->GetXObject()))

pdftron::PDF::Image::Image ( const Image  ) 


Member Function Documentation

static Image pdftron::PDF::Image::Create ( SDF::SDFDoc doc,
const UString filename,
SDF::Obj  encoder_hints = 0 
) [static]

Create and embed an Image from an external file taking into account specified compression hints.

Returns:
PDF::Image object representing the embedded image.
By default the function will either pass-through data preserving the original compression or will compress data using Flate compression. It is possible to fine tune compression or to select a different compression algorithm using 'encoder_hints' object.

Parameters:
doc - A document to which the image should be added. To obtain SDF::Doc from PDFDoc use PDFDoc::GetSDFDoc() or Obj::GetDoc().
filename - The name of the image file. Currently supported formats are JPEG, PNG, GIF, TIFF, BMP, EMF, and WMF. Other raster formats can be embedded by decompressing image data and using other versions of Image::Create(...) method.
encoder_hints - An optional SDF::Obj containing a hint (or an SDF::Array of hints) that could be used to select a specific compression method and compression parameters. For a concrete example of how to create encoder hints, please take a look at JBIG2Test and AddImage sample projects. The image encoder accepts the following hints:
  • /JBIG2; SDF::Name("JBIG2"), An SDF::Name Object with value equal to "JBIG2". If the image is monochrome (i.e. bpc == 1), the encoder will compress the image using JBIG2Decode lossless filter.

  • [/JBIG2 /Lossy] - An SDF::Array with two SDF::Name parameters. If the image is monochrome (i.e. bpc == 1), the encoder will compress the image using JBIG2Decode lossy filter. Generally the lossy compression results in smaller files but image may loose some information.

  • [/JBIG2 /Threshold 0.6 /SharePages 50] - Compress a monochrome image using lossy JBIG2Decode compression with the given image threshold and by sharing segments from a specified number of pages. The threshold is a floating point number in the rage from 0 to 1. Increasing the threshold value will decrease the loss of image quality, but may increase the file size. The default value for threshold is 0.85. "SharePages" parameter can be used to specify the maximum number of pages sharing a common 'JBIG2Globals' segment stream. Increasing the value of this parameter improves compression ratio at the expense of memory usage.

  • [/JPEG] - Use JPEG compression with default compression.
  • [/JPEG /Quality 60] - Use JPEG compression with given quality setting. The "Quality" value is expressed on the 0..100 scale.

  • [/JP2] or [/JPEG2000] - Use JPEG2000 compression to compress a RGB or a grayscale image

  • [/Flate] - Use Flate compression with maximum compression at the expense of speed.

  • [/Flate /Level 9] - Use Flate compression using specified compression level. Compression "Level" must be a number between 0 and 9: 1 gives best speed, 9 gives best compression, 0 gives no compression at all (the input data is simply copied a block at a time).

  • /RAW or [/RAW] - The encoder will not use any compression method and the image will be stored in the raw format.

Note:
For C++ developers: Current document does not take the ownership of the encoder_hints object. Therefore it is a good programming practice to create encoder_hints object on the stack.

static Image pdftron::PDF::Image::Create ( SDF::SDFDoc doc,
const char *  image_data,
size_t  image_data_size,
int  width,
int  height,
int  bpc,
ColorSpace  color_space,
SDF::Obj  encoder_hints = 0 
) [static]

Create and embed an Image.

Embed the raw image data taking into account specified compression hints.

By default the function will compress all images using Flate compression. It is possible to fine tune compression or to select a different compression algorithm using 'encoder_hints' object.

Returns:
PDF::Image object representing the embedded image.
Parameters:
doc - A document to which the image should be added. The 'Doc' object can be obtained using Obj::GetDoc() or PDFDoc::GetSDFDoc().
image_data - The stream or buffer containing image data. The image data must not be compressed and must follow PDF format for sample representation (please refer to section 4.8.2 'Sample Representation' in PDF Reference Manual for details).
width - The width of the image, in samples.
height - The height of the image, in samples.
bpc - The number of bits used to represent each color component.
color_space - The color space in which image samples are represented.
encoder_hints - An optional parameter that can be used to fine tune compression or to select a different compression algorithm. See Image::Create() for details.

static Image pdftron::PDF::Image::Create ( SDF::SDFDoc doc,
Filters::FilterReader image_data,
int  width,
int  height,
int  bpc,
ColorSpace  color_space,
SDF::Obj  encoder_hints = 0 
) [static]

Create and embed an Image.

Embed the raw image data taking into account specified compression hints.

Note:
see Image::Create for details.

static Image pdftron::PDF::Image::Create ( SDF::SDFDoc doc,
Gdiplus::Bitmap *  bmp,
SDF::Obj  encoder_hints = 0 
) [static]

Create and embed an Image from any GDI+ Bitmap taking into account specified compression hints.

Note:
see Image::Create for details.

This method is available only on Windows platforms.

Parameters:
doc - A document to which the image should be added. The 'Doc' object can be obtained using Obj::GetDoc() or PDFDoc::GetSDFDoc().
bmp - GDI+ bitmap.
Returns:
PDF::Image object representing the embedded image.

static Image pdftron::PDF::Image::CreateImageMask ( SDF::SDFDoc doc,
const char *  image_data,
size_t  image_data_size,
int  width,
int  height,
SDF::Obj  encoder_hints = 0 
) [static]

Create and embed an ImageMask.

Embed the raw image data taking into account specified compression hints. The ImageMask can be used as a stencil mask for painting in the current color or as an explicit mask specifying which areas of the image to paint and which to mask out. One of the most important uses of stencil masking is for painting character glyphs represented as bitmaps.

Returns:
PDF::Image object representing the embedded ImageMask.
Parameters:
doc - A document to which the image should be added. The 'Doc' object can be obtained using Obj::GetDoc() or PDFDoc::GetSDFDoc().
image_data - The stream or buffer containing image data stored in 1 bit per sample format. The image data must not be compressed and must follow PDF format for sample representation (please refer to section 4.8.2 'Sample Representation' in PDF Reference Manual for details).
width - The width of the image, in samples.
height - The height of the image, in samples.
encoder_hints - An optional parameter that can be used to fine tune compression or to select a different compression algorithm. See Image::Create() for details.

static Image pdftron::PDF::Image::CreateImageMask ( SDF::SDFDoc doc,
Filters::FilterReader image_data,
int  width,
int  height,
SDF::Obj  encoder_hints = 0 
) [static]

Create and embed an ImageMask.

Note:
see Image::CreateImageMask for details.

static Image pdftron::PDF::Image::CreateSoftMask ( SDF::SDFDoc doc,
const char *  image_data,
size_t  image_data_size,
int  width,
int  height,
int  bpc,
SDF::Obj  encoder_hints = 0 
) [static]

Create and embed a Soft Mask.

Embed the raw image data taking into account specified compression hints.

Parameters:
A soft-mask image (see “Soft-Mask Images” in PDF Reference Manual) to be used as a source of mask shape or mask opacity values in the transparent imaging model.
doc - A document to which the image should be added. The 'Doc' object can be obtained using Obj::GetDoc() or PDFDoc::GetSDFDoc().
image_data - The stream or buffer containing image data represented in DeviceGray color space (i.e. one component per sample). The image data must not be compressed and must follow PDF format for sample representation (please refer to section 4.8.2 'Sample Representation' in PDF Reference Manual for details).
width - The width of the image, in samples.
height - The height of the image, in samples.
bpc - The number of bits used to represent each color component.
encoder_hints - An optional parameter that can be used to fine tune compression or to select a different compression algorithm. See Image::Create() for details.
Note:
this feature is available only in PDF 1.4 and higher.

static Image pdftron::PDF::Image::CreateSoftMask ( SDF::SDFDoc doc,
Filters::FilterReader image_data,
int  width,
int  height,
int  bpc,
SDF::Obj  encoder_hints = 0 
) [static]

Create and embed a Soft Mask.

Embed the raw image data taking into account specified compression hints.

Note:
see Image::CreateSoftMask for details.

static Image pdftron::PDF::Image::Create ( SDF::SDFDoc doc,
const char *  image_data,
size_t  image_data_size,
int  width,
int  height,
int  bpc,
ColorSpace  color_space,
InputFilter  input_format 
) [static]

Directly embed the image that is already compressed using the Image::InputFilter format.

The function can be used to pass-through pre-compressed image data.

Returns:
PDF::Image object representing the embedded image.
Parameters:
doc - A document to which the image should be added. The 'Doc' object can be obtained using Obj::GetDoc() or PDFDoc::GetSDFDoc().
image_data - The stream or buffer containing compressed image data. The compression format must match the input_format parameter.
width - The width of the image, in samples.
height - The height of the image, in samples.
bpc - The number of bits used to represent each color component.
color_space - The color space in which image samples are specified.
input_format - Image::InputFilter describing the format of pre-compressed image data.
encoder_hints - An optional parameter that can be used to fine tune compression or to select a different compression algorithm. See Image::Create() for details.

static Image pdftron::PDF::Image::Create ( SDF::SDFDoc doc,
Filters::FilterReader image_data,
int  width,
int  height,
int  bpc,
ColorSpace  color_space,
InputFilter  input_format 
) [static]

Embed the raw image data taking into account specified compression hints.

Note:
see the above method for details.

Image& pdftron::PDF::Image::operator= ( const Image  ) 

SDF::Obj pdftron::PDF::Image::GetSDFObj (  )  const

Returns:
the underlying SDF/Cos object

bool pdftron::PDF::Image::IsValid (  )  const

Returns:
whether this is a valid raster image. If the function returns false the underlying SDF/Cos object is not a valid raster image and this Image object should be treated as null.

Filters::Filter pdftron::PDF::Image::GetImageData (  )  const

Returns:
A stream (filter) containing decoded image data

int pdftron::PDF::Image::GetImageDataSize (  )  const

Returns:
the size of image data in bytes

Gdiplus::Bitmap* pdftron::PDF::Image::GetBitmap (  )  const

Convert PDF image to GDI+ Bitmap.

Returns:
GDI+ bitmap from this image. PDFNet creates a GDI+ bitmap that closely matches the original image in terms of the image depth and the number of color channels. PDF color spaces that do not have a counterpart in GDI+ are converted to RGB.
Note:
This method is available only on Windows platforms.

ColorSpace pdftron::PDF::Image::GetImageColorSpace (  )  const

Returns:
The SDF object representing the color space in which image samples are specified or NULL if:
  • the image is an image mask
  • or is compressed using JPXDecode with missing ColorSpace entry in image dictionary.
The returned color space may be any type of color space except Pattern.

int pdftron::PDF::Image::GetImageWidth (  )  const

Returns:
the width of the image, in samples.

int pdftron::PDF::Image::GetImageHeight (  )  const

Returns:
the height of the image, in samples.

SDF::Obj pdftron::PDF::Image::GetDecodeArray (  )  const

Returns:
Decode array or NULL if the parameter is not specified. A decode object is an array of numbers describing how to map image samples into the range of values appropriate for the images color space . If ImageMask is true, the array must be either [0 1] or [1 0]; otherwise, its length must be twice the number of color components required by ColorSpace. Default value depends on the color space, See Table 4.36 in PDF Ref. Manual.

int pdftron::PDF::Image::GetBitsPerComponent (  )  const

Returns:
the number of bits used to represent each color component. Only a single value may be specified; the number of bits is the same for all color components. Valid values are 1, 2, 4, 8, and 16.

int pdftron::PDF::Image::GetComponentNum (  )  const

Returns:
the number of color components per sample.

bool pdftron::PDF::Image::IsImageMask (  )  const

Returns:
a boolean indicating whether the inline image is to be treated as an image mask.

bool pdftron::PDF::Image::IsImageInterpolate (  )  const

Returns:
a boolean indicating whether image interpolation is to be performed.

SDF::Obj pdftron::PDF::Image::GetMask (  )  const

Returns:
an image XObject defining an image mask to be applied to this image (See 'Explicit Masking', 4.8.5), or an array specifying a range of colors to be applied to it as a color key mask (See 'Color Key Masking').
If IsImageMask() return true, this method will return NULL.

void pdftron::PDF::Image::SetMask ( Image image_mask  ) 

Set an Explicit Image Mask.

Parameters:
An Image object which serves as an explicit mask for the base (this) image. The base image and the image mask need not have the same resolution (Width and Height values), but since all images are defined on the unit square in user space, their boundaries on the page will coincide; that is, they will overlay each other. The image mask indicates which places on the page are to be painted and which are to be masked out (left unchanged). Unmasked areas are painted with the corresponding portions of the base image; masked areas are not.
Note:
image_mask must be a valid image mask (i.e. image_mask.IsImageMask() must return true.

void pdftron::PDF::Image::SetMask ( SDF::Obj  mask  ) 

Set a Color Key Mask.

Parameters:
mask is an Cos/SDF array specifying a range of colors to be masked out. Samples in the image that fall within this range are not painted, allowing the existing background to show through. The effect is similar to that of the video technique known as chroma-key. For details of the array format please refer to section 4.8.5 'Color Key Masking' in PDF Reference Manual.
Note:
the current document takes the ownership of the given SDF object.

SDF::Obj pdftron::PDF::Image::GetSoftMask (  ) 

Returns:
an image XObject defining a Soft Mask to be applied to this image (See section 7.5.4 'Soft-Mask Images' in PDF Reference Manual), or NULL if the image does not have the soft mask.

void pdftron::PDF::Image::SetSoftMask ( Image soft_mask  ) 

Set a Soft Mask.

Parameters:
soft_mask is a subsidiary Image object defining a soft-mask image (See section 7.5.4 'Soft-Mask Images' in PDF Reference Manual) to be used as a source of mask shape or mask opacity values in the transparent imaging model. The alpha source parameter in the graphics state determines whether the mask values are interpreted as shape or opacity.

GState::RenderingIntent pdftron::PDF::Image::GetImageRenderingIntent (  )  const

Returns:
The color rendering intent to be used in rendering the image.

int pdftron::PDF::Image::Export ( const UString filename  ) 

Saves this image to a file.

The output image format (TIFF, JPEG, or PNG) will be automatically selected based on the properties of the embedded image. For example, if the embedded image is using CCITT Fax compression, the output format will be TIFF. Similarly, if the embedded image is using JPEG compression the output format will be JPEG. If your application needs to explicitly control output image format you may want to use ExportAsTiff() or ExportAsPng().

Parameters:
filename string that specifies the path name for the saved image. The filename should not include the extension which will be appended to the filename string based on the output format.
Returns:
the number indicating the selected image format: (0 - PNG, 1 - TIF, 2 - JPEG).

int pdftron::PDF::Image::Export ( Filters::FilterWriter writer  ) 

Saves this image to the output stream.

Returns:
the number indicating the selected image format: (0 - PNG, 1 - TIF, 2 - JPEG).
Parameters:
writer A pointer to FilterWriter used to write to the output stream. If the parameter is null, nothing will be written to the output stream, but the function returns the format identifier.
Note:
see the overloaded Image::Export method for more information.

void pdftron::PDF::Image::ExportAsTiff ( const UString filename  ) 

Saves this image to a TIFF file.

Parameters:
filename string that specifies the path name for the saved image. The filename should include the file extension

void pdftron::PDF::Image::ExportAsTiff ( Filters::FilterWriter writer  ) 

Saves this image to a TIFF output stream.

Parameters:
writer FilterWriter used to write to the output stream.

void pdftron::PDF::Image::ExportAsPng ( const UString filename  ) 

Saves this image to a PNG file.

Parameters:
filename string that specifies the path name for the saved image. The filename should include the file extension

void pdftron::PDF::Image::ExportAsPng ( Filters::FilterWriter writer  ) 

Saves this image to a PNG output stream.

Parameters:
writer FilterWriter used to write to the output stream.


© 2002-2010 PDFTron Systems Inc.