The ImageToolbox Silver API Reference ************************************* Version: 2.0.1 November, 2000 The ImageToolbox Silver (ITBS20.DLL) is designed to provide very fast conversions between MO:DCA/IOCA and TIFF file formats. Both source and destination files must have the same compression format (normally G4). The functions are designed to provide the fastest possible image file conversions. To achieve such speed, we have created specialized APIs to deal with each type of file format. Using this approach, the code does not need to waste time determining the input file format. The Toolbox now supports conversion of MO:DCA/IOCA files containing JPEG compressed images to TIFF and JPG file formats. The JPEG display capabilities in various image viewers is not always available, so the Toolbox provides two different methods of storing these images. Running the conversions on a computer with a fast hard drive is very desirable. Normally the conversion speed is limited by the speed of the file read/writes. ---------------------------------------------------------------------- Files Included In The ImageToolbox Silver ----------------------------------------- The ImageToolbox has one runtime DLL, ITBS20.DLL which is required to use the API functions. The file should normally reside with 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 ITBSDEFS.BAS can be included in the project instead to provide the same information. Include the library file ITBS20.LIB when linking your application (if required by your link environment) to resolve the API functions contained in ITBS20.DLL. ---------------------------------------------------------------------- System Resources Used --------------------- The ImageToolbox Silver DLL features, settings and options are controlled by the program that is using the DLL. The Toolbox does not create any temporary files, use any environment variables, nor create or use any Windows Registry entries. ---------------------------------------------------------------------- Year 2000 Compliance -------------------- Aside from using the Operating System (OS) functions to create output files and obtain the current system date there are no other date sensitive operations in the DLL. Our testing has shown that when running an OS that is Y2K ready the Toolbox correctly creates files on the dates Dec 31/1999, Jan 1/2000 and Feb 29/2000. ---------------------------------------------------------------------- JPEG Compression Issues ----------------------- The JPEG compression standard continues to evolve and support different methods of compression. Many Image Viewer programs can display only the earliest versions of JPEG compression. Before converting a large number of JPEG compressed image files, please test a few to determine if your viewer program can handle the images. Generally JPEG generation programs (such as some of the the IBM Image products) should be configured to create Baseline JPEG compressed images (not Progressive JPEG). ********************************************************************** *** IMAGETOOLBOX DLL INFORMATION AND STATISTICS FUNCTIONS *** int ITBAPI ITB_GetVersionInfo(int FAR *Major, int FAR *Minor, int FAR *Build, int FAR *ExpDay, int FAR *ExpMonth, int FAR *ExpYear) Description: Determine the revision information about the DLL. If the Toolbox is time limited, the function returns one of the values listed below and the last date the Toolbox will operate is returned. Parameters: Major Far pointer to an int, the Toolbox major revision is returned. Minor Far pointer to an int, the Toolbox minor revision is returned. Build Far pointer to an int, the Toolbox build revision is returned. ExpDay Far pointer to an int, the expiration day is returned. ExpMonth Far pointer to an int, the expiration month is returned. ExpYear Far pointer to an int, the expiration year is returned. Return Value: 1 = Unrestricted version. The values of ExpDay, ExpMonth, and ExpYear are meaningless. 0 = The Toolbox has a time restriction. The expiration date is contained in the return values of ExpDay, ExpMonth, and ExpYear. The DLL will still operate. -1 = The Toolbox has a time restriction that has expired. The expiration date is contained in the return values of ExpDay, ExpMonth, and ExpYear. The DLL will not convert any image files. int ITBAPI ITB_GetLicenseInfo(char FAR *lpLicense) Description: Retrieve the license information from the DLL. Parameters: lpLicense Pointer to a character array to receive the null terminated license information string. The buffer must be at least 20 characters long. Return Value: N = length of the license string in bytes. int ITBAPI ITB_GetPagesInLastImage(void) Description: Retrieve the number of pages converted/translated in the last image file processed. Return Value: N = The number of image pages processed in the last file. If the file conversion encounters an error, the returned value is 0. long ITBAPI ITB_GetTotalPagesProcessed(void) Description: Retrieve the total number of pages converted/translated since the DLL was loaded. This counter value may be set to a user specified value using the function ITB_SetPagesProcessedCounter(). Return Value: N = The total processed counter value. Note the function return is a "long" value due to the large volumes that could occur in production environments. ---------------------------------------------------------------------- *** MODCA/IOCA FORMAT CONVERSION TO TIFF OR JPEG FUNCTIONS *** int ITBAPI ITB_CnvModca2Tif(char FAR *lpModcaFileSpec, int FilesToConvert, char FAR *lpTiffFileBase, int NamingMethod, int NameDigits) Description: Called to convert a MO:DCA file to a TIFF file. Both single and multi-image MO:DCA files can be processed, as well as IOCA files. Multi-image source files are converted using the strategy specified by FilesToConvert. The file naming strategy is controlled by the NamingMethod setting. If JPEG compressed images are stored in the MO:DCA source file, these images will be stored in the output TIFF file(s). If you want to create raw JPEG files instead, use the Toolbox function ITB_CnvModca2FileType(). Parameters: lpModcaFileSpec Far pointer to a null terminated string containing a fully qualified path to the MO:DCA file to be converted. FilesToConvert Which pages in the file to convert. 1 = convert the first image only 2 = convert all images in the MO:DCA file to separate TIFF files 3 = convert 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. Return Value: 0 = no errors non-zero = error as defined in ITBDEFS.H int ITBAPI ITB_CnvModca2FileType(char FAR *lpModcaFileSpec, int FilesToConvert, char FAR *lpOutFileBase, int NamingMethod, int NameDigits) Description: Called to convert a MO:DCA file to single page TIFF or JPEG file(s) in the specified directory. Both single and multi-image MO:DCA files can be processed, as well as IOCA files. Multi-image source files are converted to multiple single page files using the naming strategy selected by the NamingMethod value. When an image is found that is stored with JPEG compression, the output file is created as a raw JPEG file. All other compression methods (such as Uncompressed, CCITT G3 and G4) are written to single page TIFF files. If you want to store JPEG compressed images to one or more TIFF files, use the Toolbox function ITB_CnvModca2Tif(). Parameters: lpModcaFileSpec Far pointer to a null terminated string containing a fully qualified path to the MO:DCA file to be converted. FilesToConvert Which pages in the file to convert. 1 = convert the first image only 2 = convert all images in the MO:DCA file to separate TIFF files lpOutFileBase The base of a fully qualified path to the output 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 lpOutFileBase parameter is used. 1 = use the name as specified in lpOutFileBase 2 = append numeric extensions to each file starting with ".001" 3 = append a right justified numeric then ".TIF" or ".JPG", depending on the type of compression used in the MO:DCA file. The length of the numeric string is controlled by NameDigits. The filename extensions can be changed using the APIs ITB_SetTiffExtension() and 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. Return Value: 0 = no errors non-zero = error as defined in ITBDEFS.H ---------------------------------------------------------------------- *** TIFF FORMAT CONVERSION TO MODCA/IOCA FUNCTIONS *** int ITBAPI ITB_CnvTif2Modca(char FAR *lpTiffFileSpec, int FilesToConvert, char FAR *lpModcaFileBase, int NamingMethod, int NameDigits, int ModcaFormat) Description: Called to convert a TIFF file to a MO:DCA file. Both single and multi-image TIFF files can be converted to MO:DCA or IOCA files. Multi-image source files are converted using the strategy specified by FilesToConvert. The file naming strategy is controlled by the NamingMethod setting. If JPEG compressed images are stored in the TIFF source file, these images will be stored in the output file(s) in the format selected by the ModcaFormat setting. Parameters: lpTiffFileSpec Far pointer to a null terminated string containing a fully qualified path to the TIFF file to be converted. FilesToConvert Which pages in the file to convert. 1 = convert the first image only 2 = convert all images in the TIFF file to separate MO:DCA files 3 = convert 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 Return Value: 0 = no errors non-zero = error as defined in ITBDEFS.H int ITBAPI ITB_T2M_BeginBatch(char FAR *lpModcaFileSpec) Description: Begin converting multiple TIFF files into a single MO:DCA file. This function must be called once before calls to ITB_T2M_WriteBatch() to open the named output file. Parameters: lpModcaFileSpec A fully qualified name of a MO:DCA file that is to be written. If the specified MO:DCA file already exists, it is overwritten. Return Value: 0 = no errors non-zero = error as defined in ITBDEFS.H int ITBAPI ITB_T2M_WriteBatch(char FAR *lpTiffFileSpec, int WriteAll) Description: Convert the contents of a TIFF file to the MO:DCA file previously opened with the function ITB_T2M_BeginBatch(). The image(s) are appended to any already existing in the output file. If JPEG compressed images are stored in the TIFF source file, these images will be stored in the output MO:DCA file using the same JPEG compression. This function may be called repeatedly to create multiple image MO:DCA files. After all the TIFF files desired have been written, the function ITB_T2M_EndBatch() must be called to close the MO:DCA file. Note that the MO:DCA architecture does not support an infinite number of images per file, and viewers may have lower limits than the MO:DCA specification. Users must ensure that the larger MO:DCA files created can be used by their target application. Parameters: lpTiffFileSpec Far pointer to a null terminated string containing a fully qualified path to the TIFF file to be converted. WriteAll Specifies which images to write to the output file: 0 = first image of the TIFF file 1 = all images in the TIFF file Return Value: 0 = no errors non-zero = error as defined in ITBDEFS.H int ITBAPI ITB_T2M_EndBatch(void) Description: Called after all the TIFF files desired have been written using ITB_T2M_WriteBatch() to properly terminate the MO:DCA file and close it. Return Value: 0 = no errors non-zero = error as defined in ITBDEFS.H ---------------------------------------------------------------------- *** IMAGE CONVERSION CONFIGURATION FUNCTIONS *** void ITBAPI ITB_SetPagesProcessedCounter(long CounterValue) Description: Set the total pages converted/translated counter to a value. This can be used if batch counts are required. Parameters: CounterValue The new value for the counter. Note this is a "long" value due to the large volumes that could occur in production environments. Return Value: none void ITBAPI ITB_SetTiffBlackBit(int BlackBit) Description: Set the value of the photometric interpretation TIFF tag. This tag specifies whether bits set to 1 in bilevel images should be interpreted as black or white. Parameters: BlackBit Valid values are 1 and 0 only. If this function is not called, the default setting is 1. Note that many TIFF viewers appear to ignore this bit setting. Return Value: none void ITBAPI ITB_ReadMMRAsG4(int ReadAsG4) Description: When converting MO:DCA to TIFF, interpret image compression settings of MMR as G4. Some versions of IBM products may have set this value improperly. The default behaviour of the Toolbox is to treat MMR as MMR, which is an unsupported format in TIFF. Changing this setting does NOT have any effect on the image data. If the data is truly encoded as MMR the output file will not display properly. To modify the compressed image data, use the Gold version of the Toolbox, and the API called ITB_TransModca2Tif(). The setting remains in effect until the function is called again or the Toolbox is terminated. Parameters: ReadAsG4 Specifies how to interpret the MMR compression setting: 0 = treat MMR compressed images as MMR (default) 1 = interpret the setting as G4 instead of MMR Return Value: none void ITBAPI ITB_SetTiffExtension(char FAR *lpExtension) void ITBAPI ITB_SetModcaExtension(char FAR *lpExtension) void ITBAPI ITB_SetIocaExtension(char FAR *lpExtension) void ITBAPI ITB_SetJpegExtension(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: TIFF -> TIF MO:DCA -> MOD IOCA -> ICA JPEG -> JPG Parameters: lpExtension Far pointer to a null terminated string of up to 3 characters. All characters must be valid DOS filename characters. Return Value: none ********************************************************************** *** IMAGETOOLBOX SILVER SAMPLE CODE *** For more code samples of these and the Gold functions, please see the file ITBGAPI.TXT. #include "itbdefs.h" int rc; int Major, Minor, Build, ExpDay, ExpMonth, ExpYear; char licensestr[22]; rc = ITB_GetVersionInfo(&Major,&Minor,&Build,&ExpDay,&ExpMonth,&ExpYear); if (rc) // this is an unrestricted version else // this is a restricted version good until ExpDay/ExpMonth/ExpYear rc = ITB_GetLicenseInfo(licensestr); // get the ImageToolbox license string ITB_SetTiffExtension((char FAR *)"TIFF"); // TIFF files created using NamingMethod 3 will have this extension ITB_SetModcaExtension((char FAR *)"MOD"); // 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 /* Convert the named MO:DCA file to TIF file(s) in the directory specified using the input strategies. FilesToConvert 1 = first page only 2 = all pages to separate files 3 = all pages to a single TIFF file NamingMethod 1 = use the name as specified 2 = append extension starting with 001 3 = append right justified numeric then .TIF NameDigits Number of digits to use when NamingMethod 3 in use NULL return code indicates no errors, otherwise it's an error code. */ ITB_ReadMMRAsG4(TRUE); // all following MODCA/IOCA images have a compression setting of MMR // but are actually G4 compressed // first page only to the exact name specified rc = ITB_CnvModca2Tif((LPSTR)"source.mod",1,(LPSTR)"outfile.tif",1,0); // all pages using the named base and appending an extension rc = ITB_CnvModca2Tif((LPSTR)"source.mod",2,(LPSTR)"outfile",2,0); // results in files outfile.001, outfile.002, outfile.003 ... ITB_ReadMMRAsG4(FALSE); // all following MODCA files have accurate compression settings // all pages using the named base and appending a two digit zero padded // right justified number and extension rc = ITB_CnvModca2Tif((LPSTR)"source.mod",2,(LPSTR)"image_",3,2); // results in files image_01.tif, image_02.tif, image_03.tif ... // all pages using the named base and appending an 8 digit numeric // filename and ext rc = ITB_CnvModca2Tif((LPSTR)"source.mod",2,(LPSTR)"g:\\tiffs\\",3,8); // results in files g:\tiffs\00000001.tif, g:\tiffs\00000002.tif ... // Convert all pages using the named base and appending an 8 digit // numeric filename and extension by file type. The source file // contains mixed bitonal and JPEG content, so the output files are // created as TIFF for bitonal, and JPG for JPEG. rc = ITB_CnvModca2FileType((LPSTR)"mixed.mod",2,(LPSTR)"g:\\mixed\\",3,8); // results in files g:\mixed\00000001.tif, g:\mixed\00000002.jpg ... // ----------------------------------------------------------------------- /* Convert the named TIFF file to MO:DCA or IOCA file(s) in the directory specified using the input strategies. FilesToConvert 1 = first page only 2 = all pages to separate files (type determined by ModcaFormat setting) 3 = all pages to a single MO:DCA file NamingMethod 1 = use the name as specified 2 = append extension starting with 001 3 = append right justified numeric then .MOD/ICA NameDigits Number of digits to use when NamingMethod 3 in use ModcaFormat 1 = MODCA output format 0 = IOCA file format NULL return code indicates no errors, otherwise it's an error code. */ // first page only to the exact name specified (MO:DCA) rc = ITB_CnvTif2Modca((LPSTR)"source.tif",1,(LPSTR)"outfile.mod",1,0,1); // first page only to the exact name specified (IOCA) rc = ITB_CnvTif2Modca((LPSTR)"source.tif",1,(LPSTR)"outfile.ica",1,0,0); // all pages to the exact name specified (MO:DCA only) rc = ITB_CnvTif2Modca((LPSTR)"source.tif",3,(LPSTR)"allimgs.mod",1,0,1); // all pages using the named base and appending an extension (MO:DCA) rc = ITB_CnvTif2Modca((LPSTR)"source.tif",2,(LPSTR)"outfile",2,0,1); // results in MO:DCA files outfile.001, outfile.002, outfile.003 ... // all pages using the named base and appending an extension (IOCA) rc = ITB_CnvTif2Modca((LPSTR)"source.tif",2,(LPSTR)"outfile",2,0,0); // results in IOCA files outfile.001, outfile.002, outfile.003 ... // all pages using the named base and appending a two digit zero padded // right justified number and extension (MO:DCA) rc = ITB_CnvTif2Modca((LPSTR)"source.tif",2,(LPSTR)"image_",3,2,1); // results in files image_01.mod, image_02.mod, image_03.mod ... // all pages using the named base and appending a three digit zero padded // right justified number and extension (IOCA) rc = ITB_CnvTif2Modca((LPSTR)"source.tif",2,(LPSTR)"image",3,3,0); // results in files image001.ica, image002.ica, image003.ica ... // all pages using the named base and appending an 8 digit numeric // filename and ext (IOCA) rc = ITB_CnvTif2Modca((LPSTR)"source.tif",2,(LPSTR)"g:\\iocas\\",3,8,0); // results in files g:\iocas\00000001.ica, g:\iocas\00000002.ica ... rc = ITB_GetPagesInLastImage(); // returns the # of pages processed by the last conversion call rc = (WORD)ITB_GetTotalPagesProcessed(); // returns the total # of pages processed since the last counter setting ITB_SetPagesProcessedCounter(0L); // set the total pages processed counter to 0 ITB_SetTiffBlackBit(0); // interpret bits set to 0 as black // Convert a batch of TIFF files to MO:DCA rc = ITB_T2M_BeginBatch("G:\\BATCH.MOD"); // open the MO:DCA file if (! rc) { rc = ITB_T2M_WriteBatch("G:\\src1.tif",0); // write 1st image only if (! rc) { rc = ITB_T2M_WriteBatch("G:\\src2.tif",1); // write all images if (! rc) { rc = ITB_T2M_EndBatch(); // close the MO:DCA file } } }