FAQ

This page answers the most common questions developers have when working with the Perfectly Clear SDK. Questions are organized by topic to help you find answers quickly.

General questions

These are the questions developers ask most frequently when integrating and using the SDK.

What's the minimum image size required for processing?

For consistent, high-quality results across all SDK features, use the largest size image you have access to.
Processing preview images or thumbnail-sized images can affect scene detection, face detection, skin tone detection, and correction quality.
It's best to process the full resolution image whenever possible, then downscale to a smaller size afterward if needed.

The absolute minimum image size is 32x32. Images smaller than this are not processed.

What's the maximum image size required for processing?

There is not a hard-coded upper limit -- it depends on available RAM and system resources. Very large images (400+ megapixels) might require significant memory and processing time. If you encounter issues processing very large images, then consider downscaling them before processing.

What color space does the SDK work in?

The SDK requried all images to be RGB or RGBA color formats, and will automatically handle color management based on embedded profiles.
If you are not using PFCImageFile to read and write images, then it is safest to ensure your images are in sRGB color space before processing.
For troubleshooting information, see color profile handling.

Are correction outputs identical across different platforms?

The AI tools are not 100% identical across different operating systems (Windows, macOS, Linux), architectures (x86 vs ARM64), or applications (CLI vs Workbench vs SDK). However, results will be very similar. EyeQ strives for "visually identical" output.

For critical image quality review, use the same output creation path that your customers will see: same OS, architecture, and application. Review prints or digital output exactly as your customers will experience them.

When should I resize images for previews or thumbnails?

For best image quality, process the full resolution image first, save the full-sized output, then resize to create previews, thumbnails, or other smaller images.

Downscaling before processing can be faster, but it reduces the information available for AI Scene Detection and Skin Tone detection, potentially affecting correction quality. The recommended workflow is:

1. Process the full resolution image.
2. Save the corrected full-size output.
3. Resize the corrected output to create smaller versions.

How do I export custom presets for use in the SDK?

You can export presets from Perfectly Clear Workbench in two ways.

For AI Preset Selection models (recommended)

Follow the steps to export AI Present Selection:

1. Select the AI Preset Selection model you want to use.
2. Switch to Edit mode in the AI Preset Selection panel.
3. Click the three dots menu.
4. Click Export Preset Group.

This creates a .preset file containing all presets in the model, which the AI can choose from based on image content.

For individual presets

Follow the steps to export individual presets:

1. Select the preset in the Other Presets panel.
2. Switch to Edit mode.
3. Click the three dots menu.
4. Click Export Preset.

Load preset files in the SDK using the PFC_ReadPresets() function.

For programmatic control, use Export to SDK from the Edit menu in Workbench. This generates C and C# code for all parameters, which you can copy into your source code to enable, disable, or modify individual settings programmatically.

Performance questions

These questions address processing speed, optimization, and throughput.

How can I improve processing speed?

There are several approaches to optimize SDK performance depending on your use case.

For the SDK

If processing multiple images, then create one AI Engine instance and reuse it for all images instead of creating a new engine for each image. Engine initialization takes time, so keeping a single instance throughout your session significantly improves throughput.

For multi-core machines

Process multiple images concurrently. Try using 50% to 80% of available CPU cores for concurrent image processing. For example, on a 24-core machine, experiment with 12, 14, 16, or 18 concurrent images. The optimal number depends on disk access times, memory bandwidth, CPU scheduling, image sizes, and other factors.

What throughput can I expect from the SDK?

On typical hardware, the SDK can correct an average of 16,000 images per hour. Actual throughput depends on several factors:

On an AWS instance (8 CPUs, 16 GB RAM), typical performance with AI Preset Selection and AI Image Correction enabled:

• CLI implementation: Lower throughput due to file I/O overhead
• Direct SDK integration: Higher throughput by eliminating file I/O

A 16-CPU instance would approximately double this performance.

What's the best way to integrate the SDK for maximum performance?

There are three main integration approaches with different performance characteristics.

Command line application

It is the easiest to implement, often up and running in under a day. However, file I/O can consume up to 40% of total processing time, and you have less control over concurrent processing.

Direct SDK integration

Eliminates file I/O entirely by working with image data already in memory. Provides the finest control over threading and concurrency. Best choice when performance is a priority.

Hybrid approach

Build a custom command line application tuned to your environment, or integrate the SDK directly while still working with image files. This is the most common approach, with performance between the two extremes.

What's the best deployment option for AWS Lambda?

EyeQ uses Lambda internally with the CLI. You have several options:

1. Run pfcaiserver on the same Lambda instance as the CLI: Provides the best single-image performance
2. Have the CLI call a remote pfcaiserver: Useful for shared AI server across multiple instances
3. Skip pfcaiserver entirely: Adds approximately 10% processing time but simplifies deployment and management

If single-image performance is not critical, then skipping the AI server is a simpler option to manage and deploy.

Licensing questions

These questions cover license setup, validation, and common licensing issues.

How do I set up SDK license protection?

Place your license files in a writable folder accessible to the SDK, then call PFC_SetProtectionPath() with the folder path:

int status = PFC_SetProtectionPath("/path/to/sdk_license", NULL);

The license folder must contain:

• license.key: Your license key file
• registration_email.txt: Registration email address
• ShaferFilechck.dll / .so / .dylib: License handling library
• PFCAppTrack.dll / libPFCAppTrack.so / libPFCAppTrack.dylib: Usage tracking library

The SDK validates the license every 12 hours via network connection to my.nalpeiron.com (184.106.60.185). Ensure your server has outbound internet access to this address.

What do the license status codes mean?

The PFC_SetProtectionPath() function returns a status code indicating the license state:

See the error code index for a complete list of license status codes.

How does node-based licensing work?

Each SDK license is enabled for a certain number of "nodes", unique computers where the SDK can be used. When you exceed your node limit, you'll receive status code 115 (exceed allowed activations) or 119 (no available licenses).

If deploying on virtual machines or cloud compute instances, then be aware that cloning and deploying new instances affects your node count. Contact EyeQ at any time to reset previous activations if you're nearing your limit.

How should I handle licensing in multithreaded applications?

Call PFC_SetProtectionPath() once before spawning any worker threads, then call PFC_Apply() or PFC_AutoCorrect() from individual threads:

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

// Then process images from multiple threads
// Do not call PFC_SetProtectionPath from individual threads

Setting up license protection takes approximately 100–150ms, so in performance-sensitive operations, construct one PerfectlyClear instance and process many images through it rather than creating a new instance for each image.