Hermes SDK 1.0.1A
Acquisition methods

Functions

HermesReturn HermesLiveSetModeON (Hermes_H Hermes)
 
HermesReturn HermesLiveSetModeOFF (Hermes_H Hermes)
 
HermesReturn HermesLiveGetImg (Hermes_H Hermes, UInt16 *Img)
 
HermesReturn HermesSnapPrepare (Hermes_H Hermes)
 
HermesReturn HermesSnapAcquire (Hermes_H Hermes)
 
HermesReturn HermesSnapGetImageBuffer (Hermes_H Hermes, BUFFER_H *buffer, int *DataDepth)
 
HermesReturn HermesSnapGetImgPosition (Hermes_H Hermes, UInt16 *Img, UInt32 Position, UInt16 counter)
 
HermesReturn HermesContAcqToFileStart (Hermes_H Hermes, char *filename)
 
HermesReturn HermesContAcqToFileGetMemory (Hermes_H Hermes, double *total_bytes)
 
HermesReturn HermesContAcqToFileStop (Hermes_H Hermes)
 
HermesReturn HermesContAcqToMemoryStart (Hermes_H Hermes)
 
HermesReturn HermesContAcqToMemoryGetBuffer (Hermes_H Hermes, double *total_bytes, BUFFER_H *buffer)
 
HermesReturn HermesContAcqToMemoryStop (Hermes_H Hermes)
 

Detailed Description

Functions for acquiring data from the Hermes camera.

Function Documentation

◆ HermesContAcqToFileGetMemory()

HermesReturn HermesContAcqToFileGetMemory ( Hermes_H  Hermes,
double *  total_bytes 
)

Dump the camera memory to the PC and save data to the file specified with the HermesContAcqToFileStart() function in Hermes file format (for details on the format see function HermesSaveImgDisk).

This function must be repeatedly called, as fast as possible, in order to free the camera internal memory and keep the acquisition going. If the internal camera memory get full during acquisition an error is generated. WARNING The camera can generate data with very high throughput, up to about 205MB/s. Be sure to have enough disk space for your measurement.

Parameters
HermesHermes handle
total_bytesTotal number of bytes read. Value is referenced.
Returns
OK
NULL_POINTER The provided Hermes_H or BUFFER_H point to an empty memory location
UNABLE_CREATE_FILE It was not possible to access the output file.
INVALID_OP Continuous acquisition was not yet started. Use Hermes_HermesContAcqToFileStart() before calling this function.
COMMUNICATION_ERROR Communication error during data download.
Hermes_MEMORY_FULL Camera internal memory got full during data download. Data loss occurred. Reduce frame-rate or optimize your software to reduce dead-time between subsequent calling of the function.
See also
HermesContAcqToFileStart()
HermesContAcqToFileStop()
HermesSaveImgDisk();
Examples
SDK_Example.c.

◆ HermesContAcqToFileStart()

HermesReturn HermesContAcqToFileStart ( Hermes_H  Hermes,
char *  filename 
)

Put the camera in "continuous acquisition" mode.

Compatible with FLIM mode. If the camera was set to wait for an external sync, the acquisition will start as soon as a pulse is detected on the Sync input, otherwise it will start immediately. The output file name must be provided when calling this function. Data are stored in the camera internal memory and must be downloaded calling the HermesContAcqToFileGetMemory() function as soon as possible, in order to avoid data loss.

Parameters
HermesHermes handle
filenameFull path of the output file. The string length must not exceed 1024 characters. Value is referenced.
Returns
OK
NULL_POINTER The provided Hermes_H or BUFFER_H point to an empty memory location
UNABLE_CREATE_FILE It was not possible to create the output file.
See also
HermesContAcqToFileGetMemory()
HermesContAcqToFileStop()
Examples
SDK_Example.c.

◆ HermesContAcqToFileStop()

HermesReturn HermesContAcqToFileStop ( Hermes_H  Hermes)

Stop the continuous acquisition of data and close the output file.

This function must be called at the end of the continuous acquisition, in order to properly close the file. WARNING If not called, the output file may be unreadable, and camera may have unexpected behavior if other functions are called beforehand.

Parameters
HermesHermes handle
Returns
OK
NULL_POINTER The provided Hermes_H or BUFFER_H point to an empty memory location
UNABLE_CREATE_FILE It was not possible to access the output file.
See also
HermesContAcqToFileStart()
HermesContAcqToFileGetMemory()
Examples
SDK_Example.c.

◆ HermesContAcqToMemoryGetBuffer()

HermesReturn HermesContAcqToMemoryGetBuffer ( Hermes_H  Hermes,
double *  total_bytes,
BUFFER_H buffer 
)

Dump the camera memory to the PC and pass the pointer to the image buffer in which acquisition is stored.

This function must be repeatedly called, as fast as possible, in order to free the camera internal memory and keep the acquisition going. If the internal camera memory get full during acquisition an error is generated. Refer to Figure 7 of the User Manual for pixels readout order and position in the image. WARNING User must pay attention not to exceed the dimension of the buffer when accessing it. Refer to the value saved into the parameter total_bytes.

Parameters
HermesHermes handle
total_bytesTotal number of bytes read. Value is referenced
bufferPointer to the buffer Handle in which the function will save reference to the camera buffer. Value is referenced.
Returns
OK
NULL_POINTER The provided Hermes_H or BUFFER_H point to an empty memory location
INVALID_OP Continues acquisition was not yet started. Use HermesContAcqToMemoryStart() before calling this function.
COMMUNICATION_ERROR Communication error during data download.
Hermes_MEMORY_FULL Camera internal memory got full during data download. Data loss occurred. Reduce frame-rate or optimize your software to reduce deadtime between subsequent calling of the function.
See also
HermesContAcqToMemoryStart()
HermesContAcqToMemoryStop()
Examples
SDK_Example.c.

◆ HermesContAcqToMemoryStart()

HermesReturn HermesContAcqToMemoryStart ( Hermes_H  Hermes)

Put the camera in "continuous acquisition" mode.

Compatible with FLIM mode. If the camera was set to wait for an external sync, the acquisition will start as soon as a pulse is detected on the Sync input, otherwise it will start immediately. Data are stored in the camera internal memory and must be downloaded calling the HermesContAcqToMemoryGetBuffer() function as soon as possible, in order to avoid data loss.

Parameters
HermesHermes handle
Returns
OK
NULL_POINTER The provided Hermes_H or BUFFER_H point to an empty memory location
See also
HermesContAcqToMemoryGetBuffer()
HermesContAcqToMemoryStop()
Examples
SDK_Example.c.

◆ HermesContAcqToMemoryStop()

HermesReturn HermesContAcqToMemoryStop ( Hermes_H  Hermes)

Stop the continuous acquisition of data.

This function must be called at the end of the continuous acquisition. WARNING If not called, camera may have unexpected behavior if other functions are called.

Parameters
HermesHermes handle
Returns
OK
NULL_POINTER The provided Hermes_H point to an empty memory location
See also
HermesContAcqToMemoryStart()
HermesContAcqToMemoryGetBuffer()
Examples
SDK_Example.c.

◆ HermesLiveGetImg()

HermesReturn HermesLiveGetImg ( Hermes_H  Hermes,
UInt16 Img 
)

Get a Live image.

Acquire a live image and store the data into the user-allocated Img array. This command is working only when the Live mode is turned on by the HermesLiveSetModeON() function.

Parameters
HermesHermes handle
ImgPointer to the output image array. The size of the array must be at least 4 KB.
Returns
OK
NULL_POINTER The provided Hermes_H or Img point to an empty memory location
INVALID_OP The live-mode has not been started yet
See also
HermesLiveSetModeON()
Examples
SDK_Example.c.

◆ HermesLiveSetModeOFF()

HermesReturn HermesLiveSetModeOFF ( Hermes_H  Hermes)

Turn off the Live mode.

Parameters
HermesHermes handle
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
INVALID_OP The live mode is already inactive
See also
HermesLiveSetModeON()
Examples
SDK_Example.c.

◆ HermesLiveSetModeON()

HermesReturn HermesLiveSetModeON ( Hermes_H  Hermes)

Turn on the Live mode.

The camera is set in the Live mode, i.e. it continuously acquires images (free-running mode). The frames which are not transferred to the computer are discarded. Therefore, the time-laps between two frames is not constant and it will depend on the transfer speed between the host computer and the camera. This mode is very useful to adjust optical components or to align the camera position. When the camera is in Live mode, no acquisition of images by HermesSnapAcquire() or HermesContAcqToFileGetMemory() can be performed.

Parameters
HermesHermes handle
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
INVALID_OP The live mode has been already started
See also
HermesLiveSetModeOFF()
HermesContAcqToFileGetMemory()
HermesSnapAcquire()
Examples
SDK_Example.c.

◆ HermesSnapAcquire()

HermesReturn HermesSnapAcquire ( Hermes_H  Hermes)

Get a selected number of images.

Acquire a set of images according to the parameters defined by HermesSetCameraPar(). In FLIM mode NFrames "FLIM acquisitions" will be acquired. This command works only when HermesSnapPrepare() has already been called. This function will not exit until the required number of images has been downloaded. For this reason, if the camera is configured for waiting and External Sync, before calling this function it could be useful to poll the camera for the trigger state, using the HermesIsTriggered() function.

Parameters
HermesHermes handle
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
INVALID_OP Unable to acquire images when the live mode is ON. Use instead HermesLiveGetImg().
INVALID_OP When the background subtraction, dead-time correction or normal acquisition mode are enabled, a maximum of 65536 images can be acquired
See also
HermesSetCameraPar()
HermesSnapPrepare()
HermesSetSyncInState()
HermesIsTriggered()
Examples
SDK_Example.c.

◆ HermesSnapGetImageBuffer()

HermesReturn HermesSnapGetImageBuffer ( Hermes_H  Hermes,
BUFFER_H buffer,
int *  DataDepth 
)

Get the pointer to the image buffer in which snap acquisition is stored.

Refer to Figure 7 of the User Manual for pixels readout order and position in the image. WARNING User must pay attention not to exceed the dimension of the buffer (2*1024*65534 bytes) when accessing it.

Parameters
HermesHermes handle
bufferPointer to the buffer Handle in which the function will save reference to the camera image buffer
DataDepthReturn the number of bits per pixel (8 or 16) in the image. The value is referenced.
Returns
OK
NULL_POINTER The provided Hermes_H or BUFFER_H point to an empty memory location
See also
HermesSnapAcquire()

◆ HermesSnapGetImgPosition()

HermesReturn HermesSnapGetImgPosition ( Hermes_H  Hermes,
UInt16 Img,
UInt32  Position,
UInt16  counter 
)

Export an acquired image to an user allocated memory array.

Once a set of images have been acquired by HermesSnapAcquire(), a single image can be exported from the SDK image buffer and saved in the memory (Img array).

Parameters
HermesHermes handle
ImgPointer to the output image array. The size of the array must be at least 4kB.
PositionIndex of the image to save. Accepted values: 1 ... Number of acquired images
counterNumber of the desired counter. Accepted values: 1 ... Number of used counters
Returns
OK
NULL_POINTER The provided Hermes_H or Img point to an empty memory location
OUT_OF_BOUND Parameters are out of bound.
See also
HermesSnapAcquire()

◆ HermesSnapPrepare()

HermesReturn HermesSnapPrepare ( Hermes_H  Hermes)

Prepare the camera to the acquisition of a snap.

This command configures the camera to acquire a snap of NFrames images, as set by the HermesSetCameraPar() function. In FLIM mode NFrames "FLIM acquisitions" of a FLIM sequence will be acquired. If an External Sync is required, the camera will wait for a pulse on the Sync input before acquiring the images and saving them to the internal memory, otherwise they are acquired and saved immediately. Once acquired, snap must then be transferred to the PC using the HermesSnapAcquire() function.

Parameters
HermesHermes handle
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
INVALID_OP Unable to acquire images when the live mode is ON. Use instead HermesLiveGetImg().
INVALID_OP When the background subtraction, dead-time correction or normal acquisition mode are enabled, a maximum of 65536 images can be acquired
See also
HermesSetCameraPar()
HermesSnapAcquire()
HermesSetSyncInState()
Examples
SDK_Example.c.