Get started
Theory Of Operation
This is how qCrop works:
Every image that is supposed to be automatically cropped to arbitrary aspect ratios in an automated production workflow with qCrop, shall be prepared first by a human user. Preparation takes place in a special piece of software, called the qCrop Client. Basically, the user interactively repositions three visual guides (two frames and a pointer) on top of the master image. Those visual guides are cropping hints and the sophisticated qCrop algorithm takes those hints into account when deciding the clipping area for a given aspect ratio of that image.
During the application of the cropping hints, the qCrop Client provides a live cropping simulation for a selection of common aspect ratios. It is the user’s task to find a setting for the visual guides that provides satisfying cropping results for all aspect ratios in the live previews. A satisfying result is one that preserves the declarative emphasis of the motif in the context of the image’s intended use; that keeps the spatial composition as good as possible; and eschews unsightly clippings - an assessment that, to our believe, can only be achieved by a human being. In qCrop terminology, the person applying the cropping hints is called a qCrop Operator.
Once committed, the cropping hints are automatically embedded in the EXIF metadata of the image, which is not altered in any other way. It is important to understand that applying the qCrop cropping hints does not produce actual cropped versions of the image, but just the information that is needed later on to produce a concrete aspect ratio. The live previews of the qCrop Client are a transient visualization and the assumption is, that if all of the previews look good, so will all other aspect ratios in-between.
Image preparation is performed by qCrop Operators, the cropping hints are universal for all possible aspect ratios of an image, they have to be created only once in a preparation step that takes only a couple of seconds and the hints live forever completely within the image file - no external databases are required to store or access that information.
The qCrop Client is intended to be integrated into production environments. It might be part of your DAM or Content Management system or some custom-made in-house tool. For example, for teaching purposes, we have integrated the qCrop Client into this documentation (you will encounter the qCrop Client in the next chapter).
The second major building block of qCrop is the qCrop Service, a cloud-based application, that will crop an image to any given target size (and therefore any possible aspect ratio). To retrieve a cropped image from the qCrop Service, all that is required is to generate and call a URL consisting of three parts:
- the service address and service type, for example: “https://qcrop.net/crop-to-file”. The service address depends on the actual qCrop environment. There are additional service types, that will be introduced later in this documentation.
- a parameter block for the desired target specification, for example: “w480:h320:mjpg” to get a cropped image 480 pixels wide and 320 pixels high in JPEG format. There are many more parameters, that will be introduced later in this documentation.
- the URL of the master image, for example: “qcrop.cloud/QCROP_SAMPLES/24.jpg”
A complete qCrop Service URL might look like this (and yes, you can click it to see the result and you might want to copy/paste the URL to your browser’s address bar and play with the parameters to get different results):
https://qcrop.net/crop-to-file/w480:h320:mjpg/qcrop.cloud/QCROP_SAMPLES/24.jpg
Upon reception of such a request, the qCrop Service retrieves the image file, crops it to the given target size and file type (obeying the qCrop cropping hints within the image’s metadata) and finally delivers the cropped image to the caller. The cropped image is also cached for faster delivery the next time.
Integration of the qCrop Service typically consists of generating the qCrop URL syntax within the templates of the Content Management System. The qCrop Service can be self-hosted by the customer, or rented as a Saas solution. IT personell, that integrates the qCrop Client or the qCrop Service in existing systems and workflows are called qCrop Integrators in qCrop’s terminology.
Next steps
The next chapter provides a 5 minutes interactive tutorial “Preparing your first image” which is recommended for all audiences as basic quick-start prerequisite for the advanced how-to guides.