Common Errors

This page covers the most common errors developers encounter when integrating the Perfectly Clear SDK, along with their causes and solutions.

Invalid image

The SDK returns APPLY_NOSOURCE (-4) or APPLY_BADFORMAT (-5) when it cannot process the provided image data.

Symptoms

These indicators suggest an invalid image error:

• PFC_AutoCorrect() or PFC_Apply() returns -4 or -5.
• Error message indicates the source image is missing or has an unsupported format.
• Image appears corrupted or displays incorrectly after processing.

Causes

The APPLY_NOSOURCE error occurs when:

• The pImage pointer passed to the function is NULL
• The image data buffer has been freed or is inaccessible
• The PFCIMAGE structure was not properly initialized

The APPLY_BADFORMAT error occurs when:

• The pixel format specified in PFCIMAGE.format doesn't match the actual data
• The image uses an unsupported bit depth or channel configuration
• The stride value is incorrect for the image dimensions

Solutions

Verify your PFCIMAGE structure is correctly populated:

PFCIMAGE im;
im.width = imageWidth;
im.height = imageHeight;
im.stride = imageWidth * bytesPerPixel;  // Must match actual row width in bytes
im.format = PFC_PixelFormat24bppRGB;     // Must match actual pixel layout
im.data = imageBuffer;                    // Must point to valid, allocated memory

Ensure the pixel format constant matches your image data:

Unsupported format

The SDK has specific requirements for color spaces and image formats.

Symptoms

These signs indicate a format compatibility issue:

• Images appear with incorrect colors after processing.
• The SDK skips processing without returning an explicit error.
• Color profile warnings appear in verbose output.

CMYK color space

The Perfectly Clear SDK operates on RGB or RGBA image data. If your source images are in CMYK, Indexed color, or monochrome color spaces, you must convert them to RGB before processing.

Color profile handling

The SDK is fully color-managed, ensuring color consistency across devices and for different color profiles. This support is provided by the optional PFCImageFile class. When using PFCImageFile to read and write images, you can control color profile conversion as follows:

1. Convert to sRGB: Set bConvertToSRGB to true when loading, and set bConvertToOriginalColorSpace to false when saving. This converts the images to sRGB, processes thenm, then leaved them in sRGB on save:

// Load converting to sRGB
sRGBImageFile.LoadImageFile(filename, true, iccFolderPath);

// Process the image...

// Save leaving in sRGB
sRGBImageFile.SaveImageFile(
    outputFilename,
    quality,
    false,  // bConvertToSRGB
    true   // bPreserveOriginalMetadata
); 

2. Preserve original profile: Convert to sRGB, then return to the input profile:

// Load preserving original color space
originalImageFile.LoadImageFile(filename, true, iccFolderPath);

// Process the image...

// Save converting back to original color space
originalImageFile.SaveImageFile(
    outputFilename,
    quality,
    true,  // bConvertToOriginalColorSpace
    true   // bPreserveOriginalMetadata
);

3. No color management: Load and save without any profile conversion. This should only be used if the rest of your imaging pipeline is handling color management.

// Load without color management
noColorMgmtImageFile.LoadImageFile(filename, false, iccFolderPath);

// Process the image...

// Save without color management
noColorMgmtImageFile.SaveImageFile(
    outputFilename,
    quality,
    false,  // bConvertToSRGB
    false   // bPreserveOriginalMetadata
);

Out-of-memory

Memory exhaustion can occur when processing very large images or running batch operations.

Symptoms

These indicators suggest memory-related issues:

• PFCCORE_STATUS returns PFC_CORE_INSUFFICIENTMEMORY (4).
• The application crashes or becomes unresponsive.
• Processing slows dramatically before failing.

Causes

Memory issues typically arise from these scenarios:

• Processing images with very high resolution (500+ megapixels)
• Creating multiple PFCENGINE instances simultaneously
• Not releasing PFCPROFILE objects after processing
• Batch processing without proper memory management

Solutions

Release resources properly:

// Always release the profile after processing each image
PFC_ReleaseProfile(pProfile);

// Release the engine when done with the session
PFC_DestroyEngine(pEngine);

Reuse engine instances:

// Create ONE engine for your session
PFCENGINE* pEngine = PFC_CreateEngine();

// Process multiple images with the same engine
for (int i = 0; i < imageCount; i++) {
    PFCPROFILE pProfile = PFC_Calc(&images[i], NULL, pEngine, CALC_ALL, -1, NULL, NULL, NULL, PFC_REJECT_CLIPART);
    PFC_Apply(&images[i], pEngine, pProfile, param, NULL, 100, NULL);
    PFC_ReleaseProfile(pProfile);  // Release after each image
}

// Destroy engine at end of session
PFC_DestroyEngine(pEngine);

Parameter mismatch

Incorrect or incompatible parameter configurations can cause unexpected behavior or processing failures.

Symptoms

These signs indicate parameter configuration issues:

• PFC_ReadPresets() returns a negative error code
• Image corrections don't match expected results
• Features are unexpectedly disabled or produce no visible effect

Preset file errors

There are two functions to load presets:

• PFC_ReadPresets() - This loads a single Perfectly Clear preset file.
• PFC_LoadScenePresets() - This loads an AI Scene Detection preset file - containing multiple presets for different scene types.

Ensure you are using the correct function for the preset file type. Both of these functions return specific error codes:

For all errors - the most common issue is a malformed or corrupted preset file. Try exporting a new preset from the Perfectly Clear application to ensure the file is valid. Ensure single presets are loaded with PFC_ReadPresets() and scene presets with PFC_LoadScenePresets().

Missing license

License validation failures prevent the SDK from processing images.

Symptoms

These indicators point to license-related issues:

• PFC_Apply() returns APPLY_INVALIDLICENSE (-6)
• PFC_SetProtectionPath() returns an error code other than 0, 102, or 103
• Images are returned unprocessed

License setup requirements

The SDK license requires three files in a writable folder:

Common causes

License validation can fail for several reasons:

1. Incorrect path: The path provided to PFC_SetProtectionPath() doesn't exist or isn't accessible
2. Missing files: One or more license files are missing from the folder
3. Permission issues: The SDK cannot read from or write to the license folder
4. Network connectivity: License validation requires periodic internet access
5. Expired license: The license has reached its expiration date
6. Node limit exceeded: All available activations have been used

Solutions

Verify the license path:

int status = PFC_SetProtectionPath("/path/to/sdk_license", NULL);
if (status != 0 && status != 102 && status != 103) {
    printf("License error: %d\n", status);
}

Interpret license status codes:

Ensure network connectivity:

The SDK validates the license periodically, by default every 12 hours, and needs access to these addresses:

• IP: 184.106.60.185
• appsmanager.athentech.com (IPs: 52.72.235.36 or 52.203.55.148)

Ensure your firewall allows outbound connections to these addresses.

Handle license in multithreaded applications:

// Call PFC_SetProtectionPath ONCE before spawning threads
PFC_SetProtectionPath("/path/to/sdk_license", NULL);

// Then call PFC_Apply or PFC_AutoCorrect from individual threads
// Do NOT call PFC_SetProtectionPath from multiple threads

See the error code index for a complete list of license-related return codes.