Perfectly Clear SDK Documentation  9.5.2.443
Command Line Application
Perfectly Clear Command Line Application
Perfectly Clear Command Line Application

This command line application called pfccmd is the quickest way to integrate the Perfectly Clear technology into your photo workflow. The application was built using this SDK, and offers all of the image corrections of the full SDK, along with easy-to-use parameters that allow it to adapt to a wide range of uses.

Table of Contents

  1. Description
  2. Usage
  3. SDK License Protection
  4. Scene Detection
  5. About Resizing Parameters
  6. Status & Exit Codes
  7. JSON Output Report
  8. Scene Detection
  9. Example Usage

Description

The pfccmd command line application operates either on a single image file, or on a list of images or directory. Every supported image found in the input directories will be processed. When multiple files are being processed, the output filenames will be the based on the input filename, but will end with "_perfectlyclear" (IMG_1234.jpg becomes IMG_1234_perfectlyclear.jpg).

Scene Detection

This application has been updated to include support for Scene Detection - allowing you to easily apply different presets to photos with different content, subject matter, or lighting conditions. Scene Detection is an optional component to our SDK. Contact your SDK account exectuive for pricing and availability. If Scene Detection has been enabled for your business, then the use of Scene Detection will be enabled by default.

Usage

Usage: pfccmd [options ...] [paths] ...

The following options influence how the pfccmd application operates:

paths to process A list of files or folders to process.
-h, --help Show usage help and exit
-s, --sdk-license PATH Path to sdk_license folder provided by EyeQ. If you are provided a SDK license and do not set it here, then the pfccmd command line application will not apply corrections to your photos.
-p, --preset PATH Path to .preset file wtih correction parameters to apply. If this option is omitted, then the default iAuto corrections will apply. Also accepts: auto and none.
Specifying a preset file will disable Scene Detection.
-o, --output-path PATH Path to write the output file to. If a single input file is provided, then PATH is the full path and filename for the output file - and a file type extention is required. Otherwise, PATH will used as the output directory where output files are written.
-q, --output-quality INT Compression quality to use when creating lossy compressed output files (JPEG or WEBP), limited to the range [40-100].
--stdio Read file from stdin and write the output to stdout. Type should be suplied with input-type and output-type
--input-type TEXT Sets the input filetype when using stdio processing. Defaults to JPEG.
--output-type TEXT Used for stdio mode. Defaults to the same as input type.
-m, --scale-mode TEXT Resize the image using: none, width, height, long, short, scale.
-v, --scale-value INT Resize image to this size. Units are in pixels for all modes other than scale which is in integer percentage: 200 = 200% = double height and double width of the image. This option is required when using --scale-mode.
--skip TEXT Controls the digital photograph detection mechanism. Options are clipart (default), legacy, none. 'Clipart' uses AI to detect non-photographic images, 'legacy' uses the same mechanism as the v8 SDK, and 'none' will attempt to process every image regardless of image content. Skipping a file will result in 'Success' exit code and a status message indicating it was skipped.
-f, --fast-fae Enable the 'Fast Face Aware Exposure' processing mode. The default is to use 'High Quality Face Aware Exposure' to provide the best face detection.
-j, --json Enable image attribute report in JSON format.
--profile-only Do not create an output image - useful when used with --json.
--image-list-file PATH Path to a text file, with one line per image to correct. Images in the file are overwritten with the corrected image. The file should like the path to the image to correct, then a space, then a path to the preset to apply to each image, contained in double quotes if the paths contain spaces. For example:
C:\images\img_1234.jpg C:\presets\best_corrections.preset
C:\images\img_1235.png C:\presets\other_corrections.preset
C:\images\img_1236.tif C:\presets\still_more_corrections.preset
"C:\My Photos\Image Number 4.jpg" "C:\My Presets\correction.preset"
--scene-detection "on" , "off" or Path to a .preset file with presets to use for scene detection. By default scene detection is on.

SDK License Protection

You will be provided with a "sdk_license" folder when you receive this application. It contains a unique license key indentifier and will be actived online once every 12 to 24 hours.

The path to this folder must be set with either the --sdk-license option or the PFC_SDK_LICENSE environment varaible. If both are present, then the --sdk-license takes priority.

The pfccmd needs read and write permission to this folder. If the path does not exist or cannot be read or written, the pfcmd application will return an error and your images will not be corrected.

Scene Detection

This application has been updated to include support for Scene Detection - allowing you to easily apply different presets to photos with different content, subject matter, or lighting conditions. Scene Detection is an optional component to our SDK. Contact your SDK account exectuive for pricing and availability. If Scene Detection has been enabled for your business, then the use of Scene Detection will be enabled by default.

To make use of this technology we include a model named eff_1.pnn that must be in the same folder as pfccmd. If you are using a custom model by EyeQ, ensure that the file is the correct, custom model.

Use --scene-detection=on to enable Scene Detection and to apply default embedded presets for these scenes.

To customize the presets applied by this application, make edits to the presets in Workbench, then 'Export Presets' to create a .preset file that contains all presets in the Scene Detection group. Then, pass that filename into this application with --scene-detection=[filename.preset] to enable Scene Detection and automatically apply your custom presets.

Disable Scene Detection with --scene-detection=off.

Scene Detection Server

Scene detection initial setup can take up to a second, so we've created a "Scene Detection Server" to minimize the impact on an individual image proessing time. This server loads the Scene Detection model once, and then accepts images to be processed from the pfccmd command. To make use of it, just run pfcaiserver and have pfccmd connect to it.

From the command line all you need to do is enable scene-detection normally and pass the protocol (optional), address and port pfccmd --scene-detection=on --scene-detection-server=tcp:127.0.0.1:29170

The server requires at least the --sdk-license folder parameter (or through an environment varaible PFC_SDK_LICENSE) and optionally an IP or interface to listen to --address, by default tcp:127.0.0.1:29170. Although the server uses tcp, it's not intended for public internet use or to be run on a differennt machine.

In you are using Custom Scene Detection, you can specify which Scene Detection model to use through the --model parameter that would point to a path that contains the .pnn file and the PFCAI library. If ommited, it defaults to the same directory as pfcaiserver.

About Resizing Parameters

When resizing, only one parameter is used even if multiple parameters are provided. Non-integer paramerer are ignored. The order of priority is:

  1. width
  2. height
  3. long
  4. short
  5. scale

Width and Height will set the output size to have either the specified width or height - which ever is specified. The other dimension will be automatically determined to maintain the same aspect ratio as the original image.

Long and Short will set the output size based on the long or short side - which ever is specified. The other dimension will be automatically determined to maintain the same aspect ratio as the original image.

When using the scale parameter, the value should be an integer represenation of the percent scale you would like to apply. For example, scale=50 would be a 50% scale, or half the width and half the height of the original image.

Status & Error Codes

A status will be reported for the overall operation, and then a status will be reported for each image that is processed. The Status Message will be displayed, and the corresponding exit code will be returned.

Job-Based Status and Exit Codes

Ok = 0 Success. License was activated, preset loaded and all passed images returned OK.
LicenseError = 1 License could not be authenticated. Images were not corrected.
PresetError = 2 Couldn't parse the preset given. Images were not corrected.
ArgumentsError = 3 Some of the arguments given are not correct. Also includes a message with further details on the error.
ImageError = 4 At least one of the given images has errors.

Per-image Status Messages

Ok Success: image was processed and written successfully.
LoadError Image could not be loaded.
CorrectionError Corrections could not be applied.
ResizeError Error occured during resizing.
SaveError Error writing the output image.
CategorizationError Error while doing scene detection on the image.

JSON output

When using the --json option, a report will be generated in JSON format that includes Job-based Status as well as an element for each image processed. For example:

{
  "images": [
    {
      "allFacesRect": {
        "height": 1148,
        "left": 169,
        "top": 303,
        "width": 2332
      },
      "faces": [
        {
          "height": 881,
          "left": 169,
          "top": 570,
          "width": 881
        },
        {
          "height": 516,
          "left": 1985,
          "top": 605,
          "width": 516
        },
        {
          "height": 418,
          "left": 1201,
          "top": 303,
          "width": 418
        }
      ],
      "facesCount": 3,
      "input": "img_1234.jpg",
      "output": "img_1234_perfectlyclear.jpg",
      "status": "ok"
    },
    {
      "allFacesRect": {
        "height": 573,
        "left": 910,
        "top": 495,
        "width": 573
      },
      "faces": [
        {
          "height": 573,
          "left": 910,
          "top": 495,
          "width": 573
        }
      ],
      "facesCount": 1,
      "input": "img_2345.jpg",
      "output": "img_2345_perfectlyclear.jpg",
      "status": "ok"
    }
  ],
  "message": "",
  "status": "ok"
}

Example Usage

The some common ways to call this application include:

1. Applies default correction parameters to input.jpg and writes result to input_pfccmd.jpg

pfccmd input.jpg

2. Applies default correction parameters to input.png, and writes result to output.jpg - changing filetype to JPEG

pfccmd input.png -o output.jpg

3. Applies default correction parameters to input.png, and writes result to input_perfectlyclear.jpg - changing filetype to JPEG

pfccmd --output-type jpg input.png

4. Applies custom correction parameters to input.jpg, and writes result to output.jpg

pfccmd input.jpg -o output.jpg -p path/to/correction.preset

5. Corrects every image in the 'input' directory and writes output files to 'output' directory

pfccmd input -o output

6. Corrects and resized to 1000 pixels on the longer side

pfccmd -m long -v 1000 input.jpg

7. Use standard input and output, defaulting to JPEG input and output

pfccmd < in.jpg > out.jpg

8. Use standard input and output, and setting input and output formats

pfccmd  --input-type png --output-type jpg < ../some/path/in.png > output/path/out.jpg

9. Use list file

pfccmd --image-list-file" path/to/list.txt

10. Use scene detection file

pfccmd --scene-detection=on input.jpg