This documentation is for the old version. Go to the latest Upload Suite docs

Resizing and Recompressing

As you know, any image transformed and sent by Image Uploader is called thumbnail. To upload thumbnails you need to create a ConverterConverter (ASP.NET)Converter (PHP)converter (JavaScript) and set its ModeMode (ASP.NET)Mode (PHP)mode (JavaScript) property to Thumbnail. Then you should use its ThumbnailXXX properties to configure thumbnails. This topic examines resizing and recompressing settings and describes how to handle the situation when a thumbnail cannot be created.

Thumbnail Size

Note

Image Uploader Express and Professional restrict a size (width x height) of each created thumbnail to 3 and 5 megapixels respectively. For example, the size of 1500x1500 thumbnail is 2.25 megapixels (1500 pixels x 1500 pixels = 2.25 megapixels), thus, such a thumbnail can be uploaded with Image Uploader Express. See the Comparison of Image Uploader Editions topic for details.

There are three settings specifying how the original image will be resized to create a thumbnail:

The ThumbnailFitMode is quite complicated, so let us describe it in detail. Fit mode is an important setting for thumbnail creation. It specifies if the thumbnail should be resized at all, and if so, how it should be shrunk to fit the specified dimensions. The ThumbnailFitMode property has the following possible values:

  • Fit means that the original image should be resized to fit the rectangle specified with the ThumbnailHeight and ThumbnailWidth properties. Note that the proportions of the original image will be kept.
  • Width means that the original image should be resized to be no wider than the ThumbnailWidth value. Image is resized proportionally, so the ThumbnailHeight property is ignored in this mode.
  • Height means that the original image should be resized to be no higher than the ThumbnailHeight value. Image is resized proportionally, so the ThumbnailWidth property is ignored in this mode.
  • ActualSize means that dimensions of the original image should be kept; however, it can be rotated or recompressed if necessary.
Note

Image Uploader can only downsize images, so if specified thumbnail size (ThumbnailHeight and ThumbnailWidth) is larger than size of the original image, thumbnail and the original image will be equal in size.

The next example illustrates how to create a thumbnail converter and set its general properties.

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

Thumbnail Quality

The only thumbnail supported file format is JPEG. It means that a thumbnail will be a JPEG image whatever format an original image has. This image format has an ability to balance between file size and image quality. You can specify JPEG quality of a thumbnail via the ThumbnailJpegQualityThumbnailJpegQuality (ASP.NET)ThumbnailJpegQuality (PHP)thumbnailJpegQuality (JavaScript) property which accepts 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, small images have rather low quality (to be loaded quickly), whereas screen-size images have higher quality. The default ThumbnailJpegQuality value is 80 which is the most balanced and common JPEG 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 is 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 the ThumbnailResizeQualityThumbnailResizeQuality (ASP.NET)ThumbnailResizeQuality (PHP)thumbnailResizeQuality (JavaScript) property which is related to the thumbnail quality. This property specifies 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 between the following quality values: Low, Medium, and High. The default is Medium, as soon as it provides fast resizing and good quality at the same time.

Thumbnail Resolution

Image Uploader allows specifying image resolution for created thumbnails via the ThumbnailResolutionThumbnailResolution (ASP.NET)ThumbnailResolution (PHP)thumbnailResolution (JavaScript) property. This parameter is measured in DPI and sets horizontal and vertical resolution of a thumbnail. You can set your custom resolution for thumbnails or keep an original image resolution. The default value of the ThumbnailResolution is 0 meaning that the original image resolution is used.

If Thumbnail is Bigger Than 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 to send 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 ThumbnailCompressOversizedOnlyThumbnailCompressOversizedOnly (ASP.NET)ThumbnailCompressOversizedOnly (PHP)thumbnailCompressOversizedOnly (JavaScript) property 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 images. The thumbnails will simply be created on a background of some color. You can set this color using the ThumbnailBgColorThumbnailBgColor (ASP.NET)ThumbnailBgColor (PHP)thumbnailBgColor (JavaScript) property. To specify desired background color use a hex representation of the RGB triad in HTML-style syntax (#rrggbb). Default background color is white (#FFFFFF).

Keeping Image Color Space

Note

Image Uploader Express and Professional do not keep original color space while creating thumbnails. See the Comparison of Image Uploader Editions topic for details.

An original image may have RGB, CMYK, Grayscale, or some else color space. By default Image Uploader creates RGB thumbnails. If this behavior does not suit you, set the ThumbnailKeepColorSpaceThumbnailKeepColorSpace (ASP.NET)ThumbnailKeepColorSpace (PHP)thumbnailKeepColorSpace (JavaScript) property to true, as a result the thumbnail will be created in the original color space.

If Thumbnail Cannot be Created

It is possible that some specific thumbnail will fail to be created, for example, when the original file is corrupted or it is non-image. To handle this situation specify one more conversion mode (e.g. SourceFile or Icon) after the Thumbnail one. In this case, if applying of the first mode has failed, Image Uploader will try to use the next one.

The following example illustrates the idea.

ASP.NET
<aur:Uploader ID="Uploader1" runat="server">
    <Converters>
        <!-- Send the source file if the thumbnail cannot be created -->
        <aur:Converter Mode="*.*=Thumbnail;*.*=SourceFile" />
        <!-- Send an icon if the thumbnail cannot be created -->
        <aur:Converter Mode="*.*=Thumbnail;*.*=Icon" />
    </Converters>
</aur:Uploader>
PHP
$uploader = new Uploader("Uploader1");
$converters = &$uploader->getConverters();
$converter = new Converter();
//Send the source file if the thumbnail cannot be created
$converter->setMode("*.*=Thumbnail;*.*=SourceFile");
$converters[] = $converter;
$converter = new Converter();
//Send an icon if the thumbnail cannot be created
$converter->setMode("*.*=Thumbnail;*.*=Icon");
$converters[] = $converter;
JavaScript
var u = $au.uploader({
    id: 'Uploader1',
    converters: [
        //Send the original file if the thumbnail cannot be created
        {mode: '*.*=Thumbnail;*.*=SourceFile'}, 
        //Send an icon if the thumbnail cannot be created
        {mode: '*.*=Thumbnail;*.*=Icon'}
    ]
});

See Also

Reference

Manual