Loading and Saving Images

LEADTOOLS provides many options for loading and saving image files. Nevertheless, the code can be as simple as the following, which loads a LEAD compressed file and saves it as a Windows BMP file: 

LBitmapBase TmpBitmap; /* LBitmapBase object for the temporary bitmap */   
/* Load a bitmap at its own bits per pixel */   
TmpBitmap.Load(TEXT("v:\\images\\eagle.cmp"), 0, ORDER_BGR);   
/* Save the image as a 24-bit Windows BMP file */   
TmpBitmap.Save(TEXT("d:\\temp\\test.bmp"), FILE_BMP, 24, 0, 0); 

Obtaining Image File Information

LEADTOOLS has many functions that provide file information, including the following functions: 

• LBaseFile::GetFilterInfo - Gets the current information for a specific filter.
• LFile::GetInfo - Gets the current information for a specific file.
• LBaseFile::GetFilterListInfo - Gets information for an array of filters used by LEADTOOLS.
• LBaseFile::SetFilterInfo - Changes information for all of the fillters.
• LBaseFile::FreeFilterInfo - Frees the memory allocated by calling the LBaseFile::GetFilterListInfo or LBaseFile::GetFilterInfo function.
• LFile::GetInfo - Provides information about the specified file.
• FILTERINFO - Structure containing filter information.
• FILEINFO - Structure containing file information. 

Whether an image file is on disk or in memory, you can get information about the image before loading it.  For more information, see Raster Image Functions: Getting and Setting File Information.

Loading Images

Regardless of the video mode, with LEADTOOLS functions you can load an image at its own color resolution, manipulate it, and display it. You can also handle file-format-specific information, such as the page number or physical resolution. 

LEADTOOLS will attempt to load corrupted files (so you can see at least a portion of the image). For such images, the load functions will return SUCCESS, but LBitmapBase::GetLoadStatus will return an error code. 

LEADTOOLS also supports super compressed images. Only 1-bit and 24-bit bitmaps can be kept super compressed in memory. For more information, refer to Super Compressed Bitmaps. 

Support for loading images is provided by the following functions: 

• LBitmapBase::LoadResize - Loads an image from a file into a bitmap, resizing it as it loads.
• LFile::StartFeedLoad, LFile::FeedLoad, and LFile::StopFeedLoad - Controls the execution of a load or file information procedure as you supply transmitted image data.

Saving Images

LEADTOOLS toolkits offer many ways to save a file on disk, as follows:

• LBitmapBase::Save  - Saves the class object's bitmap image to a file in any of the supported compressed or uncompressed formats.
• LFile::Save - Saves an image contained in the class object's associated bitmap to a file, in any of the supported compressed or uncompressed formats.
• LFile::SaveList - Saves the specified list of bitmaps in a multipage file.
• LBitmapList::Save - Saves the class object's bitmap list in a multi-page file.
• LFile::SaveWithLayers - Saves the class object's associated bitmap to a file, along with the specified layers.
• LFile::SaveCMYKArray - Saves an array of bitmaps as a CMYK TIFF file.
• LFile::SaveFile - Creates a file in any of the supported compressed or uncompressed formats.
• LFile::SaveOffset - Saves a bitmap to a file in any supported format letting you specify an offset within the file to begin saving, making it possible to embed an image file in another file.
• LFile::SaveTile - Saves the class object's associated bitmap to a specified rectangular location in an existing FlashPix file. It only works with uncompressed FlashPix files. If a compressed FlashPix file is passed in, an error will be returned.

There are also several ways to save a file in memory. LMemoryFile::SaveBitmapBuffer or LMemoryFile::SaveFileBuffer - Saves a bitmap to a file in a memory buffer. The LMemoryFile::SaveFileBuffer function uses an optional LMemoryFile::SaveFileBufferCallBack to allow additional processing of the saved material. This is useful when the buffer of the LBuffer object used by LMemoryFile::SaveBitmapBuffer is not large enough to accommodate the file in memory. The callback makes it possible to reallocate the buffer size. In addition, the LMemoryFile::SaveFileBuffer also calls the LMemoryFile::SaveFileCallBack to the image data from the specified bitmap. The LMemoryFile::SaveFileCallBack can be overridden if the user wants to supply the image data to save.

For information on saving bitmaps that have been window leveled, refer to Saving Window-Leveled Bitmaps.

Converting Images

Conversion from one file format to another can take place when loading or saving a file, or when performing file-to-file conversion. Converting can include the simultaneous resizing of an image. It can also change the image's bits per pixel. Of course, conversion takes longer when resizing or changing the bits per pixel is included. When reducing a file to a 4- or 8-bit format, LEADTOOLS must reduce the number of colors. Therefore, the image cannot be converted back to the original image format and retain its original colors. When converting from 24 bits or less to a 32-bit file, the alpha channel will be filled with zeroes. 

The LEADTOOLS SDK has its own data type for storing and accessing image data  (Each target platform (ex. Windows, Android, WinRT, etc.), also has its own native image data structure or class.)  To make it easy to work with both the LEADTOOLS image data type and the target platform’s native image data type, the LEADTOOLS SDK provides functions for converting between the two.

 The following platforms are supported:

• .NET
• C API
• C++ Class Library
• WinRT
• Silverlight
• Android
• iOS / OS X 

LEADTOOLS functions make it possible to perform the following tasks:

• Convert from the LEADTOOLS image data type to the target platform’s native image data type.

• Convert from the target platform’s native image data type to the LEADTOOLS image data type.  

If you load a LEAD or JPEG file and convert it to 8 bits per pixel while loading, LEADTOOLS dithers the image using the fixed palette. To use an optimized palette, you should first load it as a 24-bit bitmap; then use LBitmapBase::ColorRes to reduce the image using an optimized palette. 

Callbacks

LEADTOOLS can load overlay files, which are usually PTOCA files, by either loading directly from the disk, or by calling an overlay callback function to get the overlay bitmap from the user. To set the callback function to use, as well as the methods and the order of those methods LEADTOOLS should use to load an overlay file, call LBase::EnableOverlayCallBack. To determine the current overlay callback function, (which is the one last set), use LBase::EnableOverlayCallBack. This overlay callback must adhere to the function syntax specified in LBase::OverlayCallBack. 

You can supply the input for a load operation or the output of a save operation, and you can add processing, such as a paint-while-load feature. Using Callback Functions describes these features. Callbacks lists the functions that you can supply.

Multi-page Files

Work with multi-page files by using the following functions:

• LFile::SaveList - Saves a list of bitmaps in a multi-page file.
• LFile::LoadBitmapList - Creates a bitmap list and loads bitmaps from a multi-page file into the list.
• LFile::DeletePage - Deletes individual pages within a multi-page file. 

The bitmap list functions can also be used:

• LBitmapList::Destroy
• LBitmapList::CopyItems
• LBitmapList::GetItemsCount
• LBitmapList::InsertItem
• LBitmapList::RemoveItem
• LBitmapList::DeleteItems
• LBitmapList::GetItem
• LBitmapList::SetItem 

Specific File Format Support

LEADTOOLS supports a vast number of image formats. For the most current listing of all supported file formats, see: Supported File Formats 

The following topics provide more information about specific file formats:

• Controlling Progressive Loads and Saves
• Implementing GIF Features
• Implementing PhotoCD and FlashPix Features
• Implementing FlashPix Extension
• Implementing JBIG Features
• Implementing Exif Features
• Implementing TIFF Comments and Tags
• Implementing GeoKeys (GeoTIFF tags)
• Multipage File Formats
• Saving Window-Leveled Bitmaps
• Saving A Region
• Working with the RAW File Filter 

The LEADTOOLS toolkits have many functions to support specific file formats. They include: 

• PSD - PSD file formats support layers. LEADTOOLS provides the LFile::LoadLayer function to allow the loading of an individual layer. PSD files can also be saved with layer information by calling LFile::SaveWithLayers.

• File Formats: PLT (plt)- When loading HPGL files, you can use the LFileSettings::GetPLTOptions to get the current values for the control options used by LEADTOOLS when loading an HPGL file. You can then use LFileSettings::SetPLTOptions to change the values for the control options. 

• File Formats: AFP (afp/ptoca/im1) - When loading PTOCA and AFP:PTOCA files, you can use the LFileSettings::GetPTKOptions to get the current values for the control options used by LEADTOOLS when loading a PTOCA file. You can then use LFileSettings::SetPTKOptions to change the values for the control options.

• MRC - Please note that the Document and Medical editions support the loading and saving of Mixed Raster Content (MRC) files. The Mixed Raster Content format was defined for use for color and grayscale fax as part of the RFC-2301, File Format for Internet Fax. The Mixed Raster Content mode (T.44) enables different coding methods and resolutions to be used within a single page by defining a 3-layer image model for structuring and combining the scanned image data. For more information, refer to the LEADTOOLS Mixed Raster Content (MRC) Class Library Help File.

• JBIG2 - When saving a JBIG2 file, you can use the LFileSettings::GetJBIG2Options to get the current values for the control options used by LEADTOOLS. You can also use LFileSettings::SetJBIG2Options to change the values for the control options before saving JBIG2 file.

• VFF - When loading VFF files, you can use the LFileSettings::GetVFFOptions to get the current values for the control options used by LEADTOOLS. You can also use LFileSettings::SetVFFOptions to change the values for the control options before loading the VFF files.

Document Formats

LEADTOOLS provides support for loading a document as a raster image. Documents formats such as PDF, XPS, XLS, RTF and Text do not contain physical width, height or resolution. It is up to the loader to specify the transformation from logical coordinates to physical pixels through a process called rasterization. Rasterization is the process of converting a document to a raster image. To check if a certain file on disk or memory contains a document file rather than a regular raster image, call LFile::GetInfo and check the bIsDocFile member of the result FILEINFO structure. To obtain information about a raster PDF file created by LEADTOOLS Raster PDF plugin, call LFile::GetRasterPdfInfo. When rasterizing document files, you can use the LFileSettings::GetRasterizeDocOptions to get the current values for the control options used by LEADTOOLS. You can also use LFileSettings::SetRasterizeDocOptions to change the values for the control options before rasterizing document files.

• PDF - Use the L_GetRasterPdfInfo to get information for a raster PDF file created by the LEADTOOLS Raster PDF plugin.

• File Formats: Rich Text Format (rtf) - When loading RTF files, you can use the LFileSettings::GetRTFOptions to get the current values for the control options used by LEADTOOLS when loading an RTF file. You can then use LFileSettings::SetRTFOptions to change the values for the control options.

• File Formats: TXT (txt) - When loading TXT files, you can use the LFileSettings::GetTXTOptions to get the current values for the control options used by LEADTOOLS. You can also use LFileSettings::SetTXTOptions to change the values for the control options before loading TXT file.

• File Formats: XML Paper Specification (xps) - When loading XPS files, you can use the LFileSettings::GetXPSOptions to get the current values for the control options used by LEADTOOLS. You can also use LFileSettings::SetXPSOptions to change the values for the control options before loading the XPS files.

• File Formats: Microsoft Excel Spreadsheet Format (XLS, XLSX) - Microsoft Excel 2003 (XLS) files have no physical width or height in pixels. You can use RASTERIZEDOCOPTIONS to control how the final document is rendered as a raster image. When loading XLS files, you can use the LFileSettings::GetXLSOptions to get the current values for the control options used by LEADTOOLS. You can also use LFileSettings::SetXLSOptions to change the values for the control options before loading the XLS files.

• File Formats: Tagged Image File Format (TIFF / BigTIFF) - Regions are saved automatically inside TIFF files. For more information, refer to Saving A Region. LEADTOOLS supports loading TIFF CMYK files without converting the data to BGR. This is done by loading each CMYK plane as a separate LEADTOOLS bitmap using LFile::LoadCMYKArray. To save the bitmap as TIFF CMYK, call LFile::SaveCMYKArray.

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

• Mayo Clinic Analyze (anz) - When loading ANZ (Analyze format) files, you can use the LFileSettings::GetANZOptions to get the current values for the control options used by LEADTOOLS. You can also use LFileSettings::SetANZOptions to change the values for the control options before loading the ANZ files.

• DOC - When loading DOC files, you can use the LFileSettings::GetDOCOptions to get the current values for the control options used by LEADTOOLS. You can also use LFileSettings::GetDOCOptions to change the values for the control options before loading the DOC files. 

Vector

When loading vector files, use the L_GetVectorOptions function to get the current values for the control options used by LEADTOOLS. Use the L_SetVectorOptions function to change the values for the control options before loading the vector files.

• WMF - When loading WMF/EMF files, you can use the LFileSettings::GetWMFResolution to get the current DPI (dots per inch) value for the control options used by LEADTOOLS when loading a WMF/EMF file. You can then use LFileSettings::SetWMFResolution to change the values for the control options.

Saving Colored Images as Bitonal

LEADTOOLS can automatically save a colored image (an image that has more than 1 bit/pixel) as bitonal (an image that has 1 bit/pixel). This is accomplished by passing "1" as the nBitsPerPixel parameter of LBitmapBase::Save or LFile::SaveFile. 

Whenever you reduce an image's color resolution to 8 bits per pixel or less, a dithering method comes into play. One alternative is to use a nearest-color match (no dithering), which means that the color of each pixel is changed to the palette color that most closely matches it. If the original image contains subtle color details, the result of a nearest-color match may have large blotches of color that are not very pleasing.

Dithering methods create the appearance of more subtle shades by mixing in pixels of different colors. This is similar to the way newspaper pictures produce the appearance of shades of gray, even though the only actual colors are black and white. 

In LEADTOOLS version 17 and up, when saving a colored image (such as a 24-bits per pixel image) to bitonal (1-bit per pixel), the toolkit will not use any dithering when converting the image data. This is done because dithering is not recommended when converting colored images containing text for document processing such as OCR and Barcode. The resulting text will be fuzzy and hard for a recognition engine to process. To save a colored image as bitonal with Floyd-Stein dithering (the behavior of LEADTOOLS 16.5 and earlier), first set the dithering method to Floyd-Stein by calling LBitmapBase::SetDitheringMethod with the uDitheringMethod parameter set to FLOYD_STEIN_DITHERING. Next, set the Flags member of the SAVEFILEOPTION structure to ESO_USEDITHERINGMETHOD. Then, call LBitmapBase::Save or LFile::SaveFile.