PTPDFDraw

@interface PTPDFDraw : NSObject

PDFDraw contains methods for converting PDF pages to images and to Bitmap objects. Utility methods are provided to export PDF pages to various raster formats as well as to convert pages to GDI+ bitmaps for further manipulation or drawing.

Note

This class is available on all platforms supported by PDFNet.

  • PDFDraw constructor and destructor

    Declaration

    Objective-C

    - (instancetype)initWithDpi:(double)dpi;

    Swift

    init!(dpi: Double)

    Parameters

    dpi

    - Default resolution used to rasterize pages. If the parameter is not specified, the initial resolution is 92 dots per inch. DPI parameter can be modified at any time using PDFDraw::SetDPI() method.

  • Sets the core graphics library used for rasterization and rendering. Using this method it is possible to quickly switch between different implementations. By default, PDFDraw uses the built-in, platform independent rasterizer.

    Note

    This method is deprecated, since the GDI+ rasterizer itself is deprecated and will be removed in a future version of PDFNet. It is strongly recommended to use the built-in rasterizer and to use the XPS print path where vector conversion is needed.

    Declaration

    Objective-C

    - (void)SetRasterizerType:(PTRasterizerType)type;

    Swift

    func setRasterizerType(_ type: PTRasterizerType)

    Parameters

    type

    Rasterizer type.

  • Sets the output image resolution.

    DPI stands for Dots Per Inch. This parameter is used to specify the output image size and quality. A typical screen resolution for monitors these days is 92 DPI, but printers could use 200 DPI or more.

    Note

    The size of resulting image is a function of DPI and the dimensions of the source PDF page. For example, if DPI is 92 and page is 8 inches wide, the output bitmap will have 92*8 = 736 pixels per line. If you know the dimensions of the destination bitmap, but don’t care about DPI of the image you can use pdfdraw.SetImageSize() instead.

    Note

    if you would like to rasterize extremely large bitmaps (e.g. with resolutions of 2000 DPI or more) it is not practical to use PDFDraw directly because of the memory required to store the entire image. In this case, you can use PDFRasterizer directly to generate the rasterized image in stripes or tiles.

    Declaration

    Objective-C

    - (void)SetDPI:(double)dpi;

    Swift

    func setDPI(_ dpi: Double)

    Parameters

    dpi

    value to set the image resolution to. Higher value = higher resolution.

  • SetImageSize can be used instead of SetDPI() to adjust page scaling so that image fits into a buffer of given dimensions.

    If this function is used, DPI will be calculated dynamically for each page so that every page fits into the buffer of given dimensions.

    Declaration

    Objective-C

    - (void)SetImageSize:(int)width
                   height:(int)height
    preserve_aspect_ratio:(BOOL)preserve_aspect_ratio;

    Swift

    func setImageSize(_ width: Int32, height: Int32, preserve_aspect_ratio: Bool)

    Parameters

    width

    - The width of the image, in pixels/samples.
    height

    - The height of the image, in pixels/samples.
    preserve_aspect_ratio

    - True to preserve the aspect ratio, false otherwise. By default, preserve_aspect_ratio is true.

  • Selects the page box/region to rasterize.

    Declaration

    Objective-C

    - (void)SetPageBox:(PTBox)region;

    Swift

    func setPageBox(_ region: PTBox)

    Parameters

    region

    Page box to rasterize. By default, PDFDraw will rasterize page crop box.

  • clip the render region to the provided rect (in page space)

    Declaration

    Objective-C

    - (void)SetClipRect:(PTPDFRect *)clip_rect;

    Swift

    func setClipRect(_ clip_rect: PTPDFRect!)

    Parameters

    clip_rect

    clipping rect. By default, PDFDraw will rasterize the entire page box.

  • Flips the vertical (i.e. Y) axis of the image.

    Declaration

    Objective-C

    - (void)SetFlipYAxis:(BOOL)flip_y;

    Swift

    func setFlipYAxis(_ flip_y: Bool)

    Parameters

    flip_y

    true to flip the Y axis, false otherwise. For compatibility with most raster formats ‘flip_y’ is true by default.

  • Sets the rotation value for this page.

    Note

    This method is used only for drawing purposes and it does not modify the document (unlike Page::SetRotate()).

    Declaration

    Objective-C

    - (void)SetRotate:(PTRotate)r;

    Swift

    func setRotate(_ r: PTRotate)

    Parameters

    r

    Rotation value to be set for a given page. Must be one of the Page::Rotate values.

  • Enable or disable annotation and forms rendering. By default, all annotations and form fields are rendered.

    Declaration

    Objective-C

    - (void)SetDrawAnnotations:(BOOL)render_annots;

    Swift

    func setDrawAnnotations(_ render_annots: Bool)

    Parameters

    render_annots

    True to draw annotations, false otherwise.

  • Enable or disable highlighting form fields. Default is disabled.

    Declaration

    Objective-C

    - (void)SetHighlightFields:(BOOL)highlight_fields;

    Swift

    func setHighlightFields(_ highlight_fields: Bool)

    Parameters

    highlight_fields

    true to highlight, false otherwise.

  • Enable or disable drawing ui elements. Default is disabled.

    Declaration

    Objective-C

    - (void)SetDrawUIElements:(BOOL)draw_ui_elements;

    Swift

    func setDrawUIElements(_ draw_ui_elements: Bool)

    Parameters

    draw_ui_elements

    true to draw ui elements, false otherwise.

  • Enable or disable anti-aliasing.

    Anti-Aliasing is a technique used to improve the visual quality of images when displaying them on low resolution devices (for example, low DPI computer monitors).

    Declaration

    Objective-C

    - (void)SetAntiAliasing:(BOOL)enable_aa;

    Swift

    func setAntiAliasing(_ enable_aa: Bool)

    Parameters

    enable_aa

    if true anti-aliasing will be enabled. @default Anti-aliasing is enabled by default.

  • Enable or disable path hinting.

    Declaration

    Objective-C

    - (void)SetPathHinting:(BOOL)enable_hinting;

    Swift

    func setPathHinting(_ enable_hinting: Bool)

    Parameters

    enable_hinting

    if true path hinting will be enabled. Path hinting is used to slightly adjust paths in order to avoid or alleviate artifacts of hair line cracks between certain graphical elements. This option is turned on by default.

  • Set thin line adjustment parameters.

    Declaration

    Objective-C

    - (void)SetThinLineAdjustment:(BOOL)pixel_grid_fit
                stroke_adjust:(BOOL)stroke_adjust;

    Swift

    func setThinLineAdjustment(_ pixel_grid_fit: Bool, stroke_adjust: Bool)

    Parameters

    pixel_grid_fit

    if true (horizontal/vertical) thin lines will be snapped to integer pixel positions. This helps make thin lines look sharper and clearer. This option is turned off by default and it only works if path hinting is enabled.
    stroke_adjust

    if true auto stroke adjustment is enabled. Currently, this would make lines with sub-pixel width to be one-pixel wide. This option is turned on by default.

  • This setting controls the thickness of zero-width lines when rendered. In a PDF, a line width of zero denotes the thinnest line that can be rendered at device resolution: 1 device pixel wide. However, on high-resolution devices, a single pixel can be nearly invisible.

    Declaration

    Objective-C

    - (void)SetThinLineScaling:(double)scaling;

    Swift

    func setThinLineScaling(_ scaling: Double)

    Parameters

    scaling

    use this setting to increase the apparent thickness of these zero-width lines. @default 1.0 (1 pixel wide)

  • Enable or disable image smoothing.

    The rasterizer allows a tradeoff between rendering quality and rendering speed. This function can be used to indicate the preference between rendering speed and quality.

    Note

    image smoothing option has effect only if the source image has higher resolution that the output resolution of the image on the rasterized page. PDFNet automatically controls at what resolution/zoom factor, ‘image smoothing’ needs to take effect.

    Declaration

    Objective-C

    - (void)SetImageSmoothing:(BOOL)smoothing_enabled
      hq_image_resampling:(BOOL)hq_image_resampling;

    Swift

    func setImageSmoothing(_ smoothing_enabled: Bool, hq_image_resampling: Bool)

    Parameters

    smoothing_enabled

    True to enable image smoothing, false otherwise.
    hq_image_resampling

    True to use a higher quality (but slower) smoothing algorithm @default image smoothing is enabled and hq_image_resampling is false.

  • Enables or disables caching. Caching can improve the rendering performance in cases where the same page will be drawn multiple times.

    Declaration

    Objective-C

    - (void)SetCaching:(BOOL)enabled;

    Swift

    func setCaching(_ enabled: Bool)

    Parameters

    enabled

    - if true PDFRasterizer will cache frequently used graphics objects.

  • Sets the gamma factor used for anti-aliased rendering.

    Gamma correction can be used to improve the quality of anti-aliased image output and can (to some extent) decrease the appearance common anti-aliasing artifacts (such as pixel width lines between polygons).

    Note

    Gamma correction is used only in the built-in rasterizer.

    Declaration

    Objective-C

    - (void)SetGamma:(double)exp;

    Swift

    func setGamma(_ exp: Double)

    Parameters

    exp

    is the exponent value of gamma function. Typical values are in the range from 0.1 to 3.

  • Sets the Optional Content Group (OCG) context that should be used when rendering the page. This function can be used to selectively render optional content (such as PDF layers) based on the states of optional content groups in the given context.

    Declaration

    Objective-C

    - (void)SetOCGContext:(PTContext *)ctx;

    Swift

    func setOCGContext(_ ctx: PTContext!)

    Parameters

    ctx

    Optional Content Group (OCG) context, or NULL if the rasterizer should render all content on the page.

  • Tells the rasterizer to render the page ‘print’ mode. Certain page elements (such as annotations or OCG-s) are meant to be visible either on the screen or on the printed paper but not both. A common example, is the “Submit” button on electronic forms.

    Declaration

    Objective-C

    - (void)SetPrintMode:(BOOL)is_printing;

    Swift

    func setPrintMode(_ is_printing: Bool)

    Parameters

    is_printing

    set to true if the page should be rendered in print mode. @default By default, print mode flag is set to false.

  • Sets the default color of the page backdrop.

    @default By default, the page color is white.

    Note

    Only when the page backdrop is not set to transparent (SetPageTransparent), default page color is used.

    Declaration

    Objective-C

    - (void)SetDefaultPageColor:(unsigned char)r
                          g:(unsigned char)g
                          b:(unsigned char)b;

    Swift

    func setDefaultPageColor(_ r: UInt8, g: UInt8, b: UInt8)

    Parameters

    r

    the red component of the page backdrop color.
    g

    the green component of the page backdrop color.
    b

    the blue component of the page backdrop color.

  • Sets the page color to transparent.

    @default By default, PDFDraw assumes that the page is imposed directly on an opaque white surface. Some applications may need to impose the page on a different backdrop. In this case any pixels that are not covered during rendering will be transparent.

    Note

    If page transparency is enabled, the alpha channel will be preserved when the image is exported as PNG, TIFF(when in RGB space), or RAW.

    Declaration

    Objective-C

    - (void)SetPageTransparent:(BOOL)is_transparent;

    Swift

    func setPageTransparent(_ is_transparent: Bool)

    Parameters

    is_transparent

    If true, page’s backdrop color will be transparent. If false, the page’s backdrop will be a opaque white.

  • Enable or disable support for overprint and overprint simulation. Overprint is a device dependent feature and the results will vary depending on the output color space and supported colorants (i.e. CMYK, CMYK+spot, RGB, etc).

    @default By default overprint is only enabled for PDF/X files.

    Declaration

    Objective-C

    - (void)SetOverprint:(PTOverprintPreviewMode)op;

    Swift

    func setOverprint(_ op: PTOverprintPreviewMode)

    Parameters

    op

    e_op_on: always enabled; e_op_off: always disabled; e_op_pdfx_on: enabled for PDF/X files only.

  • A utility method to export the given PDF page to an image file.

    @encoder format - The file format of the output image. Currently supported formats are: - “RAW” : RAW format. There are four possibilities: e_rgba - if transparent and color page; e_gray_alpha - if transparent and gray page; e_rgb - if opaque and color page; e_gray - if opaque and gray page. NOTE that if page is set to be transparent (SetPageTransparent), the output color channels are already multiplied by the alpha channel. - “BMP” : Bitmap image format (BMP) - “JPEG” : Joint Photographic Experts Group (JPEG) image format - “PNG” : 24-bit W3C Portable Network Graphics (PNG) image format - “PNG8” : 8-bit, palettized PNG format. The exported file size should be smaller than the one generated using “PNG”, possibly at the expense of some image quality. - “TIFF” : Tag Image File Format (TIFF) image format. - “TIFF8” : Tag Image File Format (TIFF) image format (with 8-bit palete).

    By default, the function exports to PNG.

    Parameter/Key Output Format Description/Value Example
    Quality JPEG The value for compression ‘Quality’ must be a number between 0 and 100 specifying the tradeoff between compression ratio and loss in image quality. 100 stands for best quality.

    hint.PutNumber(“Quality”, 60);

    See the Example 2 in PDFDraw sample project.
    Dither PNG, PNG8, TIFF or TIFF8. A boolean used to enable or disable dithering. Relevent only for when the image is exported in palettized or monochrome mode. hint.PutBool(“Dither”, true);
    ColorSpace PNG or TIFF for grayscale; TIFF for CMYK; PNG, BMP, JPEG, or TIFF for Separation. A name object used to select the rendering and export color space. Currently supported values are “Gray”, “RGB, "CMYK”, and “Separation”. The output image format must support specified color space, otherwise the parameter will be ignored. An example of image format that supports CMYK is TIFF. Image formats that support grayscale are PNG and TIFF. Separation output is supported in either a single N-Channel TIFF, or in separate single-channel files (either PNG, BMP, or JPEG). Output in “Separation” space implies that overprint simulation is on. By default, the image is rendered and exported in RGB color space. hint.PutName(“ColorSpace”, “CMYK”);
    BPC PNG or TIFF. A number used to specify ‘bits per pixel’ in the output file. Currently supported values are 1 and 8 (default is 8). To export monochrome (1 bit per pixel) image, use 1 as the value of BPC parameter and use TIFF or PNG as the export format for the image. By default, the image is not dithered when BPC is 1. To enable dithering add ‘Dither’ option in the export hint. hint.PutNumber(“BPC”, 1);

    Declaration

    Objective-C

    - (void)ExportWithObj:(PTPage *)page
             filename:(NSString *)filename
               format:(NSString *)format
       encoder_params:(PTObj *)encoder_params;

    Swift

    func export(withObj page: PTPage!, filename: String!, format: String!, encoder_params: PTObj!)

    Parameters

    page

    The source PDF page.
    filename

    - The name of the output image file. The filename should include the extension suffix (e.g. ‘c:/output/myimage.png’).
    encoder_params

    - An optional SDF dictionary object containing key/value pairs representing optional encoder parameters. The following table list possible parameters for corresponding export filters:

  • Export the given PDF page to an image stream.

    Declaration

    Objective-C

    - (void)Export:(PTPage *)page
      filename:(NSString *)filename
        format:(NSString *)format;

    Swift

    func export(_ page: PTPage!, filename: String!, format: String!)

    Parameters

    page

    The source PDF page.
    stream

    - The output stream. @encoder format - The output image format. See the overloaded method for details.
    encoder_params

    - Optional encoder parameters. See the overloaded method for details.

  • Returns a GDI+ bitmap for the given page.

    Note

    this method is available on .NET platform.

    Declaration

    Objective-C

    - (PTBitmapInfo *)GetBitmap:(PTPage *)page
                    pix_fmt:(PTPixelFormat)pix_fmt
                     demult:(BOOL)demult;

    Swift

    func getBitmap(_ page: PTPage!, pix_fmt: PTPixelFormat, demult: Bool) -> PTBitmapInfo!

    Parameters

    page

    The source PDF page.

    Return Value

    GDI+ bitmap containing the rasterized image of the given page.

  • Returns a vector of rasterized separations for the given image.

    Note

    This method is relatively low-level and is only available in PDFNet for C++. If you are using PDFNet for .NET, you can use the function with the same name that directly returns GDI+ Bitmap.

    Declaration

    Objective-C

    - (NSMutableArray *)GetSeparationBitmaps:(PTPage *)page;

    Swift

    func getSeparationBitmaps(_ page: PTPage!) -> NSMutableArray!

    Parameters

    page

    The source PDF page.

    Return Value

    Separation has a pointer to the internal memory buffer containing the rasterized image of the given page. The buffer size is at least ‘out_height*out_stride’ bytes. The pixel data is stored in 8 bit per component, BGRA format.

  • Sets the error handling function to be called in case an error is encountered during page rendering.

    Declaration

    Objective-C

    - (void)SetErrorReportProc:(PTCallback *)instance;

    Swift

    func setErrorReportProc(_ instance: PTCallback!)

    Parameters

    error_proc

    Error handling callback function (or delegate in .NET)
    data

    Custom data to be passed as a second parameter to ‘error_proc’.

  • Set the color post processing transformation. This transform is applied to the rasterized bitmap as the final step in the rasterization process, and is applied directly to the resulting bitmap (disregarding any color space information). Color post processing only supported for RGBA output.

    Declaration

    Objective-C

    - (void)SetColorPostProcessMode:(PTColorPostProcessMode)mode;

    Swift

    func setColorPostProcessMode(_ mode: PTColorPostProcessMode)

    Parameters

    mode

    is the specific transform to be applied