@regulaforensics/face-sdk 6.5.67-beta → 6.5.84-beta

package/www/types/match_faces/compared_faces_pair.d.ts

@@ -0,0 +1,36 @@
+import { ComparedFace } from './compared_face'
+import { MatchFacesException } from './match_faces_exception'
+
+/**
+ * Represents a result of the {@link ComparedFace} attempt to compare input images.
+ */
+export class ComparedFacesPair {
+    /**
+     * The first face in the comparison pair.
+     */
+    get first(): ComparedFace
+
+    /**
+     * The second face in the comparison pair.
+     */
+    get second(): ComparedFace
+
+    /**
+     * Similarity of the faces pair. Floating point value from 0 to 1.
+     */
+    get similarity(): number
+
+    /**
+     * The raw value returned by the service without applying any thresholds or comparison rules.
+     * The value shows the degree of similarity of compared faces, the lower - the more similar, and vice versa less similar.
+     * The `score` is used in conjunction with the input image `imageType` to evaluate `similarity`.
+     */
+    get score(): number
+
+    /**
+     * The error describes a failed pair comparison and contains {@link MatchFacesErrorCode} codes.
+     */
+    get error(): MatchFacesException | null
+
+    private constructor()
+}

package/www/types/match_faces/compared_faces_split.d.ts

@@ -0,0 +1,8 @@
+import { ComparedFacesPair } from './compared_faces_pair'
+
+export class ComparedFacesSplit {
+    get matchedFaces(): Array<ComparedFacesPair>
+    get unmatchedFaces(): Array<ComparedFacesPair>
+
+    private constructor()
+}

package/www/types/match_faces/match_faces_backend_exception.d.ts

@@ -0,0 +1,6 @@
+export class MatchFacesBackendException {
+    get code(): number
+    get message(): string
+
+    private constructor()
+}

package/www/types/match_faces/match_faces_config.d.ts

@@ -0,0 +1,14 @@
+export class MatchFacesConfig {
+    processingMode: ProcessingMode
+
+    constructor(
+        params?: {
+            processingMode?: ProcessingMode
+        }
+    )
+}
+
+export enum ProcessingMode {
+    ONLINE,
+    OFFLINE,
+}

package/www/types/match_faces/match_faces_detection.d.ts

@@ -0,0 +1,30 @@
+import { MatchFacesImage } from './match_faces_image'
+import { MatchFacesDetectionFace } from './match_faces_detection_face'
+import { MatchFacesException } from './match_faces_exception'
+
+/**
+ * Represents detection results on an input image as a part of {@link MatchFacesResponse}.
+ */
+export class MatchFacesDetection {
+    /**
+     * The index to the input image in the input array provided to the request.
+     */
+    get imageIndex(): number
+
+    /**
+     * The input image used for comparison operation.
+     */
+    get image(): MatchFacesImage
+
+    /**
+     * The array of faces detected on the image.
+     */
+    get faces(): Array<MatchFacesDetectionFace>
+
+    /**
+     * The error describes a failed face detection and contains {@link MatchFacesErrorCode} codes.
+     */
+    get error(): MatchFacesException | null
+
+    private constructor()
+}

package/www/types/match_faces/match_faces_detection_face.d.ts

@@ -0,0 +1,43 @@
+import { Point } from '../image_params/point'
+import { Rect } from '../image_params/rect'
+
+/**
+ * Represents face detection information as a part of {@link MatchFacesResponse}.
+ */
+export class MatchFacesDetectionFace {
+    /**
+     * The index of the face detection object in the array of detections.
+     */
+    get faceIndex(): number
+
+    /**
+     * Main coordinates of the detected face (eyes, nose, lips, ears and etc.).
+     */
+    get landmarks(): Array<Point>
+
+    /**
+     * Rectangular area of the detected face in the original image.
+     */
+    get faceRect(): Rect
+
+    /**
+     * Rotation is measured counterclockwise in degrees, with zero indicating
+     * that a line drawn between the eyes is horizontal relative to the image orientation.
+     */
+    get rotationAngle(): number | null
+
+    /**
+     * Coordinates of the rectangle with the face on the original image prepared for the face crop.
+     * Requires {@link OutputImageCrop.returnOriginalRect} is set.
+     * Returns `null` if {@link OutputImageCrop.returnOriginalRect} isn't set.
+     */
+    get originalRect(): Rect | null
+
+    /**
+     * String image of the aligned and cropped portrait.
+     * Returned if {@link MatchFacesRequest.outputImageParams} is set or predefined scenario is used.
+     */
+    get crop(): string | null
+
+    private constructor()
+}

package/www/types/match_faces/match_faces_exception.d.ts

@@ -0,0 +1,21 @@
+import { MatchFacesBackendException } from './match_faces_backend_exception'
+
+export class MatchFacesException {
+    get code(): MatchFacesErrorCode
+    get message(): string
+    get underlyingError(): MatchFacesBackendException | null
+
+    private constructor()
+}
+
+export enum MatchFacesErrorCode {
+    IMAGE_EMPTY,
+    FACE_NOT_DETECTED,
+    LANDMARKS_NOT_DETECTED,
+    FACE_ALIGNER_FAILED,
+    DESCRIPTOR_EXTRACTOR_ERROR,
+    IMAGES_COUNT_LIMIT_EXCEEDED,
+    API_CALL_FAILED,
+    PROCESSING_FAILED,
+    NO_LICENSE
+}

package/www/types/match_faces/match_faces_image.d.ts

@@ -0,0 +1,34 @@
+import { ImageType } from '../face_capture/face_capture_image'
+
+/**
+ * This class represents the input image and its attributes for {@link MatchFacesRequest}.
+ */
+export class MatchFacesImage {
+    /**
+     * The underlying image.
+     */
+    get image(): string
+
+    /**
+     * The image type.
+     * The imageType influences matching results, therefore this field is required.
+     */
+    get imageType(): ImageType
+
+    /**
+     * Defines whether the comparison and detection should apply for all faces found on the image. Defaults to `false`.
+     * When set to `false`, only the most centered faces are compared and detected.
+     * Otherwise, all the faces are compared and detected.
+     */
+    get detectAll(): boolean
+    
+    get identifier(): string
+
+    constructor(
+        image: string,
+        imageType: ImageType,
+        params?: {
+            detectAll?: boolean
+        }
+    )
+}

package/www/types/match_faces/match_faces_request.d.ts

@@ -0,0 +1,34 @@
+import { MatchFacesImage } from './match_faces_image'
+import { OutputImageParams } from '../image_params/output_image_params'
+
+/**
+ * Compares two or more images with faces on them to find out the similarity of pairs.
+ * The request is used as a parameter to {@link FaceSDK.matchFaces}.
+ */
+export class MatchFacesRequest {
+    /**
+     * Images with faces to match.
+     */
+    get images(): Array<MatchFacesImage>
+
+    /**
+     * If set the uploaded image is processed according to the indicated settings.
+     */
+    get outputImageParams(): OutputImageParams | null
+
+    /**
+     * Defines tag that can be used in match faces processing. Defaults to `null`.
+     */
+    get tag(): string | null
+
+    get metadata(): Record<string, any> | null
+
+    constructor(
+        images: Array<MatchFacesImage>,
+        params?: {
+            outputImageParams?: OutputImageParams
+            tag?: string
+            metadata?: Record<string, any>
+        }
+    )
+}

package/www/types/match_faces/match_faces_response.d.ts

@@ -0,0 +1,27 @@
+import { ComparedFacesPair } from './compared_faces_pair'
+import { MatchFacesDetection } from './match_faces_detection'
+import { MatchFacesException } from './match_faces_exception'
+
+/**
+ * The response from the {@link MatchFacesRequest}.
+ */
+export class MatchFacesResponse {
+    /**
+     * Face comparison results with score and similarity values.
+     */
+    get results(): Array<ComparedFacesPair>
+
+    /**
+     * Face detection results for each given image.
+     */
+    get detections(): Array<MatchFacesDetection>
+
+    get tag(): string | null
+
+    /**
+     * The error describes a failed match faces request and contains {@link MatchFacesErrorCode} codes.
+     */
+    get error(): MatchFacesException | null
+
+    private constructor()
+}

package/www/types/person_database/edit_group_persons_request.d.ts

@@ -0,0 +1,8 @@
+export class EditGroupPersonsRequest {
+    constructor(
+        params: {
+            personIdsToAdd?: string[],
+            personIdsToRemove?: string[],
+        }
+    )
+}

package/www/types/person_database/image_upload.d.ts

@@ -0,0 +1,20 @@
+/**
+ * An object that represents uploaded image with its settings.
+ */
+export class ImageUpload {
+    /**
+     * Creates an object of {@link ImageUpload} using an image.
+     * 
+     * @param imageData - Image base64.
+     */
+    static withImageData(imageData: string): ImageUpload
+
+    /**
+     * Creates an object of {@link ImageUpload} using an image url.
+     * 
+     * @param imageUrl - Image url.
+     */
+    static withImageUrl(imageUrl: string): ImageUpload
+
+    private constructor()
+}

package/www/types/person_database/pageable_item_list.d.ts

@@ -0,0 +1,7 @@
+export class PageableItemList<T> {
+    get items(): T[] | null
+    get page(): number
+    get totalPages(): number
+
+    private constructor()
+}

package/www/types/person_database/person.d.ts

@@ -0,0 +1,33 @@
+
+/**
+ * A Person Database object that represents Person.
+ */
+export class Person {
+    /**
+     * Person name.
+     * Updatable field.
+     */
+    name: string
+
+    /**
+     * Person update date.
+     */
+    get updatedAt(): Date
+
+    /**
+     * Array if Group IDs Person belongs to.
+     */
+    get groups(): string[]
+
+    get id(): string
+
+    /**
+     * A free-form object containing Person extended attributes.
+     * Updatable field.
+     */
+    metadata: any
+
+    get createdAt(): Date
+
+    private constructor()
+}

package/www/types/person_database/person_database.d.ts

@@ -0,0 +1,95 @@
+import { Person } from './person'
+import { PersonImage } from './person_image'
+import { ImageUpload } from './image_upload'
+import { PageableItemList } from './pageable_item_list'
+import { PersonGroup } from './person_group'
+import { EditGroupPersonsRequest } from './edit_group_persons_request'
+import { SearchPersonRequest } from './search_person_request'
+import { SearchPerson } from './search_person'
+
+/**
+ * Represents Regula Database layer and is the entry point for Person Database operations.
+ */
+export class PersonDatabase {
+    createPerson(
+        name: string,
+        params?: {
+            groupIds?: string[],
+            metadata?: any,
+        }
+    ): Promise<[Person | null, string | null]>
+
+    updatePerson(person: Person): Promise<[boolean, string | null]>
+
+    deletePerson(personId: string): Promise<[boolean, string | null]>
+
+    getPerson(personId: string): Promise<[Person | null, string | null]>
+
+    addPersonImage(
+        personId: string,
+        image: ImageUpload
+    ): Promise<[PersonImage | null, string | null]>
+
+    deletePersonImage(
+        personId: string,
+        imageId: string
+    ): Promise<[boolean, string | null]>
+
+    getPersonImage(
+        personId: string,
+        imageId: string
+    ): Promise<[PersonImage | null, string | null]>
+
+    getPersonImages(personId: string): Promise<[PageableItemList<PersonImage>, string | null]>
+
+    getPersonImagesForPage(
+        personId: string,
+        page: number,
+        size: number
+    ): Promise<[PageableItemList<PersonImage>, string | null]>
+
+    createGroup(
+        name: string,
+        params?: {
+            metadata?: any,
+        }
+    ): Promise<[PersonGroup | null, string | null]>
+
+    updateGroup(group: PersonGroup): Promise<[boolean, string | null]>
+
+    editPersonsInGroup(
+        groupId: string,
+        request: EditGroupPersonsRequest
+    ): Promise<[boolean, string | null]>
+
+    deleteGroup(groupId: string): Promise<[boolean, string | null]>
+
+    getGroup(groupId: string): Promise<[PersonGroup | null, string | null]>
+
+    getGroups(): Promise<[PageableItemList<PersonGroup>, string | null]>
+
+    getGroupsForPage(
+        page: number,
+        size: number
+    ): Promise<[PageableItemList<PersonGroup>, string | null]>
+
+    getPersonGroups(personId: string): Promise<[PageableItemList<PersonGroup>, string | null]>
+
+    getPersonGroupsForPage(
+        personId: string,
+        page: number,
+        size: number
+    ): Promise<[PageableItemList<PersonGroup>, string | null]>
+
+    getPersonsInGroup(groupId: string): Promise<[PageableItemList<Person>, string | null]>
+
+    getPersonsInGroupForPage(
+        groupId: string,
+        page: number,
+        size: number
+    ): Promise<[PageableItemList<Person>, string | null]>
+
+    searchPerson(request: SearchPersonRequest): Promise<[SearchPerson[] | null, string | null]>
+
+    private constructor()
+}

package/www/types/person_database/person_group.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Person Database object that represents Group of {@link Person}.
+ */
+export class PersonGroup {
+    /**
+     * PersonGroup name.
+     * Updatable field.
+     */
+    name: string
+
+    get id(): string
+
+    /**
+     * A free-form object containing Group extended attributes.
+     * Updatable field.
+     */
+    metadata: any
+
+    get createdAt(): Date
+
+    private constructor()
+}

package/www/types/person_database/person_image.d.ts

@@ -0,0 +1,10 @@
+export class PersonImage {
+    get path(): string
+    get url(): string
+    get contentType(): string | null
+    get id(): string
+    get metadata(): any
+    get createdAt(): Date
+
+    private constructor()
+}

package/www/types/person_database/search_person.d.ts

@@ -0,0 +1,31 @@
+import { SearchPersonImage } from './search_person_image'
+import { SearchPersonDetection } from './search_person_detection'
+
+/**
+ * A Person Database object that represents th result of Person search.
+ */
+export class SearchPerson {
+    /**
+     * Array of images where the Person is found.
+     */
+    get images(): SearchPersonImage[]
+
+    /**
+     * Detection data relative to the search input image.
+     */
+    get detection(): SearchPersonDetection | null
+
+    name: string
+
+    get updatedAt(): Date
+
+    get groups(): string[]
+
+    get id(): string
+
+    metadata: any
+    
+    get createdAt(): Date
+
+    private constructor()
+}

package/www/types/person_database/search_person_detection.d.ts

@@ -0,0 +1,11 @@
+import { Point } from '../image_params/point'
+import { Rect } from '../image_params/rect'
+
+export class SearchPersonDetection {
+    get landmarks(): Point[]
+    get rect(): Rect
+    get crop(): string | null
+    get rotationAngle(): number | null
+
+    private constructor()
+}

package/www/types/person_database/search_person_image.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A Person Database object that represents Image result of Person Search.
+ */
+export class SearchPersonImage {
+    /**
+     * The similarity score.
+     * From 0.0 to 1.0.
+     */
+    get similarity(): number
+
+    /**
+     * The similarity distance score.
+     * The lower the distance, the higher the face's similarity.
+     * From 0.0 to 2.0.
+     */
+    get distance(): number
+    get path(): string
+    get url(): string
+    get contentType(): string | null
+    get id(): string
+    get metadata(): any
+    get createdAt(): Date
+
+    private constructor()
+}

package/www/types/person_database/search_person_request.d.ts

@@ -0,0 +1,39 @@
+import { ImageUpload } from './image_upload'
+import { OutputImageParams } from '../image_params/output_image_params'
+
+/**
+ * Request object that configures Search settings.
+ */
+export class SearchPersonRequest {
+    /**
+     * Create {@link SearchPersonRequest} object.
+     * 
+     * @param image - Image Upload object to apply search with.
+     * 
+     * @param params.groupIdsForSearch - The Group IDs of the groups in which the search is performed.
+     * 
+     * @param params.threshold - The similarity distance threshold, should be between 0.0 and 2.0, 
+     * where 0.0 is for returning results for only the most similar persons and 2.0 
+     * is for all the persons, even the dissimilar ones.
+     * Default: 1.
+     * 
+     * @param params.limit - The number of returned Persons limit. 
+     * Default: 100.
+     * 
+     * @param params.detectAll - Whether to process only the one face on the image or all the faces. 
+     * Default: `false`.
+     * 
+     * @param params.outputImageParams - If set the uploaded image is processed according to the indicated settings.
+     */
+
+    constructor(
+        image: ImageUpload,
+        params?: {
+            groupIdsForSearch?: string[],
+            threshold?: number,
+            limit?: number,
+            detectAll?: boolean,
+            outputImageParams?: OutputImageParams
+        }
+    )
+}