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).

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` or `auto`	Enable Scene Detection and apply Universal presets for the scenes that are detected
`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. Skipping a file will result in 'Success' exit code and a status message indicating it was skipped.

`clipart`	(Default) Uses AI to detect non-photographic images that should be skipped, which is far more accurate than the 'legacy' mode.
`legacy`	Uses the same mechanism as the v8 SDK - a fast and simple method to detect non-photographic images. Only very simply images will be detected as clipart.
`none`	Never skip processing. This can damage actual clipart or other non-photographic images, so use this with caution.

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.

--output-color-space TEXT

Sets the color space of the output image. Accepts

`original`	Default. Use the profile from the original image as the output profile (match original).
`sRGB`	Convert the file to sRGB.
`PATH`	Convert the output file to the ICC profile provided in the file specified in the PATH. For example `--output-color-space "/tmp/p3.icc"`

--skip-exif-software TEXT Optional. Skip correction of photos edited by software applications named by this parameter. See the section on EXIF Software Skipping for details.

--log-pdf-images If set log all images from a PDF file and their reports as file.pdf#Object_number.

--enable-composite TEXT Enable composite photo extraction feature - true by default on builds that support this feature. Set to false to disable composite image extraction.

The following options relate to AI Preset Selection and it's implementation of 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` If your `pfcaiserver` is remote and listening for HTTP conentions, then use "http://HOSTNAME:PORT" or "https://HOSTNAME:PORT".
--ssl-certs-path TEXT	For Linux only: If you are using a remote scene detection server and are using HTTPS, then TEXT is the path of root certificates to use when validating the SSL certificate. This defaults to `/etc/ssl/certs` For all systems, you can specify `disabled` to disable SSL certificate validation. This can be a security risk, so use this option with caution.
--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.

The options below relate to Auto Cropping, aimed at school portrait photography and other similar use-cases. These are most easily determined by using Perfectly Clear Workbench, and exporting auto crop values from the cropping tool.

--autocrop TEXT

Enable Auto Cropping. Possible values are below:

`false`	Default. Do not apply Auto Cropping.
`true`	Enable Auto Cropping.

--autocrop_size TEXT The head size factor used for autocrop. Default is 3, which means the full image width is three times the size of the detected head width.

--autocrop_x TEXT The x offset of the center of the head from the center of the image. Default is 0.

--autocrop_y TEXT The y offset of the center of the head from the center of the image. Default is 0.

--autocrop_topheadgap TEXT Amount of extra space to include between the top of the head (including hats or hair) and the top of the image.

--crop_arw TEXT The aspect ratio width of the crop. Default is 4.

--crop_arh TEXT The aspect ratio height of the crop. Default is 5.

AI Preset Selection & AI Server

This application has been updated to include support for AI Preset Selection, Skin Tone detection and other advanced AI correrctions - allowing you to easily apply different presets to photos with different content, subject matter, or lighting conditions. These AI tools are an optional component to our SDK. Contact your SDK account exectuive for pricing and availability. If the AI Tools have been enabled for your business, then the use of these will be enabled by default.

To make use of this technology we include various model ending with .pnn. If you are using a custom model by EyeQ, ensure that the file is the correct custom model.

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 --preset=[filename.preset] to enable Scene Detection and automatically apply your custom presets.

AI Server

Scene detection, Skin Tone detection and AI Correction profiling take some time to load, so we've created a "AI Server" called pfcaiserver to minimize the impact on an individual image proessing time. This server loads the various AI models once, and then accepts images to be processed from pfccmd, which improve processing speed substantially for some workflows. To make use of it, just run pfcaiserver on the same instance as pfccmd and have pfccmd connect to it as shown below.

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 following options influence how the pfccmd application operates:

-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.
--model PATH	PATH on disk to custom scene detection models to load. This defaults to the same path that contains pfcaiserver.
--http	Enable communication over HTTP instead of TCP. HTTP is necessary if your pfcaiserver or servers are behind load balancers that operate only on HTTP connections. You can also use HTTP if you need to have encrypted communication over HTTPS. In this case, you can run a proxy with a custom SSL certificate in front of the pfcaiserver. If you do not specify this argument, the pfcaiserver will communicate over TCP.
--address IP:PORT	IP address and port number to listen on. Defautls are `127.0.0.1` and `29170` for TCP and `80` for HTTP.

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.

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.

EXIF Software Skipping

This parameter allows you to skip corrections on photos that were edited by specific applications like Photoshop. Supply a comma-separated list of terms, for example:

--skip-exif-software "photoshop,lightroom"

In this example any photo that has the terms "photoshop" or "lightroom" (case-insensitive) in the Software (0x0131) or Processing Software (0x000b) EXIF tags will not receive any image corrections.

NOTE: Resizing will still be applied and the image will be re-encoded.

Environment Variables

The following environment variables can be used to configure this command line application.

PFC_SDK_LICENSE	Set the path to the sdk_license folder.
PFC_SD_SERVER	Set the URL to the pfcaiserver. For example tcp://127.0.0.1:29170
PFC_SINGLE_THREAD	Forces this tool to run on a single CPU, instead of multi-threading. Set to 'true' to enable this, or any other value to disable.
PFC_ENABLE_COMPOSITE	Enable/disable composite photo extraction feature - true by default on builds that support this feature.

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"

Require valid EXIF Flash tag that shows the flash was used in order to enable Red Eye Correction
```
pfccmd --red-eye=flash input.jpg
```
Skip processing for images last edited with Photoshop
```
pfccmd --skip-exif-software photoshop input.jpg
```
Process all images in the input folder, convering all to P3 profile provided in /profile/p3.icc
```
pfccmd --output-color-space "/profile/p3.icc" input -o output
```

Table of Contents