Source: tfsdk.js

  1. "use strict";
  3. const FFI = require("ffi-napi");
  4. const Ref = require("ref-napi");
  5. const ArrayType = require("ref-array-di")(Ref);
  6. const StructType = require("ref-struct-di")(Ref);
  8. class TFSDKDataChecker {
  9.   constructor() {
  10.     this.exception = false;
  11.     this.consoleError = false;
  12.   }
  13.   throw(message) {
  14.     if (this.exception) throw new Error(message);
  15.     if (this.consoleError) console.error(message);
  16.     return 6;
  17.   }
  18.   isString(value) {
  19.     return typeof value === "string" || value instanceof String;
  20.   }
  21.   isNumber(value) {
  22.     return typeof value === "number" && isFinite(value);
  23.   }
  24.   isArray(value) {
  25.     return value && typeof value === "object" && value.constructor === Array;
  26.   }
  27.   isObject(value) {
  28.     return value && typeof value === "object" && value.constructor === Object;
  29.   }
  30.   isNull(value) {
  31.     return value === null;
  32.   }
  33.   isUndefined(value) {
  34.     return typeof value === "undefined";
  35.   }
  36.   isBoolean(value) {
  37.     return typeof value === "boolean";
  38.   }
  39. }
  41. module.exports = class TFSDK {
  42.   constructor(options = {}, libPath = "./artifacts/") {
  43.     this.dc = new TFSDKDataChecker();
  45.     this.int = Ref.types.int;
  46.     this.IntArray = ArrayType(this.int);
  48.     const libType = "void";
  49.     const libPtr = Ref.refType(libType);
  51.     this.licensed = false;
  53.     this.imageProperties = StructType({
  54.       width: Ref.types.uint,
  55.       height: Ref.types.uint,
  56.       channels: Ref.types.uint,
  57.       isGpuImage: Ref.types.bool,
  58.     });
  59.     const ImagePropertiesPtr = Ref.refType(this.imageProperties);
  61.     this.lib = FFI.Library(`${libPath}/libtfsdk`, {
  62.       TFSDK__create: [libPtr, []],
  63.       TFSDK__json_createWithConfigurationOptions: [libPtr, ["string"]],
  64.       TFSDK__destory: ["void", [libPtr]],
  66.       TFSDK__setLicense: ["bool", [libPtr, "string"]],
  67.       TFSDK__isLicensed: ["bool", [libPtr]],
  68.       TFSDK__getVersion: ["double", [libPtr]],
  70.       TFSDK__setImage: ["int", [libPtr, this.IntArray, "int", "int", "int"]],
  71.       TFSDK__setImageFromFile: ["int", [libPtr, "string"]],
  72.       TFSDK__estimateFaceImageQuality: [this.IntArray, [libPtr, "double"]],
  74.       TFSDK__json_detectObjects: ["string", [libPtr]],
  75.       TFSDK__json_detectLargestFace: ["string", [libPtr]],
  76.       TFSDK__json_detectFaces: ["string", [libPtr]],
  77.       TFSDK__json_getLargestFaceFeatureVector: ["string", [libPtr]],
  78.       TFSDK__json_getSimilarity: ["string", [libPtr, "string", "string"]],
  79.       TFSDK__json_estimateHeadOrientation: ["string", [libPtr, "string"]],
  80.       // TFSDK__json_detectBlink: ["string", [libPtr]],
  81.       TFSDK__json_getFaceLandmarks: ["string", [libPtr, "string"]],
  82.       TFSDK__createDatabaseConnection: ["int", [libPtr, "string"]],
  83.       TFSDK__createLoadCollection: ["int", [libPtr, "string"]],
  84.       TFSDK__json_enrollFaceprint: ["string", [libPtr, "string", "string"]],
  85.       TFSDK__removeByUUID: ["int", [libPtr, "string"]],
  86.       TFSDK__removeByIdentity: ["int", [libPtr, "string"]],
  87.       TFSDK__json_identifyTopCandidate: [
  88.         "string",
  89.         [libPtr, "string", Ref.types.float],
  90.       ],
  91.       TFSDK__getImageProperties: ["string", [libPtr, ImagePropertiesPtr]],
  92.       TFSDK__getFaceLandmarks: ["string", [libPtr, "string"]],
  93.       // TFSDK__json_getFaceLandmarks: ["string", [libPtr, "string"]],
  95.       TFSDK__json_getFaceFeatureVector: ["string", [libPtr, "string"]],
  96.       TFSDK__detectActiveSpoof: ["string", [libPtr, "string", "string"]],
  97.       TFSDK__checkSpoofImageFaceSize: ["string", [libPtr, "string", "string"]],
  98.       TFSDK__json_detectMask: ["string", [libPtr, "string"]],
  99.       TFSDK__json_detectGlasses: ["string", [libPtr, "string"]],
  100.       TFSDK__extractAlignedFace: [this.IntArray, [libPtr, "string"]],
  101.     });
  103.     this.ptr = Ref.alloc(libPtr);
  105.     if (options && Object.keys(options).length === 0) {
  106.       this.ptr = this.lib.TFSDK__create();
  107.     } else {
  108.       this.ptr = this.lib.TFSDK__json_createWithConfigurationOptions(
  109.         JSON.stringify(options)
  110.       );
  111.     }
  112.   }
  113.   getColorSpace(bitmap) {
  114.     if (!this.dc.isObject(bitmap) || !this.dc.isBoolean(bitmap._rgba))
  115.       return this.dc.throw(`bitmap: must be a object, ${bitmap} was given`);
  116.     if (bitmap._rgba === true) {
  117.       return 3;
  118.     } else {
  119.       return 0;
  120.     }
  121.   }
  122.   /**
  123.    * Return the text description of the error code
  124.    * @function getError
  125.    * @param {string} error code as number
  126.    * @returns {string} the description of error code
  127.    */
  128.   getError(error) {
  129.     if (!this.dc.isNumber(error))
  130.       return this.dc.throw(`error: must be a number, ${error} was given`);
  131.     const ErrorCode = [
  132.       "NO_ERROR",
  133.       "INVALID_LICENSE",
  134.       "FILE_READ_FAIL",
  135.       "UNSUPPORTED_IMAGE_FORMAT",
  136.       "UNSUPPORTED_MODEL",
  137.       "NO_FACE_IN_FRAME",
  138.       "FAILED",
  139.       "COLLECTION_CREATION_ERROR",
  140.       "DATABASE_CONNECTION_ERROR",
  141.       "ENROLLMENT_ERROR",
  142.     ];
  143.     return ErrorCode[error];
  144.   }
  146.   /**
  147.    * Sets and validates the given license token. Need to call this method
  148.    * before being able to use the SDK.
  149.    * @function setLicense
  150.    *
  151.    * @param {string} token the license token (if you do not have this talk to
  152.    *        support@trueface.ai).
  153.    * @returns {boolean} Whether the given license token is valid.
  154.    */
  155.   setLicense(license) {
  156.     if (!this.dc.isString(license))
  157.       return this.dc.throw(`license: must be a string, ${license} was given`);
  158.     const res = this.lib.TFSDK__setLicense(this.ptr, license);
  159.     this.licensed = res;
  160.     return res;
  161.   }
  162.   /**
  163.    * Checks whether the given license token is valid and you can use
  164.    * the SDK.
  165.    *
  166.    * @function isLicensed
  167.    * @returns {boolean} Whether the given license token is valid.
  168.    */
  169.   isLicensed() {
  170.     return this.licensed;
  171.   }
  172.   /**
  173.    * Gets the version-build number of the SDK.
  174.    * @function getVersion
  175.    *
  176.    * @returns {string} Version Number.
  177.    */
  178.   getVersion() {
  179.     return this.lib.TFSDK__getVersion(this.ptr);
  180.   }
  181.   /**
  182.    * Set the image that is processed by the other methods.
  183.    * @function setImage
  184.    *
  185.    * @param {Buffer} image an 8-bit decoded image array, in the CPU memory or the GPU memory.
  186.    * @param {number} width the image width.
  187.    * @param {number} height the image height.
  188.    * @param {number} color the image color model, see ColorCode.
  189.    *
  190.    * @returns {object} error code, see {@link exports.getError}ErrorCode.
  191.    * Note, it is highly encouraged to check the return value from setImage before proceeding.
  192.    * If the license is invalid, the INVALID_LICENSE error will be returned.
  193.    */
  194.   setImage(data, width, height, color) {
  195.     if (!this.dc.isArray(data))
  196.       return this.dc.throw(`data: must be an array, ${data} was given`);
  197.     if (!this.dc.isNumber(width))
  198.       return this.dc.throw(`width: must be a number, ${width} was given`);
  199.     if (!this.dc.isNumber(height))
  200.       return this.dc.throw(`height: must be a number, ${height} was given`);
  201.     if (!this.dc.isNumber(color))
  202.       return this.dc.throw(`color: must be a number, ${color} was given`);
  204.     const arr = new this.IntArray(data.length);
  205.     for (const [i, v] of data.entries()) arr[i] = v;
  206.     return this.lib.TFSDK__setImage(this.ptr, arr, width, height, color);
  207.   }
  208.   /**
  209.    * Set the image from a image file
  210.    * @function setImageFromFile
  211.    *
  212.    * @param {string} path image's path
  213.    * @returns {object} errorCode if there's error from set image
  214.    */
  215.   setImageFromFile(path) {
  216.     if (!this.dc.isString(path))
  217.       return this.dc.throw(`path: must be a string, ${path} was given`);
  218.     return this.lib.TFSDK__setImageFromFile(this.ptr, path);
  219.   }
  220.   /**
  221.    * Detect and identify all the objects in the image.
  222.    * @function detectObjects
  223.    * @returns {object} errorCode, see ErrorCode.
  224.    *
  225.    * @returns {object} array of object description, object location in the image.
  226.    */
  227.   detectObjects() {
  228.     const result = this.lib.TFSDK__json_detectObjects(this.ptr);
  229.     return JSON.parse(result);
  230.   }
  231.   /**
  232.    * Detect all the faces in the image. This method has a small false positive rate.
  233.    * To reduce the false positive rate to near zero, filter out faces with score lower than 0.90.
  234.    * Alternatively, you can use the `Trueface::FaceDetectionFilter`
  235.    * configuration option to filter the detected faces.
  236.    *
  237.    * The face detector has a detection scale range of about 5 octaves. \ref ConfigurationOptions.smallestFaceHeight
  238.    * determines the lower of the detection scale range. E.g., setting \ref ConfigurationOptions.smallestFaceHeight to
  239.    * 40 pixels yields the detection scale range of ~40 pixels to 1280 (=40x2^5) pixels.
  240.    *
  241.    * @function detectFaces
  242.    * @returns {object} faceBoxAndLandmarks a vector of \ref FaceBoxAndLandmarks representing each of the detected faces.
  243.    * If not faces are found, the vector will be empty. The detected faces are sorted in order of descending face score.
  244.    *
  245.    * @returns {object} error code, see ErrorCode.
  246.    */
  247.   detectFaces() {
  248.     const result = this.lib.TFSDK__json_detectFaces(this.ptr);
  249.     return JSON.parse(result);
  250.   }
  251.   /**
  252.    * Detect the largest face in the image.
  253.    * This method has a small false positive rate.
  254.    * To reduce the false positive rate to near zero, filter out faces with score lower than 0.90.
  255.    * Alternatively, you can use the `Trueface::FaceDetectionFilter`
  256.    * configuration option to filter the detected faces.
  257.    * See detectFaces() for the detection scale range.
  258.    *
  259.    * @function detectLargestFace
  260.    * @returns {object} faceBoxAndLandmarks the FaceBoxAndLandmarks containing the landmarks and bounding box
  261.    * of the largest detected face in the image.
  262.    * @returns {boolean} found whether a face was found in the image.
  263.    *
  264.    * @returns {object} error code, see ErrorCode.
  265.    */
  266.   detectLargestFace() {
  267.     const result = this.lib.TFSDK__json_detectLargestFace(this.ptr);
  268.     return JSON.parse(result);
  269.   }
  270.   /**
  271.    * Detect the largest face in the image and return its feature
  272.    * vector.
  273.    *
  274.    * @function getLargestFaceFeatureVector
  275.    * @returns {object} Faceprint object which will contain
  276.    *             the face feature vector.
  277.    * @returns {boolean} foundFace indicates if a face was detected in the image.
  278.    * If no face was detected, then the faceprint will be empty.
  279.    *
  280.    * @returns {object} error code, see ErrorCode{@link getError}.
  281.    */
  282.   getLargestFaceFeatureVector() {
  283.     const result = this.lib.TFSDK__json_getLargestFaceFeatureVector(this.ptr);
  284.     return JSON.parse(result);
  285.   }
  286.   /**
  287.    * Compute the similarity between two feature vectors, or how
  288.    * similar two faces are.
  289.    *
  290.    * @function getSimilarity
  291.    * @param {object} faceprint1 the first Faceprint to be compared.
  292.    * @param {object} faceprint2 the second Faceprint to be compared.
  293.    * @returns {number} matchProbability the probability the two face feature vectors are a match.
  294.    * @returns {number} similarityMeasure the computed similarity measure.
  295.    *
  296.    * @returns error code, see ErrorCode.
  297.    */
  298.   getSimilarity(faceprint1, faceprint2) {
  299.     if (!this.dc.isObject(faceprint1))
  300.       return this.dc.throw(
  301.         `faceprint1: must be a object, ${faceprint1} was given`
  302.       );
  303.     if (!this.dc.isObject(faceprint2))
  304.       return this.dc.throw(
  305.         `faceprint2: must be a object, ${faceprint2} was given`
  306.       );
  307.     const result = this.lib.TFSDK__json_getSimilarity(
  308.       this.ptr,
  309.       JSON.stringify(faceprint1),
  310.       JSON.stringify(faceprint2)
  311.     );
  312.     return JSON.parse(result);
  313.   }
  314.   /**
  315.    * Estimate the head pose.
  316.    *
  317.    * @function estimateHeadOrientation
  318.    * @param {object} faceBoxAndLandmarks FaceBoxAndLandmarks returned by detectFaces() or detectLargestFace().
  319.    *
  320.    * @returns {object} <b>yaw</b> the rotation angle around the image's vertical axis, in radians. <b>pitch</b> the rotation angle around the image's transverse axis, in radians. <b>roll<b> the rotation angle around the image's longitudinal axis, in radians.
  321.    * @returns {object} error code, see ErrorCode.
  322.    */
  323.   estimateHeadOrientation(face) {
  324.     if (!this.dc.isObject(face))
  325.       return this.dc.throw(`face: must be a object, ${face} was given`);
  326.     const result = this.lib.TFSDK__json_estimateHeadOrientation(
  327.       this.ptr,
  328.       JSON.stringify(face)
  329.     );
  330.     return JSON.parse(result);
  331.   }
  332.   /*
  333.   detectBlink() {
  334.     const result = this.lib.TFSDK__json_detectBlink(this.ptr);
  335.     return JSON.parse(result);
  336.   }
  337.   */
  338.   /**
  339.    *
  340.    * Create a connection to a new or existing database.
  341.    * If the database does not exist, a new one will be created with the provided name.
  342.    * If the `Trueface::DatabaseManagementSystem::NONE` memory only
  343.    * configuration option is selected, this function does not need to be called (and is a harmless no-op).
  344.    *
  345.    *
  346.    * If `Trueface::DatabaseManagementSystem::SQLITE` is selected, this should be the filepath to the database.
  347.    * ex. "/myPath/myDatabase.db".
  348.    * If `Trueface::DatabaseManagementSystem::POSTGRESQL`
  349.    * is selected, this should be a database connection string.
  350.    * <a href="https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS">Here</a>
  351.    * is a list of all supported PostgreSQL connection parameters.
  352.    * @function createDatabaseConnection
  353.    * @example
  354.    * "hostaddr=192.168.1.0 port=5432 dbname=face_recognition user=postgres password=my_password"
  355.    * @example
  356.    * "host=localhost port=5432 dbname=face_recognition user=postgres password=m_password"
  357.    * To enable ssl, add "sslmode=require" to the connection string.
  358.    *
  359.    * @param {string} databaseConnectionString
  360.    *
  361.    * @returns {object} error code, see ErrorCode.
  362.    */
  363.   createDatabaseConnection(databaseConnectionString) {
  364.     if (!this.dc.isString(databaseConnectionString))
  365.       return this.dc.throw(
  366.         `databaseConnectionString: must be a string, ${databaseConnectionString} was given`
  367.       );
  368.     return this.lib.TFSDK__createDatabaseConnection(
  369.       this.ptr,
  370.       databaseConnectionString
  371.     );
  372.   }
  373.   /**
  374.    * Create a new collection, or load data from an existing collection into memory (RAM) if one with the
  375.    * provided name already exists in the database.
  376.    * Equivalent to calling createCollection() then loadCollection().
  377.    *
  378.    * @function createLoadCollection
  379.    * @param {string} collectionName the name of the collection.
  380.    *
  381.    * @returns {object} error code, see ErrorCode.
  382.    */
  383.   createLoadCollection(collectionName) {
  384.     if (!this.dc.isString(collectionName))
  385.       return this.dc.throw(
  386.         `collectionName: must be a string, ${collectionName} was given`
  387.       );
  388.     return this.lib.TFSDK__createLoadCollection(this.ptr, collectionName);
  389.   }
  390.   /**
  391.    * Enroll a Faceprint for a new or existing identity in the collection.
  392.    *
  393.    * @function enrollFaceprint
  394.    * @param {object} faceprint the Faceprint to enroll in the collection.
  395.    * @param {string} identity the identity corresponding to the Faceprint.
  396.    * @returns {string} UUID universally unique identifier corresponding to the Faceprint.
  397.    *
  398.    * @returns {object} error code, see ErrorCode.
  399.    */
  400.   enrollFaceprint(faceprint, identity) {
  401.     if (!this.dc.isObject(faceprint))
  402.       return this.dc.throw(
  403.         `faceprint: must be a object, ${faceprint} was given`
  404.       );
  405.     if (!this.dc.isString(identity))
  406.       return this.dc.throw(`identity: must be a string, ${identity} was given`);
  407.     const result = this.lib.TFSDK__json_enrollFaceprint(
  408.       this.ptr,
  409.       JSON.stringify(faceprint),
  410.       identity
  411.     );
  412.     return JSON.parse(result);
  413.   }
  414.   /**
  415.    * Remove a Faceprint from the collection using the UUID.
  416.    *
  417.    * @function removeByUUID
  418.    * @param {string} UUID the universally unique identifier returned by enrollFaceprint().
  419.    *
  420.    * @returns {object} error code, see ErrorCode.
  421.    */
  422.   removeByUUID(UUID) {
  423.     if (!this.dc.isString(UUID))
  424.       return this.dc.throw(`UUID: must be a string, ${UUID} was given`);
  425.     return this.lib.TFSDK__removeByUUID(this.ptr, UUID);
  426.   }
  427.   /**
  428.    * Remove all Faceprints in the collection corresponding to the identity.
  429.    *
  430.    * @function removeByIdentity
  431.    * @param {string} identity the identity to remove from the collection.
  432.    * @returns {number} numFaceprintsRemoved the the number of Faceprint which were removed for that identity.
  433.    *
  434.    * @returns {object} error code, see ErrorCode.
  435.    */
  436.   removeByIdentity(identity) {
  437.     if (!this.dc.isString(UUID))
  438.       return this.dc.throw(`identity: must be a string, ${identity} was given`);
  439.     return this.lib.TFSDK__removeByIdentity(this.ptr, identity);
  440.   }
  441.   /**
  442.    * Get the top match Candidate in the collection and the corresponding similarity score and match probability.
  443.    *
  444.    * @function identifyTopCandidate
  445.    * @param {object} faceprint the Faceprint to be identified.
  446.    * @param {number }[in] threshold the similarity score threshold above which it is considered a match.
  447.    * Higher thresholds may result in faster queries.
  448.    * Refer to our <a href="https://docs.trueface.ai/ROC-Curves-d47d2730cf0a44afacb39aae0ed1b45a">ROC curves</a> when selecting a threshold.
  449.    *
  450.    * @returns {string} candidate the top match Candidate.
  451.    * @returns {boolean} found set to true if a match is found.
  452.    *
  453.    * @returns {object} error code, see ErrorCode.
  454.    */
  455.   identifyTopCandidate(faceprint, threshold = 0.3) {
  456.     if (!this.dc.isObject(faceprint))
  457.       return this.dc.throw(
  458.         `faceprint: must be an object, ${faceprint} was given`
  459.       );
  460.     if (!this.dc.isNumber(threshold))
  461.       return this.dc.throw(
  462.         `threshold: must be a float, ${threshold} was given`
  463.       );
  464.     const result = this.lib.TFSDK__json_identifyTopCandidate(
  465.       this.ptr,
  466.       JSON.stringify(faceprint),
  467.       threshold
  468.     );
  469.     // console.log("result", result);
  470.     return JSON.parse(result);
  471.   }
  472.   /**
  473.    * Get properties of the image set by setImage().
  474.    *
  475.    * @function getImageProperties
  476.    * @returns {object} imageProperties the image properties
  477.    */
  478.   getImageProperties() {
  479.     // need to use json format
  480.     /*
  481.     struct ImageProperties {
  482.         unsigned int width = 0;
  483.         unsigned int height = 0;
  484.         unsigned int channels = 0;
  485.         bool isGpuImage = false;
  486.     };
  487.     assert(imageProperties.height == 200);
  488.     assert(imageProperties.width == 192);
  489.     assert(imageProperties.channels == 3);
  490.     assert(imageProperties.isGpuImage == false);
  491.     */
  493.     /* const ImageProperties = StructType({
  494.       width: Ref.types.uint,
  495.       height: Ref.types.uint,
  496.       channels: Ref.types.uint,
  497.       isGpuImage: Ref.types.bool
  498.     }); */
  500.     const ip = new this.imageProperties({
  501.       width: 0,
  502.       height: 0,
  503.       channels: 0,
  504.       isGpuImage: false,
  505.     });
  506.     this.lib.TFSDK__getImageProperties(this.ptr, ip.ref());
  507.     return ip;
  508.   }
  509.   /**
  510.    * Obtain the 106 face landmarks.
  511.    *
  512.    * @function getFaceLandmarks
  513.    * @param {object} faceBoxAndLandmarks FaceBoxAndLandmarks returned by {@link detectFaces()} or {@link detectLargestFace()}.
  514.    * @returns {object} landmarks an array of 106 face landmark points.
  515.    *
  516.    * @returns {object} error code, see ErrorCode.
  517.    */
  518.   getFaceLandmarks(faceBoxAndLandmarks) {
  519.     if (!this.dc.isObject(faceBoxAndLandmarks))
  520.       return this.dc.throw(
  521.         `faceBoxAndLandmarks: must be an object, ${faceBoxAndLandmarks} was given`
  522.       );
  523.     const result = this.lib.TFSDK__json_getFaceLandmarks(
  524.       this.ptr,
  525.       JSON.stringify(faceBoxAndLandmarks)
  526.     );
  527.     return JSON.parse(result);
  528.   }
  529.   /**
  530.    * Extract the face feature vector from an aligned face image.
  531.    *
  532.    * @function getFaceFeatureVector
  533.    * @param {object} alignedFaceImage buffer returned by extractAlignedFace().
  534.    * Face image must be have size of 112x112 pixels (default extractAlignedFace() margin and scale values).
  535.    * @param {object} faceprint a Faceprint object which will contain
  536.    *             the face feature vector.
  537.    *
  538.    * @returns {object} error code, see ErrorCode.
  539.    */
  540.   getFaceFeatureVector(faceBoxAndLandmarks) {
  541.     if (!this.dc.isObject(faceBoxAndLandmarks))
  542.       return this.dc.throw(
  543.         `faceBoxAndLandmarks: must be an object, ${faceBoxAndLandmarks} was given`
  544.       );
  545.     const result = this.lib.TFSDK__json_getFaceFeatureVector(
  546.       this.ptr,
  547.       JSON.stringify(faceBoxAndLandmarks)
  548.     );
  549.     return JSON.parse(result);
  550.   }
  551.   /**
  552.    * Detect the largest face in the image and return its feature
  553.    * vector.
  554.    *
  555.    * @function getLargestFaceFeatureVector
  556.    * @returns {object} faceprint a Faceprint object which will contain
  557.    *             the face feature vector.
  558.    * @returns {object} foundFace indicates if a face was detected in the image.
  559.    * If no face was detected, then the faceprint will be empty.
  560.    *
  561.    * @returns {object} error code, see ErrorCode.
  562.    */
  563.   getLargestFaceFeatureVector() {
  564.     const result = this.lib.TFSDK__json_getLargestFaceFeatureVector(this.ptr);
  565.     return JSON.parse(result);
  566.   }
  567.   /**
  568.    *  Align the the detected face to be optimized for passing to
  569.    *  feature extraction. If using the face chip with Trueface algorithms (ex face recognition),
  570.    *  do not change the default margin and scale values.
  571.    *
  572.    * @function extractAlignedFace
  573.    * @param {object} faceBoxAndLandmarks the FaceBoxAndLandmarks returned
  574.    *            by detectLargestFace() or detectFaces().
  575.    * @returns {object} faceImage the pointer to a uint8_t buffer of
  576.    *             112x112x3 = 37632 bytes (when using default margins and scale).
  577.    *             The aligned face image is stored in this buffer.
  578.    *             The memory must be allocated by the user.
  579.    *             If using non-default margin and scale
  580.    *             (again, non-standard face chip sizes will not work with Trueface algorithms),
  581.    *             the faceImage will be of size:
  582.    *             width = int((112+marginLeft+marginRight)*scale),
  583.    *             height = int((112+marginTop+marginBottom)*scale),
  584.    *             and therefore the buffer size is computed as:
  585.    *             width * height * 3
  586.    *
  587.    * @param {number} marginLeft adds a margin to the left side of the face chip.
  588.    * @param {number} marginTop adds a margin to the top side of the face chip.
  589.    * @param {number} marginRight adds a margin to the right side of the face chip.
  590.    * @param {number} marginBottom adds a margin to the bottom side of the face chip.
  591.    * @param {number} scale changes the scale of the face chip.
  592.    *
  593.    * @returns error code, see ErrorCode.
  594.    */
  595.   extractAlignedFace(faceBoxAndLandmarks) {
  596.     if (!this.dc.isObject(faceBoxAndLandmarks))
  597.       return this.dc.throw(
  598.         `faceBoxAndLandmarks: must be an object, ${faceBoxAndLandmarks} was given`
  599.       );
  600.     const result = this.lib.TFSDK__extractAlignedFace(
  601.       this.ptr,
  602.       JSON.stringify(faceBoxAndLandmarks)
  603.     );
  604.     return result;
  605.   }
  606.   /**
  607.    * Estimate the quality of the face image for recognition.
  608.    *
  609.    * @function estimateFaceImageQuality
  610.    * @param {array} alignedFaceImage The array returned by extractAlignedFace().
  611.    * @returns {number} quality a value between 0 to 1, 1 being prefect quality for recognition.
  612.    * We suggest using a threshold of 0.999 as a filter for enrollment images.
  613.    *
  614.    * @returns {object} error code, see ErrorCode.
  615.    */
  616.   estimateFaceImageQuality(alignedFaceImage) {
  617.     if (!this.dc.isArray(alignedFaceImage))
  618.       return this.dc.throw(
  619.         `alignedFaceImage: must be a array, ${alignedFaceImage} was given`
  620.       );
  621.     const arr = new this.IntArray(alignedFaceImage.length);
  622.     for (const [i, v] of alignedFaceImage.entries()) arr[i] = v;
  623.     return this.lib.TFSDK__estimateFaceImageQuality(this.ptr, arr);
  624.   }
  625.   /**
  626.    * Detect if there is a presentation attack attempt.
  627.    * Must call checkSpoofImageFaceSize() on both input faces before calling this function.
  628.    *
  629.    * @function detectActiveSpoof
  630.    * @param {object} nearFaceLandmarks The face landmarks of the near face, obtained by calling getFaceLandmarks().
  631.    * @param {object} farFaceLandmarks The face landmarks of the far face, obtained by calling getFaceLandmarks().
  632.    * @returns {number} spoofScore The output spoof score.
  633.    * If the spoof score is above the threshold, then it is classified as a real face.
  634.    * If the spoof score is below the threshold, then it is classified as a fake face.
  635.    * @returns {boolean} spoofPrediction The predicted spoof result, using a spoofScore threshold of 1.05.
  636.    *
  637.    * @returns {object} error code, see ErrorCode.
  638.    */
  639.   detectActiveSpoof(nearFaceLandmarks, farFaceLandmarks) {
  640.     if (!this.dc.isObject(nearFaceLandmarks))
  641.       return this.dc.throw(
  642.         `nearFaceLandmarks: must be an object, ${nearFaceLandmarks} was given`
  643.       );
  644.     if (!this.dc.isObject(farFaceLandmarks))
  645.       return this.dc.throw(
  646.         `nearFaceLandmarks: must be an object, ${farFaceLandmarks} was given`
  647.       );
  648.     const result = this.lib.TFSDK__json_detectActiveSpoof(
  649.       this.ptr,
  650.       JSON.stringify(nearFaceLandmarks),
  651.       JSON.stringify(farFaceLandmarks)
  652.     );
  653.     return JSON.parse(result);
  654.   }
  655.   /**
  656.    * Ensures that the face size meets the requirements for active spoof.
  657.    * Must check return value of function!
  658.    * Active spoof works by analyzing the way a persons face changes as they move closer to a camera.
  659.    * The active spoof solution therefore expects the face a certain distance from the camera.
  660.    * **In the far image, the face should be about 18 inches from the camera, while in the near image,
  661.    * the face should be 7-8 inches from the camera.**
  662.    * This function must be called before calling detectActiveSpoof().
  663.    *
  664.    * @function checkSpoofImageFaceSize
  665.    * @param {object} faceBoxAndLandmarks The face on which to run active spoof detection.
  666.    * @param {object} imageProperties The properties of the image, obtained from getImageProperties().
  667.    * @param {object} activeSpoofStage The stage of the image, either near stage or far stage.
  668.    *
  669.    * @returns {object} error code, see ErrorCode.
  670.    * If `ErrorCode::NO_ERROR` is returned, then the image is eligible for active spoof detection.
  671.    * If `ErrorCode::FACE_TOO_CLOSE` or `ErrorCode::FACE_TOO_FAR` is returned, the image is not eligible for active spoof detection.
  672.    *
  673.    */
  674.   checkSpoofImageFaceSize(faceBoxAndLandmarks, imageProperties) {
  675.     if (!this.dc.isObject(faceBoxAndLandmarks))
  676.       return this.dc.throw(
  677.         `faceBoxAndLandmarks: must be an object, ${faceBoxAndLandmarks} was given`
  678.       );
  679.     if (!this.dc.isObject(imageProperties))
  680.       return this.dc.throw(
  681.         `imageProperties: must be an object, ${imageProperties} was given`
  682.       );
  683.     const result = this.lib.TFSDK__json_checkSpoofImageFaceSize(
  684.       this.ptr,
  685.       JSON.stringify(faceBoxAndLandmarks),
  686.       JSON.stringify(imageProperties)
  687.     );
  688.     return JSON.parse(result);
  689.   }
  690.   /**
  691.    * Detect whether the face in the image is wearing a mask or not
  692.    *
  693.    * @function detectMask
  694.    * @param {object} faceBoxAndLandmarks FaceBoxAndLandmarks returned by detectFaces() or detectLargestFace().
  695.    * @returns {boolean} result The predicted MaskLabel for face image.
  696.    *
  697.    * @returns {object} error code, see ErrorCode.
  698.    */
  699.   detectMask(faceBoxAndLandmarks) {
  700.     if (!this.dc.isObject(faceBoxAndLandmarks))
  701.       return this.dc.throw(
  702.         `faceBoxAndLandmarks: must be an object, ${faceBoxAndLandmarks} was given`
  703.       );
  704.     const result = this.lib.TFSDK__json_detectMask(
  705.       this.ptr,
  706.       JSON.stringify(faceBoxAndLandmarks)
  707.     );
  708.     return JSON.parse(result);
  709.   }
  710.   /**
  711.    * Detect whether the face in the image is wearing any type of eye glasses or not
  712.    *
  713.    * @function detectGlasses
  714.    * @param {object} faceBoxAndLandmarks FaceBoxAndLandmarks returned by detectFaces() or detectLargestFace().
  715.    * @param {boolean} result The predicted GlassesLabel for face image.
  716.    * @param {score} glassesScore The glasses score for this image. This can be used for setting custom thresholds that work
  717.    * better for the use case. By default, we use a glasses score greater than 0.0 to determine that glasses were detected.
  718.    *
  719.    * @returns {object} error code, see ErrorCode.
  720.    */
  721.   detectGlasses(faceBoxAndLandmarks) {
  722.     if (!this.dc.isObject(faceBoxAndLandmarks))
  723.       return this.dc.throw(
  724.         `faceBoxAndLandmarks: must be an object, ${faceBoxAndLandmarks} was given`
  725.       );
  726.     const result = this.lib.TFSDK__json_detectGlasses(
  727.       this.ptr,
  728.       JSON.stringify(faceBoxAndLandmarks)
  729.     );
  730.     return JSON.parse(result);
  731.   }
  732. };