Skip to content

Adapter - SFA

This page describes version 2.0.18 of the adapter.

Overview

This adapter is used to connect to NeoFace Kaoato application.

The adapter can be used to access the below commands:

  • registRegistrant: register a new Registrant into the database;
  • deleteRegistrant: deletes a specific registrant from a database identified with its registrantID; this command will NOT delete the facial information attached to that registrant, if any;
  • registRegistrantWithFace: register a new Registrant into the database, along with its picture and face related information;
  • deleteRegistrantWithFace: deletes from the databse the registrant information identified by its registrantID, along with all the facial information attached to that registrant;
  • getRegistrant: retrieve a registrant using its registrantID;
  • getRegistrantByUniqueID: retrive a registrant using its uniqueID;
  • addFace: adding a face (picture) to an existing registrant;
  • modifyFace: modifing a face (picture) of an existing registrant;
  • deleteFace: deleting the face information (picture) of an existing registrant;
  • matchFaceImage: try to match two faces (images) returning a match or not match result based on a threshold value;
  • searchCandidate: searches the database after all registrants whos pictures are maching a specific face image, returning an array of candidates;
  • matchFaceWithRegistrant: searches the database for maches against a face image and returnes only the most significat match if more matches are detected;

Some behavioral notes

Behavioral information
All properties that are of Flag type (0 or 1 value) take 0 as value if any number greater than 1 is used or any other character is typed in.
If a registrant is added in the database with the command RegistRegistrant using any of DeleteRegistrant or DeeteRegistrantWithFace commands will remove that registrant information from the database.
If a registrant is added into the database with RegistRegistrantWithFace command, running the DeleteRegistrant command will remove from the database the registrant information but not the facial information associated with it.
If a registrant is added into the database with RegistRegistrantWithFace command, running the DeleteRegistrantWithFace command will remove from the database both, the registrant information and the facial information associated with it.
If a registrant is added into the database with RegistRegistrant command and after that the AddFace command is successfully executed, running the DeleteRegistrant command will remove from the database the registrant information but not the facial information associated with it.
If a registrant is added into the database with RegistRegistrant command and after that the AddFace command is successfully executed, running the DeleteRegistrantWithFace command will remove from the database both, the registrant information and the facial information associated with it.
We should also pay attention to the enableFlg (Authentication target flag) property used with registRegistrant and registRegistrantWithFace commands
If this property is set to 1 or is left empty, the registrant registered with registRegistrant or registRegistrantWithFace commands (let's name it Registrant1), may be used for target authentication. That means that any subsequent use of SearchCandidate or MatchFaceWithRegistrant commands (using same image as the one used with registRegistrant or registRegistrantWithFace commands), will return Registrant1 in the command response field.
If this property (enableFlg) is set to 0 (zero), the registrant registered with registRegistrant or registRegistrantWithFace commands (let's name it Registrant0), will NOT be used for target authentication. That means that any subsequent use of SearchCandidate or MatchFaceWithRegistrant commands (using same image as the one used with registRegistrant or registRegistrantWithFace commands), will NOT return Registrant0 in the command response field.

Kaoato configuration setup

The adapter would work only after "High-speed verification platform(KaoatoVS.exe)" is started.

Kaoato configuration setup used with SFA Match Event adapter

If the SFA adapter is intended to be used along with the SFA Match Event adapter the below configuration should be implemented in the Kaoato GCA configuration file!

The GCA Kaoato module should be configured to send data via TCP. To enable the TCP data transmission, the GCA application should be configured by setting the Operating Mode Settings/Operating Mode (output) to 10.

Also the format of the authentication OK mode should be set in the Authentication result mode settings/OKlog section of the GCA configuration file. The format SFA Match Event adapter needs should be as below:

BEGINLogDateTime~[DT]~CameraName~[Camera]~SuspectID~[SuspectID]~AlertType~[AlertType]~VerifyScore~[VerifyScore]~UniqueID~[SI_UniqueID]~Name1~[SI_Name1]~Name2~[SI_Name2]~Birthday~[SI_Birthday]~



Properties

Name Display Is Required Comments Type Default Value Maximum Value Minimum Value Maximum Length Minimum Length
uri SFA URI True The URI to the SFA Api string https:// 1024 1
userName User Name True User name to login to the SFA Api in secured mode string 1024 1
password Password True Password to login to the SFA Api in secured mode password 1024 1
deviceid deviceId True Device ID string 1024 1



Commands

Match Images (matchFaceImage)

Match 2 images (base64 encoded strings) and return a match score (0-100)

Request Properties

Name Display Description Is Required Type
FaceImage1 FaceImage1 First image True string
FaceImage2 FaceImage2 Second image True string
MinScore MinScore The minimum score for which the adapter will consider the match as successful. Note: When the actual match score was less than the MinScore, the adapter command will fail, with an error message that mentions a HTTP 204 error (no content returned by the Kaoato API). False string

Response Properties

Name Description Type
status Status of the command - true/false string
error Error message (if any) string
VerifyScore VerifyScore string

Add Face (addFace)

Add an image to a specific registrant entry.

Request Properties

Name Display Description Is Required Type
registrantID RegistrantID Registrant information ID True string
captureImage CaptureImage Face image to be associated with the registrant, encoded as a Base-64 string. True string
memo Memo A note associated with the image False string
protectFlg ProtectFlg Image protection flag. Can be 0 or 1. If not specified, or if the value is different than 0 or 1, it defaults to 0. False string
judgementScore JudgementScore Collation judgement score. False string
acceptFlg AcceptFlg Flag to authorize face information 0: Authorized 1: Unauthorized. If not specified, or if the value is different than 0 or 1, it defaults to 0. False string

Response Properties

Name Description Type
status Status of the command - true/false string
error Error message (if any) string
faceID ID of the face information that was just added. string

Modify Face (modifyFace)

Modify the image associated with a specific faceID

Request Properties

Name Display Description Is Required Type
faceID FaceID The facial information ID whos image will be modified. True string
captureImage CaptureImage The new face image to be associated with the above faceID, encoded as a Base-64 string. True string
memo Memo A note associated with the image False string
protectFlg ProtectFlg Image protection flag. Can be 0 or 1. If not specified, or if the value is different than 0 or 1, it defaults to 0. False string
judgementScore JudgementScore Collation judgement score. False string
acceptFlg AcceptFlg Flag to authorize face information 0: Authorized 1: Unauthorized. If not specified, or if the value is different than 0 or 1, it defaults to 0. False string

Response Properties

Name Description Type
status Status of the command - true/false string
error Error message (if any) string
faceID ID of the face information that was just modified. string

Delete Face (deleteFace)

Delete all information associated with a specific faceID

Request Properties

Name Display Description Is Required Type
faceID FaceID The facial information ID which will be deleted. True string

Response Properties

Name Description Type
status Status of the command - true/false string
error Error message (if any) string
faceID ID of the face information that was just deleted. string

Detect Face (detectFace)

Detect face from images

Request Properties

Name Display Description Is Required Type
captureImage captureImage Character string encoded image (jpg) with Base64. True string
detectReliability detectReliability Reliability (0~100). False string
detectEyeMax detectEyeMax Maximum value of eyes distance to judge as face (1~9999 pixel). False string
detectEyeMin detectEyeMin Minimum value of eyes distance to judge as face (1~9999 pixel). False string
detectEyeDeg detectEyeDeg Eye inclination range when detecting face (0~90 degree). False string

Response Properties

Name Description Type
status Status of the command - true/false string
error Error message (if any) string
detectedFaceList[0].frontalScore Frontal score. string
detectedFaceList[0].eyeDistance Eyes distance. string
detectedFaceList[0].reliability Reliability. string
detectedFaceList[0].lEyeX Left eye X coordinate. string
detectedFaceList[0].lEyeY Left eye Y coordinate. string
detectedFaceList[0].rEyeX Right eye X coordinate. string
detectedFaceList[0].rEyeY Right eye Y coordinate. string
detectedFaceList[0].faceLeft Left position of two coordinates between upper left and under right of rectangle face. string
detectedFaceList[0].faceTop Upper position of two coordinates between upper left and under right of rectangle face. string
detectedFaceList[0].faceRight Right position of two coordinates between upper left and under right of rectangle face. string
detectedFaceList[0].faceBottom Bottom position of two coordinates between upper left and under right of rectangle face. string
detectedFaceList[0].roll Face roll. string

Register Registrant (registRegistrant)

Register new registrant.

Request Properties

Name Display Description Is Required Type
uniqueID UniqueID UniqueID False string
name1 Name1 Name1 False string
name2 Name2 Name2 False string
yomi1 Name 1 (How to read) Name 1 (How to read) False string
yomi2 Name 2 (How to read) Name 2 (How to read) False string
birthday Birthday Birthday (yyyy/MM/dd) True string
nationality Nationality Nationality False string
postcode Postcode Postal Code False string
prefecture Prefecture Prefecture, state, district, etc. False string
address1 Address1 Address1 False string
address2 Address2 Address2 False string
phone1 Phone1 Telephone number 1 False string
phone2 Phone2 Telephone number 2 False string
email1 Email1 E-mail address 1 False string
email2 Email2 E-mail address 2 False string
company Company Company False string
department Department Department False string
employeeCode EmployeeCode Employee Code False string
colourCode Alert Color Code Alert Color Code False string
effectiveFrom EffectiveFrom Start effective period (yyyy/MM/dd HH:mm:ss) True string
effectiveTo EffectiveTo End effective period (yyyy/MM/dd HH:mm:ss) True string
gender Gender 1: Male, 2: Female, 3: Unknown False string
bodyFeature BodyFeature BodyFeature False string
regReason RegReason To classify registrant False string
groupIDs Group IDs Group ID, comma separated list. False string
enableFlg Authentication target flag Flag to determine if registrant is authentication target - 0: Invalid, 1: Valid, 0: when nothing is specified. False string

Response Properties

Name Description Type
status Status of the command - true/false string
error Error message (if any) string
registrantID Registrant information ID string

Delete Registrant (deleteRegistrant)

Delete registrant information.

Request Properties

Name Display Description Is Required Type
registrantID Registrant ID Registrant information ID. True string

Response Properties

Name Description Type
status Status of the command - true/false string
error Error message (if any) string
registrantID Registrant information ID. string

Register Registrant With Face (registRegistrantWithFace)

Register new registrant with picture.

Request Properties

Name Display Description Is Required Type
uniqueID UniqueID Unique ID False string
name1 Name1 Name1 False string
name2 Name2 Name2 False string
yomi1 Name 1 (How to read) Name 1 (How to read) False string
yomi2 Name 2 (How to read) Name 2 (How to read) False string
birthday Birthday Birthday (yyyy/MM/dd) True string
nationality Nationality Nationality False string
postcode Postcode Postal Code False string
prefecture Prefecture Prefecture, state, district, etc. False string
address1 Address1 Address1 False string
address2 Address2 Address2 False string
phone1 Phone1 Telephone number 1 False string
phone2 Phone2 Telephone number 2 False string
email1 Email1 E-mail address 1 False string
email2 Email2 E-mail address 2 False string
company Company Company False string
department Department Department False string
employeeCode EmployeeCode Employee Code False string
colourCode Alert Color Code Alert Color Code False string
effectiveFrom EffectiveFrom Start effective period (yyyy/MM/dd HH:mm:ss) True string
effectiveTo EffectiveTo End effective period (yyyy/MM/dd HH:mm:ss) True string
gender Gender 1: Male, 2: Female, 3: Unknown False string
bodyFeature BodyFeature BodyFeature False string
regReason RegReason To classify registrant False string
groupIDs Group IDs Group ID, comma separated list. False string
captureImage CaptureImage CaptureImage True string
memo Memo Memo False string
protectFlg Protection flag 0: Do not protect, 1: Protect. If not specified, or if the value is different than 0 or 1, it defaults to 0. False string
judgementScore JudgementScore JudgementScore False string
enableFlg Authentication target flag Flag to determine if registrant is authentication target - 0: Invalid, 1: Valid, 0: when nothing is specified. False string
acceptFlg Flag to authorize Flag to authorize face information 0: Authorized 1: Unauthorized. If not specified, or if the value is different than 0 or 1, it defaults to 0. False string

Response Properties

Name Description Type
status Status of the command - true/false string
error Error message (if any) string
registrantID Registrant information ID string
faceID Facial information ID string

Delete Registrant With Face (deleteRegistrantWithFace)

Delete registrant information and face information connected to the registrant information.

Request Properties

Name Display Description Is Required Type
registrantID Registrant ID Registrant information ID. True string

Response Properties

Name Description Type
status Status of the command - true/false string
error Error message (if any) string
registrantID Registrant information ID. string
faceIDList A list of face information ID corresponding to registrant information. string

Search Candidate (searchCandidate)

Returns all registrants matching the face from the database, ordered by matching score.

Request Properties

Name Display Description Is Required Type
faceImage faceImage Face image as search condition, a string encoded by Base64 from an image True string
count Acquisition count Acquired data count (the specified number of candidates are returned), all will be acquired when not specified False string
minScore Minimum collation score Collation score information is not returned when it is below this score even though within the specified count, the specified number of information is False string
faceFlg Face image acquisition flag 0: No face images exist, 1: Face images exist. If not specified, or if the value is different than 0 or 1, it defaults to 0. False string
itemFlg Registrant information aquisition flag. 0: No items exist, 1: Items exist. If not specified, or if the value is different than 0 or 1, it defaults to 0. False string

Response Properties

Name Description Type
status Status of the command - true/false string
error Error message (if any) string
candidateList.count The number of candidates (partially) matching with the specified criteria string
candidateList[0].no Rank order string
candidateList[0].registrantID Registrant information ID string
candidateList[0].faceID Facial information ID string
candidateList[0].uniqueID Registrant information unique ID string
candidateList[0].verifyScore Collation score with the registrant to be search conditions string
candidateList[0].captureImage Omitted when the face image acquisition flag is 0. string
candidateList[0].registrant.uniqueID Unique ID string
candidateList[0].registrant.name1 Name1 string
candidateList[0].registrant.name2 Name2 string
candidateList[0].registrant.yomi1 Name 1 (How to read) string
candidateList[0].registrant.yomi2 Name 2 (How to read) string
candidateList[0].registrant.birthday Birthday (yyyy/MM/dd) string
candidateList[0].registrant.nationality Nationality string
candidateList[0].registrant.postcode Postal Code string
candidateList[0].registrant.prefecture Prefecture, state, district, etc. string
candidateList[0].registrant.address1 Address 1 string
candidateList[0].registrant.address2 Address 2 string
candidateList[0].registrant.phone1 Telephone number 1 string
candidateList[0].registrant.phone2 Telephone number 2 string
candidateList[0].registrant.email1 E-mail address 1 string
candidateList[0].registrant.email2 E-mail address 1 string
candidateList[0].registrant.company Company string
candidateList[0].registrant.department Department string
candidateList[0].registrant.employeeCode Employee Code string
candidateList[0].registrant.effectiveFrom Start effective period (yyyy/MM/dd HH:mm:ss) string
candidateList[0].registrant.effectiveTo End effective period (yyyy/MM/dd HH:mm:ss) string
candidateList[0].registrant.gender 1: Male, 2: Female, 3: Unknown string
candidateList[0].registrant.bodyFeature BodyFeature string
candidateList[0].registrant.regReason RegReason string
candidateList[0].registrant.groupIDs Group IDs, comma separated list. string
candidateList[0].registrant.memo A note associated with the image string
candidateList[0].registrant.protectFlg Image protection flag. Can be 0 or 1. string
candidateList[0].registrant.faceID FaceID string

Match face with registrant (matchFaceWithRegistrant)

Returns the most significat matches from the database.

Request Properties

Name Display Description Is Required Type
faceImage faceImage Face image as search condition, a string encoded by Base64 from an image True string
faceFlg Face image acquisition flag 0: No face images exist, 1: Face images exist. 0 is selected when not specified. False string
minScore Minimum collation score Collation score information is not returned when it is below this score even though within the specified count, the specified number of information is False string
itemFlg Registrant information aquisition flag. 0: No items exist, 1: Items exist. If not specified, or if the value is different than 0 or 1, it defaults to 0. False string

Response Properties

Name Description Type
status Status of the command - true/false string
error Error message (if any) string
no Rank order string
registrantID Registrant information ID string
faceID Facial information ID string
uniqueID Unique ID string
verifyScore Verification score string
captureImage Capture image string
registrant.registrantID Registrant information ID string
registrant.faceData Face Data string
registrant.uniqueID UniqueID string
registrant.name1 Name1 string
registrant.name2 Name2 string
registrant.yomi1 Name 1 (How to read) string
registrant.yomi2 Name 2 (How to read) string
registrant.birthday Birthday (yyyy/MM/dd) string
registrant.nationality Nationality string
registrant.postcode Postcode string
registrant.prefecture Prefecture string
registrant.address1 Address1 string
registrant.address2 Address2 string
registrant.phone1 Telephone number 1 string
registrant.phone2 Telephone number 2 string
registrant.email1 E-mail address 1 string
registrant.email2 E-mail address 2 string
registrant.company Company string
registrant.department Department string
registrant.employeeCode EmployeeCode string
registrant.effectiveFrom Start effective period (yyyy/MM/dd HH:mm:ss) string
registrant.effectiveTo End effective period (yyyy/MM/dd HH:mm:ss) string
registrant.gender Gender string
registrant.bodyFeature BodyFeature string
registrant.regReason RegReason string
registrant.groupIDs Group IDs, comma separated list. string
registrant.memo A note associated with the image string
registrant.protectFlg Image protection flag. Can be 0 or 1. If not specified it defaults to 0. string
registrant.faceID Face ID string

Get Registrant (getRegistrant)

Get Registrant by RegistrantId

Request Properties

Name Display Description Is Required Type
registrantID RegistrantID RegistrantID True string

Response Properties

Name Description Type
status Status of the command - true/false string
error Error message (if any) string
registrantID Registrant information ID string
faceData Face Data string
uniqueID UniqueID string
name1 Name1 string
name2 Name2 string
yomi1 Name 1 (How to read) string
yomi2 Name 2 (How to read) string
birthday Birthday string
nationality Nationality string
postcode Postal Code string
prefecture Prefecture, state, district, etc. string
address1 Address 1 string
address2 Address 2 string
phone1 Telephone number 1 string
phone2 Telephone number 2 string
email1 E-mail address 1 string
email2 E-mail address 2 string
company Company string
department Department string
employeeCode Employee Code string
effectiveFrom Start effective period (yyyy/MM/dd HH:mm:ss) string
effectiveTo End effective period (yyyy/MM/dd HH:mm:ss) string
gender 1: Male, 2: Female, 3: Unknown string
bodyFeature BodyFeature string
regReason To classify registrant string
groupIDs Group ID, comma separated list. string
enableFlg Flag to determine if registrant is authentication target - 0: Invalid, 1: Valid, 0: when nothing is specified. string

Get Registrant By Unique ID (getRegistrantByUniqueID)

Get Registrant by UniqueId

Request Properties

Name Display Description Is Required Type
uniqueID UniqueID UniqueID True string

Response Properties

Name Description Type
status Status of the command - true/false string
error Error message (if any) string
registrantList[0].registrant.registrantID Registrant information ID string
registrantList[0].registrant.uniqueID Registrant information unique ID string
registrantList[0].registrant.name1 Name1 string
registrantList[0].registrant.name2 Name2 string
registrantList[0].registrant.yomi1 Name 1 (How to read) string
registrantList[0].registrant.yomi2 Name 2 (How to read) string
registrantList[0].registrant.birthday Birthday (yyyy/MM/dd) string
registrantList[0].registrant.nationality Nationality string
registrantList[0].registrant.postcode Postal Code string
registrantList[0].registrant.prefecture Prefecture, state, district, etc. string
registrantList[0].registrant.address1 Address 1 string
registrantList[0].registrant.address2 Address 2 string
registrantList[0].registrant.phone1 Telephone number 1 string
registrantList[0].registrant.phone2 Telephone number 2 string
registrantList[0].registrant.email1 E-mail address 1 string
registrantList[0].registrant.email2 E-mail address 1 string
registrantList[0].registrant.company Company string
registrantList[0].registrant.department Department string
registrantList[0].registrant.employeeCode Employee Code string
registrantList[0].registrant.effectiveFrom Start effective period (yyyy/MM/dd HH:mm:ss) string
registrantList[0].registrant.effectiveTo End effective period (yyyy/MM/dd HH:mm:ss) string
registrantList[0].registrant.gender 1: Male, 2: Female, 3: Unknown string
registrantList[0].registrant.bodyFeature BodyFeature string
registrantList[0].registrant.regReason RegReason string
registrantList[0].registrant.faceData[0].faceID FaceID string
registrantList[0].registrant.faceData[0].captureImage Face image to be associated with the registrant, encoded as a Base-64 string. string
registrantList[0].registrant.faceData[0].memo A note associated with the image string
registrantList[0].registrant.faceData[0].protectFlg Image protection flag. Can be 0 or 1. If not specified it defaults to 0. string
registrantList[0].registrant.faceData[0].acceptFlg Flag to authorize face information 0: Authorized 1: Unauthorized string
registrantList[0].registrant.faceData.count Count string
registrantList[0].enableFlg Flag to determine if registrant is authentication target - 0: Invalid, 1: Valid, 0: when nothing is specified. string
registrantList[0].count Count string

Release History

Version Type Description Tracking # Date
2.0.1 Initial First release in the Adapter Type store.
2.0.11 Feature New commands added: modifyFace, deleteFace. NAP-14944
2.0.13 Feature New commands added: deleteRegistrant, deleteRegistrantWithFace. NAP-16373
2.0.14 Bug fix Change the code to use the minScore property in the MatchFaceWithRegistrant command. NAP-18929
2.0.15 Maintenance Updated third-party components and improved maintainability. NAP-11518
2.0.17 Bug fix
Maintenance
Remove any logging that may send PII information
Crowdin update and use jenkins shared lib for docker image push and adapter store upload
NAP-20525
NAP-20555
2.0.18 Maintenance Updated third-party components and improved maintainability. NAP-23945 2022-11-30

Categories