In This Topic ▼

L_CompactFile

Summary

Compacts TIFF / BigTIFF files, Exif metadata in PNG and Exif JPEG files. Can also compact Exif metadata in PNG or Exif JPEG files.

Note: It can also be used to copy or extract one or more pages from a TIFF / BigTIFF file and copy them without recompression to another TIFF / BigTIFF file.

Syntax

#include "l_bitmap.h"

L_LTFIL_API L_INT L_CompactFile(pszSrcFile, pszDstFile, uPages, pLoadFileOption, pSaveFileOption)

Parameters

L_TCHAR* pszSrcFile

Character string containing the name of the file being compacted. All of the pages will be read from this file.

L_TCHAR* pszDstFile

Character string containing the name of the file to which all the pages will be written. This cannot be NULL. If this is NULL, the function will return an error. The pages can be added to this file using the pSaveFileOption parameter.

L_UINT uPages

Value that represents the number of pages to copy. Use 0 to copy all of the pages. If uPages is > 0, only uPages will be copied to pszDstFile.

pLOADFILEOPTION pLoadFileOption

Optional pointer to the LOADFILEOPTION structure, which can be used to specify a starting page. You can speed up access to the starting page by using the IFD. Passing NULL is equivalent to starting from the first page and to use the default load options.

pSAVEFILEOPTION pSaveFileOption

Optional pointer to the SAVEFILEOPTION structure, which can be used to specify where to save the data or how to modify an existing file. You can modify whether the new pages should appended, inserted, or replace existing pages. Pass NULL to use the default save options.

Returns

Value	Meaning
SUCCESS	The function was successful.
ERROR_COMPACT_ABORTED	The function encountered an error while reading a page from the source file. Not all of the pages have been copied to the destination file.
ERROR_TAG_VALUE_TOO_BIG	This error can occur while converting BigTIFF files to regular TIFF files when the source file contains a 64-bit integer value that cannot be converted into a 32-bit integer value due to overflow. This error can occur because TIFF files do not support 64-bit integer values.
< 1	An error occurred. Refer to Return Codes.

Comments

This function can also be used to convert a TIFF file to BigTIFF and vice versa (BigTIFF -> TIFF).

The following members of the LOADFILEOPTION structure are important for this function:

PageNumber: specifies the start page. Page 0 is the first page, page 1 is the second page, etc. The pages will be read starting with this page.
Flags: specifies whether to use the IFD.
IFD: used only if Flags contains the ELO_USEIFD flag. If ELO_USEIFD is not set, the PageNumber references the beginning of the file.

If pSaveFileOption is NULL and if pszDstFile exists, pszDstFile will be overwritten regardless of its format. Also, defaults will be used when saving the file (it will be saved in Intel format). Refer to the SAVEFILEOPTION documentation. TIFF files can be saved either in Intel or Motorola byte order (see SAVEFILEOPTIONS.Flags and the ESO_MOTOROLAORDER flag.)

NOTE: To save a region inside a TIFF file, you must have an unlocked Document or Medical Imaging license.

If pSaveFileOption is not NULL, the following members of the SAVEFILEOPTION structure are important for this function:

PageNumber: specifies the starting page. This parameter is used as follows:
- If ESO_INSERTPAGE is set in Flags, all pages are inserted before this page.
- If ESO_REPLACEPAGE is set in Flags, this page and the remaining uPages 1 will be replaced.
If none of the above parameters are set, then:
- If PageNumber is 0, the file will be overwritten.
- If PageNumber is <> 0, the pages will be appended to the end of the file.
IFD: can be used to speed up file access for TIFF files having many pages. Used only if ESO_USEIFD is set in Flags.

Flags: can be used to specify one or more options:

ESO_NOSUBFILETYPE if this flag is set, the TGSUBFILETYPE tag will be stripped from all the pages.
ESO_REPLACEPAGE if this is set, the pages in pszDstFile are replaced starting with page PageNumber.
ESO_INSERTPAGE - if this is set, all pages are inserted before page PageNumber.
ESO_USEIFD if this is set, the first page in pszDstFile is at offset IFD. All pages will be relative to that page. (Note that this might not be the first physical page in the file). This is a common technique for manipulating files with thousands of pages.
ESO_MOTOROLAORDER if this is set and a new file is being created, the pages will be saved in Motorola byte order. If the flag is not set, the pages will be saved in Intel byte order. If you are modifying an existing file, this flag has no meaning: the pages will be saved in the same byte order that the file uses.

Flags2: Can be used to specify one or more of the following options:

ESO2_BIGTIFF: if set, the destination file will be BigTIFF instead of regular TIFF. BigTIFF files are similar to TIFF files, but are somewhat non-standard and not supported by all readers. But BigTIFF files use 64-bit file offsets so they can be greater than 4GB.

If the source file is PNG or Exif JPEG, this function will compact and regenerate the Exif metadata to save space. This is particularly useful for JPEG files, since the exif metadata is limited to 64K in size. Consequently, compacting the Exif metadata can make the difference between being able to add comments, tags or stamps to a Exif JPEG file and failing.

Also, if the source file is Exif JPEG or PNG, the settings regarding pages, IFD, should be used carefully because you might not get the results you expect. The only useful values for uPages are 0 or 1 because exif metadata has at most 2 IFDs: one describing the main image and the second containing an optional stamp. The side effect is that calling L_CompactFile for a PNG or Exif JPEG file and passing a 1 for the number of pages, discards the stamp.

Required DLLs and Libraries

LTFIL
LFTIF
For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application.

Platforms

Win32, x64, Linux.

Example

The first example will compact all the pages in a TIFF file.
It will create a new file called dstfile.tif.
The second example will compact all the pages in a TIFF file.
It will append all the pages to an existing file called dstfile.tif.

L_INT CompactFileFirstExample(L_VOID) 
{ 
   L_INT nRet; 
   nRet = L_CompactFile(MAKE_IMAGE_PATH(TEXT("clean.tif")),MAKE_IMAGE_PATH(TEXT("dstfile.tif")), 0, NULL, NULL); 
   if(nRet != SUCCESS) 
   { 
      MessageBox(NULL, TEXT("Error compacting file!"), TEXT("ERROR"), MB_OK); 
      return nRet; 
   } 
   return SUCCESS; 
} 
 
L_INT CompactFileSecondExample(L_VOID) 
{ 
   L_INT nRet; 
   SAVEFILEOPTION SaveFileOption; 
   nRet = L_GetDefaultSaveFileOption(&SaveFileOption, sizeof(SaveFileOption)); 
   if(nRet != SUCCESS) 
      return nRet; 
   SaveFileOption.PageNumber = 2; 
 
   nRet = L_CompactFile(MAKE_IMAGE_PATH(TEXT("clean.tif")),MAKE_IMAGE_PATH(TEXT("dstfile.tif")), 0, NULL, &SaveFileOption);  
   if(nRet != SUCCESS)  
   { 
      MessageBox(NULL, TEXT("Error compacting file!"), TEXT("ERROR"), MB_OK); 
      return nRet; 
   } 
   return SUCCESS;  
}