*.dm5 documentation
*.dm5 files are written using the HDF5 libraries and can, therefore, be read by many applications. This document explains the internal structure of a .dm5 file.
To open and view the internal structure of a *.dm5 file, you can use the HDFView application that is found free here.
Files that are referred to within this document and examples can be found here.
Overview
When saving a simple 2D image, there will be the following nodes in the *.dm5 file:
DocumentObjectList
DocumentObjects are displays or other items added to an actual document, i.e., the item you see in the ImageWindow. In this basic example, there will be one item in this list that corresponds to the 2D raster display of the image.
Image Behavior
This tag is only used when laying out image displays and other objects in page mode. We will not cover that in this document.
ImageList
This group lists all the images saved in the document. In this basic example, there will be two images listed. One is the actual image, and one is the thumbnail image, i.e., a small representation of what the image looks like.
ImageSourceList
ImageSources in DigitalMicrograph are objects that are used to link Images to ImageDisplays. Each ImageDisplay generally has one ImageSource, and each ImageSource can contain multiple Images. This is extensively used when combining multiple images in lineplots. In this example, there will be only one ImageSource, corresponding to the ImageDisplay listed in the DocumentObjectList.
Page Behavior
This group is only used when displaying the document in page layout mode, which is not covered in this document.
Thumbnails
Each time a document is saved, a thumbnail image is generated, showing what the image looks like in DigitalMicrograph. This thumbnail is, for example, used in Windows Explorer for the file icon.
There will be, at most, one thumbnail in each document.
How to read the Thumbnail
The attribute /Thumbnails:[0]:ImageIndex contains the index of the thumbnail image in ImageList. In this case, this value is 0.
So, the data for the thumbnail image is in /ImageList:[0]. This group contains one attribute and three subgroups:
Attribute:
Name: The name of the thumbnail image, here “Image Of Untitled1”
Groups:
ImageData
ImageData:DataType: For thumbnails, this is always 23, which corresponds to RGBA. So, 8 bits each for Red, Green, Blue, and Alpha. The alpha channel contains no useful data.
ImageData:PixelDepth: 4 bytes to accommodate the RGBA data.
ImageData:Calibrations: All values are default values since thumbnails are not calibrated
ImageData:Data: This is the actual ImageData of the thumbnail, which is tagged as an HDF5 image object.
ImageData:Dimensions: This is the size of the thumbnail. Here 384 by 384.
ImageTags
Thumbnails do not tend to have any meta-data associated with them. The only attribute here would be “GMS Version”.
UniqueID
This group contains four 32-bit unsigned integers, together creating a unique ID.
How to read the raw image data
To read the actual image data, we must start with the value of /DocumentObjectList:[0]:ImageSource. The value here is 0.
So that means we need to read /ImageSourceList:[0]:ImageRef, which is 1. So, image 1 contains the main data of the saved image.
So we look at /ImageList[1]. Just like for the thumbnail image, this again contains one attribute and 3 groups:
Attribute:
Name: The name of the image, here “untitled1”
Other interesting attributes:
The DocumentImageList:[0]:ImageDisplayInfo group contains several other attributes that are needed to recreate the same ImageDisplay as shown in DigitalMicrograph:
- The display limits for the image can be found at LowLimit and HighLimit
- Contrast, brightness, and gamma setting are found in the attributes Contrast, Brightness, and Gamma
Groups:
ImageData
ImageData:DataType: For my example images, this value is 1, corresponding to signed int16. See list of data Types below.
ImageData:PixelDepth: Here 2 bytes to accommodate the 16-bit integer.
ImageData:Calibrations: This would include any of the calibrations of the image if there were any present. ImageData:Calibrations:Brightness would correspond to the intensity calibration, and ImageData:Calibrations:Dimension:[x] corresponds to spatial calibration. Each calibration has an Origin and a Scale, both type 32-bit float.
ImageData:Data: This is the actual ImageData of the image.
ImageData:Dimensions: This is the size of the image. Here 256 by 256.
ImageTags
Images can have lots of metadata attached to them. All this data is stored here in the same hierarchy as can be viewed in the Image tag viewer in DigitalMicrograph.
Image tags are shown in the DM Image Info dialog and in the HDFView application.
UniqueID
This group contains four 32-bit unsigned integers, together creating a unique ID.
What happens if there are annotations on the image display?
Annotations placed on an ImageDisplay appear in the group DocumentImageList:[0]:AnnotationGroupList. This group will have as many sub-groups as there are annotations.
The entry DocumentImageList:[0]:AnnotationGroupList:[0] will have many attributes. These are all attributes of an annotation object. Since an ImageDisplay is also a kind of annotation, you can see the same kind of list in DocumentImageList:[0].
The most important attributes are:
AnnotationType. Here is a list of annotation types:
| Annotation Type | Description |
| 2 | live annotation |
| 3 | arrow annotation |
| 4 | double arrow annotation |
| 5 | box annotation |
| 6 | oval annotation |
| 8 | spot mask annotation |
| 9 | array mask annotation |
| 12 | profile marker |
| 13 | text annotation |
| 15 | bandpass mask annotation |
| 17 | group annotation |
| 19 | wedge mask annotation |
| 20 | image display |
| 23 | rectangle ROI |
| 24 | root/master |
| 25 | line ROI |
| 26 | polyline ROI |
| 27 | point ROI |
| 28 | oval ROI |
| 29 | irregular ROI |
| 31 | scale bar |
| 32 | particle mask |
| 33 | intensity bar |
| 34 | overlay |
Rectangle: This is written as a compound type containing top, left, bottom, and right—each 32-bit float. Coordinates are w.r.t. the top-left of the parent and are in pixels.
BackgroundColor and ForegroundColor: This is written as a compound type containing red, green, and blue. Each is a 16-bit unsigned integer ranging from 0 to 65535.
Different annotations write type-specific attributes, such as the attribute Text for text annotations (type 13).
How about line plots
Line plots are much more complicated because they can show results from multiple images in one plot. Here is a description of a lineplot that was made by copying one lineplot on top of another, with both images being 1D. (Here are two EDS spectra.) The image looks like this:
The top-level group contains the same five groups as before, only now there are three images in the ImageList group, and the way to find the thumbnail for this image hasn’t changed from what was described above.
So, let’s traverse the tree to find all the relevant information:
In the group /DocumentObjectList is one object that corresponds to the ImageDisplay. It has an attribute AnnotationType with value 20, meaning it is an ImageDisplay as expected, and ImageDisplayType with value 3, which corresponds to a LinePlot. (In the previous example, this value was 1, corresponding to a 2D raster ImageDisplay.)
Next, we read the attribute ImageSource which has value 0. So, we will look at /ImageSourceList:[0], which describes the ImageSource for this display. This group contains several groups, including a group named (again) ImageSourceList, which itself contains two subgroups. This means the ImageSource for this ImageDisplay combines data from two separate images. These are images 1 and 2, read from /ImageSourceList:[0]:ImageSourceList:[0]:ImageRef and /ImageSourceList:[0]:ImageSourceList:[1]:ImageRef.
So all the information about the images can be found in /ImageList:[1]:ImageData and /ImageList:[2]:ImageData. These groups contain information about the DataType, PixelDepth, Calibrations, and Dimensions. The data itself can be read from /ImageList:[n]:ImageData/Data.
In most cases, all one wants to do is get the data and associated meta-data. If one wants to reconstruct how DigitalMicrograph renders the actual lineplot, we have to go back to the group /DocumentObjectList:[0]:ImageDisplayInfo which contains all the necessary information. For example:
The style in how the different curves are rendered is in /DocumentObjectList:[0]:ImageDisplayInfo/SliceList:[n] in attributes like DrawFill, DrawLine, FillColor, etc.
The data range displayed can be deduced from the values /DocumentObjectList:[0]:ImageDisplayInfo:SectionList:[0]:GroupList:[0]:GroupToDisplay, which contains an Offset and Scale attribute describing how to convert data values to scale on the display.
Data Type list
| Description | Type ID |
| SIGNED_INT16_DATA | 1 |
| REAL4_DATA | 2 |
| COMPLEX8_DATA | 3 |
| PACKED_DATA | 5 |
| UNSIGNED_INT8_DATA | 6 |
| SIGNED_INT32_DATA | 7 |
| RGB_DATA | 8 |
| SIGNED_INT8_DATA | 9 |
| UNSIGNED_INT16_DATA | 10 |
| UNSIGNED_INT32_DATA | 11 |
| REAL8_DATA | 12 |
| COMPLEX12_DATA | 13 |
| BINARY_DATA | 14 |
| RGB_UINT8_0_DATA | 15 |
| RGB_UINT8_1_DATA | 16 |
| RGB_UINT16 | 17 |
| RGB_FLOAT32_DATA | 18 |
| RGB_FLOAT64_DATA | 19 |
| RGBA_UINT8_0_DATA | 20 |
| RGBA_UINT8_1_DATA | 21 |
| RGBA_UINT8_2_DATA | 22 |
| RGBA_UINT8_3_DATA | 23 |
| RGBA_UINT16_DATA | 24 |
| RGBA_FLOAT32_DATA | 25 |
| RGBA_FLOAT64_DATA | 26 |
| COMPLEX8_PACKED_DATA | 27 |
| COMPLEX16_PACKED_DATA | 28 |