Jcrop Sizing Issues

Jcrop » Sizing Issues

jcrop.png

Jcrop works on all sizes of images. However, some interface issues arise if the image is larger than the browser window. This document presents several approaches allowing an end-user to crop a scaled down image, while Jcrop returns coordinates mapped to the "true" image size.

Terminology and Concepts

In version 0.9.2, the concept of true image size is introduced. The true image size represents the natural size of the image outside of Jcrop. True image size is either set or calculated, and this is used to determine the scale of the returned coordinates.

Additionally, this document will refer to the size of the image being cropped in the Jcrop interface as the effective or interface size. To indicate the original size of the image without modifications, the term natural or true (size, coordinates) will be used.

Box Sizing Method

Box Sizing is the easiest way to handle larger images with Jcrop. This approach scales large images automatically within the browser. Constraints can be set on height and/or width, and Jcrop will handle the rest automatically.

Two options apply to Box Sizing:

boxWidth integer Maximum width of cropping area, (default: 0, no limit)
boxHeight integer Maximum height of cropping area (default: 0, no limit)

One or both can be set. If so, the image will be proportionally scaled to fit within these limits. If the image is already within that size, no scaling will occur. Jcrop automatically returns transformed coordinates mapped to the initial image size.

An example of this approach:

$(function() {
    $('#cropbox').Jcrop({ boxWidth: 450, boxHeight: 400 });
});

Jcrop will scale the image proportionally within the box dimensions and return the coordinates based on the image's initial size.

Explicit Sizing Method

For exact control, these values can be set manually. Using this approach, the height and width are already set on the image object in the DOM (usually in the HTML, see below). Jcrop is invoked with a specified true image size, and returns coordinates accordingly.

To set the true image size, pass an array of [w,h] to this option:

trueSize array Specify the true size of the image

Jcrop will return coordinates mapped to this specified true size. If set in this manner, trueSize will override any other calculation or setting for true image size.

An example of this approach:

<script>
    $(window).load(function() {
        $.Jcrop('#cropbox',{ trueSize: [500,370] });
    });
</script>
...
<img src="test.jpg" width="450" height="333" />

Important: You must use the API invocation method when using the explicit sizing method. Also note if you do not set trueSize but do set width and height for the image other than it's natural size, the coordinates returned will match the size of the scaled image. This may or may not be what you want.

API Methods on Scaled Images

Since v0.9.6, API methods setSelect and animateTo automatically scale coordinate input. Other options that use coordinates such as minSize and maxSize currently do not automatically scale input. Ideally, interfacing with the API should be done with true coordinates and the scale of the Jcrop widget should be a display issue. In cases where this is not the behavior, Jcrop will move closer to that goal in subsequent releases.

Considerations

Some browsers suffer a performance hit when working on scaled images. The operation of Jcrop is the same whether an image is scaled or not, so I must conclude this is an issue beyond my control. To solve all of these problems, the ideal solution to large images is to pre-size them on the server:

  • Pre-sized image is created server-side
  • Invoke as per Explicit Sizing Method (setting trueSize)
  • User crops representative pre-sized image
  • Jcrop transforms the coordinates automatically

The advantages to this approach are:

  • Resampled image looks better than resized image in most browsers
  • Potentially better cropping performance vs. browser-scaled image
  • More effectively handles very large images (less bandwidth)

Happy Cropping!