Main Considerations

There are a few main use-cases and considerations that will guide how best to configure and implement the Perfectly Clear SDK. Let's review these.

Single Preset, or AI Models of presets

We strongly recommend using [AI Models](TODO - link to scene detection topic) to ensure every image you process is analyzed and the best correction parameters are automatically selecetd from your approved preset list based on the content of the photo. However, there are valid use cases where a single preset needs to be applied to every photo - when every photo you process is shot under very controlled conditions. It is important to be aware of this difference and to ensure you use the process to load either a single preset or an AI Model of many presets.

AutoCorrect once, or re-process the same image several times

If your application will only correct each image once - with a pre-determined preset or AI Model of presets - then use PFC_AutoCorrect. This is what is demonstrated in the Quick Start above, and see the "Simple AI" code samples later in this guide as a reference implementation of this process.

But, some applications are interactive - like desktop photo editors. In these cases, a single image is initially corrected with a a pre-determined preset or AI Model of presets, but then will be re-processed with different correction parameters. This is best implemented with our separate PFC_Calc() and PFC_Apply() functions. PFC_Calc() is called once per image, then PFC_Apply() is called each time you need an updated image - when correction parameters have changed. See the "Detailed AI" code samples later in this guide as a reference implementation of this process.

It is safe to use the PFC_Calc() and PFC_Apply() calling pattern even if you only process images a single time. But, it's slightly slower to process and requires more code to implement.

One image or Batches of images

When operating on batches of images, there are objects you'll want to create once and then re-use on all images. There are also threading and I/O details to consider.

Loading image files or using Raster image data from other sources

We provide a PFCImageFile class to make it easy to read and write common image file types, while being fully color-managed and properly handling metadata. However, if your application already parses and decodes image files in existing code, then it can be more efficient to operate directly on those in-memory image rasters.

Configuration

Loading AI Models

AI models are distributed as .pnn files and must be loaded before use:

PFCENGINE *pAiEngine = PFC_CreateEngine();
std::string exePath = std::string(argv[0]);
std::string binPath = exePath.substr(0, exePath.find_last_of('/')).c_str();
int aistatus  = PFC_LoadAIEngine(pAiEngine, AI_SCENE_DETECTION | AI_CORRECTIONS | AI_COLOR | AI_FACEMESH, binPath.c_str());
if ((aistatus & AI_SCENE_DETECTION) == 0) {
	printf("Cannot load AI Scene Detection. Make sure the appropriate .pnn files, PFCAI and onnx libraries are in the executable directory or change binPath in code and re-compile.\n");
	printf("status %d\n", aistatus);
	exit(1);
}

Setting Correction Parameters

Parameters can be set in three ways:

1. Load an AI Model preset file - to select the best preset from an approved AI Model preset group

PFC_LoadScenePresets(pAiEngine, "/path/to/AI_Model_preset.preset");

The AI Engine is now aware of all presets within the AI Model, and will choose the best preset using AI Scene Detection during PFC_AutoCorrect() or PFC_Calc().

2. Load from preset file - when you know you will apply a single preset to all images.

PFCPARAM param;
PFC_ReadPresets(param, "/path/to/preset.preset");

The param struct now contains the all the parameters listed in the approved preset file, and will be applied to the image during PFC_AutoCorrect() or PFC_Apply().

3. Set programmatically (see Parameters guide) This is useful when you need to manipulate specific parameters - sharpening, exposure, depth, Retouching parameters or to apply a specific LOOK.