1. ActiveX/Java Uploader 8.5.81
  2. ActiveX/Java Uploader
  3. Using ActiveX/Java Uploader
  4. Uploading Images

Rotating and Cropping via ActiveX/Java Uploader

Rotating and cropping are two basic photo-editing actions. ActiveX/Java Uploader provides the built-in image editor to perform these actions manually, you can also configure ActiveX/Java Uploader to rotate and crop images automatically. This topic consists of two parts, namely, rotating images and cropping images, each tells how to configure ActiveX/Java Uploader to upload edited versions of images and edit images automatically.

Rotating Images

There are two approaches to rotating images in ActiveX/Java Uploader:

Manual Rotation

By default manual rotation is enabled in ActiveX/Java Uploader. It means that a user can rotate images either by clicking the rotation control or using the image editor. To upload rotated images you just need to specify a ConverterConverter (ASP.NET)Converter (PHP)converter (JavaScript) with Thumbnail ModeMode (ASP.NET)Mode (PHP)mode (JavaScript), as it is shown in the example below.

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

You may also get rotation angle value on the server and handle it in a way that suites your requirements, for more information, please, see the receiving rotation angle receiving rotation angle in ASP.NET receiving rotation angle in PHP paragraph.

To disable manual image rotation set the Uploader.EnableRotationEnableRotation (ASP.NET)EnableRotation (PHP)enableRotation (JavaScript) property to false.

Automatic Rotation

Automatic rotation means that ActiveX/Java Uploader rotates images automatically, if needed. The decision, whether to rotate an image or not, is based on the EXIF metadata contained in the original image. To turn automatic rotation on you have to set the Uploader.EnableAutoRotationEnableAutoRotation (ASP.NET)EnableAutoRotation (PHP)enableAutoRotation (JavaScript) property to true and add a Thumbnail converter, as it is shown in the following example.

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

Cropping Images

This paragraph describes main approaches to cropping in ActiveX/Java Uploader:

  • Manual cropping is a classic use case for any crop tool. It allows a user to remove unwanted areas from an image.
  • Automatic cropping is a programmatic way to crop each user-selected image using a predefined rectangular area.
  • Uploading rectangular selection is especially helpful in social networking. This allows users to highlight an area of an image.

Manual Cropping

This approach assumes that users can crop images in ActiveX/Java Uploader by selecting a rectangular area of an image via the image editor. To add the crop functionality to the image editor you should set the ImageEditor.EnableCropEnableCrop (ASP.NET)EnableCrop (PHP)enableCrop (JavaScript) property to true. The Converter.ThumbnailApplyCropThumbnailApplyCrop (ASP.NET)ThumbnailApplyCrop (PHP)thumbnailApplyCrop (JavaScript) property indicates if the image thumbnail should be cropped according to the user-selected rectangle; this property makes sense only if a thumbnail converter is specified in uploader configuration.

A user can resize and move the selection rectangle, but you can impose limits on it. For example, you can specify the minimum width and height of the rectangle using the ImageEditor.CropMinSizeCropMinSize (ASP.NET)CropMinSize (PHP)cropMinSize (JavaScript) property. The default value of this property is 50, which means that a user cannot make the selection rectangle smaller than 50x50.

Also you can set an aspect ratio for the selected rectangle using the ImageEditor.CropRatioCropRatio (ASP.NET)CropRatio (PHP)cropRatio (JavaScript) property. CropRatio defines the width-to-height proportion and accepts the following formats: 0.75, 3:4, 3/4. All these values specify the 3:4 aspect ratio of the cropping rectangle in the portrait orientation. A user can change the portrait orientation to landscape and vice versa with ease, but you can deny this by adding ; fixed to the CropRatio value.

The following code snippet enables cropping images on the client side. The selection rectangle has the 3:4 ratio in the portrait orientation only, and the minimum width is 30:

ASP.NET
<aur:Uploader ID="Uploader1" runat="server" >
    <Converters>
        <aur:Converter Mode="*.*=Thumbnail" 
           ThumbnailFitMode="ActualSize"
           ThumbnailApplyCrop="true" />
    </Converters>
    <ImageEditor CropRatio="3/4; fixed" 
        EnableCrop="True" 
        CropMinSize="30"/>
</aur:Uploader>
PHP
$uploader = new Uploader("Uploader1");
$converters = &$uploader->getConverters();
$converter = new Converter();
$converter->setMode("*.*=Thumbnail");
$converter->setThumbnailFitMode("ActualSize");
$converter->setThumbnailApplyCrop(true);
$converters[] = $converter;

$uploader->getImageEditor()->setCropRatio("3/4; fixed");
$uploader->getImageEditor()->setEnableCrop(true);
$uploader->getImageEditor()->setCropMinSize("30");
JavaScript
var u = $au.uploader({
    id: 'Uploader1',
    converters: [{mode: '*.*=Thumbnail', 
        thumbnailFitMode: 'ActualSize',
        thumbnailApplyCrop: true}],
    imageEditor: {
        enableCrop: true,
        cropMinSize: "30",
        cropRatio: "3/4; fixed"}
});
u.writeHtml();

Automatic Cropping

This paragraph describes how to crop each user-selected image automatically. Automatic cropping consists of two parts:

  1. Setting crop bounds. To perform this task you should iterate through user-selected images and specify crop bounds for each of them via the file.cropBounds property. This should be done before upload begins, so we recommend that you place the corresponding code to the BeforeUpload event handler. For more information about client events in ActiveX/Java Uploader, please, see the using events topic.
  2. Upload cropped images. Here, you just create a Thumbnail converter and set its ThumbnailApplyCrop property to true.
Note

Manual cropping does not work in automatic mode, i.e. if a user defines the crop rectangle in the image editor, it will not affect an uploaded image. This may confuse users, thus we recommend that you disable the crop functionality in the image editor by setting ImageEditor.EnableCrop to false.

The following example crops 200 x 200 pixels rectangle out of the center of each user-selected image.

ASP.NET
<script type="text/javascript">
function beforeUploadHandler(){
    var cropWidth = 200;
    var cropHeight = 200;
    var count = $au.uploader('Uploader1').files().count();
    for (var i=0; i < count; i++) {
        var $file = $au.uploader('Uploader1').files().get(i);
        var imageCenterX = $file.width() / 2;
        var imageCenterY = $file.height() / 2;
        var cropBounds = [(imageCenterX - cropWidth/2), 
            (imageCenterY - cropHeight/2), cropWidth, cropHeight];
        $file.cropBounds(cropBounds);
    }
}
</script>

<aur:Uploader ID="Uploader1" runat="server" >
    <Converters>
        <aur:Converter Mode="*.*=Thumbnail" 
           ThumbnailFitMode="ActualSize"
           ThumbnailApplyCrop="true" />
    </Converters>
    <ClientEvents>
        <aur:ClientEvent EventName="BeforeUpload" HandlerName="beforeUploadHandler" />
    </ClientEvents>
    <ImageEditor EnableCrop="False"/>
</aur:Uploader>
PHP
<script type="text/javascript">
function beforeUploadHandler(){
    var cropWidth = 200;
    var cropHeight = 200;
    var count = $au.uploader('Uploader1').files().count();
    for (var i=0; i < count; i++) {
        var $file = $au.uploader('Uploader1').files().get(i);
        var imageCenterX = $file.width() / 2;
        var imageCenterY = $file.height() / 2;
        var cropBounds = [(imageCenterX - cropWidth/2), 
            (imageCenterY - cropHeight/2), cropWidth, cropHeight];
        $file.cropBounds(cropBounds);
    }
}
</script>
<?php
$uploader = new Uploader("Uploader1");
$converters = &$uploader->getConverters();
$converter = new Converter();
$converter->setMode("*.*=Thumbnail");
$converter->setThumbnailFitMode("ActualSize");
$converter->setThumbnailApplyCrop(true);
$converters[] = $converter;

$uploader->getImageEditor()->setEnableCrop(false);

$uploader->getClientEvents()->setBeforeUpload("beforeUploadHandler");
$uploader->render();
?>
JavaScript
function beforeUploadHandler(){
    var cropWidth = 200;
    var cropHeight = 200;
    var count = this.files().count();
    for (var i=0; i < count; i++) {
        var $file = this.files().get(i);
        var imageCenterX = $file.width() / 2;
        var imageCenterY = $file.height() / 2;
        var cropBounds = [(imageCenterX - cropWidth/2), 
            (imageCenterY - cropHeight/2), cropWidth, cropHeight];
        $file.cropBounds(cropBounds);
    }
}

var u = $au.uploader({
    id: 'Uploader1',
    converters: [{mode: '*.*=Thumbnail', 
        thumbnailFitMode: 'ActualSize',
        thumbnailApplyCrop: true}],
    imageEditor: { enableCrop: false },
    events: { beforeUpload: beforeUploadHandler }
});
u.writeHtml();

Uploading Rectangular Selection

Selecting an image area to highlight a person or an object is a popular idea in social networking. In ActiveX/Java Uploader a user actually selects a rectangular area in an image while cropping the image. Boundaries of this rectangle will be uploaded along with the image, no matter what converter mode you use (in this case you can set SourceFile mode). So, on the server side you may receive a user designated selection and show the highlighted area on the image.

To get to know how to obtain crop bounds on the server side, please, see the receiving crop bounds receiving crop bounds in ASP.NET receiving crop bounds in PHP paragraph.

See Also

Reference

Manual