Image

Description

This class implements a (possibly invisible) image-manipulation object, using the ImageMagick^TM open-source package. It can be used to load images from file in over 90 different formats, transform them, optionally draw on them from APLX, and save them, again in a wide range of different formats.

It can also be used to manipulate an APL pixel array, i.e. a matrix of pixel values where each point is represented by an integer which encodes the Red, Green and Blue intensities. This can be created directly in APL, or can be read from the bitmap property of the System object (i.e. retrieved from the Clipboard), or from a Chart, Picture or Window. It can also be created using the Draw method GetBitmap keyword.

You can also use the Draw method to 'draw' directly on the off-screen bitmap of an Image object, allowing you to create your own image from within APLX, or add graphic elements to an existing image read from file. You can then save the image in one of the many formats supported by ImageMagick.

A single Image object can contain a sequence of actual images. These might, for example, be displayed as a moving image in an animated GIF. The Image object also allows you to combine images, for example for place a semi-transparent foreground picture on top of a background picture.

Note that the Image object itself is not visible, and cannot be placed directly on a window. Instead, it can either be created at the top level (child of the System object), or be a child of a Picture object. In the latter case, it effectively becomes visible, since whenever it is changed, the Picture object will automatically transfer the current bitmap of the Image to the Picture.

About ImageMagick

ImageMagick is copyright ImageMagick Studio LLC, a non-profit organization. ImageMagick is distributed under a Apache-style license, which is approved by the Open Source Initiative. ImageMagick is available for free, may be used to support both open and proprietary applications, and may be redistributed without fee, subject to the conditions of the license supplied with the software. It is available for a wide variety of platforms, and can be used in conjunction with APLX under Windows, Linux, and MacOS X (APLX cannot interface to it under Mac OS 9). For more information, visit http://www.imagemagick.org.

Installation of ImageMagick

To use the Image object, you must have ImageMagick version 6.1 or later installed on your system. If it is not already installed, when you try to create the Image object, APLX will put up a dialog box to report the error. An APL DOMAIN ERROR will also be raised.

ImageMagick may be installed already on your system (for example, many Linux distributions include it as standard). If not, the easiest way to install ImageMagick is to download pre-built Binary releases from http://www.imagemagick.org, or a mirror site. Versions for Windows, MacOS and Linux are available. We recommend you use the 8-bit versions (8 bits per pixel color). At the time of writing, the files you need to install are:

Windows: ImageMagick-6.1.9-Q8-windows-dll.exe ('dynamic' version)

Linux: ImageMagick-i686-pc-linux-gnu.tar.gz

MacOS X: ImageMagick-powerpc-apple-darwin7.8.0.tar.gz

If you have installed ImageMagick and APLX still reports that it cannot find it, the most likely reason is that the shared library path is not set up correctly. Check first that the ImageMagick utility programs (such as 'display' and 'convert') work correctly outside APLX.

Under Windows, the ImageMagick directory (under 'c:\Program Files') should be in the path. Under Linux, the ImageMagick shared library files should be in /usr/lib.

Supported Graphics Formats

The exact set of supported file formats will depend on the platform, the ImageMagick version, and on whether you have installed extensions called 'delegates'. Each format is identified by a tag string (also used, by default, as the file extension). Some of the most important formats include:

Not all formats will necessarily be available, and some may be read-only (i.e you can read the format into the image, but not write it out in that format). Note that APLX itself does not contain any format-conversion code for the Image object; this is done in the ImageMagick package or 'delegates', which you install separately.

You can determine which formats are supported by reading the formats property of an Image object.

Loading or creating an image

You can either load an existing image from file, or from an APL pixel array, or from the Clipboard, or you can create it from scratch using the Draw method of the Image itself.

Load method: This takes a single argument, which is a character vector containing the full filename of an image file, in one of the supported formats, which you want to display or manipulate. If you specify an empty vector for the file name, APLX will display a dialog asking the user to select an image file. You can also use pseudo-filenames for certain built-in images and patterns, such as 'magick:logo' or 'magick:rose'. See the ImageMagick documentation for more details. The current image, if any, is replaced (unless you have set the style property so that images are appended).

bitmap property: This is an integer matrix, with one element per pixel. Each pixel is encoded as 256 ⊤ Blue Green Red. If you write to this property, any current image is replaced with the pixels you specify (unless you have set the style property so that new images are appended). You can create the pixel array directly in APL, or read it from the bitmap property of the System object (read from Clipboard), of a Chart object, or of a Picture object.

Paste method: This method takes no arguments. It causes any picture on the Clipboard to be loaded into the Image.

In order to create the image from scratch using the Draw method, you need first to set the image size using the imagesize property. You then use the Draw method in the normal way.

Saving or reading back an image

Similarly, you can save the image to a file, read it back into an APL pixel array, or transfer it to the Clipboard:

Save method: This method again takes a character vector argument, which is the file name under which you want to save the image. You can specify the format in which you want to save it by setting the format property before calling this method, or alternatively allow the format to be determined automatically from the file extension. If you specify an empty vector for the filename, APLX displays a dialog allowing the user to specify the file name and type.

In this example, an invisible Image object is used to load an image file in JPEG format, and save it out as a PDF (Adobe Acrobat) file:

      Img←'⎕' ⎕NEW 'Image'
      Img.Load 'c:\temp\sds.jpg'
      Img.Save 'c:\temp\sds.pdf'

bitmap property: As well as writing the image out to file, you can also read it back at any time from the bitmap property, as an integer array of pixel values. (The size of the returned array will be the same as the internal image size, as returned by the imagesize property). You can then manipulate the pixel array further in APL, or write it to the Clipboard using the System object, or display it on a Picture object. You can also display it on a window (or other control), or print it, using the Draw method GetBitmap keyword.

Copy: This method takes no arguments. It causes the currently-active image to be copied to the Clipboard as a bitmap.

Main properties of the Image object

imagesize or bitmapsize: This is a two-element numeric vector, which contains the height and width of the image, in the current scale units. (We recommend that you always use scale 5, pixels, for Image objects). In most cases, the initial size of the image is set automatically when you Load the image from file, or write an array to the bitmap property. If you are creating a new image from scratch using the Draw method, you should first specify the size of the image by writing to the imagesize property; this will create a new image of the size specified, using the current background color. If you write a new value to the imagesize property of an existing image, it will be re-scaled to the new size.

file: A character vector, which contains the name of the image file from which the image was loaded (if any). Writing to this property causes the image to be loaded from the named file. Writing an empty vector will bring up a dialog allowing the user to chose the name.

format: A character string, which is the tag associated with the file format to be used when the Image is saved to file, for example 'BMP' or 'GIF' or 'PDF'. (It should be one of the values returned by the formats property). When you load a graphics file, this property will initially be set to the original format. If you change it, when the file is saved the new format will be used. (You can also set the format implicitly by the file extension).

formats: Read-only Returns a nested vector of character strings, which are the tags for the formats supported by the underlying ImageMagick package.

quality: Some image formats allow you to specify an image-quality parameter, where higher values give a better-quality image but require a larger file size. This integer-scalar property allows you to set or retrieve the quality parameter. The exact meaning depends on the image format. See the ImageMagick documentation for more details.

colorback or colourback: Sets the background color for the image. This is used to fill the new area when a creating a new image by setting the imagesize property, and for filling any new regions which are created when you transform the image, for example in a rotate or shear operation. You can specify it either as a three-element vector of Red Green Blue values (each in the range 0 to 255), or as a single integer of 256 ⊤ Blue Green Red. When you read the property, APLX returns the single-integer form.

Handling multiple images within a single Image object

A single Image object may contain multiple images, although only some file formats support this feature. The following properties apply to multiple images:

imagecount: Read-only An integer scalar, containing the number of images in the object.

imageindex: An integer scalar, which specifies the currently active image, in index origin 1. This is therefore a number in the range 1 to imagecount. The currently-active image is the one on which any transformations or drawing takes place, and is also the one which will be displayed by the parent Picture object, if appropriate. (You can thus display an animated image by using a timer to advance the imageindex value at regular intervals.)

style: This is an integer scalar. The default value of 0 means that, when you create a new image using the Load or Paste method, or by writing to the bitmap property, the currently-active image is replaced. If the style property is 1, the new image will be appended to the end of the image list, and will become the new active image. This allows you to create a sequence of images (for example, an animated GIF), directly from APL.

The Transform method

ImageMagick includes a very wide range of functions for transforming an image. For example, you can shear, scale, crop, rotate or skew the image, sharpen edges, adjust colors and intensity, and filter out noise. You can also apply special effects to the image, such as making it look like a charcoal drawing or an oil painting. The Transform method of the APLX Image object allows you to use many of these functions directly.

See the documentation on the Transform method for more information.

Other Methods

Draw: This is fully supported for Image objects, allowing you to add graphics elements and text to an existing or new image. See the documentation on the Draw method for details.

Setopacity: ImageMagick supports images which are transparent, which means that when you place one image on top of another using the Overlay method, the background image will still be partially visible through the foreground image. Some file formats, such as PNG, allow specific parts of the image to be transparent. The Setopacity method allows you to specify that the whole image is transparent. it takes a single argument, which is a number between 0.0 (completely transparent) to 1.0 (fully opaque, i.e. the background is not visible at all).

Overlay: This method allows you to overlay one image (the foreground) on top of another (the background). If the foreground image is transparent, the background image will partially show through it. Normally you first load the background image into the Image object, and then use the Overlay method to load the foreground image (from file) on top of it, at a specified position. You can also overlay an image from another Image object. See the documentation on the Overlay method for details.

Calling ImageMagick directly

The ImageMagick package includes many other features which are not directly supported by the Image object. You can access these features either using ⎕NA, or by writing a small Auxiliary Processor. In order to do this, you need the handle to the underlying ImageMagick 'Magick Wand'; this can be read from the handle property.

Interaction between the Image object and the Picture object

The Image object itself is always invisible. However, if you create it as the child of a Picture object, the Picture object will display it. Whenever the Image object is changed, the Picture object will be re-drawn to reflect the changes.

If you are making a series of changes to the Image object, APLX attempts to buffer these up to avoid multiple redraws. However, for best performance when making several changes to an Image, and to avoid flickering effects, you can temporarily set the update property of the Picture object to 0 before changing the Image. This suppresses automatic redrawing. When the changes are complete, you should set the update property back to 1, which will cause the Image to be redrawn with all the changes you have made.

Example

     ∇DEMO_Image;DEMO;X
[1]   ⍝ Sample function demonstrating use of the Image object
[2]   ⍝ You must have ImageMagick installed on your system to run this demo
[3]   ⍝
[4]   ⍝ Create window with a Picture, which we'll use to display Image object
[5]   DEMO←'⎕' ⎕NEW 'Window' ⋄ DEMO.scale←5 ⋄ DEMO.size←376 280
[6]   DEMO.title←'Image'
[7]   DEMO.Pic.New 'Picture' ⋄ DEMO.Pic.align←¯1
[8]   ⍝
[9]   ⍝ Create the Image object, as a child of the Picture.
[10]  ⍝ This effectively makes the image visible.
[11]  ⍝ Use error trapping in case ImageMagick is not installed.
[12]  :Try
[13]    DEMO.Pic.Img.New 'Image'
[14]  :CatchAll
[15]    'You must have ImageMagick installed to run this demo.'
[16]    'See http://www.imagemagick.org'
[17]    →0
[18]  :EndTry
[19]  DEMO.Pic.Img.scale←5
[20]  ⍝
[21]  ⍝ Load a picture into the Image object.  This could come from file,
[22]  ⍝ in any format supported by ImageMagick (JPEG, GIF, BMP, SVG etc).
[23]  ⍝ Here we use an array of pixels, encoded as 256 ⊤ Blue Green Red
[24]  DEMO.Pic.Img.bitmap←SAMPLE_BITMAP
[25]  ⍝
[26]  ⍝ Show the original image for a few seconds
[27]  DEMO.Show
[28]  X←⎕DL 3
[29]  ⍝
[30]  ⍝ Rescale to twice original size, and flip around vertical axis
[31]  ⍝ We'll suppress updates temporarily so we don't get a redraw
[32]  ⍝ until both operations are done
[33]  DEMO.Pic.update←0
[34]  DEMO.Pic.Img.Transform 'magnify'
[35]  DEMO.Pic.Img.Transform 'flop'
[36]  DEMO.Pic.update←1  ⍝ Now do redraw
[37]  X←⎕DL 3
[38]  ⍝
[39]  ⍝ Now use one of ImageMagick's image-transformation functions
[40]  ⍝ (see workspace 10 HELPTRANSFORM for more examples):
[41]  DEMO.Pic.Img.Transform 'charcoal' 1 2
[42]  ⍝
[43]  ⍝ Use the Draw method to add text to the Image object
[44]  DEMO.Pic.Img.Draw 'Color' 255
[45]  DEMO.Pic.Img.Draw 'Text' 'APLX and ImageMagick' 2 60
[46]  ⍝
[47]  ⍝ Wait a few seconds, then allow user to save the image to file,
[48]  ⍝ in any of the formats supported by ImageMagick (JPEG, GIF, PDF, BMP etc)
[49]  ⍝ Providing an empty file name automatically brings up the dialog
[50]  X←⎕DL 3
[51]  DEMO.Pic.Img.Save ''
[52]  ⍝
[53]  ⍝ Window will be deleted when function ends and DEMO goes out of scope
     ∇

Properties

bitmap bitmapsize children class colorback data events file format formats handle imagecount imageindex imagesize methods name opened properties quality self style tie

Methods

Close Copy Create Delete Draw Load New Open Overlay Paste Save Send Set Setopacity Transform Trigger

Callbacks

onClose onDestroy onOpen onSend