The Adaptive Image Servlet

The AdaptiveImageServlet is responsible for image processing and streaming.

What is an image

An image is a Resource with the sling:resourceType property set to core/wcm/components/image or to any other resource type inheriting from it ¹, with either a fileReference property, pointing to a DAM asset, or a file nt:file subnode, that was uploaded directly to the component node.

Servlet properties

Out of the box, the AdaptiveImageServlet comes with the following configurations:

• sling.servlet.resourceTypes=["core/wcm/components/image"], sling.servlet.selectors=["img"], sling.servlet.extensions=["jpg","jpeg","png","gif"] - for the Core Image v1 URLs
• sling.servlet.resourceTypes=["core/wcm/components/image", "cq/Page"], sling.servlet.selectors=["coreimg"], sling.servlet.extensions=["jpg","jpeg","png","gif"] - for the Core Image v2 URLs

For more details about the servlet's configurations, check the AdaptiveImageServletMappingConfigurationFactory OSGi configuration factory in the configuration console (/system/console/configMgr).

URL formats

The URLs to which the AdaptiveImageServlet is bound have the following pattern:

/content/<project_path>/<page_path>/<component_path>/<component_name>.<configured selectors>.<quality>.<width>.<configured extension>/<timestamp>.<configured extension>

• <quality> defines the image quality for JPEGs (0 lowest quality / size to 100 highest quality / size). Default value is 82.
• <width> defines the client requested width, which is compared against the widths defined by an image's content policy configuration. When this selector is not present, the servlet will resize images to the default resize width, without overscaling.
• <timestamp> defines the last modification date of the currently rendered Image Component; when this suffix is missing or not the expected value, the servlet will redirect the request to the correct URL.

Operations

The following operations, listed in the order in which they're actually applied, can be executed on an image:

1. cropping - based on the value of the com.day.cq.commons.ImageResource#PN_IMAGE_CROP property on the image resource; the value of this property is a CSV list, defining two sets of (x, y) coordinates for the cropping rectangle;
2. rotation - based on the value of the com.day.cq.commons.ImageResource#PN_IMAGE_ROTATE property on the image resource; the value of this property is an Integer number, defining the rotation angle;
3. horizontal flipping - based on the value of the com.adobe.cq.wcm.core.components.models.Image#PN_FLIP_HORIZONTAL property on the image resource; the value is a Boolean;
4. vertical flipping - based on the value of the com.adobe.cq.wcm.core.components.models.Image#PN_FLIP_VERTICAL property on the image resource; the value is a Boolean;
5. resizing - based on the width request selector defined above

Conditional Requests

Conditional requests via the Last-Modified header are supported by the Adaptive Image Servlet, but the caching of the Last-Modified header needs to be enabled in the Dispatcher.

The AEM Project Archetype's sample Dispatcher configuration already contains this configuration.

Picking Renditions

The Adaptive Image Servlet will try to pick the best rendition for the requested image size and type. It's recommended that DAM renditions and Image component allowed widths are defined in sync so that the Adaptive Image Servlet does as little processing as possible. This will improve performance and avoid some images not being correctly processed by the underlying image processing library.

---

1 - all Core Image Component's resource types (core/wcm/components/image/v1/image, core/wcm/components/image/v2/image) inherit from this resource type