Image Helper

asString( )

Generates an Image Specifier String from an ImageHelper object.

The asString method generates an image specifier string in the format used internally by the Upload ease applet. This is useful when using callbacks to determine constrained image parameters at upload time (rather than statically at page creation time when the applet is usually embedded). See the callback option for an example of its use.

This method should always be used to generate the internal format so that your implementation does not suffer compatibility issues should the format change in a future release.

setParam( name, value )

Sets an ImageHelper option.

Parameter	Type	Description
name	String	Parameter Name
value	See Parameter Detail	Parameter Value

The setParam method allows you to specify ImageHelper options individually.

Usage example:

...
<script type="text/javascript">
  ...
  var ue = new ueAppletHelper( { options... } );
  ...
  var ih = new ue.ImageHelper();
  ...
  
  ih.setParam('width', 100); //<= constrains image to a width of 100 pixels
  
  ...
</script>
...

setProgressive( enable )

Sets the progressive mode ImageHelper option.

Parameter	Type	Description
enable	Boolean	Enable progressive mode

The setProgressive method is a convenience method for setting the progressive mode output option for image formats that support it (e.g. JPEG).

Usage example:

...
<script type="text/javascript">
  ...
  var ue = new ueAppletHelper( { options... } );
  ...
  var ih = new ue.ImageHelper( { options... } );
  ...
  
  ih.setProgressive(true); //<= enable progressive mode where available
  
  ...
</script>
...

setQuality( quality )

Sets the output quality option on an ImageHelper object.

Parameter	Type	Description
quality	0-10, 'nn%', or x where 0.0 < x < 1.0	Image Output Quality indicator

The setQuality method is a convenience method for setting the output quality option for image formats that support it.

NOTE: Do not use literal 1.0 (100%) except as a String else it will be seen as integer 1 (10%) which will have a large impact on image quality!

Usage example:

...
<script type="text/javascript">
  ...
  var ue = new ueAppletHelper( { options... } );
  ...
  var ih = new ue.ImageHelper( { options... } );
  ...
  
  ih.setQuality(7); //<= sets image output quality to 70%
  ih.setQuality('85%'); //<= sets image output quality to 85%
  ih.setQuality(0.95); //<= sets image output quality to 95%
  
  ...
</script>
...

setSize( width, height )

Sets the size constraint of an ImageHelper object.

Parameter	Type	Description
width	Integer or *	Image Width Constraint
height	Integer or *	Image Height Constraint

The setSize method allows you to conveniently specify the width and/or height constraints of an uploaded image. This is equivalent to calling the ImageHelper setParam for each of the width and height options.

Usage example:

...
<script type="text/javascript">
  ...
  var ue = new ueAppletHelper( { options... } );
  ...
  var ih = new ue.ImageHelper( { options... } );
  ...
  
  ih.setSize(100, '*'); //<= constrains image to a width of 100 pixels
  
  ...
</script>
...

setWatermark( options )

Sets a watermark on an ImageHelper object.

Parameter	Type	Description
options	Object	Watermark options

The setWatermark method allows you to conveniently specify a watermark for an uploaded image. Only one watermark can be specified per image. See the example below for usage:

...
<script type="text/javascript">
  ...
  var ue = new ueAppletHelper( { options... } );
  ...
  var ih = new ue.ImageHelper( { options... } );
  ...
  
  ih.setWatermark({ //<= set image watermark for this image
    image: 'http://MySite.com/images/logo.png', //<= image URL
    top: 5, //<= 5 pixels from top
    left: '50%', //<= 50% from left 
    halign: 'center', //<= horizontally center 
    valign: 'top', //<= vertically align top 
    opacity: '50%' //<= 50% opacity
  });
  
  ...
  var ih2 = new ue.ImageHelper( { options... } );
  ...
  
  ih2.setWatermark({ //<= set text watermark for this image
    text: 'Hello world', //<= text to apply
    bottom: 0.5, //<= 50% from bottom
    right: '10%', //<= 10% from right
    halign: 'right', //<= horizontally align right side
    valign: 'center', //<= vertically align center
    opacity: '70%', //<= 70% opacity
    font: 'Courier-PLAIN-10', //<= Courier plain 9px font
    color: '#eee' //<= Off-white colour
  });
  
  ...
</script>
...

callback

Specifies a callback method that provides the image constraints at upload time.

Type:	String
Values:	Javascript function name
Default:	none

In order to support dynamic configuration at upload time or from user input, Upload ease 1.3 introduces image "callbacks".

When the uploader is generating constrained images for an image and comes upon any with a callback, it ignores the options specified for that constrained image and instead queries the callback for them. This allows the web application to decide at upload time what sort of constrained images (if any) to generate, based on any information including user input and image properties passed to the callback by the Upload ease image generation engine.

The image properties passed to the callback are in the form of a Javascript object with the following properties:

name

The image file name

width

The image width in pixels

height

The image height in pixels

size

The image size in bytes

status

Whether the image appears to be in a recognised format (0 if OK, non-zero otherwise)

If no image is to be generated the callback should return false.

Usage example:

...
<script type="text/javascript">
  ...
  var ue = new UploadEaseHelper( { options... } );
  ...
  var ih = new ue.ImageHelper( { callback: 'getImageConstraints' } ); //<= can be set with options
  ...
  ih.setCallback('getImageConstraints'); //<= can be set individually like this
  ...
  ue.addImage(ih); //<= add the image specifier to the uploader
  ...
  /*
  When the user has selected images to upload and pressed the Upload button
  the getImageConstraints Javascript function (below) will be
  called for each constrained image to be generated. This function can decide
  if and how to constrain the image based on any information including that
  passed into the callback about the source image.

  In this example we create two ImageHelper objects, one that scales and one
  that passes the raw image through. If a GIF file is seen it is passed through
  untouched, otherwise the image is scaled.
  */

  var ihScale = new ue.ImageHelper( { width: 200 } ); //<= scale to maximum width of 200 pixels
  var ihRaw = new ue.ImageHelper( { raw: true } ); //<= pass raw image

  function getImageConstraints( info ) {
    var isGif = info.name.match(/.*\.gif$/i);
    var result = false;
    if (!isGif) {
      result = ihScale.asString();
    } else {
      result = ihRaw.asString();
    }
    return result;
  }
</script>
...

distort

Determines whether or not to allow aspect ratio distortion.

Type:	Boolean
Values:	true, false
Default:	false

If true, distortion of an image's aspect ratio will be allowed when meeting scaling constraints, with potentially non-uniform scaling of each axis to fill the specified extents.

If false, an image's aspect ratio is maintained when meeting scaling constraints, with one axis chosen to determine a scaling factor that will fit the image in the specified extents.

Usage example:

...
<script type="text/javascript">
  ...
  var ue = new UploadEaseHelper( { options... } );
  ...
  var ih = new ue.ImageHelper( { distort: true, ... } ); //<= can be set with options
  ...
  ih.setParam('distort', true); //<= can be set individually like this
  ...
  ue.addImage(ih); //<= add the image specifier to the uploader
  ...
</script>
...

enlarge

Determines whether or not to allow upscaling of images.

Type:	Boolean
Values:	true, false
Default:	false

If true, an image will be enlarged (upscaled) even if it's dimensions are smaller than the specified size (subject to the distort constraint). This is not usually what is wanted (as it can increase the size of an image for no real gain) so is false by default.

If false, an image will not be upscaled if it is already smaller than the specified size.

Usage example:

...
<script type="text/javascript">
  ...
  var ue = new UploadEaseHelper( { options... } );
  ...
  var ih = new ue.ImageHelper( { enlarge: true, ... } ); //<= can be set with options
  ...
  ih.setParam('enlarge', true); //<= can be set individually like this
  ...
</script>
...

pad

Provides padding of the specified colour to the specified extents (if necessary).

Type:	String
Values:	Colour Specifier
Default:	white

When an image is scaled to fit within the specified width and height constraints and the distort option is false, one of it's dimensions will not fill the destination image unless the aspect ratios of the source and destination images happen to be the same. In that case, the destination image will be smaller in one dimension than was specified. The pad option allows you to ensure the destination image is exactly the size required by applying "padding" of the specified colour. This is particularly important where correct page layout would rely on the size of the image.

The padding colour may be specified in several ways, by name (case insensitive):

• black
• blue
• cyan
• darkgray
• gray
• green
• lightgray
• magenta
• orange
• pink
• red
• white
• yellow

or by a hex digit (0-9, A-F) sequence (where r=red, g=green, b=blue, a=alpha):

• #rgb (shorthand for #rrggbb)
• #rgba (shorthand for #rrggbbaa)
• #rrggbb
• #rrggbbaa

Note that alpha values can only be used with image formats that support transparency. Use with other image formats may result in incorrect image colours. Here are some examples of specifying colours this way:

• #F00 (100% red)
• #00F8 (100% blue with 47% transparency)
• #808080 (50% grey)
• #00FF0080 (100% green with 50% transparency)

Note that 100% alpha indicates full opacity, and 0% alpha indicates full transparency.

Usage example (both uses set the padding colour to yellow):

...
<script type="text/javascript">
  ...
  var ue = new UploadEaseHelper( { options... } );
  ...
  var ih = new ue.ImageHelper( { pad: '#ff0', ... } ); //<= can be set with options
  ...
  ih.setParam('pad', 'yellow'); //<= can be set individually like this
  ...
</script>
...

progressive

Determines whether or not progressive output mode is selected for an image.

Type:	Boolean
Values:	true, false
Default:	false

If true, and the image format supports it, the constrained image will be written out in progressive mode.

See the setProgressive() helper method for more examples.

Usage example:

...
<script type="text/javascript">
  ...
  var ue = new UploadEaseHelper( { options... } );
  ...
  var ih = new ue.ImageHelper( { progressive: true, ... } ); //<= can be set with options
  ...
  ih.setProgressive(true); //<= can be set individually like this
  ...
  ue.addImage(ih); //<= add the image specifier to the uploader
  ...
</script>
...

quality

Determines the quality/compression trade-off factor for an image.

Type:	Image Quality/Compression indicator
Values:	0-10, 'nn%', or x where 0.0 < x < 1.0
Default:	none

If the image format supports it, this option specifies the quality/compression trade-off when the image is written.

This can be specified as an integer 0-10, as a percentage, or as a floating point number from 0.0 - 1.0 (although 1.0 should not be used except in quotes as it will be seen as the integer 1 and be interpreted as 10%).

Lower values put greater emphasis on compression (minimising file size) at the expense of quality, while the converse is true for higher values.

See the setQuality() helper method for more examples.

Usage example:

...
<script type="text/javascript">
  ...
  var ue = new UploadEaseHelper( { options... } );
  ...
  var ih = new ue.ImageHelper( { quality: '85%', ... } ); //<= can be set with options
  ...
  ih.setQuality('85%'); //<= can be set individually like this
  ...
  ue.addImage(ih); //<= add the image specifier to the uploader
  ...
</script>
...

raw

Determines whether the image should be processed or uploaded in its raw file format.

Type:	Boolean
Values:	true, false
Default:	false

As well as specifying one or more thumbnails or other constrained images you may also want to upload the original image unchanged, which is the purpose of the raw option. Although the width & height constraints would be ignored anyway, they may each be specified as '*' for clarity.

Usage example:

...
<script type="text/javascript">
  ...
  var ue = new UploadEaseHelper( { options... } );
  ...
  var ih = new ue.ImageHelper( { raw: true, ... } ); //<= can be set with options
  ...
  ih.setParam('raw', true); //<= can be set individually like this
  ...
</script>
...

scaleHint

Specifies the preferred scaling quality/speed trade-off.

Type:	Image scaling method hint
Values:	averaging | fast | replicate | smooth
Default:	System dependent

The scaleHint option gives Upload ease a hint as to how images should be scaled and the trade-off between quality and speed.

This option determines how the image is up-scaled or down-scaled and should not be confused with the quality option that determines the quality/compression trade-off.

Possible values and their meanings for scaleHint are:

averaging

Use the Area Averaging image scaling algorithm, a simple algorithm that produces smoother results than the nearest neighbor algorithm.

fast

Choose an image-scaling algorithm that gives higher priority to scaling speed than smoothness of the scaled image.

replicate

Uses a simple algorithm to produce pixels for an image of the specified size by replicating rows and columns of pixels to scale up or omitting rows and columns of pixels to scale down.

smooth

Choose an image-scaling algorithm that gives higher priority to image smoothness than scaling speed.

If no scaleHint is specified the system default is chosen, which will usually favour speed rather than quality. For the best and most consistent results we recommend always specifying the scaleHint. Furthermore, unless there is a compelling reason not to, we recommend the use of the smooth hint for the best image quality.

Usage example:

...
<script type="text/javascript">
  ...
  var ue = new UploadEaseHelper( { options... } );
  ...
  var ih = new ue.ImageHelper( { scaleHint: 'smooth', ... } ); //<= can be set with options
  ...
  ue.addImage(ih); //<= add the image specifier to the uploader
  ...
</script>
...

tag

Specifies a "tag" to append to the uploaded image's filename part (inserted before the file extension).

Type:	String
Values:	Tag Name
Default:	WIDTHxHEIGHT

The tag option is provided in order to conveniently distinguish between different constrained images uploaded to the server. For example, you may wish to upload small / thumbnail, medium, and large versions as well as the original image to be displayed in different parts of your site.

While the default tag (<width>x<height>) might be fine, what if you decided to change the width & height to suit a new layout? The tag option would allow you to upload the constrained images with "_small" / "_thumb", "_medium", and "_large" suffixes and thereby making them independent of their sizes.

Usage example (setting tag to "_thumb":

...
<script type="text/javascript">
  ...
  var ue = new UploadEaseHelper( { options... } );
  ...
  var ih = new ue.ImageHelper( {
    width: 64,
    height: 64,
    tag: '_thumb' //<= can be set with options
  } );
  ...
  ih.setParam('tag', '_thumb'); //<= can be set individually like this
  ...
</script>
...

type

Specifies the format of the uploaded image.

Type:	String
Values:	'bmp', 'gif', 'jpg', 'png', ...
Default:	none

The type option specifies the image format used to produce an uploaded image. It can be used to ensure all uploaded images are in a given format, such as 'png', for example.

Usage example:

...
<script type="text/javascript">
  ...
  var ue = new UploadEaseHelper( { options... } );
  ...
  var ih = new ue.ImageHelper( { type: 'png', ... } ); //<= can be set with options
  ...
  ih.setParam('type', 'png'); //<= can be set individually like this
  ...
</script>
...