PTImage

@interface PTImage : NSObject

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()) )

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

    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.

    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.

    Declaration

    Objective-C

    + (PTImage *)CreateWithFile:(PTSDFDoc *)doc
                   filename:(NSString *)filename
              encoder_hints:(PTObj *)encoder_hints;

    Swift

    class func create(withFile doc: PTSDFDoc!, filename: String!, encoder_hints: PTObj!) -> PTImage!

    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 filter. Note that JBIG2 compression is not recommended for use on scanned text/financial documents or equivalent since its lossless nature can lead to similar looking numbers or characters being replaced.
    • [/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 range from 0.4 to 0.9. Increasing the threshold value will increase 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.
    • [/CCITT] - Compress a monochrome (i.e. bpc == 1) image using CCITT Group 4 compression. This algorithm typically produces larger output than JBIG2, but is lossless. This makes it much more suitable for scanned text documents. CCITT is the best option for more general monochrome compression use cases, since JBIG2 has potential to change image content.
    • [/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.
    • [/JPEG2000] - Use JPEG2000 compression to compress a RGB or a grayscale image.
    • [/JP2] - Use JPEG2000 compression with JP2 encoding. JP2 does not support CMYK images.
    • [/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.

    Return Value

    PDF::Image object representing the embedded image.

  • 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.

    Declaration

    Objective-C

    + (PTImage *)Create:(PTSDFDoc *)doc filename:(NSString *)filename;

    Swift

    class func create(_ doc: PTSDFDoc!, filename: String!) -> PTImage!

    Parameters

    doc

    - A document to which the image should be added. The ‘Doc’ object can be obtained using Obj::GetDoc() or PDFDoc::GetSDFDoc().
    buf

    - 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.

    Return Value

    PDF::Image object representing the embedded image.

  • Create and embed an Image. Embed the raw image data taking into account specified compression hints.

    Note

    see Image::Create for details.

    Declaration

    Objective-C

    + (PTImage *)CreateWithData:(PTSDFDoc *)doc
                        buf:(NSData *)buf
                   buf_size:(unsigned long)buf_size
                      width:(int)width
                     height:(int)height
                        bpc:(int)bpc
                color_space:(PTColorSpace *)color_space
              encoder_hints:(PTObj *)encoder_hints;

    Swift

    class func create(withData doc: PTSDFDoc!, buf: Data!, buf_size: UInt, width: Int32, height: Int32, bpc: Int32, color_space: PTColorSpace!, encoder_hints: PTObj!) -> PTImage!

  • Create and embed an Image. Embed the raw image data taking into account specified compression hints.

    Note

    see Image::Create for details.

    Declaration

    Objective-C

    + (PTImage *)CreateWithFilterData:(PTSDFDoc *)doc
                       image_data:(PTFilterReader *)image_data
                            width:(int)width
                           height:(int)height
                              bpc:(int)bpc
                      color_space:(PTColorSpace *)color_space
                    encoder_hints:(PTObj *)encoder_hints;

    Swift

    class func create(withFilterData doc: PTSDFDoc!, image_data: PTFilterReader!, width: Int32, height: Int32, bpc: Int32, color_space: PTColorSpace!, encoder_hints: PTObj!) -> PTImage!

  • Create and embed an Image. Embed the raw image data taking into account specified compression hints.

    Note

    see Image::Create for details.

    Note

    PDFNet takes ownership of the filter

    Declaration

    Objective-C

    + (PTImage *)CreateWithDataSimple:(PTSDFDoc *)doc
                              buf:(NSData *)buf
                         buf_size:(unsigned long)buf_size
                    encoder_hints:(PTObj *)encoder_hints;

    Swift

    class func create(withDataSimple doc: PTSDFDoc!, buf: Data!, buf_size: UInt, encoder_hints: PTObj!) -> PTImage!

  • Undocumented

    Declaration

    Objective-C

    + (PTImage*)CreateWithFilterDataSimple: (PTSDFDoc*)doc image_data:  (PTFilter*)image_data encoder_hints:  (PTObj*)encoder_hints;

    Swift

    class func create(withFilterDataSimple doc: PTSDFDoc!, image_data: PTFilter!, encoder_hints: PTObj!) -> PTImage!

  • 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.

    Declaration

    Objective-C

    + (PTImage *)CreateImageMaskWithBuffer:(PTSDFDoc *)doc
                                   buf:(NSData *)buf
                              buf_size:(unsigned long)buf_size
                                 width:(int)width
                                height:(int)height
                         encoder_hints:(PTObj *)encoder_hints;

    Swift

    class func createImageMask(withBuffer doc: PTSDFDoc!, buf: Data!, buf_size: UInt, width: Int32, height: Int32, encoder_hints: PTObj!) -> PTImage!

    Parameters

    doc

    - A document to which the image should be added. The ‘Doc’ object can be obtained using Obj::GetDoc() or PDFDoc::GetSDFDoc().
    buf

    - 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.

    Return Value

    PDF::Image object representing the embedded ImageMask.

  • Create and embed an ImageMask.

    Note

    see Image::CreateImageMask for details.

    Declaration

    Objective-C

    + (PTImage *)CreateImageMask:(PTSDFDoc *)doc
                         buf:(NSData *)buf
                    buf_size:(unsigned long)buf_size
                       width:(int)width
                      height:(int)height;

    Swift

    class func createImageMask(_ doc: PTSDFDoc!, buf: Data!, buf_size: UInt, width: Int32, height: Int32) -> PTImage!

  • Undocumented

    Declaration

    Objective-C

    + (PTImage*)CreateImageMaskWithStream: (PTSDFDoc*)doc image_data:  (PTFilterReader*)image_data width:  (int)width height:  (int)height encoder_hints:  (PTObj*)encoder_hints;

    Swift

    class func createImageMask(withStream doc: PTSDFDoc!, image_data: PTFilterReader!, width: Int32, height: Int32, encoder_hints: PTObj!) -> PTImage!

  • Create and embed a Soft Mask. Embed the raw image data taking into account specified compression hints. A soft-mask image (see “Soft-Mask Images” in PDF Reference Manual) is used as a source of mask shape or mask opacity values in the transparent imaging model.

    Note

    this feature is available only in PDF 1.4 and higher.

    Declaration

    Objective-C

    + (PTImage *)CreateSoftMaskWithBuffer:(PTSDFDoc *)doc
                                  buf:(NSData *)buf
                             buf_size:(unsigned long)buf_size
                                width:(int)width
                               height:(int)height
                                  bpc:(int)bpc
                        encoder_hints:(PTObj *)encoder_hints;

    Swift

    class func createSoftMask(withBuffer doc: PTSDFDoc!, buf: Data!, buf_size: UInt, width: Int32, height: Int32, bpc: Int32, encoder_hints: PTObj!) -> PTImage!

    Parameters

    doc

    - A document to which the image should be added. The ‘Doc’ object can be obtained using Obj::GetDoc() or PDFDoc::GetSDFDoc().
    buf

    - 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.

  • Create and embed a Soft Mask. Embed the raw image data taking into account specified compression hints.

    Note

    see Image::CreateSoftMask for details.

    Declaration

    Objective-C

    + (PTImage *)CreateSoftMask:(PTSDFDoc *)doc
                        buf:(NSData *)buf
                   buf_size:(unsigned long)buf_size
                      width:(int)width
                     height:(int)height
                        bpc:(int)bpc;

    Swift

    class func createSoftMask(_ doc: PTSDFDoc!, buf: Data!, buf_size: UInt, width: Int32, height: Int32, bpc: Int32) -> PTImage!

  • 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.

    Declaration

    Objective-C

    + (PTImage *)CreateSoftMaskWithStream:(PTSDFDoc *)doc
                           image_data:(PTFilterReader *)image_data
                                width:(int)width
                               height:(int)height
                                  bpc:(int)bpc
                        encoder_hints:(PTObj *)encoder_hints;

    Swift

    class func createSoftMask(withStream doc: PTSDFDoc!, image_data: PTFilterReader!, width: Int32, height: Int32, bpc: Int32, encoder_hints: PTObj!) -> PTImage!

    Parameters

    doc

    - A document to which the image should be added. The ‘Doc’ object can be obtained using Obj::GetDoc() or PDFDoc::GetSDFDoc().
    buf

    - 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.

    Return Value

    PDF::Image object representing the embedded image.

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

    Note

    see the above method for details.

    Declaration

    Objective-C

    + (PTImage *)CreateWithStreamAndFormat:(PTSDFDoc *)doc
                            image_data:(PTFilterReader *)image_data
                                 width:(int)width
                                height:(int)height
                                   bpc:(int)bpc
                           color_space:(PTColorSpace *)color_space
                          input_format:(PTInputFilter)input_format;

    Swift

    class func create(withStreamAndFormat doc: PTSDFDoc!, image_data: PTFilterReader!, width: Int32, height: Int32, bpc: Int32, color_space: PTColorSpace!, input_format: PTInputFilter) -> PTImage!

  • 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()))

    Declaration

    Objective-C

    - (instancetype)initWithImage_xobject:(PTObj *)image_xobject;

    Swift

    init!(image_xobject: PTObj!)

  • Declaration

    Objective-C

    - (PTObj *)GetSDFObj;

    Swift

    func getSDFObj() -> PTObj!

    Return Value

    the underlying SDF/Cos object

  • Declaration

    Objective-C

    - (BOOL)IsValid;

    Swift

    func isValid() -> Bool

    Return Value

    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.

  • Declaration

    Objective-C

    - (PTFilter *)GetImageData;

    Swift

    func getData() -> PTFilter!

    Return Value

    A stream (filter) containing decoded image data

  • Declaration

    Objective-C

    - (int)GetImageDataSize;

    Swift

    func getDataSize() -> Int32

    Return Value

    the size of image data in bytes

  • The returned color space may be any type of color space except Pattern.

    Declaration

    Objective-C

    - (PTColorSpace *)GetImageColorSpace;

    Swift

    func getColorSpace() -> PTColorSpace!

    Return Value

    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.

  • Declaration

    Objective-C

    - (int)GetImageWidth;

    Swift

    func getWidth() -> Int32

    Return Value

    the width of the image, in samples.

  • Declaration

    Objective-C

    - (int)GetImageHeight;

    Swift

    func getHeight() -> Int32

    Return Value

    the height of the image, in samples.

  • Declaration

    Objective-C

    - (PTObj *)GetDecodeArray;

    Swift

    func getDecodeArray() -> PTObj!

    Return Value

    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.

  • Declaration

    Objective-C

    - (int)GetBitsPerComponent;

    Swift

    func getBitsPerComponent() -> Int32

    Return Value

    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.

  • Declaration

    Objective-C

    - (int)GetComponentNum;

    Swift

    func getComponentNum() -> Int32

    Return Value

    the number of color components per sample.

  • Declaration

    Objective-C

    - (BOOL)IsImageMask;

    Swift

    func isImageMask() -> Bool

    Return Value

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

  • Declaration

    Objective-C

    - (BOOL)IsImageInterpolate;

    Swift

    func isImageInterpolate() -> Bool

    Return Value

    a boolean indicating whether image interpolation is to be performed.

  • If IsImageMask() return true, this method will return NULL.

    Declaration

    Objective-C

    - (PTObj *)GetMask;

    Swift

    func getMask() -> PTObj!

    Return Value

    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’).

  • Set an Explicit Image Mask.

    Note

    image_mask must be a valid image mask (i.e. image_mask.IsImageMask() must return true.

    Declaration

    Objective-C

    - (void)SetMaskWithImage:(PTImage *)image_mask;

    Swift

    func setMaskWith(_ image_mask: PTImage!)

    Parameters

    image_mask

    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.

  • Set a Color Key Mask.

    Note

    the current document takes the ownership of the given SDF object.

    Declaration

    Objective-C

    - (void)SetMaskWithColor:(PTObj *)mask;

    Swift

    func setMaskWithColor(_ mask: PTObj!)

    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.

  • Declaration

    Objective-C

    - (PTObj *)GetSoftMask;

    Swift

    func getSoftMask() -> PTObj!

    Return Value

    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.

  • Set a Soft Mask.

    Declaration

    Objective-C

    - (void)SetSoftMask:(PTImage *)soft_mask;

    Swift

    func setSoftMask(_ soft_mask: PTImage!)

    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.

  • Declaration

    Objective-C

    - (PTRenderingIntent)GetImageRenderingIntent;

    Swift

    func getRenderingIntent() -> PTRenderingIntent

    Return Value

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

  • 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().

    Declaration

    Objective-C

    - (int)ExportToFile:(NSString *)filename;

    Swift

    func export(toFile filename: String!) -> Int32

    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.

    Return Value

    the number indicating the selected image format: (0 - PNG, 1 - TIF, 2 - JPEG).

  • Saves this image to the output stream. (0 - PNG, 1 - TIF, 2 - JPEG).

    Note

    see the overloaded Image::Export method for more information.

    Declaration

    Objective-C

    - (int)ExportToStream:(PTFilterWriter *)writer;

    Swift

    func export(toStream writer: PTFilterWriter!) -> Int32

    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.

    Return Value

    the number indicating the selected image format:

  • Saves this image to a TIFF file.

    Declaration

    Objective-C

    - (void)ExportAsTiffFile:(NSString *)filename;

    Swift

    func export(asTiffFile filename: String!)

    Parameters

    filename

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

  • Saves this image to a TIFF output stream.

    Declaration

    Objective-C

    - (void)ExportAsTiffStream:(PTFilterWriter *)writer;

    Swift

    func export(asTiffStream writer: PTFilterWriter!)

    Parameters

    writer

    FilterWriter used to write to the output stream.

  • Saves this image to a PNG file.

    Declaration

    Objective-C

    - (void)ExportAsPngFile:(NSString *)filename;

    Swift

    func export(asPngFile filename: String!)

    Parameters

    filename

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

  • Saves this image to a PNG output stream.

    Declaration

    Objective-C

    - (void)ExportAsPngStream:(PTFilterWriter *)writer;

    Swift

    func export(asPngStream writer: PTFilterWriter!)

    Parameters

    writer

    FilterWriter used to write to the output stream.