Hermes SDK 1.0.1A
Additional methods

Functions

HermesReturn HermesSaveImgDisk (Hermes_H Hermes, UInt32 Start_Img, UInt32 End_Img, char *filename, OutFileFormat mode)
 
HermesReturn HermesSaveAveragedImgDisk (Hermes_H Hermes, UInt16 counter, char *filename, OutFileFormat mode, short isDouble)
 
HermesReturn HermesSaveFlimDisk (Hermes_H Hermes, char *filename, OutFileFormat mode)
 
HermesReturn HermesReadHermesFileFormatImage (char *filename, UInt32 ImgIdx, UInt16 counter, UInt16 *Img, char header[1024])
 
HermesReturn HermesAverageImg (Hermes_H Hermes, double *Img, UInt16 counter)
 
HermesReturn HermesStDevImg (Hermes_H Hermes, double *Img, UInt16 counter)
 
HermesReturn HermesSetCorrelationMode (Hermes_H Hermes, CorrelationMode CM, int NCorrChannels, State s)
 
HermesReturn HermesCorrelationImg (Hermes_H Hermes, UInt16 counter)
 
HermesReturn HermesSaveCorrelationImg (Hermes_H Hermes, char *filename)
 
HermesReturn HermesResetOverilluminationProtection (Hermes_H Hermes)
 

Detailed Description

Additional utility functions.

Function Documentation

◆ HermesAverageImg()

HermesReturn HermesAverageImg ( Hermes_H  Hermes,
double *  Img,
UInt16  counter 
)

Calculate the average image.

Once a set of images have been acquired by HermesSnapAcquire(), an image which contains for each pixel the average value over all the acquired images is calculated. This is stored in the Img array.

Parameters
HermesHermes handle.
ImgPointer to the output double image array. The size of the array must be at least 16 kiB, i.e. 2048 double elements.
counterDesired counter. Accepted values: 1..3
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
INVALID_OP No images were acquired
See also
HermesSnapAcquire()
Examples
SDK_Example.c.

◆ HermesCorrelationImg()

HermesReturn HermesCorrelationImg ( Hermes_H  Hermes,
UInt16  counter 
)

Calculate the autocorrelation function.

The autocorrelation function is estimated for each pixel. This function requires that a set of images have been previously acquired by HermesSnapAcquire() and that the correlation mode is set to Enabled. Depending on the selected algorithm and the total number of collected images, this function can take several tens of seconds.

Parameters
HermesHermes handle
counterDesired counter. Accepted values: 1..3
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
INVALID_OP No images were acquired or the correlation mode was not enabled
NOT_EN_MEMORY Not enough memory to calculate the correlation function
INVALID_NIMG_CORRELATION The required number of time lags of the correlation function can not be calculated from the available number of images
See also
HermesSetCorrelationMode()
HermesSnapAcquire()

◆ HermesReadHermesFileFormatImage()

HermesReturn HermesReadHermesFileFormatImage ( char *  filename,
UInt32  ImgIdx,
UInt16  counter,
UInt16 Img,
char  header[1024] 
)

Read an integer (8 - 16 bit) Hermes image from file.

Read the image at the ImgIdx position and for desired counter in the given Hermes file from the hard disk.

Parameters
filenameFull path of the output file. Value is referenced.
ImgIdxImage index in the file. Accepted values: 1 ... 65534
counterDesired counter. Accepted values: 1 ... 3
ImgPointer to the output image array. The size of the array must be at least 4 kiB.
headerArray in which the header of Hermes file is saved.
Returns
OK
UNABLE_READ_FILE Unable to read the input file. Is it a Hermes file?
OUT_OF_BOUND The desired counter or image exceeds the file size.
NOT_EN_MEMORY Not enough memory to store the data contained in the file
NULL_POINTER The provided provided handle or pointers point to an empty memory location.
Examples
SDK_Example.c.

◆ HermesResetOverilluminationProtection()

HermesReturn HermesResetOverilluminationProtection ( Hermes_H  Hermes)

Reset the internal overillumination protection circuit.

This function resets the Hermes internal protection triggered by excessive illumination. It is mandatory to check that the overillumination condition is removed before calling this function. In any case, in order to avoid damage to the Hermes, up to 3 reset cycles are allowed before having to disconnect the camera from the power supply.

Parameters
HermesHermes handle
Returns
OK
TOO_MUCH_LIGHT The protection was reset, but the illumination is still too much!
PERSISTING_TOO_MUCH_LIGHT The number of allowed reset cycles has been exceeded!
Examples
SDK_Example.c.

◆ HermesSaveAveragedImgDisk()

HermesReturn HermesSaveAveragedImgDisk ( Hermes_H  Hermes,
UInt16  counter,
char *  filename,
OutFileFormat  mode,
short  isDouble 
)

Save the selected images on the hard disk.

This function saves the average of the images acquired by a specified counter on the hard disk. File format can be proprietary Hermes or TIFF, as explained in HermesSaveImgDisk() function.

Parameters
HermesHermes handle
counterNumber of the counter to be saved. Accepted values: 1..3
filenameFull path of the output file. Value is referenced.
modeFile format of the output images
isDoubleNumber format. 0 for Uint16, 1 for Double
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
INVALID_OP No images were acquired or the selected range of images is not valid
UNABLE_CREATE_FILE Unable to create the output file
See also
HermesSaveImgDisk()
Examples
SDK_Example.c.

◆ HermesSaveCorrelationImg()

HermesReturn HermesSaveCorrelationImg ( Hermes_H  Hermes,
char *  filename 
)

Save the autocorrelation functions on the hard disk.

This function requires that HermesSetCorrelationMode() and HermesCorrelationImg() have been previously called. The autocorrelation data are stored in a .hrmc binary file. The hrmc binary file is organized as follows:

Byte offset Type Number of bytes Description
0 int 4 Number of lag-times (NLag)
4 int 4 Number of pixels. This value must be 1024 (NPix)
8 int 4 Selected algorithm: 0 Linear, 1 Multi-tau
12 double 8 * NLag Autocorrelation values of the first pixel
12 + 8 * NLag double 8 * NLag Autocorrelation values of the second pixel
... double 8 * NLag Autocorrelation values of the Nth pixel
12 + 8 * (NPix-1) * NLag double 8 * NLag Autocorrelation values of the last pixel
12 + 8 * NPix * NLag double 8 * NLag Lag times

A simple Matlab script can be used to read the data for further processing or visualization.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
MPD .HRMC file reader
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
function data = Read_HRMC(fname)
f = fopen(fname,'rb');
buf = fread(f,3,'int32');
data.NChannel = buf(1);
data.NPixel = buf(2);
data.IsMultiTau = (buf(3) == 1);
data.CorrelationImage = reshape(fread(f,data.NPixel*data.NChannel,'float64'), ...
data.NChannel,32,32);
data.CorrelationImage = permute(data.CorrelationImage,[2 3 1]);
data.t=fread(f, data.NChannel,'float64');
fclose(f);
Parameters
HermesHermes handle
filenameFull path of the output file
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
INVALID_OP The autocorrelation, which has been calculated, is not valid
UNABLE_CREATE_FILE Unable to create the output file
See also
HermesSetCorrelationMode()

◆ HermesSaveFlimDisk()

HermesReturn HermesSaveFlimDisk ( Hermes_H  Hermes,
char *  filename,
OutFileFormat  mode 
)

Save the FLIM acquisition on the hard disk.

This function saves the acquired FLIM images on the hard disk. The output file format can be either a multipage TIFF with embedded acquisition metadata according to the OME-TIFF format or the proprietary Hermes format. For standard measurements, use the Hermes_Save_Img__Disk() function. For both formats, image data is composed by a set of images following a "FLIM first, time second scheme", i.e. with the following frame sequence: 1st gate shift of 1st FLIM measurement, 2nd gate shift of 1st FLIM measurement,...,nth gate shift of 1st FLIM measurement,1st gate shift of 2nd FLIM measurement, 2nd gate shift of 2nd FLIM measurement,...,nth gate shift of 2nd FLIM measurement,etc. OME-TIFF file could be opened with any image reader compatible with TIFF file, since metadata are saved into the Image Description tag in XML format. In order to decode OME-TIFF metadata, it is possible to use a free OME-TIFF reader, such as OMERO or the Bio-Formats plugin for ImageJ. For more details see the OME-TIFF web site: http://www.openmicroscopy.org/site/support/ome-model/ome-tiff/. OME-TIFF metadata include the ModuloAlongT tag, which allows the processing of FLIM data with dedicated FLIM software such as FLIMfit (see http://www.openmicroscopy.org/site/products/partner/flimfit). Hermes file are binary files composed by a header with acquisition metadata followed by raw image data, containing the 8/16 bit pixel values in row-major order (refer to Figure 7 of the User Manual for pixels position and order). The byte order is little-endian for the 16 bit images. The header is composed by a signature of 8 byte (0x4d5044ff03000001, starting with 4d on byte 0), and a metadata section of 1024 byte described in function HermesSaveImgDisk(). Hermes file can be read using the provided ImageJ/Fiji plugin.

Parameters
HermesHermes handle
filenameFull path of the output file. Value is referenced.
modeFile format of the output images
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
INVALID_OP No images were acquired or the selected range of images is not valid
UNABLE_CREATE_FILE Unable to create the output file
See also
HermesSaveImgDisk()

◆ HermesSaveImgDisk()

HermesReturn HermesSaveImgDisk ( Hermes_H  Hermes,
UInt32  Start_Img,
UInt32  End_Img,
char *  filename,
OutFileFormat  mode 
)

Save the selected images on the hard disk.

This function saves the acquired images on the hard disk. The output file format can be either a multipage TIFF with embedded acquisition metadata according to the OME-TIFF format or the proprietary Hermes format. For FLIM measurements, use the HermesSaveFlimDisk() function. If TIFF format is selected, the desired images will be saved in a file for each enabled counter. If Hermes format is selected a single Hermes file will be created for all the counters. OME-TIFF file could be opened with any image reader compatible with TIFF file, since metadata are saved into the Image Description tag in XML format. In order to decode OME-TIFF metadata, it is possible to use a free OME-TIFF reader, such as OMERO or the Bio-Formats plugin for ImageJ. For more details see the OME-TIFF web site: http://www.openmicroscopy.org/site/support/ome-model/ome-tiff/. If subarray acquisition is enabled and the number of pixels is not an integer multiple of 32, the TIFF files will have as much rows of 32 pixels as needed to accommodate all pixels, and the missing pixels will be put to 0, e.g. if 67 pixels are acquired, the TIFF image will be 32x3, with the last 29 pixels of the 3rd row set to 0. Hermes file are binary files composed by a header with acquisition metadata followed by raw image data, containing the 8/16 bit (integer) or 64 bit (double precision) pixel values in row-major order (refer to Figure 7 of the User Manual for pixels position and order). The byte order is little-endian for the 16 or 64 bit images. In case more counters are used, data are interlaced, i.e. the sequence of frames is the following: 1st frame of 1st counter, 1st frame of 2nd counter, 1st frame of 3rd counter, 2nd frame of 1st counter, etc. The header is composed by a signature of 8 byte (0x4d5044ff04000000, starting with 4d on byte 0), and a metadata section of 1024 byte, as follows (multibyte fields are little-endian):

Byte offset Number of bytes Description
0 10 Unique camera ID (string)
10 32 Hermes serial number (string)
42 2 Firmware version (x.xx saved as xxx)
44 1 Firmware custom version (standard = 0)
45 20 Acquisition data&time (string)
65 35 Unused
100 1 Number of rows
101 1 Number of columns
102 1 Bit per pixel
103 1 Counters in use
104 2 Hardware integration time (multiples of 10ns)
106 2 Summed frames
108 1 Dead time correction enabled
109 1 Internal gate duty-cycle for counter1 (0-100%)
110 2 Hold-off time (ns)
112 1 Background subtraction enabled
113 1 Data for counters 1 and 2 are signed
114 4 Number of frames in the file
118 1 Image is averaged
119 1 Counter which is averaged
120 2 Number of averaged images
122 1 Internal gate duty-cycle for counter2 (0-100%)
123 1 Internal gate duty-cycle for counter3 (0-100%)
124 2 Frames per sync-in pulse
126 2 Number of pixels
128 72 Unused
200 1 FLIM enabled
201 2 FLIM shift (thousandths of gate period)
203 2 FLIM steps
205 4 FLIM frame length (multiples of 10ns)
209 2 FLIM bin width (fs)
211 9 Unused
220 1 Multi gate mode: 2 = dual, 3 = triple
221 2 Multi gate mode: start position (-500 - +500)
223 1 Multi gate mode: first gate width (0-100%)
224 1 Multi gate mode: second gate width (0-100%)
225 1 Multi gate mode: third gate width (0-100%)
226 2 Multi gate mode: gap1 (0-800)
228 2 Multi gate mode: gap2 (0-800)
230 2 Multi gate mode: calibrated bin-width in fs
232 1 Coarse gate 1 enabled
233 2 Coarse gate 1 start
235 2 Coarse gate 1 stop
237 1 Coarse gate 2 enabled
238 2 Coarse gate 2 start
240 2 Coarse gate 2 stop
242 1 Coarse gate 3 enabled
243 2 Coarse gate 3 start
245 2 Coarse gate 3 stop
247 53 Unused
300 1 PDE measurement
301 2 Start wavelength (nm)
303 2 Stop wavelength (nm)
305 2 Step (nm)
307 717 unused

Hermes file can be read using the provided ImageJ/Fiji plugin.

Parameters
HermesHermes handle
Start_ImgIndex of the first image to save. Accepted values: 1 ... Number of acquired images
End_ImgIndex of the last image to save. Accepted values: Start_Img ... Number of acquired images
filenameFull path of the output file. Value is referenced.
modeFile format of the output images
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
INVALID_OP No images were acquired or the selected range of images is not valid
UNABLE_CREATE_FILE Unable to create the output file
Examples
SDK_Example.c.

◆ HermesSetCorrelationMode()

HermesReturn HermesSetCorrelationMode ( Hermes_H  Hermes,
CorrelationMode  CM,
int  NCorrChannels,
State  s 
)

Enable the correlation mode.

This function must be called before invoking HermesCorrelationImg(). When this function is called, the memory required to save the new data is allocated in the heap and the previously stored data are cancelled. The deallocation of this memory is automatically performed when the Hermes_destr() function is called or by setting the State s equal to Disabled.

Parameters
HermesHermes handle
CMSelected autocorrelation algorithm
NCorrChannelsNumber of global lag channels. When the linear correlation algorithm is selected, the first NChannel lags are calculated, where NChannel must be greater than 2. This algorithm accepts only a number of images which is a power of 2. For example, if 1025 images were acquired, only 1024 images are used to calculate the autocorrelation function. In case of Multi-tau algorithm, it defines the number of channel groups. The first group has 16 lags of duration equal to the exposure time of a frame. The following groups have 8 lags each, spaced at 2^i * Exposure time.
sEnable or Disable the correlation mode
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
OUT_OF_BOUND NCorrChannels must be greater than zero for the Multi-tau algorithm and greater than 2 for the Linear one
NOT_EN_MEMORY There is not enough memory to enable the correlation mode
See also
HermesCorrelationImg()

◆ HermesStDevImg()

HermesReturn HermesStDevImg ( Hermes_H  Hermes,
double *  Img,
UInt16  counter 
)

Calculate the standard deviation image.

Once a set of images have been acquired by HermesSnapAcquire(), an image which contains for each pixel the standard deviation over all the acquired images is calculated. This is stored in the Img array.

Parameters
HermesPointer to the Hermes handle
ImgPointer to the output double image array. The size of the array must be at least 16 kiB, i.e. 2048 double elements.
counterDesired counter. Accepted values: 1..3
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
INVALID_OP No images were acquired
See also
HermesSnapAcquire()