Movatterモバイル変換


[0]ホーム

URL:


Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Sign up
Appearance settings

JavaScript SDK for CompreFace - free and open-source face recognition system from Exadel

License

NotificationsYou must be signed in to change notification settings

exadel-inc/compreface-javascript-sdk

Repository files navigation

CompreFace JavaScript SDK makes face recognition into your application even easier.

Table of content

Requirements

Before using our SDK make sure you have installed CompreFace and Nodejs on your machine.

  1. CompreFace (See below compatibility matrix)
  2. Nodejs (Version 10+)

CompreFace compatibility matrix

CompreFace JS SDK versionCompreFace 0.4.xCompreFace 0.5.xCompreFace 0.6.xCompreFace 1.0.x
0.4.1
0.5.x🟡🟡
0.6.x🟡🟡
1.0.x🟡🟡

Explanation:

  • ✔ SDK supports all functionality from CompreFace.
  • 🟡 SDK works with this CompreFace version.In case if CompreFace version is newer - SDK won't support new features of CompreFace. In case if CompreFace version is older - new SDK features will fail.
  • ✘ There are major backward compatibility issues. It is not recommended to use these versions together

Installation

To add CompreFace JS SDK to your project, run the following command in the project folder:

npm i @exadel/compreface-js-sdk

Usage

Initialization

To start using JavaScript SDK you need to importCompreFace object from 'compreface-js-sdk' dependency.

Then you need to init it withurl andport. By default, if you run CompreFace on your local machine, it'shttp://localhost and8000 respectively.You can pass optionaloptions object when creating CompreFace to set default parameters, see reference formore information.

After you initializedCompreFace object you need to init the service object with theapi key of your face service. You can use this service object to recognize faces.

However, before recognizing you need first to add faces into the face collection. To do this, get the face collection object from the service object.

import{CompreFace}from'compreface-js-sdk';letapi_key="your_key";leturl="http://localhost";letport=8000;letcompreFace=newCompreFace(url,port);// set CompreFace url and portletrecognitionService=compreFace.initFaceRecognitionService(api_key);// initialize serviceletfaceCollection=recognitionService.getFaceCollection();// use face collection to fill it with known facesletsubjects=recognitionService.getSubjects();// use subjects object to work with subjects directely

Adding faces into a face collection

Here is JavaScript code example that shows how to add an image to your face collection from your file system:

letpath_to_image="../images/boy.jpg";letname=encodeURIComponent('Tom');faceCollection.add(path_to_image,name).then(response=>{// your code}).catch(error=>{console.log(`Oops! There is problem in uploading image${error}`)})

Recognition

This code snippet shows how to recognize unknown face:

letpath_to_image="../images/team.jpg";recognitionService.recognize(path_to_image).then(response=>{console.log(JSON.stringify(response));}).catch(error=>{console.log(`Oops! There is problem with recognizing image${error}`)})

Environments

NOTE: We provide 3 ways of uploading image to our SDK. They are url, blob and relative path (from local machine).

Enviromentsfrom URLwith Blob formatfrom local machine
Browser
Nodejs

Webcam demo

Documentation is here

Reference

CompreFace Global Object

Global CompreFace Object is used for initializing connection to CompreFace and setting default values for options.Default values will be used in every service method if applicable.If the option’s value is set in the global object and passed as a function argument then the function argument value will be used.

Constructor:

new CompreFace(server, port, options)

ArgumentTypeRequiredNotes
urlstringrequiredURL with protocol where CompreFace is located. E.g.http://localhost
portstringrequiredCompreFace port. E.g.8000
optionsobjectoptionalDefault values for face recognition services

Possible options:

OptionTypeNotes
det_prob_thresholdstringminimum required confidence that a recognized face is actually a face. Value is between 0.0 and 1.0
limitintegermaximum number of faces on the image to be recognized. It recognizes the biggest faces first. Value of 0 represents no limit. Default value: 0
prediction_countintegermaximum number of subject predictions per face. It returns the most similar subjects. Default value: 1
face_pluginsstringcomma-separated slugs of face plugins. If empty, no additional information is returned.Learn more
statusbooleanif true includes system information like execution_time and plugin_version fields. Default value is false

Example:

letserver="http://localhost";letport=8000;letoptions={limit:0,det_prob_threshold:0.8,prediction_count:1,face_plugins:"calculator,age,gender,landmarks",status:"true"}letcompreFace=newCompreFace(server,port,options);

Methods

  1. compreFace.initFaceRecognitionService(api_key)

Inits face recognition service object.

ArgumentTypeRequiredNotes
api_keystringrequiredFace Recognition Api Key in UUID format

Example:

letrecognitionService=compreFace.initFaceRecognitionService(api_key);
  1. compreFace.initFaceDetectionService(api_key)

Inits face detection service object.

ArgumentTypeRequiredNotes
api_keystringrequiredFace Detection Api Key in UUID format

Example:

letdetectionService=compreFace.initFaceDetectionService(api_key);
  1. compreFace.initFaceVerificationService(api_key)

Inits face verification service object.

ArgumentTypeRequiredNotes
api_keystringrequiredFace Verification Api Key in UUID format

Example:

letverificationService=compreFace.initFaceVerificationService(api_key);

Recognition Service

Face recognition service is used for face identification.This means that you first need to upload known faces to face collection and then recognize unknown faces among them.When you upload an unknown face, the service returns the most similar faces to it.Also, face recognition service supports verify endpoint to check if this person from face collection is the correct one.For more information, seeCompreFace page.

Recognize Faces from a Given Image

recognitionService.recognize(image_location, options)

Recognizes all faces from the image.The first argument is the image location, it could be a URL or a path on the local machine.

ArgumentTypeRequiredNotes
image_locationstringrequiredURL, image in BLOB format or image from your local machine
optionsstringoptionalObject that defines recognition options

Supported options:

OptionTypeNotes
det_prob_thresholdstringminimum required confidence that a recognized face is actually a face. Value is between 0.0 and 1.0
limitintegermaximum number of faces on the image to be recognized. It recognizes the biggest faces first. Value of 0 represents no limit. Default value: 0
prediction_countobjectmaximum number of subject predictions per face. It returns the most similar subjects. Default value: 1
face_pluginsstringcomma-separated slugs of face plugins. If empty, no additional information is returned.Learn more
statusbooleanif true includes system information like execution_time and plugin_version fields. Default value is false

Response:

{"result" : [ {"age" : {"probability":0.9308982491493225,"high":32,"low":25   },"gender" : {"probability":0.9898611307144165,"value":"female"   },"mask" : {"probability":0.9999470710754395,"value":"without_mask"   },"embedding" : [9.424854069948196E-4,"...",-0.011415496468544006 ],"box" : {"probability" :1.0,"x_max" :1420,"y_max" :1368,"x_min" :548,"y_min" :295   },"landmarks" : [ [814,713 ], [1104,829 ], [832,937 ], [704,1030 ], [1017,1133 ] ],"subjects" : [ {"similarity" :0.97858,"subject" :"subject1"   } ],"execution_time" : {"age" :28.0,"gender" :26.0,"detector" :117.0,"calculator" :45.0,"mask":36.0   } } ],"plugins_versions" : {"age" :"agegender.AgeDetector","gender" :"agegender.GenderDetector","detector" :"facenet.FaceDetector","calculator" :"facenet.Calculator","mask":"facemask.MaskDetector" }}
ElementTypeDescription
ageobjectdetected age range. Return only ifage plugin is enabled
genderobjectdetected gender. Return only ifgender plugin is enabled
maskobjectdetected mask. Return only ifface mask plugin is enabled.
embeddingarrayface embeddings. Return only ifcalculator plugin is enabled
boxobjectlist of parameters of the bounding box for this face
probabilityfloatprobability that a found face is actually a face
x_max, y_max, x_min, y_minintegercoordinates of the frame containing the face
landmarksarraylist of the coordinates of the frame containing the face-landmarks. Return only iflandmarks plugin is enabled
subjectslistlist of similar subjects with size of <prediction_count> order by similarity
similarityfloatsimilarity that on that image predicted person
subjectstringname of the subject in Face Collection
execution_timeobjectexecution time of all plugins
plugins_versionsobjectcontains information about plugin versions

Example:

letimage_location="../images/team.jpg";letoptions={limit:0,det_prob_threshold:0.8,prediction_count:1,face_plugins:"calculator,age,gender,landmarks",status:"true"}recognitionService.recognize(image_location,options).then(response=>{console.log(JSON.stringify(response));}).catch(error=>{console.log(`Oops! There is problem with recognizing image${error}`)})

Get Face Collection

recognitionService.getFaceCollection()

Returns Face collection object

Face collection could be used to manage known faces, e.g. add, list, or delete them.

Face recognition is performed for the saved known faces in face collection, so before using therecognize method you need to save at least one face into the face collection.

More information about face collection and managing exampleshere

Methods:

Add an Example of a Subject

faceCollection.add(image_location, subject, options)

Adds an image to your face collection.

ArgumentTypeRequiredNotes
image_locationstringrequiredURL, image in BLOB format or image from your local machine
subjectstringrequiredName or any other person ID. It can be just a random string you generate and save for further identification
optionsstringoptionalObject that defines adding options

Supported options:

OptionTypeNotes
det_prob_thresholdstringminimum required confidence that a recognized face is actually a face. Value is between 0.0 and 1.0

Response:

{"image_id":"string","subject":"string"}
FieldstringNotes
image_idstringID of the saved image
subjectstringName or any other person ID

Example:

letimage_location="../images/boy.jpg";letname=encodeURIComponent('Tom');letoptions={det_prob_threshold:0.8}faceCollection.add(image_location,name,options).then(response=>{console.log(JSON.stringify(response));}).catch(error=>{console.log(`Oops! There is problem in uploading image${error}`)})

List of All Saved Examples of the Subject

faceCollection.list()

Retrieve a list of images saved in a Face Collection

Response:

{"faces": [    {"image_id":"string","subject":"string"    }  ]}
FieldstringNotes
image_idstringID of the saved image
subjectstringName or any other person ID

Example:

faceCollection.list().then(response=>{console.log(JSON.stringify(response));}).catch(error=>{console.log(`Oops! There is problem:${error}`)})

Delete All Examples of the Subject by Name

faceCollection.delete_all_subject(subject)

Removes image(s) according to their given subject.

ArgumentTypeRequiredNotes
subjectstringoptionalName or any other person ID. If empty deletes all images in the face collection

Response:

{    "deleted": <count>}
ElementTypeDescription
deletedintegerNumber of deleted faces

Example:

letsubject="Tom";faceCollection.delete(subject).then(response=>{console.log(JSON.stringify(response));}).catch(error=>{console.log(`Oops! There is problem${error}`)})

Delete an Example of the Subject by ID

faceCollection.delete(image_id)

Remove image from face collection.

ArgumentTypeRequiredNotes
image_idstringrequiredID of the saved image

Response:

{"image_id":"string","subject":"string"}
FieldstringNotes
image_idstringID of the deleted image
subjectstringName or any other person ID

Example:

letimage_id="79ed78d8-f015-4947-b297-a24306ebbdad";faceCollection.delete(image_id).then(response=>{console.log(JSON.stringify(response));}).catch(error=>{console.log(`Oops! There is problem${error}`)})

Delete Multiple Examples

faceCollection.delete_multiple_images(image_ids)

Remove images from face collection.

ArgumentTypeRequiredNotes
image_idsstring[]requiredIDs of the saved images to delete

Response:

{"image_id":"string","subject":"string"}
FieldstringNotes
image_idstringID of the deleted image
subjectstringName or any other person ID

Example:

letimage_id="79ed78d8-f015-4947-b297-a24306ebbdad";faceCollection.delete(image_id).then(response=>{console.log(JSON.stringify(response));}).catch(error=>{console.log(`Oops! There is problem${error}`)})

Verify Faces from a Given Image

faceCollection.verify(image_path, image_id, options)

Compares similarities of given image with image from your face collection.

ArgumentTypeRequiredNotes
image_locationstringrequiredURL, image in BLOB format or image from your local machine
optionsstringoptionalObject that defines recognition options

Supported options:

OptionTypeNotes
det_prob_thresholdstringminimum required confidence that a recognized face is actually a face. Value is between 0.0 and 1.0
limitintegermaximum number of faces on the image to be recognized. It recognizes the biggest faces first. Value of 0 represents no limit. Default value: 0
prediction_countobjectmaximum number of subject predictions per face. It returns the most similar subjects. Default value: 1
face_pluginsstringcomma-separated slugs of face plugins. If empty, no additional information is returned.Learn more
statusbooleanif true includes system information like execution_time and plugin_version fields. Default value is false

Response:

{"result" : [ {"age" : {"probability":0.9308982491493225,"high":32,"low":25    },"gender" : {"probability":0.9898611307144165,"value":"female"    },"mask" : {"probability":0.9999470710754395,"value":"without_mask"    },"embedding" : [9.424854069948196E-4,"...",-0.011415496468544006 ],"box" : {"probability" :1.0,"x_max" :1420,"y_max" :1368,"x_min" :548,"y_min" :295    },"landmarks" : [ [814,713 ], [1104,829 ], [832,937 ], [704,1030 ], [1017,1133 ] ],"subjects" : [ {"similarity" :0.97858,"subject" :"subject1"    } ],"execution_time" : {"age" :28.0,"gender" :26.0,"detector" :117.0,"calculator" :45.0,"mask":36.0    }  } ],"plugins_versions" : {"age" :"agegender.AgeDetector","gender" :"agegender.GenderDetector","detector" :"facenet.FaceDetector","calculator" :"facenet.Calculator","mask":"facemask.MaskDetector"  }}
ElementTypeDescription
ageobjectdetected age range. Return only ifage plugin is enabled
genderobjectdetected gender. Return only ifgender plugin is enabled
maskobjectdetected mask. Return only ifface mask plugin is enabled.
embeddingarrayface embeddings. Return only ifcalculator plugin is enabled
boxobjectlist of parameters of the bounding box for this face
probabilityfloatprobability that a found face is actually a face
x_max, y_max, x_min, y_minintegercoordinates of the frame containing the face
landmarksarraylist of the coordinates of the frame containing the face-landmarks. Return only iflandmarks plugin is enabled
similarityfloatsimilarity that on that image predicted person
execution_timeobjectexecution time of all plugins
plugins_versionsobjectcontains information about plugin versions
letimage_location="../images/team.jpg";letimage_id="79ed78d8-f015-4947-b297-a24306ebbdad";letoptions={limit:0,det_prob_threshold:0.8,prediction_count:1,face_plugins:"calculator,age,gender,landmarks,mask",status:"true"}faceCollection.verify(image_location,image_id,options).then(response=>{console.log(JSON.stringify(response));}).catch(error=>{console.log(`Oops! There is problem with verifying image${error}`)})

Get Subjects

recognitionService.getSubjects()

Returns subjects object

Subjects object allows working with subjects directly (not via subject examples).

More information about subjectshere

letsubjects=recognitionService.getSubjects();

Methods:

Add a Subject

Create a new subject in Face Collection.

subjects.add(subject)
ArgumentTypeRequiredNotes
subjectstringrequiredis the name of the subject. It can be any string

Response:

{"subject":"subject1"}
ElementTypeDescription
subjectstringis the name of the subject
letsubjects=recognitionService.getSubjects();subjects.add("John");

List Subjects

Returns all subject related to Face Collection.

subjects.list()

Response:

{"subjects": ["<subject_name1>","<subject_name2>"  ]}
ElementTypeDescription
subjectsarraythe list of subjects in Face Collection
letsubjects=recognitionService.getSubjects();console.log(subjects.list());

Rename a Subject

Rename existing subject. If a new subject name already exists, subjects are merged - all faces from the old subject name are reassigned to the subject with the new name, old subject removed.

subjects.rename(subject,new_name)
ArgumentTypeRequiredNotes
subjectstringrequiredis the name of the subject that will be updated
new_namestringrequiredis the name of the subject. It can be any string

Response:

{"updated":"true|false"}
ElementTypeDescription
updatedbooleanfailed or success
letsubjects=recognitionService.getSubjects();subjects.add("John");console.log(subjects.list());subjects.rename("John","Jane");console.log(subjects.list());

Delete a Subject

Delete existing subject and all saved faces.

subjects.delete(subject)
ArgumentTypeRequiredNotes
subjectstringrequiredis the name of the subject.

Response:

{"subject":"subject1"}
ElementTypeDescription
subjectstringis the name of the subject
letsubjects=recognitionService.getSubjects();subjects.add("John");console.log(subjects.list());subjects.delete("John");console.log(subjects.list());

Delete All Subjects

Delete all existing subjects and all saved faces.

subjects.deleteAll()

Response:

{"deleted":"<count>"}
ElementTypeDescription
deletedintegernumber of deleted subjects
letsubjects=recognitionService.getSubjects();subjects.add("John");subjects.add("Jane");console.log(subjects.list());subjects.deleteAll();console.log(subjects.list());

Face Detection Service

Face detection service is used for detecting faces in the image.

Methods:

Detect

detectionService.detect(image_location, options)

Finds all faces on the image.The first argument is the image location, it could be a URL or a path on the local machine.

ArgumentTypeRequiredNotes
image_locationstringrequiredURL, image in BLOB format or image from your local machine
optionsstringoptionalObject that defines detection options

Supported options:

OptionTypeNotes
det_prob_thresholdstringminimum required confidence that a recognized face is actually a face. Value is between 0.0 and 1.0
limitintegermaximum number of faces on the image to be recognized. It recognizes the biggest faces first. Value of 0 represents no limit. Default value: 0
face_pluginsstringcomma-separated slugs of face plugins. If empty, no additional information is returned.Learn more
statusbooleanif true includes system information like execution_time and plugin_version fields. Default value is false

Response:

{"result" : [ {"age" : {"probability":0.9308982491493225,"high":32,"low":25    },"gender" : {"probability":0.9898611307144165,"value":"female"    },"mask" : {"probability":0.9999470710754395,"value":"without_mask"    },"embedding" : [-0.03027934394776821,"...",-0.05117142200469971 ],"box" : {"probability" :0.9987509250640869,"x_max" :376,"y_max" :479,"x_min" :68,"y_min" :77    },"landmarks" : [ [156,245 ], [277,253 ], [202,311 ], [148,358 ], [274,365 ] ],"execution_time" : {"age" :30.0,"gender" :26.0,"detector" :130.0,"calculator" :49.0,"mask":36.0    }  } ],"plugins_versions" : {"age" :"agegender.AgeDetector","gender" :"agegender.GenderDetector","detector" :"facenet.FaceDetector","calculator" :"facenet.Calculator","mask":"facemask.MaskDetector"  }}
ElementTypeDescription
ageobjectdetected age range. Return only ifage plugin is enabled
genderobjectdetected gender. Return only ifgender plugin is enabled
maskobjectdetected mask. Return only ifface mask plugin is enabled.
embeddingarrayface embeddings. Return only ifcalculator plugin is enabled
boxobjectlist of parameters of the bounding box for this face (on processedImage)
probabilityfloatprobability that a found face is actually a face (on processedImage)
x_max, y_max, x_min, y_minintegercoordinates of the frame containing the face (on processedImage)
landmarksarraylist of the coordinates of the frame containing the face-landmarks. Return only iflandmarks plugin is enabled
execution_timeobjectexecution time of all plugins
plugins_versionsobjectcontains information about plugin versions

Example:

letimage_location="../images/team.jpg";letoptions={limit:0,det_prob_threshold:0.8,face_plugins:"calculator,age,gender,landmarks",status:"true"}detectionService.detect(image_location,options).then(response=>{console.log(JSON.stringify(response));}).catch(error=>{console.log(`Oops! There is problem with recognizing image${error}`)})

Face Verification Service

Face verification service is used for comparing two images.A source image should contain only one face which will be compared to all faces on the target image.

Methods:

Verify

verificationService.verify(source_image_location, target_image_location, options)

Compares two images provided in arguments. Source image should contain only one face, it will be compared to all faces in the target image.The first two arguments are the image location, it could be a URL or a path on the local machine.

ArgumentTypeRequiredNotes
source_image_locationstringrequiredURL, source image in BLOB format or source image from your local machine
target_image_locationstringrequiredURL, target image in BLOB format or target image from your local machine
optionsstringoptionalObject that defines detection options

Supported options:

OptionTypeNotes
det_prob_thresholdstringminimum required confidence that a recognized face is actually a face. Value is between 0.0 and 1.0
limitintegermaximum number of faces on the image to be recognized. It recognizes the biggest faces first. Value of 0 represents no limit. Default value: 0
face_pluginsstringcomma-separated slugs of face plugins. If empty, no additional information is returned.Learn more
statusbooleanif true includes system information like execution_time and plugin_version fields. Default value is false

Response:

{"result" : [{"source_image_face" : {"age" : {"probability":0.9308982491493225,"high":32,"low":25      },"gender" : {"probability":0.9898611307144165,"value":"female"      },"mask" : {"probability":0.9999470710754395,"value":"without_mask"      },"embedding" : [-0.0010271212086081505,"...",-0.008746841922402382 ],"box" : {"probability" :0.9997453093528748,"x_max" :205,"y_max" :167,"x_min" :48,"y_min" :0      },"landmarks" : [ [92,44 ], [130,68 ], [71,76 ], [60,104 ], [95,125 ] ],"execution_time" : {"age" :85.0,"gender" :51.0,"detector" :67.0,"calculator" :116.0,"mask":36.0      }    },"face_matches": [      {"age" : {"probability":0.9308982491493225,"high":32,"low":25        },"gender" : {"probability":0.9898611307144165,"value":"female"        },"mask" : {"probability":0.9999470710754395,"value":"without_mask"        },"embedding" : [-0.049007344990968704,"...",-0.01753818802535534 ],"box" : {"probability" :0.99975,"x_max" :308,"y_max" :180,"x_min" :235,"y_min" :98        },"landmarks" : [ [260,129 ], [273,127 ], [258,136 ], [257,150 ], [269,148 ] ],"similarity" :0.97858,"execution_time" : {"age" :59.0,"gender" :30.0,"detector" :177.0,"calculator" :70.0,"mask":36.0        }      }],"plugins_versions" : {"age" :"agegender.AgeDetector","gender" :"agegender.GenderDetector","detector" :"facenet.FaceDetector","calculator" :"facenet.Calculator","mask":"facemask.MaskDetector"    }  }]}
ElementTypeDescription
source_image_faceobjectadditional info about source image face
face_matchesarrayresult of face verification
ageobjectdetected age range. Return only ifage plugin is enabled
genderobjectdetected gender. Return only ifgender plugin is enabled
maskobjectdetected mask. Return only ifface mask plugin is enabled.
embeddingarrayface embeddings. Return only ifcalculator plugin is enabled
boxobjectlist of parameters of the bounding box for this face
probabilityfloatprobability that a found face is actually a face
x_max, y_max, x_min, y_minintegercoordinates of the frame containing the face
landmarksarraylist of the coordinates of the frame containing the face-landmarks. Return only iflandmarks plugin is enabled
similarityfloatsimilarity between this face and the face on the source image
execution_timeobjectexecution time of all plugins
plugins_versionsobjectcontains information about plugin versions

Example:

letsource_image_location="../images/boy.jpg";lettarget_image_location="../images/team.jpg";letoptions={limit:0,det_prob_threshold:0.8,face_plugins:"calculator,age,gender,landmarks",status:"true"}verificationService.verify(source_image_location,target_image_location,options).then(response=>{console.log(JSON.stringify(response));}).catch(error=>{console.log(`Oops! There is problem with recognizing image${error}`)})

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

After creating your first contributing pull request, you will receive a request to sign our Contributor License Agreement by commenting your pull request with a special message.

Report Bugs

Please report any bugshere.

If you are reporting a bug, please specify:

  • Your operating system name and version
  • Any details about your local setup that might be helpful in troubleshooting
  • Detailed steps to reproduce the bug

Submit Feedback

The best way to send us feedback is to file an issue athttps://github.com/exadel-inc/compreface-javascript-sdk/issues.

If you are proposing a feature, please:

  • Explain in detail how it should work.
  • Keep the scope as narrow as possible to make it easier to implement.

License info

CompreFace JS SDK is open-source facial recognition SDK released under theApache 2.0 license.


[8]ページ先頭

©2009-2025 Movatter.jp