🔗 Starting Guide


🔗 Contents


🔗 Prerequisites


🔗 System Requirements


🔗 Add library to a project

  1. Create a new project or open an existing project in Android Studio.

    • Create a new project (refer to this)

    • Open an existing project

      1. Open Android Studio.

      2. Click File > Open… to open an existing project.

  2. Download the SDK (libraries.zip) from Console.

  3. Copy the .aar files in the zip file to the libs folder of the project (usually app/libs/).

  4. Add the .aar files as dependencies.

    There are two ways to add these .aar files into the project.

    1. Add .aar files manually.

      Add the following code snippet in the root-level build.gradle file (Find the build.gradle file in the root folder of project).

      allprojects {
    repositories {
        flatDir {       /* Add this line here. */
            dirs 'libs' /* Add this line here. */
        }               /* Add this line here. */
    }
}

      If the Gradle version is 3.0 or later, add .aar files as dependencies into the build.gradle file in the module to integrate the SDK.

      For example:

      dependencies {
    implementation(name: 'PerfectLibCameraKit', ext: 'aar')
}

    2. Add the .aar files to dependencies with the GUI tool in the Android Studio (refer to this).


🔗 Use CameraKit

  1. Add the CameraKit library to the app module.

    dependencies {
    implementation(name: 'PerfectLibCameraKit', ext: 'aar')
}

  2. Request camera permission in the manifest and at runtime.

    <manifest>
    <uses-permission android:name="android.permission.CAMERA"/>
</manifest>

  3. Prepare the CameraKit models.

    • Put the CameraKit model root under the app assets folder, for example assets/model/.

    • The model root must contain the CameraKit subfolders required by the SDK, including face_detection and bad_lighting.

    • If you prefer storing models in app files storage, keep the same folder structure and pass that folder path to CameraKit.createFromFiles(...).

  4. Initialize the SDK runtime and create the CameraKit instance.

    If the app already initializes PerfectLib, set the CameraKit model path in Configuration and create CameraKit after initialization completes.

    Configuration configuration = Configuration.builder()
    .setModelPath(PerfectLib.ModelPath.assets("model"))
    .build();

PerfectLib.init(getApplicationContext(), configuration, new PerfectLib.InitialCallback() {
    @Override
    public void onInitialized(Set<Functionality> availableFunctionalities, Map<String, Throwable> preloadErrors) {
        CameraKit.create(new CameraKit.CreateCallback() {
            @Override
            public void onSuccess(CameraKit cameraKit) {
                cameraKit.setCameraKitLevel(CameraKitLevel.RELAXED);
            }

            @Override
            public void onFailure(Throwable throwable) {
                Log.e(TAG, "CameraKit create failed", throwable);
            }
        });
    }

    @Override
    public void onFailure(Throwable throwable, Map<String, Throwable> preloadErrors) {
        Log.e(TAG, "PerfectLib init failed", throwable);
    }
});

    If you want to create CameraKit with an explicit model path, use one of the following APIs after SDK initialization:

    CameraKit.createFromAssets("model", createCallback);
// or
CameraKit.createFromFiles(modelFolderPath, createCallback);

  5. Connect the camera lifecycle and submit preview frames.

    Call onCameraOpened(...) after the camera is opened and before preview starts. For each preview frame, create a CameraFrame, set its orientation if needed, and pass it to sendCameraBuffer(...).

    cameraKit.onCameraOpened(isFrontCamera, cameraOrientation, previewWidth, previewHeight);

CameraFrame frame = new CameraFrame(data, previewWidth, previewHeight, false);
frame.setFrameOrientation(frameRotationDegrees);
cameraKit.sendCameraBuffer(frame);

  6. Receive quality-check results and decide when capture is allowed.

    cameraKit.setCameraKitQualityCheckCallback(result -> {
    boolean isReady = result.getFaceAreaQuality().isOk()
        && result.getFacePoseQuality().isOk()
        && result.getLightingQuality().isOk();

    if (isReady) {
        Log.d(TAG, "CameraKit quality check passed");
    }
});

  7. Select a preset level and optionally overwrite individual thresholds.

    cameraKit.setCameraKitLevel(CameraKitLevel.RELAXED);

CameraKitParameterBuilder parameterBuilder = cameraKit
    .getCurrentParameter()
    .getParameterBuilder();
parameterBuilder.setFaceYaw(12.0f);
parameterBuilder.setLightingLower(0.60f);

cameraKit.setCameraKitOverwrite(parameterBuilder.build());

    Available preset levels are STRICT, MODERATE, and RELAXED. Applying setCameraKitLevel(...) resets thresholds to that preset. Applying setCameraKitOverwrite(...) keeps the current level and updates only the values provided in the built parameter.

  8. Release CameraKit when the screen is destroyed.

    @Override
protected void onDestroy() {
    if (cameraKit != null) {
        cameraKit.onDestroyed();
    }
    super.onDestroy();
}