Method Description

GraphicImage.copyRect()

Copy a rectangular area from one image to another

Syntax

GraphicImage = GraphicImage.copyRect(src_image, source_rect, dest_rect, mergePercent)

Parameters

The 'GraphicImage.copyRect' method takes 4 parameters:

Results

The 'GraphicImage.copyRect' method returns GraphicImage:

Remarks

copyRect is a powerful method for copying areas of one image to another. By varying the parameters regions can be copied, resized and merged.

The only mandatory parameter is the target image into which a rectangle from the source image is to be copied.

How rectangles are copied

The method takes the following steps to copy a rectangular area from the source image to the destination :

1. Initialise the source rectangle to be the whole of the source image
2. If present, any fields in source_rect are overlaid over the extent of the calculated source rectangle
3. The default destination rectangle is initialised to be identical to the source rectangle calculated in step 2
4. If the dest_rect parameter is present then any of the attributes x, y, w, h that are specified are used to adjust the target rectangle
5. The rectangle is copied from the source to the destination

Copying an entire image

In it's simplest form, copyRect can be used to copy an entire image from a source to a destination :

  var src = new GraphicImage;
  src.make('/images/background.gif','image/gif');

  var image_copy = new GraphicImage;

  // Copy the whole of the source to the new image
  image_copy.create(src.width,src.height);
  src.copyRect(image_copy);
        

Because no source or destination rectangle is specified, the whole of the source is copied to the destination. Note that the default destination rectangle is the same size as the source - not the size of the destination image.

Copying a portion of the source

The source rectangle can be adjusted to comprise a subset of the entire image :

  var src = new GraphicImage;
  src.make('/images/background.gif','image/gif');

  var image_copy = new GraphicImage;

  // Copy all but the outmost 10 pixels to the destination
  image_copy.create(src.width,src.height);
  src.copyRect(image_copy, {x:10, y:10, w:src.width-20, h:src.height-20});
        

Note again that the rectangle into which the source is copied in this case is identical in location (x,y) and dimensions (w,h).

Moving a portion of the source

The destination rectangle can be adjusted to move locate the source rectangle to a different area of the destination image :

  var src = new GraphicImage;
  src.make('/images/background.gif','image/gif');

  var image_copy = new GraphicImage;

  // Copy all but the outmost 10 pixels to the destination, and
  // locate the copied area at the top-left of the destination image.
  image_copy.create(src.width,src.height);
  src.copyRect(image_copy, 
          {x:10, y:10, w:src.width-20, h:src.height-20},
          {x:0,  y:0});
        

Scaling a rectangle

The destination rectangle width (w) and height (h) attributes can be used to resize the rectangle into the destination image :

  var src = new GraphicImage;
  src.make('/images/sample.jpg','image/jpeg');

  // Create a 100x100 thumbnail of the source image
  var thumbnail = new GraphicImage;

  // Copy all but the outmost 10 pixels to the destination, and
  // locate the copied area at the top-left of the destination image.
  thumbnail.create(100 /*width*/, 100 /*height*/);
  src.copyRect(thumbnail, null, {w:100,h:100});
        

In this case the thumbnail comprises the whole of the source image - and so no source rectangle needs to be specified so the second parameter is 'null'. We're not moving the rectangle so the destination rectagle (third parameter) only needs a width (w) and height (h), taking the source x:0 and y:0 as defaults.

Merging pixels

All the examples so far have simply copied pixels into the destination, over-writing anything that was there before. Sometimes it is useful to merge the pixels being copied into the target image. The last parameter allows this merge to be achieved :

  var background = new GraphicImage;
  var image      = new GraphicImage;

  background.make('/images/bkg.gif','image/gif');
  image.make('/images/sample.jpg','image/jpeg');

  // Overlay the 'image' over the background - allowing the background
  // to show through. Resize the source so that it fits the background
  // image
  image.copyRect(background,null,{w:background.width, h:background.height},50);

        

The 'image' is stretched and then overlayed over the background image, merging with 50% of the background showing through.