PDF2IMG

Appendix: API Calls, C Language Interface

pdf2img_check_for_missing_appearances

(ImageConversion IC, int firstPage, Int lastPage)
Return Value: int
Description This call checks pages within the specified range for annotations or form fields that cannot be rendered. It returns a value greater than 0 if the page range contains non-renderable content or 0 if the page range does not contain non-renderable content.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
int firstPage: sequence number of first input file page to be inspected counting from 1
int lastPage: sequence number of last input file page to be inspected counting from 1
Return Value int
Exceptions
Header pdf2imglib.h
Related Methods
Availability All platforms

pdf2img_convert_page

(ImageConversion iC, unsigned int pageNum, const char *outputPath)
Return Value: int
Description This call converts the specified page of the PDF file. It writes into the file specified by outputPath.
Alternatively you can suppress writing an output file by passing a NULL in place of an output file argument and then use a pdf2img_get_pagemem call to load the converted graphic into memory.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
unsigned int pageNum: sequence number of input file page to be converted counting from 1
const char *outputPath: name of file to receive converted output or NULL
Return Value int
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_get_pagemem
pdf2img_get_pagememsize
pdf2img_release_pagemem
Availability All platforms
Technical Notes
  1. While a NULL argument will suppress writing an output file, note that a work file will be temporarily created during the conversion process.
  2. If the conversion is performed “in memory,” then the ImageConversion will hold the memory for the conversion until the next call to pdf2img_convert_page, or until pdf2img_release_pagemem is called.

pdf2img_destroy_conversion

(ImageConversion IC)
Return Value: int
Description This call frees the resources used by this image conversion. After this call has been made the ImageConversion is no longer valid and must not be used.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
Return Value int
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_new_conversion  
pdf2img_new_memconversion
Availability All platforms

pdf2img_end_multipage

(ImageConversion IC)
Return Value: int
Description This call ends a multipage image span.
Parameters ImageConversion iC: the data structure containing the specifications for the active current
conversion
Return Value int
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_set_multipage
pdf2img_start_multipage
Availability All platforms

pdf2img_error_string

(ImageConversion IC)
Return Value: const char *

Return Valueconst char *

Description This call returns an English-language string representing the last error encountered during PDF processing. Do not release this string.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
Return Value const char *
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_get_extended_error
pdf2img_last_error
Availability All platforms

pdf2img_get_extended_error

(ImageConversion IC)
Return Value: const char *
Description This call returns a text string indicating the last error that occurred in a sub-component of the application. Typically this is an error reported by the Adobe PDF Library.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
Return Value const char *
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_error_string
pdf2img_last_error
Availability All platforms

pdf2img_get_num_pages

(ImageConversion IC)
Return Value: int
Description This call returns the number of pages in the PDF file to be used for the image conversion.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
Return Value int: Number of pages to be converted. Returns -1 in case of error.
Exceptions
Header pdf2imglib.h
Related Methods
Availability All platforms

pdf2img_get_pagemem

(ImageConversion IC, void *memBuf, unsigned int bufCapacity)
Return Value: Int
Description After pdf2img_convert_page has converted a graphic into memory (by specifying NULL in place of
its outputPath argument) this pdf2img_get_pagemem call will copy those results into memBuf.
Note that memBuf is owned by the caller and must have been allocated to hold at least bufCapacity bytes.
The pdf2img_get_pagememsize  call can return the necessary size for this allocation.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
void *memBuf: buffer allocated to receive the image from memory
unsigned int bufCapacity: size of the allocated buffer
Return Value int
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_convert_page
pdf2img_get_pagememsize
pdf2img_release_pagemem
Availability All platforms

pdf2img_get_pagememsize

(ImageConversion IC)
Return Value: int
Description After pdf2img_convert_page  has converted a graphic into memory (by specifying NULL in place of its
outputPath argument) this call will return the number of bytes that will be required to hold the memory output.
Results of this call will be needed to allocate the correct amount of memory buffer for a subsequent call
to  pdf2img_release_pagemem.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
Return Value int: number of bytes required to hold the memory representing the graphic created by pdf2img_convert_page
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_convert_page
pdf2img_get_pagemem
pdf2img_release_pagemem
Availability All platforms

pdf2img_get_profiledata

(ImageConversion IC)
Return Value: char *
Description If an input image in memory contains a color profile this call will return a pointer to a string containing the
ICC Profile data (or NULL if a profile is not present).
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
Return Value char *: pointer to a string containing the ICC Profile data
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_get_profilesize
Availability All platforms

pdf2img_get_profilesize

(ImageConversion IC)
Return Value: size_t
Description If an input image in memory contains a color profile this call will return its size (or 0 if a profile is not present).
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
Return Value  size_t: the size of the ICC Profile data
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_get_profiledata
Availability All platforms

pdf2img_init

(const char *fontDirList[], unsigned int listLen)
Return Value: int
Description This calling argument initializes PDF2IMG before use. If used in a multi-threaded application each calling thread must do its own initialization before use.
Parameters const char *fontDirList[]: a list of null-terminated C strings containing directories in which PDF2IMG should search for fonts and font resources to use when rasterizing documents which have non-embedded fonts
unsigned int listLen: number of strings in this list
Return Value int
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_init_ex
pdf2img_term
Availability All platforms

pdf2img_init_ex

(PDF2IMGInitParams *pinitParams)
Return Value: int
Description This calling argument initializes PDF2IMG before use in the same manner as pdf2img_init.
If used in a multi-threaded application each calling thread must do its own initialization before use.
This argument is an alternative to the standard pdf2img_init call which scans default system font resource
locations as well as its current directory at startup time. That font scanning time can be quite significant
in some cases and this call offers the option of fine-tuning performance by suppressing the default scans
and by providing a specific list of locations to be scanned instead.
When the ignoreSysFonts and ignoreCurrentDirectory elements of its PDF2IMGInitParams argument
structure are set to true (they default to false) this call will search only the indicated font resource locations passed within the fontDirList element and no other locations.
Parameters PDF2IMGInitParams *pInitParams: structure for passing a list of font resource locations to be searched at startup
along with flag settings to prevent searching the current directory or the system fonts areas.
Return Value int
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_init
pdf2img_term
Availability All platforms

pdf2img_last_error

(ImageConversion IC)
Return Value: int
Description This call returns the last error number.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
Return Value int
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_get_extended_error
Availability All platforms

pdf2img_new_conversion

(const char *inPDFPath)
Return Value: imageConversion
Description This call creates a PDF-to-Image conversion. Each is local to the thread which makes this function call and should not be shared across threads.
Parameters const char *inPDFPath: path to location of input image file
Return Value ImageConversion
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_destroy_conversion
pdf2img_new_conversion_with_password
pdf2img_new_memconversion
pdf2img_new_memconversion_with_password
Availability All platforms
Technical Notes
  1. This call maintains an open file handle for the inPDFPath argument.
  2. Of the two calls pdf2img_new_conversion and pdf2img_new_memconversion, one or the other must be called to create an image conversion, but not both.

pdf2img_new_conversion_with_password

(const char *inPDFPath, const char *password)
Return Value: ImageConversion
Description This call creates a PDF-to-Image conversion using the supplied password. Each is local to the thread which makes this function call and should not be shared across threads.
Parameters const char *inPDFPath: path to location of input image file
const char *password: password string for opening the PDF document
Return Value ImageConversion
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_destroy_conversion
pdf2img_new_conversion
pdf2img_new_memconversion
pdf2img_new_memconversion_with_password
Availability All platforms
Technical Notes
  1.  This call maintains an open file handle for the inPDFPath argument.
  2. A document with a User password but no other security restrictions can be processed by providing the User password If the document has any security restrictions on it beyond simply a User password to restrict viewing, you will need to specify its Owner password instead. Opening with an Owner password will override the document’s security restrictions, and allow the PDF2IMG conversion to proceed.
  3. It is safe to call pdf2img_new_conversion_with_password with either a NULL pointer or a pointer to zero length string in the password In such cases, this call will behave exactly the same as its non-password counterpart, pdf2img_new_conversion.
  4. Of the two calls, pdf2img_new_conversion_with_password and pdf2img_new_memconversion_with_password, one or the other must be called to create an image conversion, but not both.
  5. The password argument is copied to an internal buffer. The client’s copy may be released after this.
  6. The password must grant the following permissions on the PDF document:
If using Permission Required
Any output format Open and Copy
EPS output format High Quality printing
Color management Modify

pdf2img_new_memconversion

(const void *inPDFMem, unsigned int numBytes)
Return Value: ImageConversion
Description This call creates a PDF-to-Image conversion from a buffer of bytes. Each is local to the thread which makes this function call and should not be shared across threads.
Parameters const void *inPDFMem: pointer to location of input image in memory
unsigned int numBytes: number of bytes in this buffer
Return Value ImageConversion
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_destroy_conversion
pdf2img_new_conversion
pdf2img_new_conversion_with_password
pdf2img_new_memconversion_with_password
Availability All platforms
Technical Notes
  1.  The memory in inPDFMem must be available until pdf2img_destroy_conversion is called for this conversion; it is not copied by PDF2IMG.
  2. Of the two calls pdf2img_new_conversion and pdf2img_new_memconversion, one or the other must be called to create an image conversion, but not both.

pdf2img_new_memconversion_with_password

(const void *InPDFMem, unsigned int numBytes, const char *password)
Return Value: ImageConversion
Description This call creates a PDF-to-Image conversion from a buffer of bytes using the supplied password. Each is local to the thread which makes this function call and should not be shared across threads.
Parameters const void *inPDFMem: pointer to location of input image in memory
unsigned int numBytes: number of bytes in this buffer
const char *password: password string for opening the PDF document
Return Value ImageConversion
Exceptions pdf2img_destroy_conversion
Header pdf2imglib.h
Related Methods
pdf2img_new_conversion
pdf2img_new_conversion_with_password
pdf2img_new_memconversion
Availability All platforms
Technical Notes
  1. The memory in inPDFMem must be available until pdf2img_destroy_conversion is called for this conversion; it is not copied by PDF2IMG.
  2. A document with a User password but no other security restrictions can be processed by providing the User password If the document has any security restrictions on it beyond simply a User password to restrict viewing, you will need to specify its Owner password instead. Opening with an Owner password will override the document’s security restrictions, and allow PDF2IMG conversion to proceed.
  3. It is safe to call pdf2img_new_memconversion_with_password with either a NULL pointer or a pointer to zero length string in the password In such cases, this call will behave exactly the same as its non-password counterpart, pdf2img_new_memconversion.
  4. Of the two calls pdf2img_new_conversion_with_password and pdf2img_new_memconversion_with_password, one or the other must be called to create an image conversion, but not both.
  5. The password argument is copied to an internal buffer. The client’s copy may be released after this call.
If using Permission Required
Any output format Open and Copy
EPS output format High Quality printing
Color management Modify

pdf2img_release_pagemem

(ImageConversion IC)
Return Value: int
Description This call releases the memory held by the ImageConversion for a graphic converted "into memory" by pdf2img_convert_page. This call is required only if pdf2img_convert_page was directed to return its output in memory instead of to an output file.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
Return Value Int
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_convert_page
pdf2img_get_pagemem
pdf2img_get_pagememsize
Availability All platforms

pdf2img_set_blackisone

(ImageConversion IC, unsigned short int blackisone)
Return Value: int
Description Normal processing to TIFF output sets the photometric interpretation values as black=0; white=1. If calling pdf2img_set_blackisone with a non-zero value for the blackisone argument TIFF photometric interpretation will be transposed such that black=1 and white=0.
This function is for 1-bit grayscale TIFF output only.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
unsigned short int blackisone:
0: black = 0/white = 1 or 1 (or any non-zero)
black = 1/white = 0
(Default 0)
Return Value Int
Exceptions
Header pdf2imglib.h
Related Methods
Availability All platforms

pdf2img_set_bpc

(ImageConversion IC, unsigned int bpc)
Return Value: int
Description This calls set the Bits Per Channel (bpc) value for the output color space: either 1 (such as black and white) or 8.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
unsigned int bpc: 1 or 8
(Default 8)
Return Value Int
Exceptions
Header pdf2imglib.h
Related Methods
Availability All platforms

pdf2img_set_color_profile_from_buffer

(ImageConversion IC, void *data, size_t dataSize)
Return Value: int
Description This call defines the color profile for use with PDF2IMG by selecting the profile in a buffer; the contents of the .icc file are stored in this buffer first.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
void *data: pointer to the location of the specified color profile in memory
size_t dataSize: the number of bytes to be read at the pointer location
Return Value Int: 0 for success
Exceptions
Header pdf2imglib.h
Related Methods  pdf2img_set_color_profile_from_description
pdf2img_set_color_profile_from_output_intent
pdf2img_set_render_intent
Availability All platforms
Technical Notes

Learn more about color management.

  1. Any member of this group of functions can be called repeatedly:
  2. A call succeeds if the specified profile exists, overriding a previous call if necessary. Thus, if several output profiles are specified, pdf2imglib uses the last one. Similarly, if several (RGB) input profiles are specified, pdf2imglib uses the last (RGB) input profile.
  3. These functions are for setting the desired output color For specifying an input profile, see pdf2img_set_input_color_profile_from_description or pdf2img_set_input_color_profile_from_output_intent.

pdf2img_set_color_profile_from_description

(ImageConversion IC, const char *description)
Return Value: int
Description This call defines the color profile for use with PDF2IMG by querying the system for the profile description.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
const char *description: text string of profile description
Return Value Int: 0 for success
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_set_color_profile_from_buffer
pdf2img_set_color_profile_from_output_intent
pdf2img_set_render_intent
Availability All platforms
Technical Notes

Learn more about color management.

  1. Any member of this group of functions maybe be called repeatedly:
  2. A call succeeds if the specified profile exists, overriding a previous call if necessary. Thus, if several output profiles are specified, pdf2imglib uses the last one. Similarly, if several (RGB) input profiles are specified, pdf2imglib uses the last (RGB) input profile.
  3. These functions are for setting the desired output color For specifying an input profile, see pdf2img_set_input_color_profile_from_buffer, pdf2img_set_color_profile_from_description, or pdf2img_set_color_profile_from_output_intent.

pdf2img_set_color_profile_from_output_intent

(ImageConversion IC, const char *description)
Return Value: int
Description This call defines the color profile for use with PDF2IMG by pulling it from the output intent stored in the PDF document. An output intent is a dictionary array in the PDF document OutputIntents array.
For more detail see the ISO 32000-1:2008 Document Management-Portable Document Format section 14.11.5 “Output Intents” on page 633.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
const char *description: text string of profile description
Return Value Int: 0 for success
Exceptions
Header pdf2imglib.h
Related Methods
pdf2img_set_color_profile_from_buffer
pdf2img_set_color_profile_from_description
pdf2img_set_render_intent
pdf2img_set_input_color_profile_from_buffer
Availability All platforms
Technical Notes

Learn more about color management.

  1. Any member of this group of functions may be called repeatedly.
  2. A call succeeds if the specified profile exists, overriding a previous call if necessary. Thus, if several output profiles are specified, pdf2imglib uses the last one. Similarly, if several (RGB) input profiles are specified, pdf2imglib uses the last (RGB) input profile.
  3. These functions are for setting the desired output color For specifying an input profile, see pdf2img_set_color_profile_from_bufferpdf2img_set_color_profile_from_description or pdf2img_set_input_color_profile_from_output_intent.
  4. An output intent is a dictionary in the document’s OutputIntents array, as described in the PDF Reference, ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 14.11.5, page 633. To use an output intent’s color profile, pdf2imglib matches the description supplied by the client with its dictionary values as follows:
    • use the first embedded profile with the specified OutputCondition value
    • use the first embedded profile with the specified OutputConditionIdentifier value
    • use the first embedded profile with the specified S (subtype) value

pdf2img_set_colormanagement

(ImageConversion IC, unsigned short int managecolors)
Return Value: int
Description This call sets the Color Management Module (CMM) processing preference flag to determine whether color profile information should be embedded in the output images.
When the managecolors flag is set to false PDF2IMG will draw the output to a device color. It will also embed no profile in the image written and presume no default color model for input device colors.
When the managecolors flag is set to true (the default) PDF2IMG assumes that Device colors on input are calibrated as shown in the Technical Notes table below. The software also assumes a corresponding output profile to match. When generating TIF/JPG/PNG/BMP output PDF2IMG will embed the corresponding profile in the output image.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
unsigned short int managecolors: true or false (Default true)
Return Value Int
Exceptions
Header pdf2imglib.h
Related Methods
Availability All platforms
Technical Notes

For non-calibrated spaces, PDF2IMG will use the built-in defaults of its underlying Adobe PDF Library for conversions, depending on the colorspace.

Default Conversion Color Profiles
Colorspace ICC Color Profile (input) ICC Color Profile (output)
RGB Adobe 1998 RGB sRGB
CMYK Adobe Reader 9 CMYK Adobe Reader 9 CMYK
(Simplified US web coated SWOP V2)
Gray Gamma 2.2 Gamma 2.2

pdf2img_set_colorspace

(ImageConversion IC, ColorSpaceCode csCode)
Return Value: int
Description This call sets the output colorspace. Not all combinations of colorspace with output format are valid; see Technical Notes below for more details.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
ColorSpaceCode csCode: Output colorspace value:
CMYKcolor
GRAYcolor
LABcolor
RGBcolor
RGBAcolor
(Default RGBcolor)
Return Value Int
Exceptions
Header pdf2imglib.h
Related Methods
Availability All platforms
Technical Notes
  1. When generating EPS output, calls to pdf2img_set_colorspace will have no effect, as the PDF file is not rasterized during processing.
  2. Not all colorspaces are valid for all output See the table below:

 

Available Output Types per Colorspace
Colorspace Output Type
CMYKcolor JPEG or TIFF
GRAYcolor BMP/GIF/JPEG/PNG/TIFF
LABcolor TIFF
RGBcolor BMP/GIF/JPEG/PNG/TIFF
RGBAcolor PNG or TIFF

pdf2img_set_compression

(ImageConversion IC, CompressionCode cmCode)
Return Value: Int
Description The call sets the output compression.
This function is for TIFF output only. See Technical Notes below for more details.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
CompressionCode cmCode: Output compression value:
NOcompression
LZWcompression
G3compression
G4compression
JPGcompression
(Default LZWcompression)
Return Value Int
Exceptions
Header pdf2imglib.h
Related Methods
Availability All platforms
Technical Notes
  1. Compression codes are currently examined only when processing TIFF or JPEG graphics that use DCT compression, PNG graphics that use Flate compression, and GIF graphics that use LZW compression. BMP graphics are currently not compressed.
  2. G3compression and G4compression values are only valid for B/W (1 channel, 1 bit) TIFF images.

pdf2img_set_enhance_thin_lines

(ImageConversion IC, in newVal)
Return Value: Int
Description This call will toggle the Enhance Thin Lines setting (as used in Adobe Reader or Acrobat) on or off in the generated image. If set to true (the default) pdf2imglib will generate thin line renderings as they would appear when generated by Reader or Acrobat.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
int newVal: Set enhance_thin_lines flag:
0: Do not set
1 (or any non-zero positive): Set enhance_thin_lines flag
(Default 1)
Return Value Int
Exceptions
Header pdf2imglib.h
Related Methods
Availability All platforms
Technical Notes

This reflects a default rendering setting for enhance_thin_lines. It is intended to match the default behavior of Adobe Reader and Adobe Acrobat in enhancing thin document lines when rendering. This call allows you to turn off that behavior if you like.

pdf2img_set_horiz_res

(ImageConversion IC, unsigned Int hRes)
Return Value: int
Description This call sets the horizontal resolution of the output expressed in dots/inch.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
unsigned int hRes: horizontal output resolution in dots per Valid range is 12 to 2400. (Default 300)
Return Value Int
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_set_vert_res
Availability All platforms

pdf2img_set_input_color_profile_from_buffer

(ImageConversion IC, void *data, size_t dataSize)
Return Value: Int
Description This call defines the input color profile for use with PDF2IMG by selecting the profile in a buffer. The contents of the .icc file are stored in this buffer first.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
void *data: pointer to the location of the specified color profile in memory
size_t dataSize: the number of bytes to be read at the pointer location
Return Value Int: 0 for success
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_set_input_color_profile_from_description
pdf2img_set_input_color_profile_from_output_intent
pdf2img_set_render_intent
pdf2img_set_color_profile_from_buffer
pdf2img_set_color_profile_from_description
Availability All platforms
Technical Notes

Learn more about color management.

  1. Any member of this group of functions may be called repeatedly:
  2. A call succeeds if the specified (RGB) input profile exists, overriding a previous call if necessary. Thus, if several input profiles are specified, pdf2imglib uses the last one. Similarly, if several output profiles are specified, pdf2imglib uses the last output profile.
  3. These functions are for setting the input (RGB) color For specifying an output profile, see:

pdf2img_set_input_color_profile_from_description

(ImageConversion IC, const char *description)
Return Value: int
Description This call defines the color profile for use withe PDF2IMG by querying the system for the profile description.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
const char *description: text string of profile description
Return Value Int: 0 for success
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_set_input_color_profile_from_buffer
pdf2img_set_input_color_profile_from_output_intent
pdf2img_set_render_intent
pdf2img_set_color_profile_from_buffer
pdf2img_set_color_profile_from_description
Availability All platforms
Technical Notes

Learn more about color management.

  1. Any member of this group of functions can be called repeatedly:
  2. A call succeeds if the specified (RGB) input profile exists, overriding a previous call if necessary. Thus, if several input profiles are specified, pdf2imglib uses the last one. Similarly, if several output profiles are specified, pdf2imglib uses the last output profile.
  3. These functions are for setting the input (RGB) color For specifying an output profile, see pdf2img_set_input_color_profile_from_buffer, pdf2img_set_color_profile_from_description or pdf2img_set_input_color_profile_from_output_intent.

pdf2img_set_input_color_profile_from_output_intent

(ImageConversion IC, const char *description)
Return Value: int
Description This call defines the input color profile for use with PDF2IMG by pulling it from the output intent stored in the PDF document. An output intent is a dictionary array in the PDF document OutputIntents array.
For more detail see the ISO 32000-1:2008 Document Management-Portable Document Format section 14.11.5 “Output Intents” on page 633.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
const char *description: text string of profile description
Return Value Int: 0 for success
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_set_input_color_profile_from_buffer
pdf2img_set_input_color_profile_from_description
pdf2img_set_render_intent
pdf2img_set_color_profile_from_buffer
pdf2img_set_color_profile_from_description
Availability All platforms
Technical Notes

Learn more about color management.

  1. Any member of this group of functions pdf2img_set_input_color_profile_from_bufferpdf2img_set_input_color_profile_from_description and pdf2img_set_input_color_profile_from_output_intent may be called repeatedly. A call succeeds if the specified (RGB) input profile exists, overriding a previous call if necessary. Thus, if several input profiles are specified, pdf2imglib uses the last one. Similarly, if several output profiles are specified, pdf2imglib uses the last output profile.
  2. These functions are for setting the input (RGB) color For specifying an output profile, see pdf2img_set_color_profile_from_buffer, pdf2img_set_color_profile_from_description or pdf2img_set_color_profile_from_output_intent.
  3. An output intent is a dictionary in the document’s OutputIntents array, as described in the PDF Reference, ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 14.11.5, page 633. To use an output intent’s color profile, pdf2imglib matches the description supplied by the client with its dictionary values as follows:
    • use the first embedded profile with the specified OutputCondition value
    • use the first embedded profile with the specified OutputConditionIdentifier value
    • use the first embedded profile with the specified S (subtype) value

pdf2img_set_max_band_memory

(ImageConversion IC, unsigned int newVal)
Return Value: int
Description PDF2IMG checks to see if it has enough memory to rasterize a PDF page to JPG or TIF in one pass. If not it rasterizes the page in bands (strips) in order to use smaller chunks of memory. Then the software reassembles the bitmaps into the finished output image.This call allows you to change the threshold value for the band rasterization process setting the size in bytes above which a banding conversion will be performed instead of attempting a single full-page conversion in one step.
Parameters  ImageConversion iC: the data structure containing the specifications for the active current conversion
unsigned int newVal: number of bytes for the threshold above which banded conversion will be used.
from 1000000 (one million) to 4200000000 (4.2 billion) with a default of 300000000 (300 million)
Return Value Int
Exceptions
Header pdf2imglib.h
Related Methods
Availability All platforms
Technical Notes
  1. You will typically not need the -maxbandmem and pdf2img_set_max_band_memory calls; the banding process is automatic and used only when needed, based on input page size and available memory.
  2. The limit for JPEG output image size is 65535 x 65535 TIF output has been tested up to a band of 68898 x 34449 pixels in size.
  3. The maximum allowed value for -maxbandmem as coded in the sample driver program pdf2img is approximately 2100000000 (2.1 billion), due to the ASCII-to-integer conversion process within the Higher values are allowed if passed in through this pdf2img_set_max_band_memory API call.

pdf2img_set_multipage

(ImageConversion IC, unsigned short int multipage)
Return Value: Int
Description If a non-zero multipage value is provided as the second argument in this call pdf2imglib will create multipage TIFF output files. Each converted PDF page will correspond to a page in the multipage TIFF output.
This function is for TIFF output only.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
unsigned short int multipage: Multipage output flag:
0: Single-page output
1 (or any non-zero): Multipage output(Default 0)
Return Value Int
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_end_multipage
pdf2img_start_multipage
Availability All platforms

pdf2img_set_OPP

(ImageConversion IC, int newVal)
Return Value: Int
Description This call will toggle OverPrint Preview (OPP) on or off in the generated image. If set to true pdf2imglib will generate a graphic that represents what the input PDF page would look like after being printed. It will account for ink overprinting.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
int newVal: Set OPP flag:
0: Do not set
1 (or any non-zero positive): Set OPP flag (Default 0)
Return Value Int
Exceptions
Header pdf2imglib.h
Related Methods
Availability All platforms

pdf2img_set_output_region

(ImageConversion IC, PDFRegionCode rCode)
Return Value: Int
Description This call specifies the region of the PDF page which may be rasterized.
All regions except BOUNDINGbox are defined in the "Page Boundaries" section in the PDF Reference.
See ISO 32000-1:2008 Document Management-Portable Document Format-Part 1: PDF 1.7 section 14.11.2 page 627. The BOUNDINGbox region is the area enclosing all visible page markings.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
PDFRegionCode rCode: Region of PDF page to rasterize:
CROPbox
MEDIAbox
ARTbox
TRIMbox
BLEEDbox
BOUNDINGbox (Default CROPbox)
Return Value Int
Exceptions
Header pdf2imglib.h
Related Methods
Availability All platforms
Technical Notes

PDFRegionCode: rCode values below represent the following regions of the PDF page. For full details on all values for PDFRegionCode rCode except BOUNDINGbox. See the “Page Boundaries” section in the PDF Reference, ISO 32000-1:2008 Document Management-Portable Document Format-Part 1: PDF 1.7, section 14.11.2, page 627. The values below are a summary from this IS 32000 content.

Page Boundary Values and Areas
PDF Region Description Default Value
CROPBox Region to which the contents of the page are to be clipped (cropped) when displayed or printed None
MEDIAbox Dimensions of physical medium on which the page is to be printed. This includes any extended areas surrounding the finished page for bleed or printing marks or other purposes. None
ARTbox Extent of the page's meaningful content (including potential white space) as intended by the page's creator. Page's Crop Box
TRIMbox Intended dimensions of the finished page after trimming Page's Crop Box
BLEEDbox Region to which page contents should be clipped when output in a production environment. May include extra bleed area needed to accommodate physical limitations of cutting folding and trimming equipment. Page's Crop Box
BOUNDINGbox Area enclosing all visible page markings None

pdf2img_set_output_type

(ImageConversion IC, OutputTypeCode oCode)
Return Value: Int
Description This call specifies the output graphic type or types into which PDF2IMG will convert the document. See Technical Notes below.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
OutputTypeCode oCode: Desired output graphic format for conversion:
EPSoutput
TIFFoutput
JPEGoutput
BMPoutput
PNGoutput
RAWoutput
GIFoutput
(No Default)
Return Value Int
Exceptions
Header pdf2imglib.h
Related Methods
Availability All platforms
Technical Notes

If specifying GIFoutput as one of a group of two or more calls to pdf2img_set_output_type, specify GIFoutput last. Some internal functions assume that the GIF output format is always the last item in a list of multiple formats.

Available Output Formats
Output Format Output Code Format Description
EPS EPSoutput Encapsulated PostScript
TIFF TIFFoutput Tagged Image File Format
JPEG/JPG JPEGoutput Joint Photographic Experts Group
BMP BMPoutput Bitmap
PNG PNGoutput Portable Network Graphics
RAW RAWoutput Uncompressed format
GIF GIFoutput Graphics Interchange Format

pdf2img_set_quality

(ImageConversion IC, unsigned int quality)
Return Value: Int
Description For JPG/JPEG output format the value set via this call will determine the output image quality. It represents the balance you want between generating a small output file (but a low-resolution image) versus a high-resolution image (but a large output file). Valid quality values range from 1 to 100. The smallest file would be 1 and 100 would be for the highest quality image.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
unsigned int quality: Desired output image quality from 1 to 100 (Default 75)
Return Value Int
Exceptions
Header pdf2imglib.h
Related Methods
Availability All platforms
Technical Notes

Lowering the quality value will not only lower the detail of the image, but also lower the precision of the colors (as compared with the original input). For example, rendering a JPEG image at 50% quality rather than some value significantly higher may yield a result that not only shows less detail but also contains slightly different shades of color.

pdf2img_set_render_intent

(ImageConversion IC, RenderIntent riCode)
Return Value: Int
Description This call sets the rendering intent for the ICC profile. If a profile is supplied the value defaults to the rendering intent provided within that ICC profile. If the profile is not supplied the intent defaults to perceptual. See Technical Notes below.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
RenderIntent riCode: one of the five intent values available to choose from
perceptual
relative
saturation
absolute
profile
Return Value Int: 0 for success
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_set_color_profile_from_buffer
pdf2img_set_color_profile_from_description
Availability All platforms
Technical Notes

Learn more about color management.

The riCode parameter offers five intent values to choose from: perceptual, relative, saturation, absolute or profile.

Intent Values
perceptual Generally used for photography. This method does not map colors one for one. Rather the method estimates to match colors. Hence it often provides the most pleasing result but not necessarily the most accurate. If you do not specify a color profile in the colorprofile  option the intent value defaults to perceptual.
relative Generally used for photography. The relative method uses an algorithm to select the closest possible color map to be true to the specified color.
saturation Commonly used in charts and diagrams with a limited palette of colors. The saturation is used where hue is not as important.
absolute Often used to select a specific color or set of colors for drawings or designs.  For PDF2IMG absolute will serve to reproduce the exact colors provided in the original PDF document. A common reason for using absolute would be to reproduce the color used in a corporate logo such as IBM Blue. The color is changed by selecting a defined match. This method does not use a conversion algorithm to select the closest color available.
profile If you specify a color profile via either pdf2img_set_color_profile_from_buffer or pdf2img_set_color_profile_from_description the riCode value defaults to profile. In that case PDF2IMG will use the rendering intent provided with the ICC color profile currently in use.  For example the Adobe RGB 1998 color profile uses Relative Colormetric as its rendering intent. So if PDF2IMG specifies Adobe RGB 1998 as the color profile and you don’t enter a value via pdf2img_set_render_intent the product will use relative as the color rendering intent.

pdf2img_set_resampler

(ImageConversion IC, ResamplerCode rsCode)
Return Value: Int
Description Originally PDF2IMG would convert images without resampling. In some cases would cause unwanted artifacts or loss of detail in smaller or low-resolution output images such as thumbnails.
Automatic resampling was introduced to enhance the quality of images when they were converted.
If you use the default value of AutoResampler and ifany of the following conditions are true images will first be rasterized to 150 PPI. After that a bicubic downsampling to the desired target values will be applied:
-pixelcount:h is less than one half of the default input height
-pixelcount:w is less than one half of the default input width
-resolution is less than 150
Specifying an rsCode of BicubicResampler will apply the resampler unconditionally. Specifying NoResampler will turn it off completely for output consistent with prior releases of PDF2IMG.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
ResamplerCode rsCode: DSelected resampler setting (Default AutoResampler)
Return Value Int
Exceptions
Header pdf2imglib.h
Related Methods
Availability All platforms

pdf2img_set_reverse

(ImageConversion IC, unsigned short int reverse)
Return Value: Int
Description If a positive non-zero reverse value is provided as the second argument in this call pdf2imglib will reverse black and white in the output image
creating a negative image.This function is for grayscale output only.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
unsigned short int reverse: Reverse output flag:
0: Do not reverse
1 (or any non-zero positive): Reverse output black/white values
(Grayscale output only; Default 0)
Return Value Int
Exceptions
Header pdf2imglib.h
Related Methods
Availability All platforms

pdf2img_set_size_pixels

(ImageConversion IC, unsigned Int hPixels, unsigned Int vPixels)
Return Value: Int
Description This call sets the page conversion to emit an image of exactly hPixels wide and vPixels tall.
This call does not affect the image resolution but only the output size. Only one argument is required; the other
argument can be zero (0) which will automatically scale the image proportionately using whichever
value was given as a fixed dimension and floating the size of the other dimension as needed. (No Default)
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
unsigned int hPixels: desired horizontal output width in pixels (or 0)
unsigned int vPixels: desired vertical output height in pixels (or 0)
Return Value Int
Exceptions
Header pdf2imglib.h
Related Methods
Availability All platforms

pdf2img_set_smoothing

(ImageConversion IC, unsigned short Int Smoothing)
Return Value: Int
Description This call sets Smoothing flags as desired for Text or Line Art and/or Image Smoothing. All settings are independent; valid values for this call are a logical OR of SmoothingCode values. For full Smoothing operation set all flags.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
unsigned short int Smoothing: logical OR of available Smoothing flags:
PDFSmoothNone: None
PDFSmoothText: Text Smoothing
PDFSmoothArt: Line Art Smoothing
PDFSmoothImage:  Image  Smoothing
(No Default)
Return Value Int
Exceptions
Header pdf2imglib.h
Related Methods
Availability All platforms

pdf2img_set_vert_res

(ImageConversion IC, unsigned Int vRes)
Return Value: Int
Description This call sets the vertical resolution of the output expressed in dots/inch.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
unsigned int vRes: vertical output resolution in dots per Valid range is 12 to 2400. (Default 300)
Return Value Int
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_set_horiz_res
Availability All platforms

pdf2img_setasprinted

(ImageConversion IC, Int newVal)
Return Value: Int
Description By default a rendered page is converted to an image as it would be shown on screen but not on paper. Non-printing annotations will be shown and printable annotations will not.
This call will set the asprinted flag and reverse those distinctions: the image will represent the PDF page in its printed form and printable annotations will appear. Non-printing annotations (those only used for display on a screen) will be suppressed.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
int newVal: Set asprinted flag:
0: Do not set
1 (or any non-zero positive): Set asprinted flag
(Default: 0)
Return Value Int
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_setprintannot
Availability All platforms
Technical Notes

This command can be overridden by the pdf2img_setprintannot

pdf2img_setprintannot

(ImageConversion IC, Int newVal)
Return Value: Int
Description As with the command-line -noannot flag this call adds the capability to suppress displayable annotations from the converted output.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
int newVal: Call with 0 value to suppress annotations (No Default)
Return Value Int
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_setasprinted
Availability All platforms
Technical Notes
  1. This command should be used with Many page objects can be various forms of annotation, some more obvious than others, so you should check your output carefully to ensure that you are suppressing only those annotations that you want to block, and no others.
  2. This command will override the pdf2img_setasprinted setting.

pdf2img_start_multipage

(ImageConversion IC, const char *ImageName)
Return Value: Int
Description This call will start multipage TIFF output of the current input PDF document rather than the default of single-page sequentially- named output files. (TIFF only; No default)
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
const char *imageName: File prefix to be assigned to output TIFF file name produced
Return Value Int
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_end_multipage
pdf2img_set_multipage
Availability All platforms

pdf2img_term ()

Return Value: Int
Description This calling argument terminates PDF2IMG after use. If used in a multi-threaded application each calling thread must do its own termination after use.
Parameters
Return Value Int
Exceptions
Header pdf2imglib.h
Related Methods pdf2img_init
pdf2img_init_ex
Availability All platforms

pdf2img_verify_options

(ImageConversion IC)
Return Value: Int
Description This call verifies that the conversion options supplied are valid in context. If so a zero (0) is returned; if any are not valid a non-zero value is returned.
Parameters ImageConversion iC: the data structure containing the specifications for the active current conversion
Return Value Int: 0 if conversion options are valid; non-zero if any are not
Exceptions
Header pdf2imglib.h
Related Methods
Availability All platforms

pdf2img_version_string()

Return Value: const char *
Description This call returns a string representation (in English) of the pdf2imglib version in use. Do not release this string.
Parameters
Return Value const char *: Current pdf2imglib version in use
Exceptions
Header pdf2imglib.h
Related Methods
Availability All platforms