Rotating and Cropping Images in HTML5/Flash Uploader

Supported technologies: Adobe FlashHTML 5

HTML5/Flash Uploader may not just resize images, but also perform additional manipulations - crop and rotate them. Those operations can be done both automatically or manually (by the user). Let's see how to configure the product to carry out those operations.

Allow user rotating images manually

By default, manual rotation is enabled in HTML5/Flash Uploader. It means that a user may click the rotation button on a toolbar which appears when an image is selected. This feature may be turned off using the ImageUploaderFlash.EnableRotationEnableRotation (ASP.NET)EnableRotation (PHP)enableRotation (JavaScript) property - just change it to false

However sometimes you may notice that after the upload the image is not changed at all. To prevent this, make sure that you have a ConverterConverter (ASP.NET)Converter (PHP)converter (JavaScript) with ModeMode (ASP.NET)Mode (PHP)mode (JavaScript)=Thumbnail, rather than SourceFile. In the latter case, HTML5/Flash Uploader does not apply any imaging operations at all and sends the file as is.

What if you don't want to resize the image, but still need to have it rotated? Just use the ThumbnailFitModeThumbnailFitMode (ASP.NET)ThumbnailFitMode (PHP)thumbnailFitMode (JavaScript)=ActualSize as demonstrated below.

ASP.NET
<aur:ImageUploaderFlash ID="Uploader1" runat="server" EnableRotation="true">
    <Converters>
        <aur:Converter Mode="*.*=Thumbnail" ThumbnailFitMode="ActualSize" />
    </Converters>
</aur:ImageUploaderFlash>
PHP
$uploader = new ImageUplaoderFlash("Uploader1");
$uploader->setEnableRotation(true);
$converters = &$uploader->getConverters();
$converter = new Converter();
$converter->setMode("*.*=Thumbnail");
$converter->setThumbnailFitMode("ActualSize");
$converters[] = $converter;
JavaScript
var u = $au.imageUploaderFlash({
    id: 'Uploader1',
    enableRotation: true, // true by default    
    converters: [{mode: '*.*=Thumbnail', 
        thumbnailFitMode: 'ActualSize'}]
});

Sometimes it is useful to know how the image was rotated exactly (e.g. to give the user an opportunity to undo the rotation). To address this issue, the uploader sends the rotation angle value to the server along with files in the Angle_N field. If you are using PHP library or ASP.NET control, check out the receiving rotation angle paragraph receiving rotation angle in ASP.NET receiving rotation angle in PHP in the appropriate article.

Automatically fix the image orientation using EXIF

Most of the photos taken with modern cameras or smartphones know their orientation. When a person rotates a camera to take a portrait photo, G-sensor inside the camera detects the angle and saves it among the EXIF fields of a photo. HTML5/Flash Uploader may read this angle and rotate the image, if needed.

To turn automatic rotation on you have to set the ImageUploaderFlash.EnableAutoRotationEnableAutoRotation (ASP.NET)EnableAutoRotation (PHP)enableAutoRotation (JavaScript) property to true. Note, it is turned off by default, so you should add this property explicitly.

Like with the manual rotation, don't forget to add a Thumbnail converter. Here is a code example.

ASP.NET
<aur:ImageUploaderFlash ID="Uploader1" runat="server" EnableAutoRotation="true">
    <Converters>
        <aur:Converter Mode="*.*=Thumbnail" ThumbnailFitMode="ActualSize" />
    </Converters>
</aur:ImageUploaderFlash>
PHP
$uploader = new ImageUplaoderFlash("Uploader1");
$uploader->setEnableAutoRotation(true);
$converters = &$uploader->getConverters();
$converter = new Converter();
$converter->setMode("*.*=Thumbnail");
$converter->setThumbnailFitMode("ActualSize");
$converters[] = $converter;
JavaScript
var u = $au.imageUploaderFlash({
    id: 'Uploader1',
    enableAutoRotation: true,
    converters: [{mode: '*.*=Thumbnail', 
        thumbnailFitMode: 'ActualSize'}]
});
Note

Though it may be convenient, remember that not all the cameras recognize orientation properly. Reading EXIF data also slows down the process of folder scanning, and if the folder contains a lot of images, the decrease in speed may be noticeable.

Enable cropping tool

In certain scenarios, you may want your users to send only a part of an image, i.e. to crop them. For example, you need to force all images to have the particular aspect ratio, or your users need to higlight some portion of an image.

To make it possible, HTML5/Flash Uploader has an image editor module. To enable it, use the ImageUploaderFlash.EnableImageEditorEnableImageEditor (ASP.NET)EnableImageEditor (PHP)enableImageEditor (JavaScript) property. When it is true, an additional button appears on an upload item toolbar which opens the image editor.

Let's see an example how the image editor is configured to work as a cropping tool which forces the user to crop the image with 4x3 aspect ratio and the image should not be smaller than 100 pixels in any of dimensions:

ASP.NET
<aur:ImageUploaderFlash ID="Uploader1" runat="server" EnableImageEditor="true">
    <ImageEditor EnableCrop="true" DefaultTool="crop" CropRatio="4:3" CropMinSize="100" />
    <Converters>
        <aur:Converter Mode="*.*=Thumbnail" ThumbnailFitMode="ActualSize" ThumbnailApplyCrop="true" />
    </Converters>
</aur:ImageUploaderFlash>
PHP
$uploader = new ImageUplaoderFlash("Uploader1");
$uploader->setEnableImageEditor(true);
$uploader->getImageEditor()->setEnableCrop(true);
$uploader->getImageEditor()->setDefaultTool("crop");
$uploader->getImageEditor()->setCropRatio("4:3");
$uploader->getImageEditor()->setCropMinSize(100);
$converters = &$uploader->getConverters();
$converter = new Converter();
$converter->setMode("*.*=Thumbnail");
$converter->setThumbnailFitMode("ActualSize");
$converter->setThumbnailApplyCrop(true);
$converters[] = $converter;
JavaScript
var u = $au.imageUploaderFlash({
    id: 'Uploader1',
    enableImageEditor: true,
    imageEditor: {
        enableCrop: true,
        defaultTool: 'crop',
        cropRatio: "4:3",
        cropMinSize: 100
    },
    converters: [{mode: '*.*=Thumbnail', 
        thumbnailApplyCrop: true,
        thumbnailFitMode: 'ActualSize'}]
});

For better understanding about the capabilities of the image editor, see the ImageUploaderFlash.ImageEditorImageEditor (ASP.NET)ImageEditor (PHP)imageEditor (JavaScript) class reference. Meanwhile, let's see take a closer look into the ImageEditor.CropRatioCropRatio (ASP.NET)CropRatio (PHP)cropRatio (JavaScript) property.

This property configures the cropping tool constraints. For the freeform crop, just leave it as an empty string. Or you can set a specific aspect ratio, for example, "4:3" or "3/2" (any float number is accepted as well). If you want to keep the original image aspect ratio, just set it to "orig". In case if you want to prevent the user to change the cropping frame orientation, just append ";fixed" to the end of the line.

Take a look at the Cropping Tool demo application to see it in action.

What if you want to give a user an opportunity to undo crop after the upload? To allow this, HTML5/Flash Uploader allows turning off the crop operation for a particular converter using the Converter.ThumbnailApplyCropThumbnailApplyCrop (ASP.NET)ThumbnailApplyCrop (PHP)thumbnailApplyCrop (JavaScript) property and it sends the crop bounds to the server along with files, similar to the rotation angle (the POST variable name is CropBounds_N). This way you have an opportunity to apply the crop on the server yourself.

It is possible to access the crop bound using the JavaScript using the file.cropBounds function. You can both read the crop bounds (e.g. to verify its aspect ratio) or set it and, therefore, initialize the crop frame. However there is even simpler method to do this - see the next paragraph.

Automatically crop the image

Sometimes you need to crop images automatically, without the user interaction. For example, your page is designed to display square 100x100 thumbnails.

To achieve this, there is no need to use the Image Editor functionality of the HTML5/Flash Uploader. All you need is to set the Converter.ThumbnailFitMode to Crop and specify the necessary Converter.ThumbnailWidthThumbnailWidth (ASP.NET)ThumbnailWidth (PHP)thumbnailWidth (JavaScript) and Converter.ThumbnailHeightThumbnailHeight (ASP.NET)ThumbnailHeight (PHP)thumbnailHeight (JavaScript):

ASP.NET
<aur:ImageUploaderFlash ID="Uploader1" runat="server">
    <Converters>
        <aur:Converter Mode="*.*=Thumbnail" 
            ThumbnailFitMode="Crop" 
            ThumbnailWidth="100" 
            ThumbnailHeight="100" />
    </Converters>
</aur:ImageUploaderFlash>
PHP
$uploader = new ImageUplaoderFlash("Uploader1");
$converters = &$uploader->getConverters();
$converter = new Converter();
$converter->setMode("*.*=Thumbnail");
$converter->setThumbnailFitMode("Crop");
$converter->setThumbnailWidth(100);
$converter->setThumbnailHeight(100);
$converters[] = $converter;
JavaScript
var u = $au.imageUploaderFlash({
    id: 'Uploader1',
    converters: [{mode: '*.*=Thumbnail', 
        thumbnailFitMode: 'Crop',
        thumbnailWidth: 100,
        thumbnailHeight: 100
    }]
});

As a result, during the thumbnail generation, the uploader will create a square frame, center it, crop the image using this frame and resize it. Of course, the frame does not have to be square - you can specify any aspect ratio by setting different Converter.ThumbnailWidth and Converter.ThumbnailHeight.

See Also

Reference

Manual