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
- While a NULL argument will suppress writing an output file, note that a work file will be temporarily created during the conversion process.
- 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 *
| 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_get_region_remove_white_margins
(ImageConversion iC, unsigned int pageNum, double* left, double* top, double* right, double* bottom)
Return Value: int
| Description | Returns coordinates of a tight-fitting bounding box encompassing all text graphics and images on the page. This effectively removes the white margins around the page (assuming black foreground on white background). |
| Parameters | ImageConversion iC: the data structure containing the specifications for the active current conversion unsigned init pageNum: sequence number of input file page to be converted counting from 1 double * left: coordinate for left margin of bounding box double * top: coordinate for top margin of bounding box double * right: coordinate for right margin of bounding box double * bottom: coordinate for bottom margin of bounding box |
| Return Value | int |
| Exceptions | |
| Header | pdf2imglib.h |
| Related Methods | |
| 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 | init |
| 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
- This call maintains an open file handle for the inPDFPath argument.
- 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
- This call maintains an open file handle for the inPDFPath argument.
- 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.
- 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.
- 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.
- The password argument is copied to an internal buffer. The client’s copy may be released after this.
- 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
- The memory in inPDFMem must be available until pdf2img_destroy_conversion is called for this conversion; it is not copied by PDF2IMG.
- 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 | |
| Header | pdf2imglib.h |
| Related Methods | pdf2img_destroy_conversion pdf2img_new_conversion pdf2img_new_conversion_with_password pdf2img_new_memconversion |
| Availability | All platforms |
Technical Notes
- The memory in inPDFMem must be available until pdf2img_destroy_conversion is called for this conversion; it is not copied by PDF2IMG.
- 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.
- 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.
- 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.
- 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 call sets 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.
- Any member of this group of functions can be called repeatedly:
- pdf2img_set_color_profile_from_buffer
- pdf2img_set_color_profile_from_description
- pdf2img_set_color_profile_from_output_intent
- 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.
- 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.
- Any member of this group of functions maybe be called repeatedly:
- pdf2img_set_color_profile_from_buffer
- pdf2img_set_color_profile_from_description
- pdf2img_set_color_profile_from_output_intent
- 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.
- 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, 1.7, Document Management-Portable Document Format section 14.11.5 “Output Intents” on page 633. Find this document on the web store of the International Standards Organization (ISO). |
| 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.
- Any member of this group of functions may be called repeatedly.
- pdf2img_set_color_profile_from_buffer
- pdf2img_set_color_profile_from_description
- pdf2img_set_color_profile_from_output_intent
- 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.
- These functions are for setting the desired output color For specifying an input profile, see pdf2img_set_color_profile_from_buffer, pdf2img_set_color_profile_from_description or pdf2img_set_input_color_profile_from_output_intent.
- 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. Find this document on the web store of the International Standards Organization (ISO). 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, or 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 color space. 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: |
| Return Value | Int |
| Exceptions | |
| Header | pdf2imglib.h |
| Related Methods | |
| Availability | All platforms |
Technical Notes
- When generating EPS output, calls to pdf2img_set_colorspace will have no effect, as the PDF file is not rasterized during processing.
- 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, or TIFF | |
| LABcolor | TIFF | |
| RGBcolor | BMP, GIF, JPEG, PNG or 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: |
| Return Value | Int |
| Exceptions | |
| Header | pdf2imglib.h |
| Related Methods | |
| Availability | All platforms |
Technical Notes
- 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.
- 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: |
| 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.
- Any member of this group of functions may be called repeatedly:
- pdf2img_set_input_color_profile_from_buffer
- pdf2img_set_input_color_profile_from_description
- pdf2img_set_input_color_profile_from_output_intent
- 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.
- 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
- pdf2img_set_color_profile_from_output_intent
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.
- Any member of this group of functions can be called repeatedly:
- pdf2img_set_input_color_profile_from_buffer
- pdf2img_set_input_color_profile_from_description
- pdf2img_set_input_color_profile_from_output_intent
- 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.
- 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, 1.7, section 14.11.5 “Output Intents” on page 633. Find this document on the web store of the International Standards Organization (ISO). |
| 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.
- Any member of this group of functions pdf2img_set_input_color_profile_from_buffer, pdf2img_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.
- 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.
- 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. Find this document on the web store of the International Standards Organization (ISO). 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. The range runs 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
- 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.
- 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.
- 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. Find this document on the web store of the International Standards Organization (ISO). 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: |
| 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. Find this document on the web store of the International Standards Organization (ISO). 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 | Parameters,ImageConversion iC: the data structure containing the specifications for the active current conversion
OutputTypeCode oCode: Desired output graphic format for conversion: |
| 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_pdf_output_type
(ImageConversion IC, PDFOutputType pCode)
Return Value: Int
| Description | If selecting PDF as the output file type, select the method to use in generating the PDF output file or files. |
| Parameters | ImageConversion iC: the data structure containing the specifications for the active current conversion
PDFRegionCode pCode: Method for generating PDF output content: |
| Return Value | Int |
| Exceptions | |
| Header | pdf2imglib.h |
| Related Methods | |
| Availability | All platforms |
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: |
| 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 if any 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 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: |
| 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 |
| 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: |
| 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
- 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.
- 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 |