Implementing Markers

Some file formats (TIFF, GIF, PNG, Exif, DICOM, JPEG, LEAD, and IPTC) can contain metadata of various types. "Metadata" refers to extra information that is stored with an image, but is not necessary for decoding the image. For instance, metadata can contain information about the camera used to take the image, the author, date and time the image was taken, where the image was taken, whether the camera has GPS capabilities, etc. When an image is modified, you should preserve the original information, if possible. Metadata includes markers, tags and comments. This topic will deal primarily with markers. For more information on tags and comments, refer to the following topics:

Implementing TIFF Tags

Types of File Comments

JPEG files contain metadata information in user-defined markers. The user-defined markers are in the range $E0 to $FE. These markers can have a maximum size of $FFFD, or 65533 bytes. The markers below $E0 are reserved for the encoding of the image and inserting a reserved marker can make a file invalid. Therefore, you should not use reserved markers unless you are well acquainted with markers and image encoding in JPEG files.

TIFF files do not contain markers, however, LEADTOOLS provides a "workaround" for transferring Exif comments from JPEG files to TIFF files, and vice versa. The Exif metadata information from a TIFF file will be loaded as an APP1 marker. Therefore, you can load Exif metadata from an uncompressed file and store it in a compressed Exif file. You can also take metadata information from a compressed Exif file and store it in an uncompressed Exif file. Please note however, that some information cannot be stored inside uncompressed Exif files. For example, audio data is stored in APP2 markers and there is no built-in support for saving APP2 markers in TIFF files. However, you can still save the audio data yourself, using a custom tag. For more information on saving custom tags, refer to Implementing TIFF Tags.

Handling Markers

LEADTOOLS provides the LEADMarker control for loading, creating, setting, modifying, getting information from and freeing markers.

To load markers from an existing JPEG file, call the LoadMarkers method. Although TIFF files do not support markers, LEADTOOLS provides limited support through the use of APP1 Exif markers. When you call the LoadMarkers method for a TIFF file, an APP1 marker is created and all the TIFF, GPS and Exif comments will be stored in it. In addition, any other tag with an ID greater than $8000 (32768) will be stored in the APP1 marker. The other information will be considered as being useful only for the image and will not be loaded into the APP1 marker. The only exception is the resolution information, which will be loaded in the APP1 marker.

The CreateMarkers method lets you create a collection of markers from scratch. You can then insert markers with the InsertMarker method. After you call InsertMarker once, you can call EnumMarkers and insert markers using the OnEnumerateMarkers event.

Markers, like tags and comments can be set so that when a file is saved using the SaveXXX methods, the markers, tags and/or comments that have been set will be saved too. Set the markers to save using the SetMarkers method. Once the markers have been set using SetMarkers, all the save operations from the current thread will use these markers. If you do not want to save any markers, call SetMarkers with the Marker parameter set to NULL(Nil). To get the markers that were set by the last call to SetMarkers, call the GetMarkers method.

Please note that both the SetMarkers method and GetMarkers method use copies of the list of markers.

Markers set using SetMarkers can also be written to files using the WriteComment and WriteTag methods. The comments or tags being written by these two methods will overwrite any similar comments or tags contained in the markers. The WriteMetaData method can also be used to write markers, tags and comments to a file. The following is a summary of the methods and the type of data each method writes:

Markers are generally modified by deleting all markers of a certain type. To delete all markers of a certain type, use the DeleteMarker method. To delete a marker at a specific index, use the DeleteMarkerAt method.

The EnumMarkers method can be used to enumerate and modify a marker collection. It is a powerful method, used internally by most marker manipulation methods. For each marker enumerated by EnumMarkers, an OnEnumerateMarkers event is fired. This event lets you delete markers from or insert markers to the marker collection being enumerated. This allows you to modify the marker collection enumerated by the EnumMarkers method. To insert a new marker in a marker collection, use InsertMarker. You can get a marker by index using the GetMarker method. You can also get individual markers using the EnumMarkers method and the OnEnumerateMarkers event.

Each marker may consist of one or more elements. When getting a marker using the GetMarker method, the ElementCount property is updated with the number of elements in the marker and the Element property is updated with the actual element(s) that make up that marker. The MarkerType property is updated with type of marker retrieved by the GetMarker method. When inserting a marker using the InsertMarker method, set the desired marker information in the ElementCount, Element and MarkerType properties before calling InsertMarker.

To determine how many markers are in a collection, see the Count property.

To specify whether LEADTOOLS generates system error events, set the MethodErrorsEnabled property.

To get the error code resulting from the last method called or property set, check the Error property.

Finally, to create a copy of a marker collection and obtain a handle to the new marker collection, use CopyMarkers method.