Thermal/Mask 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 and mask detection. You can also read log records with temperature information.

Config

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

  bool auditTemperature;
  bool useRejectSound;
  bool useOverlapThermal;

  ThermalCamera camera;

  // Only for FaceStation F2 and BioStation 3
  CheckMode maskCheckMode;
  MaskDetectionLevel maskDetectionLevel;

  bool useDynamicROI;

  uint32 temperatureThresholdLow;
}

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.
temperatureThresholdHigh: Set the high 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.
useDynamicROI: If true, dynamic ROI will be used.
temperatureThresholdLow: Set the low threshold temperature in 0.01 Celsius. For instance, if the threshold is 32.5°C, it should be 3250.

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