How to use the Crop-to-File Service

Crop-to-File is the most important cCrop service. It is used to produce a cropped version of an image (which – in ideal circumstances – has been provided with qCrop cropping hints before).

The Crop-to-File Service URL

The Crop-to-File service URL consists of four elements:

  1. Service scheme + host
  2. Route
  3. Cropping parameters
  4. Image URI (without the scheme)

Service scheme and host

Please refer to Accessing the qCrop Server for details about the Service scheme and host.

For training and evaluation purposes, use https://qcrop.net/ as a service scheme and host.


Route

The second parameter of the URL (the first element of the path) is called the route – it specifies which service is requested from the server. For image cropping, the route is crop-to-file/.


Cropping parameters

The cropping parameters describe the desired constitution of the resulting, cropped image (in qCrop’s terminology: the target). Cropping parameters consist of a keyword or key character, optionally followed by some value. The parameters are separated with colon (”:“) and the parameter block is closed with a slash (”/“).

The most important parameters are:

Size related

  • w<WIDTH> : the width of the target image in pixels, e.g.: w1900.

  • h<HEIGHT> : the height of the target image in pixels, e.g.: h1020.

  • a<WIDTHxHEIGHT> : the aspect ratio of the target image as numerical relation. This means that the values for width and height have no unit. Examples: a1920x1020; a4x3; a100x100.

If the w- and h-parameters are defined, the target image will be cropped to exactly that size. Example: w1920:h1080.

If the a-parameter is used together with one of the w- or h-parameters, then the missing size parameter will be calculated from the given size parameter in respect to the given aspect ratio. Example: w1920:a4x3.

If only the a-parameter is passed to the service, the target image will be cropped to the width of the source image and the height will be calculated according to the aspect ratio of the a-parameter. Example: a1x1.

It shall be avoided to pass all three size related parameters (a, w and h) together as there might be a contradiction of the aspect ratio calculated from w and h and the a-parameter. In this case, the a-parameter is completely ignored and no error is reported. Example: a4x3:w800:h200 will crop to 800 by 200 pixels.

If no size parameters are passed to the service at all, the qCrop algorithm will use the width and height values of the source image for the target.

Notice: former versions of qCrop allowed the s-parameter for a combined definition of w and h. This parameter is still supported for backward compatibility, but will be deprecated in future releases.

Filetype related

The target image can be one of three mimetypes: JPEG, TIFF or PNG.

  • m<MIMETYPE> : the mimetype of the target image. <MIMETYPE> shall be one of the following three-letter codes: jpg, tif, png. If no m-parameter is passed, or an invalid mimetype code is passed with the m-parameter, the qCrop service will default to jpg. Examples: mjpg, mtif, mpng.

  • q<PERCENTAGE> : the compression quality of the target image. Currently this parameter only applies to targets of type JPEG, it is ignored for other mimetypes. The <PERCENTAGE> value can range from 1 (extremely small file size, but poor quality) to 100 (larger filesize, but excellent quality). If this parameter is not passed, it will default to 75.

Example: to produce a JPEG file with a quality of 75%, include mjpg:q75 in the parameter block.

Notice: Future versions of qCrop will support additional mimetypes.

Color related

Two parameters can be passed for color management:

  • c<PROFILENAME>: target color profile. Example: csRGB.

  • stripColorProfile: if set, the color profile will be removed from the target.

Color management is a complex topic and requires some background knowledge as well as careful considerations. Please refer to the comprehensive documentation of the color related parameters and a full list of supported color profiles in the dedicated reference article Color Management.

Other parameters

Crop-to-File supports a couple of additional parameters, most of which deal with pixel density and physical resolutions and dimensions. Those parameters are mainly relevant in the print domain, but hardly ever in digital publishing. Please refer to Crop-to-File URL syntax for a full reference of those parameters.


Image URI

The image URI is the web address of the source image with the scheme omitted. Any accessible image URL can be used on our demo server, but productive instances of the qCrop Server might be limited to dedicated domains.

Example: **qcrop.cloud/QCROP_SAMPLES/01.jpg”

Access to the source image will be per HTTP or HTTPS in dependance of the remote host’s preferences.


Sample URLs

Here is a list of valid sample URLs for the Crop-To-File service (source images might not contain qCrop cropping hints and therefore produce poor optical cropping results - this URLs are only intended for syntactical reference). Feel free to copy this addresses to your browser and play with the parameters according to this documentation.

https://qcrop.net/crop-to-file/w760:h480:mjpg/qcrop.cloud/QCROP_SAMPLES/12.jpg

https://qcrop.net/crop-to-file/w760:a4x3:mjpg:q75:csRGB/qcrop.cloud/QCROP_SAMPLES/35.jpg

https://qcrop.net/crop-to-file/w800h400:prRes80ppcm:phyW20cm:mjpg:q75:csRGB:noCache/qcrop.cloud/QCROP_SAMPLES/18.jpg

© 2020-2021, append[x] GmbH, Egling-Endlhausen