Working with Luna Web API v6

Applies to LUNA ID for Android only.

ApiV6

The ApiV6 interface provides methods to interact with the Luna Web API v6 for user management, verification, identification, and liveness detection. Obtain an instance via LunaID.apiHuman?.apiV6.

Extract (Create a user)

Create a user by extracting a face descriptor from an image or an existing descriptor.

Extract a descriptor from an image

fun extract(
    query: ExtractQuery,
    consumer: Consumer<Result<ExtractResponse>>
)

ExtractQuery

data class ExtractQuery(
    val userData: String, // User data
    val externalId: String, // External user ID
    val warp: Boolean, // Use normalized image
    val photo: ByteArray // Image
)

ExtractResponse

data class ExtractResponse(
    val personId: String, // ID of the created user
    val errorCode: Int = -1, // Error code
    val detail: String = "" // Error description
)

Extract a descriptor from a descriptor

fun extract(
    query: ExtractByDescriptorQuery,
    consumer: Consumer<Result<ExtractResponse>>
)

ExtractByDescriptorQuery

data class ExtractByDescriptorQuery(
    val userData: String, // User data
    val externalId: String, // User external ID
    val descriptor: ByteArray // Descriptor
)

Example

val query = ExtractQuery(
    userData = "John Doe",
    externalId = "user123",
    warp = true,
    photo = bestShot.image.toByteArray()
)

apiV6.extract(query) { result ->
    when (result) {
        is Result.Success -> {
            val personId = result.data.personId
            // Handle a successful result
        }
        is Result.Error -> {
            // Error handling
        }
    }
}

Verify (Verification)

Verify that a face in an image or a descriptor matches an existing user.

Image verification

fun verify(
    query: VerifyQuery,
    consumer: Consumer<Result<VerifyResponse>>
)

VerifyQuery

data class VerifyQuery(
    val userId: String, // User ID
    val warp: Boolean, // Use normalized image
    val photo: ByteArray // Image
)

VerifyResponse

data class VerifyResponse(
    val images: List<Image> // List of results
)

data class Image(
    val error: LunaWebErrorDescription,
    val detections: Detections
)

data class Detections(
    val faceDetections: List<FaceDetection>
)

data class FaceDetection(
    val verifications: List<Verification>
)

data class Verification(
    val status: Boolean, // Verification result
    val similarity: Double, // Similarity level
    val faceVerification: FaceVerification
)

Verification by descriptor

fun verify(
    query: VerifyByDescriptorQuery,
    consumer: Consumer<Result<VerifyResponse>>
)

VerifyByDescriptorQuery

data class VerifyByDescriptorQuery(
    val userId: String, // User ID
    val descriptor: ByteArray // Descriptor
)

Example

val query = VerifyQuery(
    userId = "user123",
    warp = true,
    photo = bestShot.image.toByteArray()
)

apiV6.verify(query) { result ->
    when (result) {
        is Result.Success -> {
            val verified = result.data.images
                .flatMap { it.detections.faceDetections }
                .flatMap { it.verifications }
                .any { it.status }
            // Process the result
        }
        is Result.Error -> {
            // Handle the error
        }
    }
}

Identify (Identification)

Search for a user in the database that matches the provided face image or descriptor.

Identification by image

fun identify(
    query: IdentifyQuery,
    consumer: Consumer<Result<IdentifyResponse>>
)

IdentifyQuery

data class IdentifyQuery(
    val warp: Boolean, // Use Normalized image
    val photo: ByteArray // Image
)

IdentifyResponse

    data class IdentifyResponse(
    val images: List<Image> // List of results
)

Identification by descriptor

fun identify(
    query: IdentifyByDescriptorQuery,
    consumer: Consumer<Result<IdentifyResponse>>
)

IdentifyByDescriptorQuery

    data class IdentifyByDescriptorQuery(
    val descriptor: ByteArray // Descriptor
)

Example

val query = IdentifyQuery(
    warp = true,
    photo = bestShot.image.toByteArray()
)

apiV6.identify(query) { result ->
    when (result) { 
        is Result.Success -> { 
            val candidates = result.data.images 
                .flatMap { it.detections.faceDetections } 
                .flatMap { it.identifications } 
                .flatMap { it.candidates } 
            // Processing candidates 
        } 
        is Result.Error -> { 
            // Error handling 
        } 
    }
}

Liveness

Performs Liveness estimation on a series of images to determine if the subject is a live person.

fun liveness( 
    query: PredictLivenessQuery, 
    consumer: Consumer<Result<LivenessResponseLegacy>>
)

PredictLivenessQuery

data class PredictLivenessQuery(
    val photos: List<ByteArray>, // List of images
    val meta: Meta = Meta(), // Device metadata
    val aggregate: Boolean = true // Aggregate results
)

LivenessResponseLegacy

data class LivenessResponseLegacy(
    val images: List<ImagesResult>, // Results for each image
    val aggregateEstimation: AggregateEstimation? // Aggregated result
)

data class ImagesResult(
    val filename: String,
    val status: Int, // 0 - error, 1 - success
    val predictionResult: PredictionResult?, // Validation result
    val description: LivenessError // Error description
)

data class PredictionResult(
    val prediction: Int, // 1 - alive, 0 - not alive
    val estimations: Estimation
)

data class Estimation(
    val probability: Float, // Probability of a living person [0.0..1.0]
    val quality: Float // Estimate quality [0.0..1.0]
)

Example

val photos = listOf( 
    bestShot1.image.toByteArray(), 
    bestShot2.image.toByteArray(), 
    bestShot3.image.toByteArray()
)

val query = PredictLivenessQuery( 
    photos = photos, 
    aggregate = true
)

apiV6.liveness(query) { result -> 
    when (result) { 
        is Result.Success -> { 
            val isAlive = result.data.aggregateEstimation 
                ?.predictionResult 
                ?.prediction == 1 
            // Process the result 
        } 
        is Result.Error -> { 
            // Error handling 
        } 
    }
}

Removing callbacks

Remove all previously registered callbacks:

fun removeCallbacks()