Image Uploader allows sending not only original images, but also their rotated, resized and recompressed versions. This may be useful when you need thumbnails, or screen versions suitable for the web, along with the source files.

Creating Thumbnails

General Properties

By default, you can upload up to three thumbnails for each image. Use the UploadThumbnail1XXX, UploadThumbnail2XXX, and UploadThumbnail3XXX properties to specify parameters for the first, second and third thumbnails accordingly. For example, the following properties specify the sizes of thumbnails:

If you need to upload more thumbnails, use the UploadThumbnailAdd method, specifying a fit mode and sizes for extra thumbnails. After that you may address the properties of any thumbnail in a general way through the UploadThumbnailXXX properties.

JavaScript CopyCode imageCopy Code
<script type="text/javascript" src="iuembed.js"></script>

<script type="text/javascript">
function ImageUploader_BeforeUpload() {
    getImageUploader("ImageUploader").UploadThumbnailAdd("Fit", 200, 200);
    //Set the quality of the extra thumbnail
    getImageUploader("ImageUploader").setUploadThumbnailJpegQuality(4, 80);
}

var iu = new ImageUploaderWriter("ImageUploader", 710, 500);

//Other params and event handlers

iu.addEventListener("BeforeUpload", "ImageUploader_BeforeUpload");

//Other params and event handlers

iu.writeHtml();
</script>

The additional thumbnails are sent to the server as the UploadThumbnailN POST fields, where N is the index of the thumbnail.

You can remove thumbnails using the UploadThumbnailRemove method.

Thumbnail Formats And Quality

One of the supported thumbnail file formats is JPEG. It is characterized by the ability to balance between file size and image quality. Using these properties:

you can specify JPEG quality of each thumbnail. The quality is a number in the range [0, 100]. If you specify 0, the file will be extremely small, but the quality will be very low (almost always unacceptable). Alternatively, if you specify 100, the file will be quite large, but JPEG artifacts will be almost invisible. Usually, thumbnails have a rather small quality (to be loaded quickly), whereas screen-size images have a higher quality.

NoteNote

If you set the JPEG quality to a large value, and upload an JPEG file that has poor quality initially, the file size may increase (although the quality will not become better). It is not guarantied that the output JPEG will have the same or less size than the original file. This effect is caused by specifics of JPEG compression algorithm.

That's why if you expect that users will upload poor-quality JPEG files, it makes sense to set the quality to a low value.

There is also another set of properties which is related to the thumbnail quality. This set includes:

These properties specify the quality of resize. The resize quality should not be confused with the JPEG quality: the latter specifies the quality of recompression, not resize. As for now, you may choose only between Medium and High resize quality. The default is Medium as it provides faster resizing.

Read more about all the supported thumbnail file formats in the Handling Files Compression topic.

Thumbnail Fit Modes

A fit mode is an important setting for thumbnail creation. It specifies if the thumbnail should be created at all, and if yes, how it should be resized. There are several properties that set the fit mode:

They all have the same set of possible values:

Off

No thumbnail should be created. This is the default value. Use it when you do not need thumbnails of some type.

Icon

An icon should be sent instead of a thumbnail.

ActualSize

The thumbnail will be equal in size to the original image. However, it may be rotated or recompressed or contain a watermark.

Fit

This value means that the original image should be resized to fit the rectangle specified with the UploadThumbnailXXXWidth and UploadThumbnailXXXHeight properties. Note, that the proportions of the original image will be kept.

Width

This value means that the original image should be resized to be no wider than UploadThumbnailXXXWidth.

Height

This value means that the original image should be resized to be no higher than UploadThumbnailXXXHeight.

If a Thumbnail is Greater Than the Original Image

Image Uploader cannot resize images up. Therefore, if you specify thumbnail dimensions greater than dimensions of the original file, the thumbnail will be actually created with dimensions of the original file. Optionally Image Uploader allows sending original file instead of thumbnail (which is recompressed to JPEG while it is created) in the case when dimensions and file size of original file are not greater than the dimensions and file size of the thumbnail. To enable this behavior you should set the appropriate properties from the set below to true.

Handling Image Transparency

All thumbnails are created as JPEG images, and the JPEG format does not support transparency. That does not mean that you will be unable to create thumbnails for transparent thumbnails. The thumbnails will simply be created on a background of some color. You can set this color using one of these properties:

How to Disable Sending of Original Images

Sometimes it is useful to disable sending of original images. For example, if you create a personal photoblog, you can resize all images to certain dimensions so that they fit the page and could be displayed in the browser relatively quickly. In this case, you do not need the original images—thumbnails will be enough for your readers. So you may disable upload of the original files setting the UploadSourceFile property to false.

If a Thumbnail Cannot Be Created

It is possible that some specific thumbnail will fail to be created, for example, when the original image is corrupted or the source file is non-image. Use these properties to handle this situation:

Using these properties you can specify whether the original file or an icon should be sent to the server, if a thumbnail could not be created.

CopyCode imageCopy Code
//Send the source file if the first thumbnail cannot be created
iu.addParam("UploadThumbnail1CompressionMode", "*.*=Jpeg,SourceFile");

//...

//Send an icon if the second thumbnail cannot be created
iu.addParam("UploadThumbnail2CompressionMode", "*.*=Jpeg,Icon");

Find more detailed information about this set of properties in Handling Files Compression topic.

Rotating

Manual Rotation

You can enable image rotation using the AllowRotate property. If this property is set to true, the user will see the rotation handles (arrows) on thumbnails. When the user clicks one of them, Image Uploader remembers how they are rotated and:

  1. Rotates all thumbnails before uploading them.
  2. Uploads the additional Angle_N fields, where N is the number of the corresponding file. This field contains the angle of rotation (clockwise).

Note, the original file is uploaded unchanged, even if you rotate it using the arrow icons in Image Uploader panes. Only thumbnails are rotated. This is behavior by design. If you send the original file, it is untouched. All the metadata (EXIF, IPTC) is preserved and quality is not lost because no recompression is performed.

If you do not care about recompression or metadata, and would like to have the original image rotated, you can use for this purpose one of the thumbnails with the ActualSize fit mode, as in the example below.

JavaScript CopyCode imageCopy Code
<script type="text/javascript" src="iuembed.js"></script>

<script type="text/javascript">
var iu = new ImageUploaderWriter("ImageUploader", 710, 500);

iu.addParam("AllowRotate", "true");
iu.addParam("UploadSourceFile", "false");
iu.addParam("UploadThumbnail1FitMode", "ActualSize");

iu.writeHtml();
</script>

The first parameter enables rotation. The second parameter disables uploading of the original files (if you still need them, remove this line). The third parameter specifies that the field Thumbnail1_N (where N is the number of the file) contains a rotated, but non-resized version of the image.

Instead of the above method, you can apply rotation on the server side using Angle_N to determine what angle is selected by the user.

Automatic Rotation

Another useful property, AllowAutoRotate makes Image Uploader rotate thumbnails automatically, if needed. The decision, whether to rotate a thumbnail or not, is based on the EXIF metadata, which are extracted from the source images.

Automatic rotation is also applied to thubmnails only. The original files themselves are still uploaded unchanged.

NoteNote

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

Samples

Let's demonstrate some typical imaging settings of Image Uploader.

Digital Photo Printing

You are creating a site for digital photo printing. You need to have original images unchanged to avoid quality loss, and you also need the to represent the images in the user photo gallery. The following settings are the most applicable in this case.

JavaScript CopyCode imageCopy Code
<script type="text/javascript" src="iuembed.js"></script>
<script type="text/javascript">
var iu = new ImageUploaderWriter("ImageUploader", 710, 500);

//...Any other params...

iu.addParam("UploadSourceFile", "true");
iu.addParam("AllowRotate", "true");

iu.addParam("UploadThumbnail1FitMode", "Fit");
iu.addParam("UploadThumbnail1Width", "100");
iu.addParam("UploadThumbnail1Height", "100");
iu.addParam("UploadThumbnail1JpegQuality", "70");

//...

iu.writeHtml();
</script>
Web Gallery

You are creating a photo gallery for browsing images from the web. In this case you do not need to keep original files, and only two kinds of resized images are necessary—thumbnails and screen-size images (e.g. not larger than 640 × 480 pixels). The small size is more important than the high quality. You may the settings below.

JavaScript CopyCode imageCopy Code
<script type="text/javascript" src="iuembed.js"></script>

<script type="text/javascript">
var iu = new ImageUploaderWriter("ImageUploader", 710, 500);

//...other params...

iu.addParam("UploadSourceFile", "false");
iu.addParam("AllowRotate", "false");

iu.addParam("UploadThumbnail1FitMode", "Fit");
iu.addParam("UploadThumbnail1Width", "100");
iu.addParam("UploadThumbnail1Height", "100");
iu.addParam("UploadThumbnail1JpegQuality", "40");

iu.addParam("UploadThumbnail2FitMode", "Fit");
iu.addParam("UploadThumbnail2Width", "640");
iu.addParam("UploadThumbnail2Height", "480");
iu.addParam("UploadThumbnail2JpegQuality", "65");

//...

iu.writeHtml();
</script>

See Also

Samples

Optimized Upload Sample
Server Imaging Sample

Reference

AllowRotate Property
AllowAutoRotate Property
UploadThumbnailFitMode Property
UploadThumbnailWidth Property
UploadThumbnailHeight Property
UploadThumbnailJpegQuality Property
UploadThumbnail1BackgroundColor Property
UploadThumbnail1ResizeQuality Property
UploadThumbnail1CompressionMode Property
UploadThumbnail1CompressOversizedOnly Property
UploadThumbnail1FitMode Property
UploadThumbnail1Width Property
UploadThumbnail1Height Property
UploadThumbnail1JpegQuality Property
UploadThumbnail2FitMode Property
UploadThumbnail2BackgroundColor Property
UploadThumbnail2ResizeQuality Property
UploadThumbnail2CompressionMode Property
UploadThumbnail2CompressOversizedOnly Property
UploadThumbnail2Width Property
UploadThumbnail2Height Property
UploadThumbnail2JpegQuality Property
UploadThumbnail3FitMode Property
UploadThumbnail3BackgroundColor Property
UploadThumbnail3ResizeQuality Property
UploadThumbnail3CompressionMode Property
UploadThumbnail3CompressOversizedOnly Property
UploadThumbnail3Width Property
UploadThumbnail3Height Property
UploadThumbnail3JpegQuality Property
UploadThumbnailAdd Method
UploadThumbnailRemove Method
UploadSourceFile Property

Manual

Working with EXIF and IPTC Metadata
Handling Files Compression