EyeQ Browser SDK Version 2.0.3

This package includes our new Browser SDK and 5 examples to demonstrate its usage. The "dist" folder contains the core SDK code, which is used by all examples. All examples can be built and run using a local Apache, Node.js, or any other static HTTP server.

AI Inference

In previous versions of our Browser SDK, AI Inference required an external "pfc ai server" to be running. In this version, the AI inference is built into the SDK, so no external server is required, but can still be used if desired. This is controlled through the options:

• inference: InferenceOption.local - Uses the built-in inference engine in the SDK
• inference: InferenceOption.remote - Uses an external server
• pfcAiServerUrl: "https://your-pfc-ai-server-url.com" - Sets the URL of the external AI inference server

The external pfc ai server is identical to the one used in our previous Browser SDK versions, but is no longer required and thus not delivered by default. Contact EyeQ if you are interested in using the external server or want to see a sample of how to set it up.

Local AI will download several model files to the browser cache, so it will take a few seconds to load the first time. After that, it will be very fast. See console logs for timing and caching information.

Parameters

All image correction parameters that are present in our Workbench desktop application are also available in this SDK. The parameters are set and read through the PFCParam object, in very nearly the same way as in our C SDK.

See the various examples for how to set and read parameters. These will usually be set automatically from AI Scene Detection presets, and then individual settings can be adjusted by the end-user, as shown in Manipulating Correction Parameters.

Functional Reference

Initialization

The first steps are to initialize the SDK and load the necessary files.

1. Initialize the SDK

pfcWasmCertificate = await pfc.init(options);

Options Configuration:

export type PfcOptions = {
    distDir: string;              // Path to the directory containing WebAssembly and JavaScript files
    modelsDir?: string;           // Path to AI models directory (optional, defaults to distDir)
    clientAPIKey: string;         // API key provided by EyeQ
    urlGetCertificate: string;    // URL to get certificate (typically https://cert.perfectlyclear.photos/wasm_certificate/)
    pfcWasmCertificate: string;   // Global variable to store the certificate
    pfcAiServerUrl?: string;      // URL of AI inference server (when using remote inference)
    inference: InferenceOption;   // Local, remote, or remoteSocket
}

Inference Options:

export enum InferenceOption {
  local,        // Process AI inference locally in browser (fastest, requires model downloads)
  remote,       // Process AI inference on remote server (requires running pfc ai server)
  remoteSocket  // Legacy AI inference using websockets
}

2. Load Image

await loadImage(imageUrl, CANVAS_ID);

Loads an image from a URL and displays it on a canvas, including scaling to preview size

3. Load Scene Presets

// Fetch and load the scene detection preset configuration
const response = await fetch("./resources/presets/sd.preset");
const presetSD = await response.text();
pfc.loadScenePresets(presetSD);

Loads scene presets from a source file to prepare for applying them to images

4. Create Objects

Create Parameter Object:

const param = pfc.createParam();
if (!param) throw Error("Failed to create param");

Creates a new PFCParam object for setting and getting image correction parameters

Create Image Object:

const canvas = document.getElementById(CANVAS_ID);
const pfcImage = pfc.createImage(canvas);
if (!pfcImage) throw Error("Failed to create image");

Creates a new PFCImage object for processing an image on a canvas

This pfcImage object holds the image data for processing with Perfectly Clear. It contains:

• originalImage - unprocessed image data, useful will re-applying corrections with new parameters
• image - image data which is updated by the apply function to contain the corrected image
• profile - profile from Perfectly Clear Calc steps within calcAIFeatures
• sceneId - ID for the scene determined by AI Scene Detection
• imageId - unique ID for this image. Use this when re-processing an image in WebWorkers

Applying Image Corrections

Once images and presets are loaded, you can apply image corrections:

// Calculate AI features and get the detected scene ID
const aiFeatures = await pfc.calcAIFeatures(im, features, jpegBlob);
const sceneID = aiFeatures?.sceneID;

// Apply the scene-specific preset to the parameters
pfc.readScenePreset(param, sceneID);

// Apply corrections and render
pfc.apply(im, param);
im.drawToCanvas(canvas);

Step-by-Step Breakdown:

1. Calculate AI Features

const aiFeatures = await pfc.calcAIFeatures(im, features, jpegBlob);

• Parameters:
  • im - The PFCImage object to process
  • features - The PFCFeatures flags for what to calculate
  • jpegBlob - The JPEG blob of the image (for remote inference)
• Returns: AI features object containing sceneID for detected scene

2. Apply Scene Preset

pfc.readScenePreset(param, sceneID);

• Parameters:
  • param - The PFCParam object to apply the preset to
  • sceneID - The ID of the detected scene from calcAIFeatures

3. Apply Parameters

pfc.apply(im, param);

• Parameters:
  • im - The PFCImage object to apply parameters to
  • param - The PFCParam object containing image correction parameters

4. Render to Canvas

im.drawToCanvas(canvas);

• Parameters:
  • canvas - The canvas element to draw the processed image on

Manipulating Image Correction Parameters

You can manipulate the image correction parameters using the PFCParam object directly and also with some helper functions. For most parameters, use the same syntax as see in the 'Export to SDK' function from Perfectly Clear Workbench. For example:

// Face beautification
param.fb.bEnabled = 1;           // Enable face beautification
param.fb.bEnhance = 1;           // Enable Eye Enhance
param.fb.iEnhanceLevel = 50;     // Set enhancement level (0-100)

// Core corrections
param.core.bUseAutomaticStrengthSelection = 0; // Disable automatic strength selection, to allow manual control
param.core.iStrength = 80;       // Set Exposure correction manually, instead of using automatic strength
param.core.bLocalContrast = 1;   // Enable Super Contrast correction

Gradient Filters (vignettes, etc) and Finishing Tools operate on 'layers'. To read or set these, you'll need these helper functions:

// Layer processing for Gradients and Finishing tools
param.getLayerProperty(layer, property);
param.setLayerProperty(layer, property, value);
param.getMaskProperty(layer, property);
param.setMaskProperty(layer, property, value);

For example, to enable and set the strength our Finishing Vibrancy correction (see sample C), you would use:

param.setLayerProperty(2, "iFinishVibrancy", value);
param.setMaskProperty(2, "type", PFCCORE_MASK_TYPE.MASK_ALL);

Creative Filters are set by referencing their GUID. See the LOOKs.md file for a list of all Creative Filters incldued in this SDK. There are many more options beyond this list - check with EyeQ if you are interested in seeing more!

// Apply output LUT
param.setOutputLUT(GUID);

EyeQ offers a 'smart' overall strength tool that can manipulate all parameters applied to the image - an overall strength slider for all corrections. You can also use this to set only SOME parameter strengths - like all Retouching parameters as shown in Option D2.

// Apply strength scaling to all parameters
pfc.applyStrengthToParam(param, strength);

copyParams is used to make a copy of parameters, in order to revert to earlier settings or for use before manipulalation with applyStrengthToParam, again as shown in Option D2.

// Copy parameters
pfc.copyParam(destinationParam, sourceParam);

Deployment Notes

1. Static Hosting The main part of this SDK doesn't use any server-side processing, so it can be deployed as a static site using AWS S3 or any other static file hosting service. The Content-type for the .wasm file should be set to application/wasm to ensure it is served correctly - this is not done automatically by AWS S3, so a command similar to the following is required:

aws s3 cp --content-type application/wasm  [bucket-name]/[folder-name] [bucket-name]/[folder-name] --metadata-directive REPLACE --exclude "*" --include "*.wasm" --recursive

In Apache, this can be done with an .htacess file including the following:

AddType text/javascript .mjs
AddType application/wasm .wasm

2. Certificate Validation The SDK requires a certificate to be validated before it can be used. Your clientAPIKey is used to validate a certificate from the EyeQ server. The clientAPIKey is locked to specific domains and EyeQ will update the domains that your API key. All keys are allowed to run on localhost for development purposes, so you can test locally without needing to set up a domain.

Change Log

• v2.0.2 - Oct 15, 2025:

  • Change 'Apply All' logic in Option F
  • UX improvements in several samples
  • Add helper script to implment Perfectly Clear WebAPI corrections - like Background removal or glasses glare removal
  • Add support to manipulate Selective Color parameters
  • Improve support for iOS Safari
  • Speed up local AI detection
  • Improve preview image quality on Firefox

• v2.0.1 - Jul 28, 2025:

  • Refactor samples to simpliy deployment process
  • Improve WebWorkers implementation

• v2.0.0 - Jun 6, 2025 : initial "v2" release