Programming with LEADTOOLS NITF Functions (original) (raw)
The National Imagery Transmission Format (NITF) File is defined by the United States Department of Defense. For background on the origination and purpose of this standard, refer to the Department of Defense Interface Standard MIL-STD-2500Cand the NITFS Technical Board Public Page.
Creating and Parsing NITF Files
- The L_NITFCreate function must be called before calling any other L_NITFXXX function. This function is used to create an empty NITF file, or parse an existing NITF file.
- To create an empty NITF file, call the L_NITFCreate function and pass NULL for the pszFileName parameter. To parse an existing NITF file, call the L_NITFCreate function with a valid file name for the pszFileName parameter.
- Whether creating or parsing a NITF file, when this function is used the NITF file handle will be initialized. Each call to the L_NITFCreate function creates a NITF file handle of type HNITF. This handle is passed to all of the other L_NITFXXX C API functions.
- To determine if the handle created by the L_NITFCreate function is a valid NITF file or an empty NITF file, call the L_NITFGetStatus function.
- If the L_NITFCreate function was used to parse an existing file, information about the NITF file header can be obtained by passing a pointer to NITFHEADER structure to the L_NITFGetNITFHeader function. To change the current information about a NITF file header, change the values in the structure pointed to by the pNITFHeader parameter and pass it to the L_NITFSetNITFHeader function. When the NITF file header information is no longer needed the function L_NITFFreeNITFHeader should be called.
- Save the created NITF file by calling the L_NITFSaveFile function.
- When the NITF file handle is no longer needed, it should be freed by calling the L_NITFDestroy function. For every call to L_NITFCreate there must be a call to L_NITFDestroy.
Appending Data to NITF Files
The following types of data can be appended to NITF files:
- Image: To append an image to a NITF file, call the L_NITFAppendImageSegment function, passing a valid BITMAPHANDLE that references the bitmap that holds the image data to be appended to an image segment in the NITF file.
- Graphic: To append a graphic, call the L_NITFAppendGraphicSegment function, passing a valid VECTORHANDLE that holds the graphic data to be appended to the graphic segment in the NITF file.
- Text: To append text, call the L_NITFAppendTextSegment function, passing a valid text file name that holds the text data to be appended to the text segment in the NITF file.
Getting and Setting Data Headers
It is possible to change information about the following data headers from or to the NITF file:
- Image Header: To obtain information about specific image header from the image segment in the NITF file, call the L_NITFGetImageHeader function, passing a pointer to an IMAGEHEADER structure along with the index of the image header in the image segment. To change the current information of a specific image header, change the values in the structure pointed to by the pImageHeader parameter and pass it to the L_NITFSetImageHeader function, specifying the index of the image header in the image segment. To get the number of the image headers in the image segment inside the NITF file, call the L_NITFGetImageHeaderCount function. When the image header information is no longer needed the function L_NITFFreeImageHeader should be called.
- Graphic Header: To obtain information about a specific graphic header from the graphic segment in the NITF file, call the L_NITFGetGraphicHeader function, passing a pointer to a GRAPHICHEADER structure along with the index of the graphic header in the graphic segment. To change the current information for a specific graphic header, change the values in the structure pointed to by pGraphicsHeader parameter and pass it to the L_NITFSetGraphicHeader function, specifying the index of the graphic header in the graphic segment. To get the number of graphic headers in the graphic segment inside the NITF file, call the L_NITFGetGraphicHeaderCount function. When the graphic header information is no longer needed the function L_NITFFreeGraphicHeader should be called.
- To retrieve the handle of the graphic data for a specific header in the graphic segment of the NITF file, call the L_NITFGetVectorHandle function, passing the index of the graphic header in the graphic segment.
- To set the handle of the graphic data of a specific header in the graphic segment of the NITF file, call the L_NITFSetVectorHandle function, passing the index of the graphic header in the graphic segment along with a valid VECTORHANDLE pointer that references this graphic data.
- Text Header: To obtain information about a specific text header in a text segment in the NITF file, call the L_NITFGetTextHeader function, passing a pointer to a TEXTHEADER structure along with the index of the text header in the text segment. To change the current information for a specific text header, change the values in the structure pointed to by the pTextHeader parameter and pass it to the L_NITFSetTextHeader function, specifying the index of the text header in the text segment. To get the number of the text headers in the text segment inside the NITF file, call the L_NITFGetTextHeaderCount function. When the text header information is no longer needed the function L_NITFFreeTextHeader should be called. To obtain the text data for a specific header in the text segment of the NITF file, call the L_NITFGetTextSegment function, passing the index of the text header in the text segment.