 |
Perfectly Clear SDK Documentation
10.7.1.1191
|
|
Perfectly Clear SDK Documentation
10.7.1.1191
|
This document will explain how to get our Docker container up and running, how to configure it, and how to use the logging facility to diagnose any issues you might encounter.
Once the container is running, you will interact with it via a HTTP API, through the process:
PFC_IMG_CACHE_TTL enviornment variable. If you need the corrected image again after this time, you'll need to re-upload and re-correct it.Docker is required to run the container.
The following packages are required by the sample "correct_image.sh" script.
These can typically be installed with sudo apt-get install jq curl on newer linux distributions.
You will interact with this container using an HTTP API interface. It is exactly the same API that our public Web API uses - the only difference is the URL endpoint.
Upload original image to make it ready for corrections
| Name | Description |
|---|---|
| Content-Type | Required. Either 'image/jpeg' or 'image/png' |
| Code | Description |
|---|---|
| 200 |
Success
Content: {
"imageKey": "string"
}
|
| 400 | Header Content-Type not found. |
| 503 | Internal server error. |
Apply Perfectly Clear image correction and get the URL to download the corrected image.
| Name | Description |
|---|---|
|
imageKey string (path) |
Required. ID of uploaded image, as returned from the PUT method |
|
preset string (query) |
Optional. Name of your preset. Mount presets to the /presets folder. If no preset is provided, Scene Detection will be used to determine the optimal preset to apply. |
|
outputType string (query) |
Optional. Either 'JPEG' or 'PNG' - used to set the type of file returned. Default = same as input file. |
|
width, height, long, short integer (query) |
Optional. Chosen dimension of the output image in pixels. Capped to 100,000px. |
|
scale integer (query) |
Optional. Scale of the image in percentage points. Capped to 100,000%. |
|
outputQuality integer (query) |
Optional. Sets the quality of the output image. Only accepted for JPEG and ignored for any other output types. Defaults to 90. Must be between 40 and 100. |
|
outputColorSpace string (query) |
Optional. Sets the color space of the output image. Accepts 'original' (default), 'srgb' or a filename to search in /presets. |
|
skip-exif-software string (query) |
Optional. Skip correction of photos edited by software applications named by this parameter. See the section on EXIF Software Skipping for details. |
|
preserveInputFileName boolean (query) |
If set to true, reuse the same input file name as the output file name inside the container. This is for advanced usage. Also see the PFC_PRESERVE_INPUT_FILENAME enviornment variable. |
|
skip string (query) |
Sets the mode to determine what images skip processing. Valid values are "clipart" (default), "legacy", and "none". 'clipart' uses a custom AI model to determine if the image file isn't a true photograph, but is actually clipart. 'legacy' uses a more simple process to attempt to detect non-photographic images, like logos and simple line art. 'none' causes every image to be corrected - and this has the potential to damage images that are actually clipart or other non-photographic content. Note: this parameter is ignored when using AI Preset Selection. The query parameter has preference over the ENV value if it's valid. |
|
autocrop string (query) |
Set to "true" to enable auto cropping |
|
autocropSize string (query) |
The head size factor used for autocrop. |
|
autocropX string (query) |
Relative horizontal offset from the head used for autocrop. |
|
autocropY string (query) |
Relative vertical offset from the head used for autocrop. |
|
cropARW string (query) |
The horizontal aspect ratio for crop. |
|
cropARH string (query) |
The vertical aspect ratio used for crop. |
|
autocropTopHeadGap string (query) |
If set positive, autocrop will target relative gap over top of the head. |
|
enable-composite string (query) |
Enable composite photo extraction feature - true by default on builds that support this feature. Set to false to disable composite image extraction. |
| Code | Description |
|---|---|
| 200 |
Success
Content: {
"corrected_url": "string",
"scene": -1
}
|
| 400 | Unknown or invalid image key. |
| 503 | Internal server error. |
Get a report on the Perfectly Clear SDK version
| Code | Description |
|---|---|
| 200 | Text report of the Perfectly Clear SDK version and features supported |
When resizing, only one parameter is used even if multiple parameters are provided. Non-integer paramerer are ignored. The order of priority is:
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.
Auto cropping uses face detection and cropping parameters from Perfectly Clear Workbench to crop portrait images with a single face to ensure that all faces are the same size and in the same position. These parameters for auto cropping are most easily set in Perfectly Clear Workbench, then copied from the 'info' panel in the cropping tool.
The container provides scene detection and application of EyeQ's default parameters for each scene by requesting the preset "scene":
curl -v -X GET "http://localhost:80/pfc/${imageKey}?preset=scene"
or simply:
curl -v -X GET "http://localhost:80/pfc/${imageKey}"
The applied scene can be obtained by examining the scene parameter in the response. A value of -1 means unknown and any other value depends on your model. The container will write a list of all known scenes into the logs when the container first starts up.
To get specific presets applied on a given scene, export the AI Presets group from Workbench, and use that exported .preset file as your 'preset'. For example:
curl -v -X GET "http://localhost:80/pfc/${imageKey}?preset=AI_Scene_Detection"
This query 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. This can also be set with the PFC_SKIP_EXIF_SOFTWARE configuration enviornment variable.
NOTE: Resizing will still be applied and the image will be re-encoded.
We have provided a simple script to demonstrate the API. You can run make in this folder to load the docker image, run the container, and upload, correct and download a sample JPEG image.
The manual steps are:
Verify that your license files are the sdk_license folder.
Add the docker image to your docker engine:
docker load --input pfc_container_image.tar
Run the imported image:
docker run -it -v "$(shell pwd)/presets":/presets -v "$(shell pwd)/sdk_license":/sdk_license \ -p 80:80 -e PFC_LOG_LEVEL='debug' pfc_container
The container is now running attached and in debug mode to inspect everything is properly setup. It has mounted the presets directory to /presets and the sdk_license folder to
/sdk_license.
Upload an image and parse and save the imageKey:
imageKey=$(curl -H "Content-Type: image/jpeg" -X PUT "http://localhost:80/pfc" --upload-file sample.jpg | jq -r '.imageKey')
Correct the image with the default Scene Detection preset:
correctedImageUrl=$(curl -v -X GET "http://localhost:80/pfc/${imageKey}" | jq -r '.corrected_url')
Download the finished image:
curl "${correctedImageUrl}" -o corrected.jpg
There are two other scripts included in this package - convert_image.sh and scale_image.sh. These are very similar to the correct_image.sh script, but show the process to convert from JPG to PNG and also
to apply image resizing.
There are three ways to configure and influence how this docker solution operates.
There are several folders that you can mount to volumes outside the container to make interacting with the container easier.
/presets Store all presets, or output colorspace .icc files here/addons Store custom .looks files here./sdk_license Copy the sdk_license files provided to you by EyeQ to this volume/input Contains all images to be corrected. Use the /put endpoint to add files to this folder, or mount this folder and externally add images to make them available for correction./output Corrected images are saved here. Mounting this to an external volume allows quicker access to corrected images, especially when using the preserveInputFileName option./scene AI Preset Selection and other AI correction model files are here. Copy any custom AI Preset Selection model .pnn files to this folder, and include the corresponding presets in the /presets folder.The container includes presets for Universal, Pro and School and Sports AI Preset Selection models. You can export presets from Perfectly Clear Workbench to .preset files. Copy these files to the
mounted /presets volume to make these available for use, by name, by the correction API.
The following environment variables will affect the behavior of the application. These can be set when calling the docker run command, for example with: -e PFC_LOG_LEVEL='debug'.
| PFC_SITE_URL | Set the URL to direct the clients to download the Image from. Defaults to http://localhost |
|---|---|
| PFC_USE_FASTFAE | The face aware exposure algorithm has a fast but less accurate setting that can be toggled on using the PFC_USE_FASTFAE setting. Defaults to "false". |
| PFC_AVX | The container can make use of AVX instruction set to improve performance, if available. Set PFC_AVX to "on", "off" or "auto" (default) which detects if AVX is available and uses it. |
| PFC_LOG_LEVEL | Sets the logging level to one of: debug, info, warning, error. Defaults to "info". |
| PFC_IMG_CACHE_TTL | Sets the time to live for uploaded and corrected images in minutes. Defaults to "60" minutes.
The container checks every 10 minutes for images older than PFC_IMG_CACHE_TTL minutes and deletes them.
|
| PFC_SKIP_EXIF_SOFTWARE | Sets the terms for EXIF Software Skipping instead of passing these as query parameters. If both the query param and this ENV VAR are present, then the query param takes precedence. |
| PFC_PRESERVE_INPUT_FILENAME | If set to true, reuse the same input file name as the output file name inside the container. This is for advanced usage. Defaults to false. If both the query param and this ENV VAR are present, then the query param takes precedence. This is intended to be used when mounting the /input and /output folders from this container to external storage. Doing this allow you to simply copy images to correct to the /input folder, bypassing the PUT call to upload images over HTTP. Then, you can correct the image by using it's filename as the imageKey. The output file will keep this same name and will be saved to the /output folder, again for access without needing HTTP transfers. |
| PFC_SKIP_MODE | Sets the mode to determine what images skip processing. Valid values are "clipart" (default), "legacy", and "none". 'clipart' uses a custom AI model to determine if the image file isn't a true photograph, but is actually clipart. 'legacy' uses a more simple process to attempt to detect non-photographic images, like logos and simple line art. 'none' causes every image to be corrected - and this has the potential to damage images that are actually clipart or other non-photographic content. Note: this parameter is ignored when using AI Preset Selection. |
| PFC_ENABLE_COMPOSITE | Enable/disable composite photo extraction feature - true by default on builds that support this feature. |
Listen address: the server inside the container listens to 0.0.0.0:80.
The server uses the logrus logger package https://github.com/Sirupsen/logrus. As such it supports the same logger levels under the environment variable PFC_LOG_LEVEL. It defaults to info.
It's configured to use json formating for easy parsing in case it's needed. They can be easily read through
docker logs pfc_container.
Server side logs divide into 4 different severity levels:
| Id | Level | Method | Message | Causes | Possible solution | User facing HTTP error |
|---|---|---|---|---|---|---|
| configuredMessage | Error | Configured | Always shown to display paramaters | |||
| unknownErrorLevelMessage | Error | Unknown log level. Defaulting to 'info' | Not recogniced error level | Use a valid error level: 'Debug', 'Info', 'Warning', 'Error' (case insensitive) | ||
| noContentTypeRequestMessage | Debug | PUT /pfc/ | Ignoring request with wrong Content-Type | An user sent a request with an unsuported header | 400 | |
| bodyRequestMessage | Error | PUT /pfc/ | Couldn't read body request | The request image itself couldn't be extracted | Probably wrongly encoded by the user or too much RAM pressure on your container | 503 |
| temporaryFileCreationMessage | Error | PUT /pfc/ | Couldn't create temporary file for input image | Make sure /input inside the container is writable and the machine has enough HDD | 503 | |
| temporaryFileWritingMessage | Error | PUT /pfc/ | Couldn't close temporary file for output | Make sure /input inside the container is writable and the machine has enough HDD | 503 | |
| savingImageMessage | Debug | PUT /pfc/ | Processing image | An image was processed | ||
| noIdMessage | Debug | GET /pfc/{id} | Ignoring request without image key | Client called GET on /pfc/ | Correct client code | 400 |
| invalidIdMessage | Debug | GET /pfc/{id} | Ignoring invalid imageKey | Sanity check for ID failed | Use correct image ID | 400 |
| unknownImageIdMessage | Debug | GET /pfc/{id} | Ignoring request with unknown image key | The given ID does not exist | Use correct image ID | 400 |
| unknownPresetMessage | Debug | GET /pfc/{id} | Unknown preset requested | The preset has not been uploaded or mounted | Make sure to mount the correct preset directory under /presets and the preset is there or correct the calling code | 400 |
| temporaryOutputFileMessage | Error | GET /pfc/{id} | Couldn't create temporary file for output | The /output partition is full or not writable | Make sure the volume or machine has enough capacity or permissions. See exact error under 'error' | 503 |
| temporaryCloseOutputFileMessage | Error | GET /pfc/{id} | Couldn't close temporary file for output | The /output partition is full or not writable | Make sure the volume or machine has enough capacity or permissions. See exact error under 'error' | 503 |
| correctingImageMessage | Debug | GET /pfc/{id} | Processing image | |||
| processingPFCErrorMessage | Error | GET /pfc/{id} | PerfectlyClear processing failed | Processing of the image caused errors check further details under 'error'. | Some specific images causes the corrections to fail and cannot be corrected through PFC. | 503 |
| cleanUpFileMessage | Info | Couldn't delete file | Couldn't delete an image from the /input or /output directories | If mounting them make sure the proper permissions are set | ||
| unknownOutputTypeMessage | Debug | Unknown output file type requested | Only JPEG (or jpg) or PNG are supported | Change the client to only ask for JPEG or PNG | ||
| versionMessage | Info | GET /version | Displays Perfectly Clear SDK version |
The corrected image appears identical to the original image. This is typically due to a failed license verification. Check that the sdk_license folder exists and contains your license key.
I get "couldn't write image" error. This could be because Docker ran out of disk spcace or you reached a quota of docker.
My small image is rejected. Perfectly clear needs images of at least 32px on its short side.
Some Beautify corrections aren't applied. Beautify corrections are disabled on images of aspect ratios higher than 21:1.