Debugging Checklist

When something isn't working as expected, use these systematic checklists to identify and resolve the problem. Start with the section most relevant to your issue.

Begin with a SDK Sample project

Start development using one of the provided SDK sample projects. These samples are pre-configured to work correctly and can help isolate issues in your environment. Once the sample project is working, adapt it to your application in incremental steps, verifying functionality at each stage.

If possible, try to isolate the Perfectly Clear SDK code into a separate module or function. This will help identify whether issues are specific to the SDK integration or arise from other parts of your application. This also can allow the EyeQ techcnical staff to build this module separately, which can be very helpful for troubleshooting.

How to isolate image issues

If images aren't processing correctly or produce unexpected results, then work through these steps to identify the root cause.

Verify the image loads correctly

Before processing, confirm the SDK can read your image data by checking that all PFCIMAGE fields are properly set. This will only be necessary if you're manually populating the PFCIMAGE structure, instead of loading via PFCImageFile.LoadImageFile() :

PFCIMAGE im;
im.width = imageWidth;
im.height = imageHeight;
im.stride = imageWidth * bytesPerPixel;
im.format = PFC_PixelFormat24bppRGB;
im.data = imageBuffer;

// Verify basic properties
printf("Image: %d x %d, stride: %d, format: %d\n", 
       im.width, im.height, im.stride, im.format);
printf("Data pointer: %p\n", (void*)im.data);

Common issues:

• Stride doesn't match actual row width (some image libraries add padding)
• Format constant doesn't match actual pixel layout (RGB vs BGR)
• Data pointer is NULL or points to freed memory

Check the return code details

Always examine the full return code to understand exactly what happened during processing:

int status = PFC_AutoCorrect(&im, NULL, param, -1, NULL, FALSE, NULL);

if (status == APPLY_SUCCESS) {
    printf("Success\n");
} else if (status > APPLY_SUCCESS) {
    printf("Warning (code %d):\n", status);
    printf("  Noise Removal: %d\n", NRRETCODE(status));
    printf("  Core: %d\n", CORERETCODE(status));
    printf("  Face Beautification: %d\n", FBRETCODE(status));
    printf("  Red Eye: %d\n", RERETCODE(status));
} else {
    printf("Error: %d\n", status);
}

Note: Warnings (positive codes) indicate partial success, while negative codes indicate failures.

How to test presets

Most preset issues arise as a mismatch between the preset file being loaded and the function used to load it. See the Common Errors section for details on preset loading functions and error codes.

Once you're certain the proper function is being used, then all remaining issues are typically due to malformed or corrupted preset files. To verify the preset file, attempt to load it into Workbench to verify the contents and format of the file.

Environment checks

Platform-specific issues often cause SDK problems. Use these checklists to verify your environment is correctly configured.

Linux

Follow these steps to verify your Linux environment is properly configured for the SDK.

Verify library dependencies:

# Check if SDK libraries are found
ldd /path/to/your/application

# Check for missing symbols
ldd -r libPerfectlyClearPro.so 2>&1 | grep "undefined"

Set library path:

# Add SDK libraries to library path
export LD_LIBRARY_PATH=/path/to/sdk/lib:$LD_LIBRARY_PATH

Check license file permissions:

# License folder must be readable and writable
ls -la /path/to/sdk_license/

# Required files:
# - license.key
# - registration_email.txt  
# - ShaferFilechck.so
# - libPFCAppTrack.so

Verify AI model files (if using AI features):

# Required .pnn files for AI features
ls -la /path/to/models/
# - eff_1.pnn (Scene Detection)
# - dynamic.pnn (AI Corrections)

# Required libraries
ls -la /path/to/lib/
# - libPFCAI.so
# - libonnxruntime.so

Windows

Follow these steps to verify your Windows environment is properly configured for the SDK.

1. Verify DLL availability:

   Place these DLLs in your application directory or system PATH:

   • PerfectlyClearPro.dll
   • ShaferFilechck.dll
   • PFCAppTrack.dll

   For AI features, also include:

   • PFCAI.dll
   • onnxruntime.dll

2. Check Visual C++ redistributable:

   The SDK requires the Visual C++ Redistributable. Download from Microsoft if you see errors about missing VCRUNTIME or MSVCP DLLs.

   Verify license folder:

   # Check license folder contents
   dir C:\path\to\sdk_license\
   
   # Verify write permissions (license validation writes to this folder)
   echo test > C:\path\to\sdk_license\test.txt
   del C:\path\to\sdk_license\test.txt

   Test with dependency walker:

   Use Dependencies or similar tools to verify all DLL dependencies are resolved.

macOS

Follow these steps to verify your macOS environment is properly configured for the SDK, and that the target architecture matches the SDK libraries (x86_64 vs arm64).

1. Verify library loading:

   # Check library dependencies
   otool -L /path/to/libPerfectlyClearPro.dylib
   
   # Check for missing symbols
   nm -u /path/to/libPerfectlyClearPro.dylib

2. Set library path:

`export DYLD_LIBRARY_PATH=/path/to/sdk/lib:$DYLD_LIBRARY_PATH

3. Code signing:

   If distributing your application, then the SDK libraries must be properly signed:

   # Check if library is signed
   codesign -dv /path/to/libPerfectlyClearPro.dylib
   
   # Re-sign if needed (requires Apple Developer certificate)
   codesign -fs "Developer ID Application: Your Name" /path/to/libPerfectlyClearPro.dylib

Notarization requirements:

For macOS 10.15+, distributed applications must be notarized. Ensure SDK libraries are included in your notarization submission.

Network connectivity checks

License validation requires periodic internet access. Use these steps to verify connectivity to the license servers.

Required endpoints

The SDK must be able to reach these servers for license validation and usage tracking:

Test connectivity

Use these commands to verify your system can reach the license servers.

  # Test license server
  ping -c 3 184.106.60.185
  curl -I https://my.nalpeiron.com

  # Test tracking server
  ping -c 3 52.72.235.36
  curl -I https://appsmanager.athentech.com

# Test license server
Test-NetConnection -ComputerName 184.106.60.185 -Port 443

# Test tracking server
Test-NetConnection -ComputerName 52.72.235.36 -Port 443

Firewall troubleshooting

If your environment uses a firewall, then configure it to allow the required connections.

Ensure outbound HTTPS (port 443) connections are allowed to:

• 184.106.60.185
• 52.72.235.36
• 52.203.55.148

Proxy troubleshooting

If you're behind a corporate proxy, then verify the SDK can connect through it.

The SDK uses system proxy settings. Ensure that:

• HTTPS proxy is configured in system settings
• Proxy allows connections to the license servers
• Any required proxy authentication is configured

If any step fails, then refer to the relevant section in this documentation for detailed troubleshooting guidance.