@imgly/plugin-perfectlyclear-web

Perfectly Clear (eyeQ) image enhancement plugin for the CE.SDK editor.

Runs fully in-browser via WebAssembly. Provides one-click AI-driven image enhancement (scene detection, skin tone correction, dynamic range, AI color, noise reduction, face/beauty adjustments) on the currently selected image fill.

For documentation, visit: https://img.ly/docs/cesdk

Overview

The plugin wires the fill-processing state machine for the Perfectly Clear runtime and registers a reusable quick action (ly.img.perfectlyClear.enhanceImage) that AI plugins can surface inside the ly.img.ai.image.canvasMenu popover alongside their own actions.

The plugin registers the canvas-menu / dock / inspector-bar / navigation-bar / canvas-bar button components, but does not insert them into any order on its own — that would collide with the AI popover integration and produce two Enhance buttons when both plugins are installed. Integrators add the component IDs to the relevant order manually, e.g.:

cesdk.ui.setCanvasMenuOrder([
  `${PLUGIN_ID}.canvasMenu`,
  ...cesdk.ui.getCanvasMenuOrder()
]);

Alternatively, surface enhancement through @imgly/plugin-ai-image-generation-web (see examples/pfc).

Key capabilities:

• In-browser enhancement via Perfectly Clear's WebAssembly runtime — no server round-trip
• Automatic scene detection + per-scene correction profiles
• Reusable AI quick action any image2image provider can opt into
• Configurable asset baseURL — bundle on your own CDN or self-host
• Transparent undo/redo via CE.SDK's fill processing metadata

Installation

npm install @imgly/plugin-perfectlyclear-web

The plugin version must match your CE.SDK version (unified versioning).

Usage

Basic setup

import CreativeEditorSDK from '@cesdk/cesdk-js';
import PerfectlyClearPlugin from '@imgly/plugin-perfectlyclear-web';

const cesdk = await CreativeEditorSDK.create('#container', config);

await cesdk.addPlugin(
  PerfectlyClearPlugin({
    apiKey: 'your-perfectly-clear-api-key'
  })
);

Custom asset base URL

await cesdk.addPlugin(
  PerfectlyClearPlugin({
    apiKey: '…',
    baseURL: 'https://cdn.your-domain.com/pfc/v1/'
  })
);

The server at baseURL must respond with CORS headers and a Cross-Origin-Resource-Policy: cross-origin header — Perfectly Clear's runtime spawns blob-URL workers (origin null) that re-fetch the runtime assets cross-origin.

AI plugin integration

The plugin registers a quick action with id ly.img.perfectlyClear.enhanceImage. Any image2image provider for @imgly/plugin-ai-image-generation-web can declare support for it to surface the enhance button inside the AI canvas-menu popover:

const myProvider: Provider<'image', { uri: string }, ImageOutput> = {
  id: 'my.provider',
  kind: 'image',
  name: 'My Provider',
  input: {
    quickActions: {
      supported: {
        'ly.img.perfectlyClear.enhanceImage': true
      }
    }
  },
  output: { generate: async () => /* … */ }
};

When the button is clicked, the PFC plugin runs its own in-browser enhancer via the shared fill-processing metadata flow — the provider's generate is never called. See examples/pfc for a runnable stub provider.

Configuration

PluginConfiguration

| Property | Type | Required | Default | Description | |--------------------|------------------------------|----------|-----------------------------------------------------------|----------------------------------------------------------------------------------------------------------------| | apiKey | string | Yes | — | Perfectly Clear (eyeQ) client API key. Must be authorized for the host origin. | | baseURL | string | No | IMG.LY CDN | URL under which the Perfectly Clear runtime assets (pfc.mjs, pfc.wasm, workers, models, presets) are served. Must support CORS. | | certificateURL | string | No | Perfectly Clear production endpoint | URL of the Perfectly Clear certificate endpoint used to validate the WASM license against your domain. | | numWorkers | number | No | 4 | Number of image-processing worker threads the engine spawns. | | cacheCertificate | boolean | No | true | Whether to cache the WASM certificate in localStorage. | | pageHostname | string | No | location.hostname | Hostname used for certificate validation when workers run from blob URLs (where location.hostname is empty). |

Asset hosting

The baseURL directory must contain the full Perfectly Clear runtime:

<baseURL>/
├── pfc.mjs
├── pfc.wasm
├── image.worker.js
├── inference.worker.js
├── ort-wasm/              # ONNX Runtime variants
├── models/                # .pnn model files
└── presets/sd.preset

Required response headers on every asset:

• Access-Control-Allow-Origin: * (or your editor's origin)
• Cross-Origin-Resource-Policy: cross-origin

The workspace plugin's assets/v1/ folder ships the complete set ready to upload to your CDN. See examples/pfc/README.md for a working Cloudflare R2 + Transform Rules setup.

How it works

1. User clicks Enhance — the AI quick-action popover entry, or any custom component the integrator wires up.
2. Fill processing metadata — the plugin flips the selected block's FillProcessingMetadata to PENDING, which drives CE.SDK's standard loading-state UI and undo/redo.
3. WASM enhancement — the ImageEnhancer loads the selected image, runs it through the Perfectly Clear runtime (scene detection → per-scene correction pipeline), and returns an enhanced buffer.
4. Write back — the enhanced image is written back as a data URL (or source-set entry), and the fill processing metadata transitions to PROCESSED.

License

This plugin is part of the IMG.LY plugin ecosystem for CreativeEditor SDK. Usage of the underlying Perfectly Clear (eyeQ) technology requires a valid API key from Perfectly Clear.