Technical issues

Table of contents

• What are the API usage requirements for the Queen SDK?

• How do I troubleshoot and debug issues?

• How do I configure input and output parameters?

• What is the performance of the SDK?

• How do I resolve a black screen issue?

• After integrating the Queen SDK, why does the screen flicker with a solid color, change color when the phone moves, but still show no image?

• Why does the application crash on startup?

• For sticker or makeup features, why are faces not detected after the image is rotated 90 degrees?

• Why does basic retouching work, but advanced retouching, makeup, or stickers do not?

API usage requirements

Troubleshooting and debugging

On Android:

After creating the engine, enable debug logging.

engine.enableDebugLog();

19417-27754/com.aliyun.android.queen_samples I/QUEEN_TAG_DEBUG: [code=-10, No retouching features are currently enabled]
19417-27754/com.aliyun.android.queen_samples I/QUEEN_TAG_DEBUG: [code=-10, No retouching features are currently enabled]
19417-27754/com.aliyun.android.queen_samples I/QUEEN_TAG_DEBUG: [code=-10, No retouching features are currently enabled]
19417-27754/com.aliyun.android.queen_samples I/QUEEN_TAG_DEBUG: [code=-10, No retouching features are currently enabled]
19417-27754/com.aliyun.android.queen_samples I/QUEEN_TAG_DEBUG: Number of faces detected=1
19417-27754/com.aliyun.android.queen_samples I/QUEEN_TAG_DEBUG: Number of faces detected=1
19417-27754/com.aliyun.android.queen_samples I/QUEEN_TAG_DEBUG: Number of faces detected=1
19417-27754/com.aliyun.android.queen_samples I/QUEEN_TAG_DEBUG: Number of faces detected=1
19417-27754/com.aliyun.android.queen_samples I/QUEEN_TAG_DEBUG: Number of faces detected=1
19417-27754/com.aliyun.android.queen_samples I/QUEEN_TAG_DEBUG: Number of faces detected=1
19417-27754/com.aliyun.android.queen_samples I/QUEEN_TAG_DEBUG: Number of faces detected=1

m.aliyun.android.queen_samples I/QUEEN: [alg_ai_image_angle.cpp:724] AlgAiImageAngle::AnalyzeAngle POS_Y, POS_X_N [renderFlipY: 1] [inputAngle: 270, outAngle: 0, flipAxis: 2]
m.aliyun.android.queen_samples D/QUEEN: [alg_input_data.cpp:255] QUEEN_INFO==CalculateScaleDivisor SRC=[1280 * 720], target = 360, SO SCALE = 2=====
m.aliyun.android.queen_samples D/QUEEN: [helper.cpp:99] ALG_IMAGE_PROCESS_TIME cost time(milliseconds):count 30 Average 1, Max 2, Min 1, last 1
m.aliyun.android.queen_samples I/QUEEN: [alg_engine.cpp:361] AlgEngine::SetInput inputData: [360, 640], inputTexture: [720, 1280], outRect: [0.000000, 0.000000, 72]
m.aliyun.android.queen_samples I/QUEEN: [alg_aai_facedetect.cpp:91] AlgAaiFaceDetect::DoRun Begin
m.aliyun.android.queen_samples I/QUEEN: [alg_aai_facedetect.cpp:166] AlgAaiFaceDetect::AdaptInput [inputWidth: 360, inputHeight: 640, stride: 1080, dataSize: 6912]
m.aliyun.android.queen_samples D/QUEEN: [helper.cpp:99] AlgAaiFaceDetect_TimeLog cost time(milliseconds):count 30 Average 14, Max 17, Min 9, last 11
m.aliyun.android.queen_samples I/QUEEN: [alg_aai_facedetect.cpp:117] AlgAaiFaceDetect::DoRun(0) End
m.aliyun.android.queen_samples D/QUEEN: [helper.cpp:99] ALG_PROCESS_TIME cost time(milliseconds):count 30 Average 16, Max 19, Min 11, last 13
m.aliyun.android.queen_samples D/QUEEN: [helper.cpp:99] EngineRender_Time cost time(milliseconds):count 30 Average 0, Max 4, Min 0, last 0
m.aliyun.android.queen_samples I/QUEEN_TAG_DEBUG: No face detected by the current algorithm. Make sure that parameters such as input angle, output angle, and flip are correct.

D-level (Debug) logs provide more detailed information, while I-level (Info) logs provide a concise summary.

Input and output parameters

SDK performance

The Queen SDK is optimized for performance and efficiency, including on low-end devices. Retouching features support multiple modes: Advanced Mode, Power-saving Mode, and Smart Adjustment Mode. Each release undergoes rigorous performance testing and large-scale validation.

Black screen issue

Cause: A black screen is typically caused by an invalid or improperly generated texture ID. Occasionally, it occurs when an application uses an invalid texture ID from the SDK or misuses a valid one.

Solution: The Queen SDK rendering layer is based on OpenGL. If you provide a valid, displayable texture ID to the Queen SDK API, the SDK guarantees that the output texture is also displayable. The Queen SDK returns the original texture even if no effects are applied, parameters are incorrect, or the license is invalid.

After integrating the Queen SDK, why does the screen show a flashing solid color that changes on movement instead of the video feed?

Conditions: This occurs when the engine is constructed with the toScreen parameter set to true, the input is an OES texture, and the parameter-less render() method is used.

Solution: Replace the render() call with renderTexture(matrix). When the input is an OES texture, you must use renderTexture. The matrix parameter required by this method must be obtained from the SurfaceTexture.

Crash on startup

Ensure that the texture ID passed to engine.setInputTexture is correct and valid, then restart the application.

Face not detected after rotation

Conditions: This issue occurs when the engine is constructed with the toScreen parameter set to true, the input is an OES texture, the parameter-less render() method is used, and the algorithm uses a frame-grabbing approach instead of the ByteBuffer approach.

Solution: Use the ByteBuffer approach. This will allow face detection, but the image may appear stretched or compressed if the width and height are mismatched.

Basic retouching works but advanced features fail

If basic retouching works, the Queen engine initialization, parameter settings, and rendering pipeline are functioning correctly. When advanced retouching, makeup, or stickers fail, the cause is usually incorrect parameters that prevent face detection. Features that rely on facial keypoints will not work without successful detection. The most common parameter errors fall into three categories:

• Incorrect width and height parameters for the texture input. In the setInputTexture(int texture, int width, int height, boolean isOES) function, the width/height parameters must match the display dimensions of the current texture and must correspond to the texture parameter. The fourth parameter, isOES, specifies whether the texture is an oes texture (Android-specific). When the texture is OES, the Queen engine performs an internal texture display conversion that requires the correct matrix from the current camera capture during rendering. The width and height also determine the aspect ratio of the rendered image, which affects image scaling for advanced feature effects. A common symptom is that advanced effects work but appear stretched or distorted.

• Incorrect width and height parameters for the input data. In the updateInputDataAndRunAlg(byte[] imageData, int format, int width, int height, int stride, int inputAngle, int outAngle, int flipAxis, boolean reuseData) method, the width/height parameters specify the actual dimensions of the input imageData. These values may match or be swapped with the texture dimensions in the first case. For example, on Android, the buffer obtained directly from the camera is often rotated by 90 degrees, with width and height swapped. These dimensions directly determine whether face recognition succeeds and whether advanced features work correctly.

• Incorrect input angle, output angle, or flip axis parameters in APIs such as updateInputDataAndRunAlg(byte[] imageData, int format, int width, int height, int stride, int inputAngle, int outAngle, int flipAxis, boolean reuseData) or the updateInputTextureBufferAndRunAlg(int inputAngle, int outAngle, int flipAxis, boolean usePreviousFrame) frame synchronization API. The inputAngle/outAngle/flipAxis parameters are required for advanced face recognition. inputAngle controls how the algorithm processes the incoming data or texture, including rotation direction and angle. outAngle controls how the algorithm renders and displays recognition results, including rotation direction and angle. flipAxis is a Queen engine enum that determines whether to flip the rendered image along the x-axis or y-axis. These parameters are critical for recognition accuracy and depend on the camera angle and front/rear camera selection. To simplify handling, these parameters are encapsulated in the QueenCameraHelper.java utility class, which you can use directly or modify as needed.