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

Note

Image Uploader Express and Standard restrict several functionalities described in the present article. These editions limit a size of each created thumbnail to 3 megapixels and allow creating thumbnails with 72 dpi resolution only. See the Comparison of Express, Standard, and Professional Versions topic for details.

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

<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.

Note

If you set the JPEG quality to a large value, and upload a JPEG file that has poor quality initially, the file size may increase (although the quality will not become better). It is not guaranteed that the output JPEG will have the same or less size than the original file. This effect is caused by specificity 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 UploadThumbnailXWidth and UploadThumbnailXHeight 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 UploadThumbnailXWidth.

Height

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

Thumbnail Resolution

Image Uploader allows specifying image resolution for created thumbnails. The following properties implement this feature.

Using these properties you can set your custom resolution for each thumbnail or apply a source image resolution.

If a Thumbnail is Bigger Than the Original Image

Image Uploader cannot resize images up. Therefore, if you specify thumbnail dimensions bigger than dimensions of the original file, the thumbnail will be actually created with the dimensions of the original file. Optionally Image Uploader allows sending the original file instead of thumbnail (which is recompressed to JPEG while it is created) in the case when dimensions and file size of the original file are not bigger 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 the 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 the 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 the 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.

JavaScript

//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 the 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 that 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

<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.

There is some difference between the ActiveX version and the Java version if UploadThumbnailXCompressOversizedOnly is true and rotated thumbnail is bigger than source image. In ActiveX version a lossless rotation will be applied to an original image and it will be sent instead of a thumbnail. In Java version a rotated thumbnail will be created from an original image with recompression.

Note

Lossless rotation crops an original image if its width or height is non-divisible by MCU size.

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 thumbnails only. The original files themselves are still uploaded unchanged.

Note

Though it may be convenient, remember that not all the 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 to represent the images in the user photo gallery. The following settings are the most applicable in this case.

JavaScript

<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 x 480 pixels). The small size is more important than the high quality. You may the settings below.

JavaScript

<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>