Hermes SDK 1.0.1A
Set methods

Functions

HermesReturn HermesSetCameraPar (Hermes_H Hermes, UInt16 Exposure, UInt32 NFrames, UInt16 NIntegFrames, UInt16 NCounters, State Force8bit, State Half_array, State Signed_data)
 
HermesReturn HermesSetCameraParSubArray (Hermes_H Hermes, UInt16 Exposure, UInt32 NFrames, UInt16 NIntegFrames, State Force8bit, UInt16 Npixels)
 
HermesReturn HermesSetDeadTime (Hermes_H Hermes, UInt16 Val)
 
HermesReturn HermesSetDeadTimeCorrection (Hermes_H Hermes, State s)
 
HermesReturn HermesSetAdvancedMode (Hermes_H Hermes, State s)
 
HermesReturn HermesSetBackgroundImg (Hermes_H Hermes, UInt16 *Img)
 
HermesReturn HermesSetBackgroundSubtraction (Hermes_H Hermes, State s)
 
HermesReturn HermesSetGateMode (Hermes_H Hermes, UInt16 counter, GateMode Mode)
 
HermesReturn HermesSetGateValues (Hermes_H Hermes, Int16 Shift, Int16 Length)
 
HermesReturn HermesSetDualGate (Hermes_H Hermes, State DualGate_State, int StartShift, int FirstGateWidth, int SecondGateWidth, int Gap)
 
HermesReturn HermesSetTripleGate (Hermes_H Hermes, State TripleGate_State, int StartShift, int FirstGateWidth, int SecondGateWidth, int ThirdGateWidth, int Gap1, int Gap2)
 
HermesReturn HermesSetCoarseGateValues (Hermes_H Hermes, UInt16 Counter, UInt16 Start, UInt16 Stop)
 
HermesReturn HermesSetTriggerOutState (Hermes_H Hermes, TriggerMode Mode)
 
HermesReturn HermesSetSyncInState (Hermes_H Hermes, State s, int frames)
 
HermesReturn HermesSetFlimPar (Hermes_H Hermes, UInt16 FLIM_steps, UInt16 FLIM_shift, Int16 FLIM_start, UInt16 Length, int *FLIM_frame_time)
 
HermesReturn HermesSetFlimState (Hermes_H Hermes, State FLIM_State)
 
HermesReturn HermesApplySettings (Hermes_H Hermes)
 

Detailed Description

Functions to set parameters of the Hermes camera.

Function Documentation

◆ HermesApplySettings()

HermesReturn HermesApplySettings ( Hermes_H  Hermes)

Apply settings to the camera.

This function must be called after any Set function, except HermesLiveSetModeON() and HermesLiveSetModeOFF(), in order to apply the settings to the camera. If several Set functions need to be called, there is no need to call this function after each Set function. A single call to this function at the end is enough to apply all the settings.

Parameters
HermesHermes handle
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
Examples
SDK_Example.c.

◆ HermesSetAdvancedMode()

HermesReturn HermesSetAdvancedMode ( Hermes_H  Hermes,
State  s 
)

Change the operating mode.

Set the operating mode to Normal or Advanced. Normal mode is the default setting. Before starting a new acquisition check that the relevant parameters for the selected modality are correctly set.

Parameters
HermesHermes handle
sEnable or disable the advanced mode
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
Examples
SDK_Example.c.

◆ HermesSetBackgroundImg()

HermesReturn HermesSetBackgroundImg ( Hermes_H  Hermes,
UInt16 Img 
)

Load a background image to perform hardware background subtraction.

The control electronics is capable of performing real-time background subtraction. A background image is loaded into the internal camera memory.

Parameters
HermesHermes handle
ImgPointer to a 2048 UInt16 array containing the background image. WARNING The user should check the array size to avoid the corruption of the memory heap.
Returns
OK
NULL_POINTER The provided Hermes_H or Img point to an empty memory location
INVALID_OP Unable to set the background image when the live-mode is ON
Examples
SDK_Example.c.

◆ HermesSetBackgroundSubtraction()

HermesReturn HermesSetBackgroundSubtraction ( Hermes_H  Hermes,
State  s 
)

Enable or disable the hardware background subtraction.

Parameters
HermesHermes handle
sEnable or disable the background subtraction
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
Examples
SDK_Example.c.

◆ HermesSetCameraPar()

HermesReturn HermesSetCameraPar ( Hermes_H  Hermes,
UInt16  Exposure,
UInt32  NFrames,
UInt16  NIntegFrames,
UInt16  NCounters,
State  Force8bit,
State  Half_array,
State  Signed_data 
)

Set the acquisition parameters for the camera.

This function behaves differently depending on the operating mode setting. In case of Normal working mode, the exposure time is fixed to 10.40 microseconds. Therefore, the parameter Exposure is not considered. Longer exposures can be obtained by summing multiple frames (i.e. by setting NIntegFrames). This operating mode does not degrade the signal to noise ratio. In fact, the camera does not have any read-out noise. In case of Advanced mode, all the parameters are controlled by the user which can set very long exposure times. The time unit of the Exposure parameter is clock cycles i.e. the exposure time is an integer number of internal clock cycles of 10 ns period. For example, the value of 10 means 100 ns exposure.

Parameters
HermesHermes handle.
ExposureExposure time for a single frame (Hardware Integration Time - HIT). The time unit is 10 ns. Meaningful only for Advanced mode. Accepted values: 1 ... 65534
NFramesNumber of frames per acquisition. Meaningful only for Snap acquisition. Accepted values: 1 ... 65534
NIntegFramesNumber of integrated frames. Each output frame is the result of the sum of NIntegFrames. Accepted values: 1 ... 65534
NCountersNumber of counters per pixels to be used. Accepted values: 1 ... 3
Force8bitForce 8-bit per pixel acquisition. Counts are truncated. Meaningful only for Advanced mode.
Half_arrayAcquire only a 32x32 array.
Signed_dataIf enabled, data from counters 2 and 3 are signed data with 8-bit integer part and 1 bit sign.
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
OUT_OF_BOUND Exposure, NFrames and NIntegFrames must be all greater than zero and smaller than 65535
Examples
SDK_Example.c.

◆ HermesSetCameraParSubArray()

HermesReturn HermesSetCameraParSubArray ( Hermes_H  Hermes,
UInt16  Exposure,
UInt32  NFrames,
UInt16  NIntegFrames,
State  Force8bit,
UInt16  Npixels 
)

Set the acquisition parameters for the camera when a subarray is used.

This function has to be used in alternative to the function HermesSetCameraPar() when the acquisition of a subarray is needed. Subarray acquisition has few limitations:

  • the pixels will be readout starting from the upper-left one and moving by rows of 32 pixels toward the center of the array
  • in live mode it is possible to acquire only 1, 2, 4, 8 full rows. If Live mode is started when the camera is set for a different number of pixels, an INVALID_OP error will be returned.
  • in snap and continuous mode any number of pixels ranging from 1 to 256 in the upper semi-array can be acquired (in any case starting from the corner and then reading by rows, i.e. if 67 pixel are required 2 rows of 32 pixels + 3 pixels from the third row will be acquired), PROVIDED that the total data acquired is an integer multiple of 1024 bytes. For the example above and assuming the camera is set to 8-bit/pixel, it means that 1024 frames (or multiples) must be acquired. Each frame will be Npixel*10ns + 160ns long. Acquisitions with a smaller number of frames are not possible. If an acquisition is triggered with invalid values of the parameter, an INVALID_OP error will be returned.
  • only counter number 1 is available.

This function behaves differently depending on the operating mode setting. In case of Normal working mode, the exposure time is fixed to Npixel*10ns + 160ns. Therefore, the parameter Exposure is not considered. Longer exposures can be obtained by summing multiple frames (i.e. by setting NIntegFrames). This operating mode does not degrade the signal to noise ratio. In fact, the camera does not have any read-out noise. In case of Advanced mode, all the parameters are controlled by the user which can set very long exposure times. The time unit of the Exposure parameter is clock cycles i.e. the exposure time is an integer number of internal clock cycles of 10 ns period. For example, the value of 10 means 100 ns exposure.

Parameters
HermesHermes handle.
ExposureExposure time for a single frame (Hardware Integration Time - HIT). The time unit is 10 ns. Meaningful only for Advanced mode. Accepted values: 1 ... 65534
NFramesNumber of frames per acquisition. Meaningful only for Snap acquisition. Accepted values: 1 ... 65534
NIntegFramesNumber of integrated frames. Each output frame is the result of the sum of NIntegFrames. Accepted values: 1 ... 65534
Force8bitForce 8-bit per pixel acquisition. Counts are truncated. Meaningful only for Advanced mode.
NpixelsNumber of pixels to be acquired. Accepted values 1 ... 256 (see limitations above for Live mode)
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
OUT_OF_BOUND Exposure, NFrames, NIntegFrames or NPixels out of bound.

◆ HermesSetCoarseGateValues()

HermesReturn HermesSetCoarseGateValues ( Hermes_H  Hermes,
UInt16  Counter,
UInt16  Start,
UInt16  Stop 
)

Change the coarse Gate settings.

A gate signal is generated within the control electronics to select valid photons, i.e. only photons which arrives when the Gate is ON are counted. The gate signal has a period equal to the hardware integration time, and the start and stop time of the ON period can be adjusted with 10ns steps. Different gate settings can be applied to the 3 counters.

Parameters
HermesHermes handle
CounterCounter to which settings refer. Accepted values: 1..3
StartStarting position of the ON period. Can range from 0 to (HIT - 6), where units is 10ns and HIT is the Hardware Integration Time set with HermesSetCameraPar().
StopStop position of the ON period. Can range from (Start+1) to (HIT - 5), where units is 10ns and HIT is the Hardware Integration Time set with HermesSetCameraPar().
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
OUT_OF_BOUND Start or Stop are outside the valid values
See also
HermesSetCameraPar()
HermesSetCameraParSubArray()

◆ HermesSetDeadTime()

HermesReturn HermesSetDeadTime ( Hermes_H  Hermes,
UInt16  Val 
)

Update the dead-time setting.

Every time a photon is detected in a pixel, that pixel remains blind for a fix amount of time which is called dead-time. This setting is user-defined and it ranges from MIN_DEAD_TIME and MAX_DEAD_TIME. Only a sub-set of this range is practically selectable: a dead-time calibration is performed during the production of the device. This function will set the dead-time to the closest calibrated value to Val. The default dead-time value is 50 ns.

Parameters
HermesHermes handle
ValNew dead-time value in nanoseconds
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
INVALID_OP Unable to change the dead-time when the live-mode is ON
Examples
SDK_Example.c.

◆ HermesSetDeadTimeCorrection()

HermesReturn HermesSetDeadTimeCorrection ( Hermes_H  Hermes,
State  s 
)

Enable or disable the dead-time correction.

The default setting is disabled.

Parameters
HermesHermes handle
sNew state for the dead-time corrector
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
Examples
SDK_Example.c.

◆ HermesSetDualGate()

HermesReturn HermesSetDualGate ( Hermes_H  Hermes,
State  DualGate_State,
int  StartShift,
int  FirstGateWidth,
int  SecondGateWidth,
int  Gap 
)

Set parameters for DualGate mode.

In this mode two counters are used, both in gated mode. Position and width of Gate 1 and width of Gate 2 can be set by user, whereas position of Gate 2 is automatically set at the end of Gate 1 plus a gap selected by the user, but not smaller than 2ns. Total duration of Gate 1 and Gate 2 plus gap can not exceed 90% of the gate period of 20ns.

Parameters
HermesHermes handle
DualGate_StateEnable or disable dual-gate mode
StartShiftStart delay for for the first gate in thousandths of gate period (20ns). Accepted values: -500 ... +500
FirstGateWidthDuration of the ON gate 1 signal. The unit is percentage. Accepted values: 0 ... 100
SecondGateWidthDuration of the ON gate 2 signal. The unit is percentage. Accepted values: 0 ... 100
GapGap between the two gates in thousandths of nominal gate period (20ns). Accepted values: 100 ... 1000
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
INVALID_OP This mode is not compatible with FLIM mode.
OUT_OF_RANGE Parameters are out of bound. Please note that the function not only checks if the single parameters are acceptable, but also checks if the combination of parameters would result in an invalid gate setting.

◆ HermesSetFlimPar()

HermesReturn HermesSetFlimPar ( Hermes_H  Hermes,
UInt16  FLIM_steps,
UInt16  FLIM_shift,
Int16  FLIM_start,
UInt16  Length,
int *  FLIM_frame_time 
)

Set FLIM parameters.

The camera can perform automatic time-gated FLIM measurements employing the embedded gate generator. Call this function to setup the FLIM acquisition parameters. Each "FLIM acquisition" is composed by FLIM_steps frames, each one consisting of an acquisition with Exposure and NIntegFrames as set with HermesSetCameraPar(). The total time required to perform each FLIM acquisition is passed back to the caller through the referenced FLIM_frame_time variable.

Parameters
HermesHermes handle
FLIM_stepsNumber of gate delay steps to be performed. Accepted values: 1 ... 1000
FLIM_shiftDelay shift between steps in thousandths of gate period (20ns). Accepted values: 1 ... 1000
FLIM_startStart delay for FLIM sequence in thousandths of gate period (20ns). Accepted values: -500 ... +500
LengthDuration of the ON gate signal. The unit is percentage. Accepted values: 0 ... 100
FLIM_frame_timeTotal time required to perform each FLIM acquisition in multiples of 10ns. Value is referenced.
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
OUT_OF_BOUND Parameters are out of bound. Please note that the function not only checks if the single parameters are acceptable, but also checks if the combination of parameters would result in an invalid gate setting. E.g. FLIM_steps=100, FLIM_start=0, FLIM_shift=15 are not allowed, since they would result in a final gate shift of +1500 thousandths of period
See also
HermesSetCameraPar()

◆ HermesSetFlimState()

HermesReturn HermesSetFlimState ( Hermes_H  Hermes,
State  FLIM_State 
)

Enable or disable FLIM mode.

FLIM mode automatically set the number of used counters to 1. FLIM mode cannot be enabled if Exposure time is set to a value lower than 1040.

Parameters
HermesHermes handle
FLIM_StateEnable or disable the FLIM mode
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location.
INVALID_OP Exposure time is lower than 1040.
See also
HermesSetCameraPar()
HermesSetFlimPar()

◆ HermesSetGateMode()

HermesReturn HermesSetGateMode ( Hermes_H  Hermes,
UInt16  counter,
GateMode  Mode 
)

Set the gate mode to continuous, coarse or pulsed (only counter 1)

Parameters
HermesHermes handle
counterCounter to which settings refer. Accepted values: 1..3
ModeNew gate mode
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
INVALID_OP Only counter 1 can be set to Pulsed mode, for fast gating also counter 2 and 3 refers to HermesSetDualGate() and HermesSetTripleGate() functions.
Examples
SDK_Example.c.

◆ HermesSetGateValues()

HermesReturn HermesSetGateValues ( Hermes_H  Hermes,
Int16  Shift,
Int16  Length 
)

Change the fast Gate settings for counter 1.

A gate signal is generated within the control electronics to select valid photons for counter 1, i.e. only photons which arrives when the Gate is ON are counted. The gate signal is a 50 MHz square wave: shift and length define the phase and duty-cycle of the signal.

Parameters
HermesHermes handle
ShiftPhase shift of the gate signal in the ON state. The unit is thousandths, i.e. 10 means a delay time of 0.01 times a 20 ns periodic signal, which is equal to 200ps. Accepted values: -500 ... +500
LengthDuration of the ON gate signal. The unit is percentage. Accepted values: 0 ... 100
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
OUT_OF_BOUND Shift or length are outside the valid values
Examples
SDK_Example.c.

◆ HermesSetSyncInState()

HermesReturn HermesSetSyncInState ( Hermes_H  Hermes,
State  s,
int  frames 
)

Set the sync-in state.

Set the camera to wait for an input trigger signal before starting an acquisition.

Parameters
HermesHermes handle
sEnable or disable the synchronization input
framesIf the synchronization input is enabled, this is the number of frames that are acquired for each pulse (0 means that the acquisition will wait only the first pulse and then continue to the end with no further pauses). Accepted values: 0 ... 100.
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
Examples
SDK_Example.c.

◆ HermesSetTriggerOutState()

HermesReturn HermesSetTriggerOutState ( Hermes_H  Hermes,
TriggerMode  Mode 
)

Select the output signal.

Parameters
HermesPointer to the Hermes handle
ModeNew trigger mode
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
Examples
SDK_Example.c.

◆ HermesSetTripleGate()

HermesReturn HermesSetTripleGate ( Hermes_H  Hermes,
State  TripleGate_State,
int  StartShift,
int  FirstGateWidth,
int  SecondGateWidth,
int  ThirdGateWidth,
int  Gap1,
int  Gap2 
)

Set parameters for TripleGate mode.

In this mode three counters are used, all in gated mode. The three gates cannot overlap (even over different periods), and they have to follow the order: Gate1, Gate 3, Gate2. Position and width of Gate 1, and width of Gate 3 and 2 can be set by user, whereas position of Gate 3 and Gate 2 are automatically set by the function depending on the Gap1 and Gap2 values specified by the user. Gap1 between Gate1 and Gate3 can be as low as 0, Gap2 between Gate3 and Gate2 must be higher than 2ns. Total duration of Gate1, Gate3, Gate2 plus Gap1 and Gap2 can not exceed 90% of the gate period of 20ns.

Parameters
HermesHermes handle
TripleGate_StateEnable or disable triple-gate mode
StartShiftStart delay for for the first gate in thousandths of gate period (20ns). Accepted values: -500 ... +500
FirstGateWidthDuration of the ON gate 1 signal. The unit is percentage. Accepted values: 0 ... 100
SecondGateWidthDuration of the ON gate 3 signal. The unit is percentage. Accepted values: 0 ... 100
ThirdGateWidthDuration of the ON gate 2 signal. The unit is percentage. Accepted values: 0 ... 100
Gap1Gap between the gate1 and gate3 in thousandths of nominal gate period (20ns). Accepted values: 0 ... 1000
Gap2Gap between the gate3 and gate2 in thousandths of nominal gate period (20ns). Accepted values: 100 ... 1000
Returns
OK
NULL_POINTER The provided Hermes_H points to an empty memory location
INVALID_OP This mode is not compatible with FLIM mode.
OUT_OF_RANGE Parameters are out of bound. Please note that the function not only checks if the single parameters are acceptable, but also checks if the combination of parameters would result in an invalid gate setting.
Examples
SDK_Example.c.