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.

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. You can also set this path using the PFC_SDK_LICENSE environment variable.

-p, --preset PATH

Path to .preset file wtih correction parameters to apply. If the .preset file contains a single preset, then this one preset will be applied. If the .preset file contains a group of AI Presets for Scene Detection, then Scene Detection will be enabled and the AI Presets specified in the file will be applied.
Instead of supplying a path, you can also use the following keywords:

`scene`	Enable Scene Detection and apply default presets for the scenes that are detected
`auto`	apply iAuto '21 preset (for backwards compatibility)
`none`	apply no corrections (useful when resizing only, for example)

-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; 'Clipart' uses AI to detect non-photographic images, 'legacy' uses the same mechanism as the v8 SDK. Skipping a file will result in 'Success' exit code and a status message indicating it was skipped.
Note: AI Scene Detection includes a scene for Clipart, so when Scene Detection is in use, this option will be set to legacy.

-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"

--red-eye TEXT

Controls when the automatic Red Eye correction will run. Default is "no-flash". Possible values are below, in order from the most to least usage:

`always`	Enable Red Eye correction for every image, regarless of settings in the preset being applied
`preset`	Use the settings in the preset being applied
`no-flash`	Require the preset to include Red Eye correction, but disable if EXIF data shows the flash was not fired. Red Eye will be applied to images without any EXIF data.
`flash`	Require the preset to include Red Eye correction, and also require EXIF data to show the flash was fired. Red Eye will NOT be applied to images without any EXIF data.
`off`	Prevent Red Eye from being applied, even if the preset used has Red Eye correction enabled.

The following options relate to Scene Detection. If Scene Detection is not being used, the following options may all be ignored. See the Scene Detection section below for examples and details.

--scene-detection TEXT	"on", "off" to enable or disable Scene Detection. By default scene detection is on for SDK packages that include Scene Detection. Setting this to "on" is identical to using `--preset scene`
--scene-detection-server TEXT	If passed an url, `pfccmd` uses to contact `pfcaiserver` and do Scene Detection remotely. Usually "tcp://127.0.0.1:29170". This can be useful to run a separate `pfcaiserver` when processing many images individually with `pfccmd`.
--scene-model-path PATH	Link to a directory containing the .pnn and PFCAI libraries. Defaults to searching in the pfccmd binary's directory.
--list-local-scenes	Loads scene detection libraries and lists the label and their names.

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.

AI Scene Detection

This application has been updated to include support for AI 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 or more, so we've created a "Scene Detection Server" called pfcaiserver 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 pfccmd. 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.

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:

width
height
long
short
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":384,
            "left":604,
            "top":302,
            "width":384
         },
         "scene":5,
         "faces":[
            {
               "angle":1,
               "blink":0,
               "confidence":100,
               "height":384,
               "left":604,
               "leftEye":{
                  "blinkLevel":0,
                  "height":84,
                  "left":686,
                  "point":{
                     "x":745472.0,
                     "y":407552.0
                  },
                  "top":356,
                  "width":84
               },
               "mouth":{
                  "height":0,
                  "left":0,
                  "top":0,
                  "width":0
               },
               "rightEye":{
                  "blinkLevel":0,
                  "height":84,
                  "left":854,
                  "point":{
                     "x":917504.0,
                     "y":409600.0
                  },
                  "top":358,
                  "width":84
               },
               "smile":26,
               "top":302,
               "width":384,
               "yawAngle":0
            }
         ],
         "facesCount":1,
         "format":1,
         "height":3597,
         "input":"/Users/admin/Pictures/Athentech/color-test.jpg",
         "message":"",
         "noise":"unknown",
         "output":"",
         "status":"ok",
         "tint-aggressive":"false",
         "tint-coservative":"false",
         "tint-default":"false",
         "tint-strongest":"false",
         "width":2380
      }
   ],
   "message":"",
   "status":"ok"
}

Example Usage

The some common ways to call this application include:

Applies Scene Detection to determine corrections parameters to input.jpg and writes result to input_pfccmd.jpg
```
pfccmd input.jpg
```
Convert output format to JPEG
```
pfccmd input.png -o output.jpg
```
Convert output format to JPEG and write output file input_perfectlyclear.jpg
```
pfccmd --output-type jpg input.png
```
Disabled Scene Detection, and instead applies custom correction parameters to input.jpg, and writes result to output.jpg
```
pfccmd input.jpg -o output.jpg -p path/to/custom.preset
```
Enables Scene Detection, and applies customized Scene Detection presets to input.jpg, and writes result to output.jpg
```
pfccmd input.jpg -o output.jpg -p path/to/AI_Presets.preset
```
Corrects every image with Scene Detection in the 'input' directory and writes output files to 'output' directory
```
pfccmd input -o output
```
Corrects and resized to 1000 pixels on the longer side
```
pfccmd -m long -v 1000 input.jpg
```
Use standard input and output, defaulting to JPEG input and output
```
pfccmd --stdio < in.jpg > out.jpg
```

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

Use list file

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

Disable Scene Detection and use the default 'iAuto '21' preset

pfccmd --scene-detection=off input.jpg

or

pfccmd --preset=auto input.jpg

Require valid EXIF Flash tag that shows the flash was used in order to enable Red Eye Correction
```
pfccmd --red-eye=flash input.jpg
```

Table of Contents