Thermal Camera API

Suprema Thermal Camera can be used in combination with face recognition terminals to detect users with elevated skin temperature. With ThermalConfig, you can specify the options related to the camera. You can also read log records with temperature information.

Config

message ThermalConfig {
  CheckMode checkMode;
  CheckOrder checkOrder;
  TemperatureFormat temperatureFormat;
  uint32 temperatureThreshold;

  bool auditTemperature;
  bool useRejectSound;
  bool useOverlapThermal;

  ThermalCamera camera;

  // Only for FaceStation F2
  CheckMode maskCheckMode;
  MaskDetectionLevel maskDetectionLevel;
}
checkMode
If it is HARD and the temperature of a user exceeds temperatureThreshold, access will be denied with a violation log record. With SOFT, the device will write a violation log record with temperature information, but allow access to the user.
checkOrder
Specify when to check the temperature.
temperatureFormat
Specify the unit of temperature.
temperatureThreshold
Set the threshold temperature in 0.01 Celsius. For instance, if the threshold is 37.5°C, it should be 3750.
auditTemperature
If true, the measured temperature will be written to log records. You can read these logs using GetTemperatureLog.
useRejectSound
If true, a recorded error message will be played when user’s access is denied.
useOverlapThermal
Display an overlay of thermal image on the LCD screen.
camera
Specify the options related to the camera itself.

The default values would be good for most cases. Since some of these parameters could have a bad effect on the camera performance, read the descriptions carefully before changing them.

maskCheckMode
If it is HARD and the user is not wearing a mask, access will be denied with a violation log record. With SOFT, the device will write a violation log record, but allow access to the user.

Please note that there is no separate maskCheckOrder. The above checkOrder parameter is applied for checking the mask, too. For example, if it is BEFORE_AUTH, authenticate only when the user is wearing a mask.

maskDetectionLevel
The sensitivity of mask detection. If it is NOT_USE, mask detection is not used.
enum CheckMode {
  OFF = 0x00;
  HARD = 0x01;
  SOFT = 0x02;
}
OFF
Do not check the temperature of a user. Or, with maskCheckMode, do not check whether the user is wearing a mask.
HARD
If the temperature of a user exceeds temperatureThreshold, access will be denied with a violation log record. With maskCheckMode, check if the user is wearing a mask.
SOFT
Even if the temperature of a user exceeds temperatureThreshold, access will be allowed. However, a violation log record will be written with temperature information. With maskCheckMode, check if the user is wearing a mask.
enum CheckOrder {
  AFTER_AUTH = 0x00;
  BEFORE_AUTH = 0x01;
  WITHOUT_AUTH = 0x02;
}
AFTER_AUTH
Measure the temperature after successful authentication.
BEFORE_AUTH
Authenticate only when the user’s temperature is within the threshold. With this mode, the device does not attempt to authenticate users if their temperature exceed the threshold.
WITHOUT_AUTH
Detect temperature without authentication. This mode allows users with normal temperature to access without checking their identities or access rights.
enum TemperatureFormat {
  FAHRENHEIT = 0x00;
  CELSIUS = 0x01;
}
message ThermalCamera {
  uint32 distance;
  uint32 emissionRate;
  ThermalCameraROI ROI;

  bool useBodyCompensation;
  int32 compensationTemperature;
}
distance
Specify the distance between the user and the device in centimeters. The default is 100.
emissionRate
The emissivity of the subject reflecting heat. As for human subject, the default is 98.
ROI
Region of interset. These four parameters limit the area for temperature measurement. The default values in percent for the coordinates(x, y) and ranges(width, height) are (47, 45) and (15, 10) respectively.
useBodyCompensation
If true, apply CompensationTemperature to the measured value.
compensationTemperature
The compensation value in 0.1 Celsius. For instance, if the compensation is -0.1°C, it should be 1.
message ThermalCameraROI {
  uint32 x;
  uint32 y;
  uint32 width;
  uint32 height;
}
enum MaskDetectionLevel {
  NOT_USE = 0;
  NORMAL = 1;
  HIGH = 2;
  VERY_HIGH = 3;
}
NOT_USE
Mask detection is not used.
NORMAL/HIGH/VERY_HIGH
The sensitivity of mask detection.

GetConfig

Get the thermal configuration of a device.

Request
Parameter Type Description
deviceID uint32 The ID of the device
Response
Parameter Type Description
config ThermalConfig The thermal configuration of the device

SetConfig

Change the thermal configuration of a device.

Request
Parameter Type Description
deviceID uint32 The ID of the device
config ThermalConfig The thermal configuration to be written to the device

SetConfigMulti

Change the thermal configurations of multiple devices.

Request
Parameter Type Description
deviceIDs uint32[] The IDs of the devices
config ThermalConfig The thermal configuration to be written to the devices

Event

To get the event logs with temperature information, ThermalConfig.auditTemperature should be true.

GetTemperatureLog

Get the event logs with temperature information.

message TemperatureLog {
  uint32 ID;
  uint32 timestamp;
  uint32 deviceID;
  string userID;
  uint32 eventCode;
  uint32 subCode;
  uint32 temperature;
}
ID
4 byte identifier of the log record. Each device manages a monotonic increasing counter for this identifier. You can use this value to specify the starting position when reading logs from devices.
timestamp
In Unix time format. The number of seconds elapsed since January 1, 1970.
eventCode
16 bit code identifying the event type.
subCode
Some event types have an additional 8 bit code providing auxiliary information.
temperature
The temperature of the user in 0.01 degree. For example, if the temperature of a user is 36.3°C, it will be 3630.
Request
Parameter Type Description
deviceID uint32 The ID of the device
startEventID uint32 The ID of the first event log to be read. If it is 0, read logs from the start
maxNumOfLog uint32 The maximum number of logs to be read. If it is 0, try to read all the event logs
Response
Parameter Type Description
temperatureEvents TemperatureLog[] The temperature event logs read from the device