The ImageToolbox Gold API Reference *********************************** Version: 3.0 December 2000 The ImageToolbox Gold (ITBG30.DLL) supports all the functions found in the Silver version, plus many additional features that dramatically enhance the file format support. All the image conversion features found in this product decompress the image data then recompress the image in the output format once the selected changes to the image have been applied. When compared to the functions in the ImageToolbox Silver these conversions require far more computing for the image manipulation, and as a result take longer to process each image (but are still very fast). We call these image conversion operations "translations" to indicate that the image data is modified while being processed. As with the ImageToolbox Silver, running the conversions on a computer with a fast hard drive is very desirable. Running this version of the Toolbox on a fast processor will make make much more difference in the processing speed per page than with the ImageToolbox Silver due to the extra image processing required. This is especially true when changing image resolutions. ---------------------------------------------------------------------- Files Included In The ImageToolbox Gold --------------------------------------- The ImageToolbox Gold has two runtime DLLs. Both ITBG30.DLL and the support file ITBG3IX.DLL should normally reside in the same directory as the application that will be calling the API functions. When creating your application, the include file ITBDEFS.H provides all function prototypes and error return code definitions for C language development. For Visual Basic developers, the file ITBGDEFS.BAS can be included in the project instead to provide the same information. NOTE: The names of the DLL files have changed from earlier versions. If you are upgrading from an earlier version of the Toolbox, please delete your old Toolbox files and replace them with the files included in this package. Your code must be rebuilt to use these changed filenames. ---------------------------------------------------------------------- Translation Functions Included In The ImageToolbox Gold ------------------------------------------------------- All the ImageToolbox Gold APIs that translate the image use "Trans" in the function name instead of "Cnv" used in the Silver API function names. These functions all return the error ERR_FUNCTIONNOTSUPPORTED if used in the ImageToolbox Silver product. ---------------------------------------------------------------------- Environment Variables Used -------------------------- Some translations create an intermediate temporary file which is deleted after the final output file is written. The directory to use for temporary files is determined by examining the environment setting of TEMP. If there is no TEMP setting, the TMP setting is used. If there is no TMP setting, the root of drive C: is used (C:\). It is a good idea to use a fast hard drive for the temporary directory. The maximum space required for the temporary file is the size of the largest image that will be created in the conversions. ********************************************************************** *** UPGRADE FUNCTIONS FROM IMAGETOOLBOX SILVER THAT INCLUDE IMAGE TRANSLATION SUPPORT *** BACKGROUND AND IMPLEMENTATION NOTES: These functions are upgrades for the functions found in the ImageToolbox Silver. The functions are similarly named (with "Trans" replacing "Cnv" in the Silver product) and have extra parameters to select the image compression method desired. Using these functions is the fastest method to upgrade from Silver to Gold. int ITBAPI ITB_TransModca2Tif(char FAR *lpModcaFileSpec, int FilesToConvert, char FAR *lpTiffFileBase, int NamingMethod, int NameDigits, int ModcaCompression, int TiffCompression) Description: Translate a MO:DCA file to a TIFF file using a different compression format. If the MO:DCA and TIFF files both use G4 compression, the "Cnv" function is invoked instead. Parameters: lpModcaFileSpec Far pointer to a null terminated string containing a fully qualified path to the MO:DCA file to be translated. FilesToConvert Which pages in the file to translate. 1 = translate the first image only 2 = translate all images in the MO:DCA file to separate TIFF files 3 = translate all images in the MO:DCA file to a single TIFF file lpTiffFileBase The base of a fully qualified path to the TIFF file(s) to be written. The way this filespec is used is controlled by the NamingMethod. NamingMethod The output file naming strategy. These values determine how the lpTiffFileBase parameter is used. 1 = use the name as specified in lpTiffFileBase 2 = append numeric extensions to each file starting with ".001" 3 = append a right justified numeric then ".TIF". The length of the numeric string is controlled by NameDigits. The extension can be changed using the API ITB_SetTiffExtension(). NameDigits Specifies how many digits are appended to the filename base when NamingMethod 3 is used. The value is ignored if NamingMethod is not set to 3. ModcaCompression Compression in use in the source MO:DCA file. TRANS_MODCA_G4 = Group 4 compression (this is usually the format) TRANS_MODCA_MMR = IBM MMR format (may not be supported by all versions of the Toolbox). TiffCompression Compression to use for the output TIFF file. TRANS_TIFF_G4 = Group 4 compression TRANS_TIFF_G3 = Group 3 compression TRANS_TIFF_UNCOMPRESSED = uncompressed raw bitmap Return Value: 0 = no errors non-zero = error as defined in ITBDEFS.H Implementation Notes: * If the input MO:DCA file compression used is unknown, or if you want to force the image decompress/recompress operation, set the value ModcaCompression = TRANS_MODCA_MMR. This will disable the conversion optimizations built into to the Toolbox and force the slower translation. int ITBAPI ITB_TransTif2Modca(char FAR *lpTiffFileSpec, int FilesToConvert, char FAR *lpModcaFileBase, int NamingMethod, int NameDigits, int ModcaFormat, int TiffCompression) Description: Translate a TIFF file to a MO:DCA file using a different compression format. If the TIFF and MO:DCA files both use G4 compression, the "Cnv" function is invoked instead. Parameters: lpTiffFileSpec Far pointer to a null terminated string containing a fully qualified path to the TIFF file to be translated. FilesToConvert Which pages in the file to translate. 1 = translate the first image only 2 = translate all images in the TIFF file to separate MO:DCA files 3 = translate all images in the TIFF file to a single MO:DCA file lpModcaFileBase The base of a fully qualified path to the MO:DCA file(s) to be written. The way this filespec is used is controlled by the NamingMethod. NamingMethod The output file naming strategy. These values determine how the lpModcaFileBase parameter is used. 1 = use the name as specified in lpModcaFileBase 2 = append numeric extensions to each file starting with ".001" 3 = append a right justified numeric then ".MOD" or ".ICA". The length of the numeric string is controlled by NameDigits. The extension can be changed using the APIs ITB_SetModcaExtension() or ITB_SetIocaExtension(). NameDigits Specifies how many digits are appended to the filename base when NamingMethod 3 is used. The value is ignored if NamingMethod is not set to 3. ModcaFormat Which type of output file to create. 1 = create MO:DCA format output files 0 = create single image IOCA files TiffCompression Compression in use in the source TIFF file. TRANS_TIFF_G4 = Group 4 compression TRANS_TIFF_G3 = Group 3 compression TRANS_TIFF_UNCOMPRESSED = uncompressed raw bitmap Return Value: 0 = no errors non-zero = error as defined in ITBDEFS.H Implementation Notes: * If the input TIFF file compression used is unknown, or if you want to force the image decompress/recompress operation, set the value TiffCompression = TRANS_TIFF_G3. This will disable the conversion optimizations built into to the Toolbox and force the slower translation. int ITBAPI ITB_T2M_TransBatch(char FAR *lpTiffFileSpec, int WriteAll, int TiffCompression) Description: Translate the contents of a TIFF file to the MO:DCA file previously opened with the function ITB_T2M_BeginBatch(). This function is compatible with the function ITB_T2M_WriteBatch() and can be called with it when writing a batch of files. If the TIFF compression is G4, the file is not translated, and the function ITB_T2M_WriteBatch() is invoked instead. The MO:DCA file is always written using G4 compression. Please see the additional implementation notes in the function ITB_T2M_WriteBatch() description. Parameters: lpTiffFileSpec Specifies the fully qualified name of a TIFF file to be translated. WriteAll Specifies which source file images to write. 0 = first image of the TIFF file 1 = all images in the TIFF file TiffCompression Compression format of the source TIFF file. TRANS_TIFF_G4 = Group 4 compression TRANS_TIFF_G3 = Group 3 compression TRANS_TIFF_UNCOMPRESSED = uncompressed raw bitmap Return Value: 0 = no errors non-zero = error as defined in ITBDEFS.H ---------------------------------------------------------------------- *** PTOCA FILE SUPPORT *** BACKGROUND AND IMPLEMENTATION NOTES: Some IBM products create MO:DCA files with PTOCA content. The full name of this IBM format is Presentation Text Object Content Architecture. Each file contains one or more pages of formatted text. The text and positioning data is stored in IBM EBCDIC (Extended Binary-Coded Decimal Interchange Code) characters. Each page may reference a PTOCA Overlay, which is merged with the text as a background. The overlay is not required to create the image, however without the overlay the text is presented on a white background. There are often a small number of PTOCA Overlay files on an IBM system, and they are all stored together. Your system administrator will know where to find them. Before processing any PTOCA files you should copy all the Overlay files to an overlay directory on your PC. These files should all share the same extension (not "TIF"), and this extension should be unique in this directory. Make sure only the overlay files share the same extension, otherwise conversion errors will be reported when non-overlay files with the same extension are processed later. When the API function ITB_SetPtocaOptions() is called, the overlay files will be converted to TIFF format and stored with the same base name and "TIF" extension (ovr1 -> ovr1.tif). This overlay file conversion is only done once. Once the TIFF equivalent files exist they are not regenerated. It might be necessary to switch the TIFF black bit setting before converting the overlays if they are generated as white on black. This can be done by calling the API ITB_SetTiffBlackBit() before the initialization call. To force regeneration of the TIFF overlay files after a setting change, delete the *.TIF files from your overlay directory. Since all PTOCA information is stored in EBCDIC, all data must be converted by the ImageToolbox before being used. The error reporting strategy and substitution character to use when unknown EBCDIC codes are detected is specified in the PTOCA initialization call ITB_SetPtocaOptions(). The TIFF file created by the PTOCA conversion is always stored using G4 compression. During the PTOCA file conversion, a temporary file is created in the same directory as the output file. This file is deleted before the conversion function returns. This does not normally cause any problem, however in a networked environment the user will require "delete" and "rename" privileges. It also means the conversions cannot write directly to a device like a CD. Only "pure" PTOCA content files can be processed in this version. Files that contain mixed PTOCA and IOCA image will generate an error if processed. Files of mixed text and image content are very rare, so this will not likely be a problem in your case. API function call examples are included in the "sample code" section at the end of this file. int ITBAPI ITB_SetPtocaOptions(char FAR *lpPtocaFontName, int FontPointSize, int FontBold, int FontItalic, int ErrOnUnknownChar, char FAR *lpSubstitutionChar, int ImageWithSpecifiedOverlay, int PrintWithSpecifiedOverlay, int ErrOnMissingOverlay, char FAR *lpOverlayPath, char FAR *lpOverlayExtension) Description: Before processing any PTOCA files the configuration options must be initialized by calling this function. If all the function inputs are valid and overlay files are to be used for either image creation or printing, the overlay files are preprocessed before the function returns. This preprocessing converts any files with a matching overlay filename extension and writes a TIFF file of the same name to the same directory. If a matching TIFF file already exists the file is not converted. If the overlays are converted to white on black, delete the TIFF files in the overlay directory to force the files to be regenerated, and add a call to the API function ITB_SetTiffBlackBit() before invoking this function to generate black on white overlays. If this function returns an error the PTOCA file processing features of the ImageToolbox Gold will be disabled. Parameters: lpPtocaFontName The name of a TrueType font to use to present the PTOCA text (such as "Courier New"). Normally this should be a monospaced font (where all letters, numbers and punctuation have the same character width). FontPointSize The font pointsize to use from 4 to 72. FontBold 1 = bold 0 = normal FontItalic 1 = italic 0 = normal ErrOnUnknownChar 1 = generate an error if an unknown EBCDIC character is detected 0 = no error reported - replace unknowns with the substitution character lpSubstitutionChar The substitution character for unknown EBCDIC characters specified as a string (such as "?"). ImageWithSpecifiedOverlay 1 = use the overlay specified in the PTOCA file when creating the TIFF image file. 0 = do not include the overlay in the image file PrintWithSpecifiedOverlay This parameter is included for future use but is ignored in this version. PTOCA format files cannot be printed directly. To print PTOCA format translate the file to TIFF using the API ITB_TransPtoca2Tif(), then print the TIFF file. ErrOnMissingOverlay 1 = generate an error if the required overlay file is missing 0 = no error reported - the file is processed without the overlay lpOverlayPath The path where the overlay files can be found (such as "c:\overlays") lpOverlayExtension The filename extension used by all overlay files in the specified overlay directory. If the files have no extension, specify a zero length string (as ""). Return Value: 0 = no errors non-zero = error as defined in ITBDEFS.H void ITBAPI ITB_SetPtocaCnvEnable(int AutoDetectPtoca) Description: Enable or disable automatic detection and handling of PTOCA format files by the API function ITB_CnvModca2Tif(). When this feature is enabled it is not necessary to determine if the input MO:DCA file contains PTOCA content before calling the function. If the PTOCA handling is disabled (default), the API function ITB_CnvModca2Tif() will report a file format error when PTOCA files are processed. In this situation, these files can be processed properly by the API function ITB_TransPtoca2Tif(). It may be desirable to keep this feature disabled if you want to detect PTOCA files for special processing. The PTOCA option initialization call to the API function ITB_SetPtocaOptions() must be successful before PTOCA files can be processed by ITB_CnvModca2Tif(). When using the ImageToolbox Silver this function has no effect. PTOCA file support is only available in the Gold version. Parameters: AutoDetectPtoca 1 = process PTOCA files in ITB_CnvModca2Tif() 0 = disable PTOCA file support in ITB_CnvModca2Tif() (default setting) Return Value: none int ITBAPI ITB_TransPtoca2Tif(char FAR *lpPtocaFileSpec, int FilesToConvert, char FAR *lpTiffFileBase, int NamingMethod, int NameDigits) Description: Translate a PTOCA file to a TIFF file using the current PTOCA generation settings. The PTOCA option initialization call to the API function ITB_SetPtocaOptions() must be successful before calling this function. Automatic PTOCA file detection is also available using the APIs ITB_SetPtocaCnvEnable() and ITB_CnvModca2Tif(). Parameters: lpPtocaFileSpec Far pointer to a null terminated string containing a fully qualified path to the PTOCA file to be translated. FilesToConvert Which pages in the file to translate. 1 = translate the first page only 2 = translate all pages in the PTOCA file to separate TIFF files 3 = translate all pages in the PTOCA file to a single TIFF file lpTiffFileBase The base of a fully qualified path to the TIFF file(s) to be written. The way this filespec is used is controlled by the NamingMethod. NamingMethod The output file naming strategy. These values determine how the lpTiffFileBase parameter is used. 1 = use the name as specified in lpTiffFileBase 2 = append numeric extensions to each file starting with ".001" 3 = append a right justified numeric then ".TIF". The length of the numeric string is controlled by NameDigits. The extension can be changed using the API ITB_SetTiffExtension(). NameDigits Specifies how many digits are appended to the filename base when NamingMethod 3 is used. The value is ignored if NamingMethod is not set to 3. Return Value: 0 = no errors non-zero = error as defined in ITBDEFS.H ---------------------------------------------------------------------- *** AUTOMATIC IMAGE FILE TRANSLATION FUNCTIONS *** BACKGROUND AND IMPLEMENTATION NOTES: Now it's possible to read many popular bitonal and color image formats and write the images out to selected file formats. Each output file format has a separate API function to provide the maximum flexibility supported by the format (such as multipage files, image compression selection and image size reduction). The current file formats supported for reading are listed below. Generally most compression types and bits per pel are supported for each format except LZW compression. TIFF MODCA IOCA JPEG PNG BMP PCX DCX DICOM JEDMICS KOFAX WINFAX Others - The list is always growing. If your desired format is not listed here please contact us for possible support. Notes: 1. PTOCA files cannot be translated directly. Please use the PTOCA file handing API functions described in this documentation to translate these files to TIFF, then using the TIFF file as an input for one of these functions. 2. Adobe PDF file reading is not supported. Additional API functions allow you to specify image handling strategies that are common to all file formats. These are described in the "Translation Configuration Functions" section of this documentation. Please review those APIs for important features that affect these functions. int ITBAPI ITB_TransImage2Tif(char FAR *lpSourceFileSpec, int FilesToConvert, char FAR *lpTifFileBase, int NamingMethod, int NameDigits, int OutputCompression, int AppendExisting) Description: Translate an image file to a TIFF file using the specified values and current output configuration settings. Parameters: lpSourceFileSpec Far pointer to a null terminated string containing a fully qualified path to the image file to be translated. FilesToConvert Which pages in the file to translate. 1 = translate the first page only 2 = translate all pages in the image file to separate TIFF files 3 = translate all pages in the image file to a single TIFF file lpTiffFileBase The base of a fully qualified path to the TIFF file(s) to be written. The way this filespec is used is controlled by the NamingMethod. NamingMethod The output file naming strategy. These values determine how the lpTiffFileBase parameter is used. 1 = use the name as specified in lpTiffFileBase 2 = append numeric extensions to each file starting with ".001" 3 = append a right justified numeric then ".TIF". The length of the numeric string is controlled by NameDigits. The extension can be changed using the API ITB_SetTiffExtension(). NameDigits Specifies how many digits are appended to the filename base when NamingMethod 3 is used. The value is ignored if NamingMethod is not set to 3. OutputCompression One of the following settings as defined in ITBDEFS.H: ITB_COMPRESSION_UNCOMPRESSED ITB_COMPRESSION_HUFFMAN ITB_COMPRESSION_PACKBITS ITB_COMPRESSION_G3 ITB_COMPRESSION_G4 AppendExisting Determines whether the output file should be appended to an existing file of the same name, or overwrite it. 0 = overwrite an existing file of same name without warning. non-zero = append pages to any existing TIFF file of the same name. Return Value: 0 = no errors non-zero = error as defined in ITBDEFS.H int ITBAPI ITB_TransImage2Modca(char FAR *lpSourceFileSpec, int FilesToConvert, char FAR *lpModcaFileBase, int NamingMethod, int NameDigits, int AppendExisting) Description: Translate an image file to a MODCA file using the specified values and current output configuration settings. All output images are saved as bitonal (1 bit per pel) using group 4 compression. Parameters: lpSourceFileSpec Far pointer to a null terminated string containing a fully qualified path to the image file to be translated. FilesToConvert Which pages in the file to translate. 1 = translate the first page only 2 = translate all pages in the image file to separate MODCA files 3 = translate all pages in the image file to a single MODCA file lpModcaFileBase The base of a fully qualified path to the MODCA file(s) to be written. The way this filespec is used is controlled by the NamingMethod. NamingMethod The output file naming strategy. These values determine how the lpModcaFileBase parameter is used. 1 = use the name as specified in lpModcaFileBase 2 = append numeric extensions to each file starting with ".001" 3 = append a right justified numeric then ".MOD". The length of the numeric string is controlled by NameDigits. The extension can be changed using the API ITB_SetModcaExtension(). NameDigits Specifies how many digits are appended to the filename base when NamingMethod 3 is used. The value is ignored if NamingMethod is not set to 3. AppendExisting Determines whether the output file should be appended to an existing file of the same name, or overwrite it. 0 = overwrite an existing file of same name without warning. non-zero = append pages to any existing MODCA file of the same name. Return Value: 0 = no errors non-zero = error as defined in ITBDEFS.H int ITBAPI ITB_TransImage2Jpeg(char FAR *lpSourceFileSpec, int FilesToConvert, char FAR *lpJpegFileBase, int NamingMethod, int NameDigits, int MaxPixelWidth, int MaxPixelHeight) Description: Translate an image file to a JPEG file using the specified values and current output configuration settings. All output images are saved as color using JPEG compression. If the input file is bitonal, it is promoted to 8 bits per pel before saving. Note that JPEG files only support a single image per file. If you are translating multiple page files, separate output files must be created. Parameters: lpSourceFileSpec Far pointer to a null terminated string containing a fully qualified path to the image file to be translated. FilesToConvert Which pages in the file to translate. 1 = translate the first page only 2 = translate all pages in the image file to separate JPEG files lpJpegFileBase The base of a fully qualified path to the JPEG file(s) to be written. The way this filespec is used is controlled by the NamingMethod. NamingMethod The output file naming strategy. These values determine how the lpJpegFileBase parameter is used. 1 = use the name as specified in lpJpegFileBase 2 = append numeric extensions to each file starting with ".001" 3 = append a right justified numeric then ".JPG". The length of the numeric string is controlled by NameDigits. The extension can be changed using the API ITB_SetJpegExtension(). NameDigits Specifies how many digits are appended to the filename base when NamingMethod 3 is used. The value is ignored if NamingMethod is not set to 3. MaxPixelWidth The maximum width the output image should be in pixels. If the image is larger than this size, reduce it down to this maximum. This feature allows you to generate an image that fits in a standard size on an HTML (web) page. The image height will be affected by this size reduction as well. To translate without specifying a maximum value, use "-1" for this input. MaxPixelHeight The maximum height the output image should be in pixels. If the image is larger than this size, reduce it down to this maximum. This feature allows you to generate an image that fits in a standard size on an HTML (web) page. The image width will be affected by this size reduction as well. To translate without specifying a maximum value, use "-1" for this input. Return Value: 0 = no errors non-zero = error as defined in ITBDEFS.H int ITBAPI ITB_TransImage2Png(char FAR *lpSourceFileSpec, int FilesToConvert, char FAR *lpPngFileBase, int NamingMethod, int NameDigits, int MaxPixelWidth, int MaxPixelHeight) Description: Translate an image file to a PNG file using the specified values and current output configuration settings. The PNG file format supports both bitonal and color images. The format is not currently supported by all internet browsers. Note that PNG files only support a single image per file. If you are translating multiple page files, separate output files must be created. Parameters: lpSourceFileSpec Far pointer to a null terminated string containing a fully qualified path to the image file to be translated. FilesToConvert Which pages in the file to translate. 1 = translate the first page only 2 = translate all pages in the image file to separate PNG files lpPngFileBase The base of a fully qualified path to the PNG file(s) to be written. The way this filespec is used is controlled by the NamingMethod. NamingMethod The output file naming strategy. These values determine how the lpPngFileBase parameter is used. 1 = use the name as specified in lpPngFileBase 2 = append numeric extensions to each file starting with ".001" 3 = append a right justified numeric then ".PNG". The length of the numeric string is controlled by NameDigits. The extension can be changed using the API ITB_SetPngExtension(). NameDigits Specifies how many digits are appended to the filename base when NamingMethod 3 is used. The value is ignored if NamingMethod is not set to 3. MaxPixelWidth The maximum width the output image should be in pixels. If the image is larger than this size, reduce it down to this maximum. This feature allows you to generate an image that fits in a standard size on an HTML (web) page. The image height will be affected by this size reduction as well. To translate without specifying a maximum value, use "-1" for this input. MaxPixelHeight The maximum height the output image should be in pixels. If the image is larger than this size, reduce it down to this maximum. This feature allows you to generate an image that fits in a standard size on an HTML (web) page. The image width will be affected by this size reduction as well. To translate without specifying a maximum value, use "-1" for this input. Return Value: 0 = no errors non-zero = error as defined in ITBDEFS.H ---------------------------------------------------------------------- *** AUTOMATIC IMAGE FILE TRANSLATION TO ADOBE ACROBAT PDF FUNCTIONS *** BACKGROUND AND IMPLEMENTATION NOTES: Now many popular bitonal and color image file formats can be translated to Adobe Acrobat PDF files. The Acrobat driver is not required to create the output files. The images are stored in the PDF file(s) as image data. A list of the supported input file formats can be found in the "Automatic Image File Translation" section. It is possible to configure a number of PDF file creation settings to match your exact output requirements using the API function ITB_SetTransPdfOptions(). Additional API functions allow you to specify image handling strategies that are common to all file formats. These are described in the "Translation Configuration Functions" section of this documentation. Please review those APIs for important features that affect these functions. If you want to create PDF files using the Acrobat driver, please see the printing API functions in the "Image Printing Functions" section of this documentation. int ITBAPI ITB_SetTransPdfOptions(int PageSize, int PageOrientation, int HorizontalMargin, int VerticalMargin, int InitialRotation, int OptimizedRotation) Description: Set various characteristics of the output PDF files. This function should be called once before translating to PDF. The settings remain in effect until called again or the DLL is unloaded from memory. If this function is not called, the default values for each setting are used. Parameters: PageSize This is the page size to create for each image. Use one of the following settings as defined in ITBDEFS.H: ITB_LETTER (default) ITB_LEGAL ITB_EXECUTIVE ITB_A4 ITB_A5 ITB_B5 ITB_IMAGESIZE = make the page size the same as the image PageOrientation This is the page orientation to use for each page. If the PageSize selected is ITB_IMAGESIZE this value has no effect. Use one of the following settings as defined in ITBDEFS.H: ITB_PORTRAIT (default) ITB_LANDSCAPE HorizontalMargin This is the margin (white space) to use on the left and right of the image in points (1/72 inch). Use 0 for no margin up to the maximum of 144. If the PageSize selected is ITB_IMAGESIZE this value will be added to sides of the image to create a larger page size. The default is 0. VerticalMargin This is the margin (white space) to use on the top and bottom of the image in points (1/72 inch). Use 0 for no margin up to the maximum of 144. If the PageSize selected is ITB_IMAGESIZE this value will be added to top and bottom of the image to create a larger page size. The default is 0. InitialRotation The number of degrees to rotate the image clockwise before determining how it fits on the page. Use this feature to rotate consistently inverted images (scanned upside down), or switch between landscape and portrait orientations. If the PageSize selected is ITB_IMAGESIZE this value has no effect. Valid values are 0, 90, 180 and 270. Use 0 for no initial rotation. The default is 0. OptimizedRotation The number of degrees to rotate the image clockwise if it fits on the page better (with less or no image reduction). If there is an InitialRotation value specified, this optimization is performed after the first rotation. Use this feature when it is desirable to to rotate some images that may be taller or wider than others, such as situations where various types of documents are scanned in a set. If the PageSize selected is ITB_IMAGESIZE this value has no effect. Valid values are 0, 90 and 270. Use 0 for no optimization. The default is 0. Return Value: 0 = no errors non-zero = error as defined in ITBDEFS.H Implementation Notes: * Some bitonal images will have better display quality if a standard page size is selected for PageSize rather than ITB_IMAGESIZE. * Combining large margin values with OptimizedRotation can cause unintentional image rotation. Documents that are wide and short (such checks or receipts) combined with large horizontal margins may fit without image reduction if rotated. Reduce your margin settings if you find your images rotated unexpectedly. * Margins on JPEG compressed images may be wider than specified depending on the program that created the source file. int ITBAPI ITB_TransImage2Pdf(char FAR *lpSourceFileSpec, int FilesToConvert, char FAR *lpPdfFileBase, int NamingMethod, int NameDigits, int AppendExisting) Description: Translate an image file to an Adobe Acrobat PDF file using the specified values and current output configuration option settings. If an image does not fit on the selected page size it is reduced to fit on the page. Each image is written to a separate page in the same order they are found in the source file. Use the API function ITB_SetTransPdfOptions() to customize the characteristics of each PDF page and how the images are positioned on the page. Parameters: lpSourceFileSpec Far pointer to a null terminated string containing a fully qualified path to the image file to be translated. FilesToConvert Which pages in the file to translate. 1 = translate the first page only 2 = translate all pages in the image file to separate PDF files 3 = translate all pages in the image file to a single PDF file lpPdfFileBase The base of a fully qualified path to the PDF file(s) to be written. The way this filespec is used is controlled by the NamingMethod. NamingMethod The output file naming strategy. These values determine how the lpPdfFileBase parameter is used. 1 = use the name as specified in lpPdfFileBase 2 = append numeric extensions to each file starting with ".001" 3 = append a right justified numeric then ".PDF". The length of the numeric string is controlled by NameDigits. The extension can be changed using the API ITB_SetPdfExtension(). NameDigits Specifies how many digits are appended to the filename base when NamingMethod 3 is used. The value is ignored if NamingMethod is not set to 3. AppendExisting Determines whether the output file should be appended to an existing file of the same name, or overwrite it. 0 = overwrite an existing file of same name without warning. non-zero = append pages to any existing PDF file of the same name. Return Value: 0 = no errors non-zero = error as defined in ITBDEFS.H ---------------------------------------------------------------------- *** IMAGE TRANSLATION CONFIGURATION FUNCTIONS *** BACKGROUND AND IMPLEMENTATION NOTES: These API functions allow you to specify image handling strategies that are common to all translated file formats. These allow you to specify algorithms and settings to best batch your image characteristics and output file requirements. void ITBAPI ITB_SetPdfExtension(char FAR *lpExtension) void ITBAPI ITB_SetPngExtension(char FAR *lpExtension) Description: Set the extension used for each file type when using NamingMethod 3. The default three character extensions for each file type are: PDF -> PDF PNG -> PNG Note that the extensions for other output file types that can be also be "converted" are specified using the functions ITB_SetTiffExtension(), ITB_SetModcaExtension(), ITB_SetIocaExtension() and ITB_SetJpegExtension() as described in the ImageToolbox Silver documentation. Parameters: lpExtension Far pointer to a null terminated string of up to 6 characters. All characters must be valid DOS filename characters. Return Value: none int ITBAPI ITB_SetTransScalingMethod(int ScalingMethod) Description: Select the scaling method to use when an image size is reduced to fit on a page or stretched to increase the DPI (dots per inch). Different scaling methods work best on different types of images. Experiment with some samples of your images to determine the best setting. This function should be called once before translating any images if you want to change the setting. Parameters: ScalingMethod The desired type of scaling to use. Use one of the following settings as defined in ITBDEFS.H: ITB_SCALEAVERAGE - averages neighboring pixels and retains more black information (default) ITB_SCALEREDUCE - scales without examining neighboring pixels which can result in lost black information Return Value: 0 = no errors non-zero = error as defined in ITBDEFS.H Implementation Notes: Here are some guidelines for using each setting: ITB_SCALEAVERAGE: - When reducing the size of a color image this will soften the image in much the same way a "fog filter" does in photography. - Retains more black detail in bitonal images but can also turn some images into a mass of black depending on the amount of black in the original. - Will retain horizontal and vertical lines on images that were skewed during scanning. ITB_SCALEREDUCE: - When reducing the size of a color image will retain more of the sharpness of the original. - Will result in cleaner looking bitonal images but will sometimes drop too much black information from the image. - Horizontal lines in skewed images may have white gaps. int ITBAPI ITB_SetTransColorStrategy(int ColorTranslationStrategy) Description: Select the color modification strategy to use when converting color images to bitonal. Different color reduction methods work best on different types of images. Experiment with some samples of your images to determine the best setting. The setting also affects the way images are printed. See the description of ITB_SetPrintOptions() for more information. This function should be called once before translating any images if you want to change the setting. Parameters: ColorTranslationStrategy The desired type of conversion to use. Use one of the following settings as defined in ITBDEFS.H: ITB_COLOR_KEEP - retain the color in the output file. If not possible due to the output format use the ITB_COLOR_HALFTONE option. (default) ITB_COLOR_BAYER - reduce to bitonal using a Bayer fixed matrix dithering technique ITB_COLOR_DIFFUSION - reduce to bitonal using error diffusion ITB_COLOR_HALFTONE - reduce to bitonal using a fixed halftone matrix dithering technique Implementation Note: Each image format has different color support and may ignore some settings. Please use a setting that makes sense for the type of file you are creating. Here are the valid settings by output file type: MODCA - bitonal only, don't use ITB_COLOR_KEEP TIFF - color support varies depending upon the output file compression: - JPEG compression - 8 and 24 bit per pel color - ignores all settings - uncompressed - 1,4,8 and 24 bits per pel - all color strategies supported - all other compression types support bitonal only so don't use the ITB_COLOR_KEEP setting JPEG - 8 and 24 bit per pel color, ignores all settings PNG - 1,4,8 and 24 bits per pel, all color strategies supported Return Value: 0 = no errors non-zero = error as defined in ITBDEFS.H int ITBAPI ITB_SetTransJpegQuality(int JpegQuality, int HorizontalSampleRate, int VerticalSampleRate) Description: Select the JPEG quality values to use when saving JPEG compressed images. Different values work best on different types of images. Experiment with some samples of your images to determine the best settings. This function should be called once before translating any images if you want to change the setting. Parameters: JpegQuality This value adjusts the compression ratio to quality factor. The smallest output files have the least detailed images. Valid values are from 1 to 100 where: 1 = the smallest file size but the least image quality 100 = the best image quality but largest file size HorizontalSampleRate The horizontal sampling rate when determining the color to store in the output image. A value of 1 samples every pixel, 2 skips every other pixel, and so on. The best image quality will be retained using every pixel. Sampling fewer pixels may reduce the compressed image size. Valid values are 1 and up. The default value is 2. VerticalSampleRate The vertical sampling rate when determining the color to store in the output image. A value of 1 samples every pixel, 2 skips every other pixel, and so on. The best image quality will be retained using every pixel. Sampling fewer pixels may reduce the compressed image size. Valid values are 1 and up. The default value is 1. Return Value: 0 = no errors non-zero = error as defined in ITBDEFS.H Implementation Notes: * Reducing the JpegQuality value can have a dramatic effect on the output file size in the range between 80 to 100. It is often possible to use a value around 80 as a starting point for your testing. Reducing the value down to 60 may not have much impact on the file size, but noticable image quality degradation may occur. * These settings have no effect on color images stored in PDF format output files because their color content is not stored using JPEG compression. ---------------------------------------------------------------------- *** IMAGE MODIFICATION FUNCTIONS *** BACKGROUND AND IMPLEMENTATION NOTES: When processing an image file it is sometimes desirable to apply one or more modifications to the image before saving it in the output file. These functions specify the desired changes or settings to use when processing the image files. Call any of these functions once and the settings will be used when processing all subsequent image files. void ITBAPI ITB_TransInvertBitmap(int InvertDuringTranslation) Description: During translation invert all pels in the image. This can be used to turn a white on black image to black on white. The default setting is not to invert the image. Undesired switching of the bitmap can happen during conversion when default formating tags are missing in an image file. If the "translation" actually "converts" the image instead, this function will have no effect. Use the ITB_SetTiffBlackBit() function instead. Parameters: InvertDuringTranslation 1 = invert the image during translation 0 = do not invert the image Return Value: none void ITBAPI ITB_TransChangeResolution(int ChangeDuringTranslation, int HorizontalDPI, int VerticalDPI, int ToleranceDPI) Description: During a translation, the resolution of the image may be changed. This feature is useful if your images come from a variety of sources and have different resolutions. Some viewers do not handle very low or high resolution images very well. The default setting is not to modify the image resolution during translation. If this setting is turned on, the optimizations in the translation APIs are disabled (where supported), and all images are decompressed and recompressed. Only the Gold translation functions are affected. The Silver conversion functions ignore this setting. This feature works when translating between most formats. The ToleranceDPI parameter allows up to the specified DPI variation from the desired DPI before the modification will occur. If you want the exact DPI values specified, set this parameter to 0. Even if one direction requires modification, the other will not necessarily be changed unless it exceeds the tolerance threshold. This can be useful if low resolution FAX are being processed for example where the image DPI is not exactly 100 or 200 (204 x 98 for low resolution fax). If the image resolution is adjusted, the bitmap is stretched in the desired direction and the image header value for the DPI is changed. The new resolution is the exact value specified in the API parameter. To turn off the feature, call the function with the parameter ChangeDuringTranslation set to 0. All other parameter values are ignored. Parameters: ChangeDuringTranslation 1 = change the image resolution during translation 0 = do not attempt resolution modifications HorizontalDPI The horizontal DPI desired for the translated image. VerticalDPI The vertical DPI desired for the translated image. ToleranceDPI The amount the DPI can vary from the desired value before DPI translation is performed. Any positive from 0 up is valid. Return Value: none ---------------------------------------------------------------------- *** IMAGE PRINTING FUNCTIONS *** BACKGROUND AND IMPLEMENTATION NOTES: Now many popular bitonal and color image file formats can be printed directly from your application using most Windows printer drivers. A list of the supported input file formats can be found in the "Automatic Image File Translation" section. It is possible to configure a number of print settings to match your exact requirements using the API function ITB_SetPrintOptions(). The printing function allows you to print directly to a selected filename and obtain status information at the end of the print processing. If you want to create PDF files without using the Adobe Acrobat driver, please see the PDF creation API functions in the "Adobe Acrobat PDF Functions" section of this documentation. int ITBAPI ITB_SetPrintOptions(int FastPrinting, int AdjustAspectRatio, int ReverseBits, int HorizontalMargin, int VerticalMargin, int InitialRotation, int OptimizedRotation) Description: Set various options to be used when printing image files. This function should be called once before printing. The settings remain in effect until called again or the DLL is unloaded from memory. If this function is not called, the default values for each setting are used. Parameters: FastPrinting Selects the type of printing used. Fast printing sends the bitmap to the printer where it may be scaled and reduced to bitonal (if required). This can result in significantly faster printing and sometimes better image quality (especially Postscript printers). Some printers may have problems or even fail to print using the FastPrinting mode. Regular printing performs all the image scaling and color conversion before sending the page to the printer and will normally work properly on all printers. Valid inputs are: 0 = use regular printing (default) non-zero = use fast printing AdjustAspectRatio Selecting this option causes images that have different values for their horizontal and vertical DPI (dots per inch) to be adjusted to the same DPI before printing. The larger DPI value is used. This can be useful when printing images such as low resolution fax pages which can sometimes print compressed vertically. The scaling method used is selected using the API ITB_SetTransScalingMethod(). Images with identical horizontal and vertical DPI values are not modified. Valid inputs are: 0 = no aspect ratio adjustment before printing non-zero = test and adjust images before printing (default) ReverseBits Reverse the setting of black and white bits before printing. This can be useful when printing documents scanned white on black. Valid inputs are: 0 = do not reverse bits before printing (default) non-zero = reverse bits before printing HorizontalMargin This is the margin (white space) to use on the left and right of the image in points (1/72 inch). Use 0 for no margin up to the maximum of 144. The default is 0. VerticalMargin This is the margin (white space) to use on the top and bottom of the image in points (1/72 inch). Use 0 for no margin up to the maximum of 144. The default is 0. InitialRotation The number of degrees to rotate the image clockwise before determining how it fits on the page. Use this feature to rotate consistently inverted images (scanned upside down), or switch between landscape and portrait orientations. Valid values are 0, 90, 180 and 270. Use 0 for no initial rotation. The default is 0. OptimizedRotation The number of degrees to rotate the image clockwise if it fits on the page better (with less or no image reduction). If there is an InitialRotation value specified, this optimization is performed after the first rotation. Use this feature when it is desirable to to rotate some images that may be taller or wider than others, such as situations where various types of documents are scanned in a set. Valid values are 0, 90 and 270. Use 0 for no optimization. The default is 0. Return Value: 0 = no errors non-zero = error as defined in ITBDEFS.H Implementation Notes: * The current setting of ITB_SetTransColorStrategy() is used to determine how to handle color images. If the current setting is ITB_COLOR_KEEP and you are printing to a bitonal printer, the driver will convert the image from color. In some cases the Windows printer driver will not manage this properly and the image will be printed as a black rectangle. In this situation, change the API setting to one of the conversion options to force the ImageToolbox to make the image bitonal before sending it to the printer. * Some printer drivers automatically add a page margin to their output to take into account the paper edge area that cannot be reliably printed. In this case the margins specified in this function are usually added to the margins created by the printer driver. If your margins are too large the setting values may need to be reduced to create the margin sizes you desire. * Combining large margin values with OptimizedRotation can cause unintentional image rotation. Documents that are wide and short (such checks or receipts) combined with large horizontal margins may fit without image reduction if rotated. Reduce your margin settings if you find your images rotated unexpectedly. int ITBAPI ITB_PrintFile(HWND hWnd, char FAR *Filename, int ShowPrintDialog, int PrintAllPages, int PrintBeginPage, int PrintEndPage, char FAR *Print2Filename, int *UserCancel, int *PagesPrinted) Description: Print an image file on the default printer. To set various print options call the API ITB_SetPrintOptions() once before printing. Parameters: hWnd The handle of the main window in your application. This value is used to associate the standard Windows "Print" dialog with your application. If you don't have access to the value of your window handle, the value NULL or 0 may be used. The value is used internally even if you do not display the dialog using the ShowPrintDialog setting. Filename The name of the image file to print. ShowPrintDialog Specifies whether the standard Windows Print dialog should be displayed before printing. If the dialog is display the user may override the values specified for PrintAllPages, PrintBeginPage, PrintEndPage and Print2Filename. Valid inputs are: 0 = do not display the dialog non-zero = display the dialog PrintAllPages Print all the pages of the image file. This value can be overridden using the Windows Print dialog if it is displayed. Valid inputs are: 0 = no, a begin and end page are specified below non-zero = yes print all the pages PrintBeginPage If PrintAllPages is zero, this specifies the first page to print, from 1 to the number of pages in the image file. This value can be overridden using the Windows Print dialog if it is displayed. PrintEndPage If PrintAllPages is zero, this specifies the last page to print, from 1 to the number of pages in the image file. This value can be overridden using the Windows Print dialog if it is displayed. Print2Filename If the print data stream should be printed to a file, this specifies the name of the file to store the print output. This has the same effect as selecting the "Print to file" option on a standard Windows Print dialog except that the output file naming is specified here. The user will not be presented with a filename query dialog when the print job begins. Specify a fully qualified path to a print file if you want to enable this feature. To print normally, specify a null pointer or string (NULL, 0 or ""). If a print file is specified the user cannot override this in the print dialog. UserCancel Indicates if the user cancelled the print operation from the Windows Print dialog. If the dialog is not displayed, the returned value will be 0. If the user cancels from a printer driver dialog, this return code will not be able to detect the action and will report that the job was not cancelled. Valid return values are: 0 = the user did not cancel the print operation from the print dialog non-zero = the user did cancel the print operation PagesPrinted Indicates the number of pages printed. The returned value can be from 0 to the number of pages in the image file. If the user cancels printing or an error is returned by the API function, this value will still be accurate. Return Value: 0 = no errors non-zero = error as defined in ITBDEFS.H ---------------------------------------------------------------------- Sample Code For The ImageToolbox Gold Functions ----------------------------------------------- For code samples of ImageToolbox Silver functions, please see the file ITBSAPI.TXT. #include "itbdefs.h" int rc; int UserCancel; int PagesPrinted; ITB_SetTiffExtension((char FAR *)"FAX"); // TIFF files created using NamingMethod 3 will have this extension ITB_SetModcaExtension((char FAR *)"MDA"); // MO:DCA files created using NamingMethod 3 will have this extension ITB_SetIocaExtension((char FAR *)"IOC"); // IOCA files created using NamingMethod 3 will have this extension ITB_SetJpegExtension((char FAR *)"JPEG"); // JPEG files created using NamingMethod 3 will have this extension ITB_SetPdfExtension((char FAR *)"PDF"); // PDF files created using NamingMethod 3 will have this extension ITB_SetPngExtension((char FAR *)"PNG"); // PNG files created using NamingMethod 3 will have this extension ITB_TransInvertBitmap(1); // invert the pels in all bitmaps translated /* Translate functions work same way as Convert functions. For more examples please see the samples in ITBSAPI.TXT. All parameters with the same name have the same input values and meanings. */ // During translations, convert all images to approximately 200 DPI. // Low res FAX (204W x 98H) will only be converted in height and the // width left at 204 DPI because the tolerance has been set to 5. ITB_TransChangeResolution(1,200,200,5); // All pages using the named base and appending a two digit zero padded // right justified number and extension. The extension is the default // or the last specified value in ITB_SetTiffExtension(). rc = ITB_TransModca2Tif((LPSTR)"source.mod",2,(LPSTR)"image_",3,2, TRANS_MODCA_G4,TRANS_TIFF_G3); // results in files image_01.fax, image_02.fax, image_03.fax ... // Turn off resolution modification during translation ITB_TransChangeResolution(0,0,0,0); // All pages using the named base and appending a two digit zero padded // right justified number and extension (MO:DCA). The extension used // is the default or one last specified by ITB_SetModcaExtension(). rc = ITB_TransTif2Modca((LPSTR)"source.tif",2,(LPSTR)"image_",3,2,1, TRANS_TIFF_G3); // results in files image_01.mda, image_02.mda, image_03.mda ... // All pages using the named base and appending a three digit zero padded // right justified number and extension (IOCA). The extension used // is the default or one last specified by ITB_SetIocaExtension(). rc = ITB_TransTif2Modca((LPSTR)"source.tif",2,(LPSTR)"image",3,3,0, TRANS_TIFF_UNCOMPRESSED); // results in files image001.ioc, image002.ioc, image003.ioc ... ITB_TransInvertBitmap(0); // turn off pel inverting when translating // Translate a batch of TIFF files to a single MO:DCA file rc = ITB_T2M_BeginBatch("G:\\BATCH.MOD"); // open the MO:DCA file if (! rc) { rc = ITB_T2M_TransBatch("G:\\src1.tif",0,TRANS_TIFF_G3); // write 1st image only if (! rc) { rc = ITB_T2M_TransBatch("G:\\src2.tif",1,TRANS_TIFF_G3); // write all images if (! rc) { rc = ITB_T2M_EndBatch(); // close the MO:DCA file } } } // Convert PTOCA files to TIFF ITB_SetTiffBlackBit(0); // overlays created using this setting // set all PTOCA processing options and preprocess the overlays rc = ITB_SetPtocaOptions("Courier New",10,1,0, 1,"$", 1,1,1, "f:\\overlays","OVL"); if (! rc) { // Enable PTOCA processing by the API ITB_CnvModca2Tif(), otherwise // encountering a PTOCA file in the Cnv function would return an error. ITB_SetPtocaCnvEnable(1); // convert MODCA/IOCA/PTOCA file types to TIFF rc = ITB_CnvModca2Tif((LPSTR)"f:\\samples\\src.pot",3, (LPSTR)"f:\\samples\\destpotc.tif",1,0); if (! rc) { // also process only PTOCA files using the dedicated function rc = ITB_TransPtoca2Tif((LPSTR)"f:\\samples\\src.pot",3, (LPSTR)"f:\\samples\\destpott.tif",1,0); } } /* Many popular image file formats can be read and converted to a selection of output file formats. */ // select the options to use during translations (call each function // once before translating to change any default values) rc = ITB_SetTransScalingMethod(ITB_SCALEREDUCE); // scaling may drop some image information rc = ITB_SetTransColorStrategy(ITB_COLOR_KEEP); // retain the input color where possible rc = ITB_SetTransJpegQuality(80,2,1); // retain most image information but create a smaller output file // now translate some image files // create a multiple page tif file stored in G4 format by appending other // TIFF files to the output file rc = ITB_TransImage2Tif((LPSTR)"source.tif",3, (LPSTR)"bigfile.tif",1,3, ITB_COMPRESSION_G4,TRUE); // create a single page bitonal MODCA file from a color JPEG using a // halftone dithering technique rc = ITB_TransImage2Modca((LPSTR)"source.jpeg",1, (LPSTR)"photo.modca",1,3, FALSE); // translate the bitonal TIFF document to JPEG and make the maximum width // and height 300 pixels for proper display on the HTML page rc = ITB_TransImage2Jpeg((LPSTR)"document.tiff",1, (LPSTR)"webdoc.jpg",1,3, 300,300); // translate the first page of a bitonal MODCA document to PNG with the // output page size the same as the source rc = ITB_TransImage2Png((LPSTR)"document.mod",1, (LPSTR)"webdoc.png",1,3, -1,-1); /* Many popular image file formats can be read and converted to Adobe Acrobat format PDF files. */ // Create images on letter sized paper in portrait orientation with no // margins added. If the source image is landscape and would fit better // rotated, do the rotation so that the bottom of the original image is // on the right side of the paper. rc = ITB_SetTransPdfOptions(ITB_LETTER,ITB_PORTRAIT, 0,0, 0,270); // translate all the pages in the TIFF file to the named PDF file and // overwrite an existing PDF file of the same name rc = ITB_TransImage2Pdf((LPSTR)"miscdocs.tif",3, (LPSTR)"thiscase.pdf",1,3, FALSE); // create actual size pages with a 1/4 inch white border that are // rotated 90 degrees clockwise rc = ITB_SetTransPdfOptions(ITB_IMAGESIZE, ITB_PORTRAIT, // ignored 18,18, 90, 0); // ignored // translate the JPEG image to the PDF in color and append it to the // existing PDF file rc = ITB_TransImage2Pdf((LPSTR)"frame6.jpg",1, (LPSTR)"vacation.pdf",1,3, TRUE); /* Many popular image file formats can be printed. */ // print using 1 inch horizontal and 1/2 inch vertical margins with // initial rotation and optimized rotations. rc = ITB_SetPrintOptions(FALSE,FALSE,FALSE, 72,36, 90,90); // Print all the pages in the MODCA file. If the function returns without // an error the values of usercancel and pagesprinted can be used for // any extra handling desired. rc = ITB_PrintFile((HWND)NULL, (LPSTR)"landscape.mod", TRUE,TRUE,0,0, (LPSTR)"", &usercancel,&pagesprinted);