Importing Graphics and graphic importers

When you import a graphic file, a graphic importer object is created. Getting information about the graphic file is done by communicating with the graphic importer object. A reference to the graphic importer object is returned by the import graphic command.

To import a graphic file in iMagine Photo

tell application "iMagine Photo"
  
set imageFile to choose file with prompt "Choose an image file to import: "
  
set thisImporter to import graphic imageFile
end tell

All the above script does is to select a graphic file and tell iMagine Photo to import it. Nothing will be displayed as importing does not display an image file.

If you have a Mac OS path to a file instead of a file specification or alias (which is the information returned by the choose file command) then the import graphic command changes slightly because the path needs to be converted into a file specification or alias first. The following code converts the path to file specification.

set imageFilePath to "path:to:my:image:file.jpg"
tell
application "iMagine Photo"
  
set thisImporter to import graphic file imageFilePath
end tell

If you have a POSIX style path then that needs to converted into a file specification or alias. This following code demonstrates how to do this:

set imageFilePath to "/path/to/my/image/file.jpg"
tell
application "iMagine Photo"
  
set thisImporter to import graphic (imageFilePath as POSIX file)
end tell

There are two main commands for obtaining information about imported graphic files, the first is the properties command which returns the same bits of information for every graphic type. The script below will leave information about the image in the results log of the Script Editor window.

set thisFile to choose file with prompt "Choose an image file: "
tell application "iMagine Photo"
  
set thisImporter to import graphic thisFile
  
set theProps to the properties of thisImporter
  
close thisImporter
end tell
theProps

Panther users can open the script above in Script Editor by clicking here.

Each property of the graphic importer can be obtained seperately. The properties record returns the read-only properties of a graphic importer object, except for the component error, DONTgamma correct, and DONTcolor match property.

The other command to get information about image files is the exif data command. How to use the exif data command is fully described in the Read/Write Exif metadata documentation section.

Once you have finished with a graphic importer it is necessary to close the graphic importer as shown in the script above, otherwise iMagine Photo will keep it open indefinitely. The following command will close all graphic importers:

close every graphic importer

Graphic importers can also be referred to by their index and by the name of the imported graphic file. For example if there is at least one graphic importer open and the name of the first imported graphic file is MyStunningPicture.jpg then the first graphic importer can be referred to by:

set thisImporter to graphic importer 1

or

set thisImporter to graphic importer "MyStunningPicture.jpg"

Graphic importers can be used to draw to a graphics/window document or can create a graphics exporter through which the graphic importer can create new image files. The simplest way to create a graphics exporter is:

tell thisImporter to make exporter

This will create a JPEG graphic exporter since the default graphics exporter type is JPEG. You can create an exporter of a particular type, for example the script below creates a graphic exporter that will create TIFF files:

tell thisImporter to make exporter with properties {export file type:"TIFF"}

Various graphic exporter properties can be set when creating a graphics exporter or they can be set later, see the Exporting graphics page for details. Various image processing operations can be performed when a graphic importer exports through a graphic exporter. Scaling, rotating, cropping are all possible as well as setting the image resolution and exif data.

Setting the resolution and the exif data are done via the graphic exporter and are described in the Exporting graphics page.

Scaling, rotation, cropping or other transformation operations do not happen until the image is exported or drawn.

The following line demonstrates how to scale so that the image is half as tall, and half as wide. A quarter of its original size.

set the scale of thisImporter to {0.5, 0.5}

The following line demonstrates how to rotate the image 90 degrees clockwise. Positive and negative numbers are both valid, positive is clockwise:

set the rotation of thisImporter to 90

The following script shows how to crop the image so that only the middle quarter of the image is exported, and to demonstrate that the different transformations can be combined, the script also rotates the final image 90 degrees anti-clockwise. Panther users can click here to open the script in Script Editor.

set thisFile to choose file with prompt "Choose an image file: "
set exportedFile to choose file name with prompt "Select the destination of the file, and provide a name: " default name "imagefile.jpg"
tell application "iMagine Photo"
  
set thisImporter to import graphic thisFile
  
set {x, y, xDim, yDim} to the natural bounds of thisImporter
  
tell thisImporter to make exporter
  
set the export file location of thisImporter to exportedFile
  
set theTop to (yDim / 4) as integer
  
set theLeft to (xDim / 4) as integer
  
set theRight to ((xDim / 2) + theLeft) as integer
  
set theBottom to ((yDim / 2) + theTop) as integer
  
set the source rectangle of thisImporter to {theLeft, theTop, theRight, theBottom}
  
set the rotation of thisImporter to -90
  
export thisImporter
  
close thisImporter
end tell

By default the source rectangle is the same as the original picture size. The destination rectangle can also be set. The destination rectangle defines the bounds of the final image and will scale the original accordingly. The scaling that occurs is the ratio of the destination rectangle to the source rectangle unless rotation has occured in which case the destination rectangle defines the bounding rectangle of the rotated image, for rotations which are multiples of 90 degrees the scaling remains simple.

As well as the scaling and rotation transformations, the graphic importer object gives you direct access to the transformation matrix. The following line will flip the image horizontally:

set the transformation matrix of thisImporter to {-1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0}

For a graphic importer to draw, the graphic importer has to be told which graphic/window document it will draw to. Graphic/window documents are fully described in the Graphic/Window documentation section. The following line shows how to tell a graphics importer which graphic/window document it will draw to.

set the drawing destination of thisImporter to thisDocument

All the transformations which can be applied to a graphic importer when it is exporting can also apply to graphic importers drawing to a graphic/window document, the difference being that when a graphics importer is exporting Quicktime normalizes the top left point so that the top left point of the exported image is always {0,0}. This does not occur when a graphic importer draws to a graphic/window document. For example when scaling a graphic importer the scaling is centred in the middle of the picture and the following script demonstrates that we can see that the top left point has moved from {0,0}. On Panther click here to open the following script in a new Script Editor window .

set thisFile to choose file with prompt "Choose an image file: "
tell application "iMagine Photo"
  
set thisImporter to import graphic thisFile
  
set {x, y, xDim, yDim} to the natural bounds of thisImporter
  
set thisDocument to make new window document with properties {dimensions:{xDim, yDim}}
  
set the drawing destination of thisImporter to thisDocument
  
set the scale of thisImporter to {0.5, 0.5}
  
draw thisImporter
  
close thisImporter
end tell

iMagine Photo provides two ways to control the location of where the graphic importer will draw. The destination rectangle property described above allows the drawing to be positioned, but there is also the top left point property. The following line shows how to set the top left point to {0,0}

  set the top left point of thisImporter to {0, 0}

A graphic importer can also have clipping points applied to it for drawing to a graphic/window document. The clipping points are the end points of the lines that make a polygon. Anything inside the polygon will be drawn and anythig outside will be clipped. The clipping points can have a inset applied to them to shrink or grow the polygon, and an inset difference can also be set which will create a clipping region which is the difference between the previous clipping region and the new inset clipping region.

The following script demonstrates setting the clipping points and its impact on drawing an image. Panther users click here to open the script in a new Script Editor window.

set thisFile to choose file with prompt "Choose an image file: "
tell application "iMagine Photo"
  
set thisImporter to import graphic thisFile
  
set {x, y, xDim, yDim} to the natural bounds of thisImporter
  
set thisDocument to make new window document with properties {dimensions:{xDim, yDim}}
  
set the drawing destination of thisImporter to thisDocument
  
set clippingPoints to {{40, 50}, {180, 120}, {50, 550}, {720, 300}, {720, 580}, {360, 550}, {720, 45}, {360, 200}}
  
set the clipping points of thisImporter to clippingPoints
  
draw thisImporter
  
close thisImporter
end tell

iMagine Photo also includes a clear transformations AppleScript commandwhich both the graphic and movie importer objects can handle. To remove all the positioning, scaling, and rotation commands from the graphic importer, plus removing clipping paths just use the clear transformations AppleScript command like follows:

clear transformations thisImporter

The copy command can be applied to a graphic importer object. It is the only iMagine Photo object that can handle the copy command. The image copied to the clipboard will be the image with all the transformations applied, like scale, crop, and rotate.

copy thisImporter

Various image file graphic types can contain more than image in the file. Graphic importers provide a mechanism for accessing all the images. The tiff graphic importer can access all the images in a tiff file, and the jpeg graphics importer can acces the thumbnail image. To access the pages after the first page in a multipage pdf file it is necessary to use a movie importer. The same goes for all but the first frame of a gif file.

The image count property returns the number of images in a graphic file. The image index property lets you specify which image you will be processing. The initial value is 1. For jpeg images 1 references the full image and if a thumbnail exists 2 references the thumbnail. The following line of AppleScript returns the number of images accessible in a image file.

set numImages to the image count of thisImporter

The following line sets which image the other graphic importer properties manipulate to 2:

set image index of thisImporter to 2

If thisImporter in the above line refers to a valid graphic importer for a jpeg file which contains a thumbnail then the image processing commands will be applied to the thumbnail.

There are a number of graphics modes available to a graphics importer when drawing. The Quickdraw graphics modes are described in Apple's developer documentation here. iMagine Photo has only implemented the following modes (iMagine Photo's names are in brackets if different):

blend, addPin (add pin), addOver (add over), subPin (sub pin), addMax (add max), subOver (sub over), adMin (add min), ditherCopy (dither copy), and transparent. As well as these iMagine has implemented the Quicktime graphics modes for images with transparency information. The Quicktime transfer modes are, straight alpha, alpha blend, pre white alpha, pre black alpha, composition and pre mul color alpha. For a description of the Quicktime modes see these apple pages.

The only graphics modes that I am going to bore you with now are, dither copy, blend, straight alpha and alpha blend.Dither copy is the default graphics mode and results in destination pixels being overwritten by the source image pixels. The blend graphics model blends the source and destination pixels. The amount the source and destination contribute to the final is dependent on the opcolor. The opcolor is defined by three components {red, green, blue} and each component defines how much the source and destination contribute for each color component of a pixel. Each of the opcolor components ranges from 0 - to 65535. If all three components are 32767 (approx half of 65535) then the destination pixels are made up of 50% of the source pixel and 50% of the destination pixel. If opcolor is equal to {65535, 32767, 0} then the source image contributes 100% of the red color to the destination image, 50% of the green, and 0% of the blue, and the destination image contributes the rest.

In iMagine Photo 2.1.2 the alphaAsGray graphics mode has been added. The alphaAsGray graphics mode will add to the destination graphics world a grayscale representation of the alpha channel of the image file if it has one.It adds the grayscale values to the pixel values that are already there. Before rendering the alpha channel as grayscale you should set the background to black.

The following script allows you to play with the blend graphics mode, by supplying different values for opcolor. Panther users can open the script in Script Editor by clicking here.

set thisFile1 to choose file with prompt "Choose first image file: "
set thisFile2 to choose file with prompt "Choose second image file, with same dimensions as the first image: "
tell application "iMagine Photo"
  
set thisImporter1 to import graphic thisFile1
  
set thisImporter2 to import graphic thisFile2
  
set {x, y, xDim, yDim} to the natural bounds of thisImporter1
  
set thisDocument to make new window document with properties {dimensions:{xDim, yDim}}
  
set the drawing destination of thisImporter1 to thisDocument
  
set the drawing destination of thisImporter2 to thisDocument
  
draw thisImporter1
  
set theResult to display dialog "Enter red component of opcolor (0-65535): " default answer 32767
  
set redComp to the (text returned of theResult) as integer
  
set theResult to display dialog "Enter green component of opcolor (0-65535): " default answer 32767
  
set greenComp to the (text returned of theResult) as integer
  
set theResult to display dialog "Enter blue component of opcolor (0-65535): " default answer 32767
  
set blueComp to the (text returned of theResult) as integer
  
set the drawing mode of thisImporter2 to {graphics mode:blend, opcolor:{redComp, greenComp, blueComp}}
  
draw thisImporter2
  
close thisImporter1
  
close thisImporter2
  
display dialog "Press OK to close window"
  
close thisDocument
end tell
 

The straight alpha graphics mode will only have an affect on images that have an alpha channel (transparency). Image formats that come with Quicktime that can contain an alpha channel are, png, photoshop, targa and TIFF. The straight alpha graphics mode will tell the graphic importer to use the transparency information in the alpha channel of the image file. The alpha blend graphics mode combines the alpha transparency information with the blend options for the blend graphics mode and like the blend mode uses the opcolor information.

From version 2.1 of iMagine Photo if when exporting a graphic you will be replacing the contents of any imported image file the imported image file will be moved to a temporary location before the export takes place where it will be deleted when the graphic importer is closed. This has a number of implications. Firstly, if you quit iMagine Photo with any open graphic importers then iMagine Photo will close those graphic importers before it finishes quitting, thus deleting the image image file. If iMagine Photo crashes or you have to force quit it, the image file will exist until next time you reboot your computer at which time it will be deleted. Secondly, if you ask for the file location of the graphic importer after replacing its contents you will get the location of where the file has been moved to, however if you ask for the parent folder you will get the parent folder of the original file, and if you ask for the file name you will get the name of the original file.

From version 2.1 of iMagine Photo the ability to turn off gamma correction or colour matching when drawing from a graphic importer has been added. The following command will turn off gamma correction:

  set DONTgamma correct of thisImporter1 to true

or to turn off colour matching:

  set DONTcolor match of thisImporter1 to true

Use these lines before drawing to a graphic document from a graphic importer. By default both these properties are set to false.

The color space property was added to the graphics importers when iMagine Photo was updated to version 2.1.2. It returns the type of color space that the image data represents. For example (rgb or cmyk). It is a read only property and is returned in the property record of a graphic importer.

The ability to open scripts in a new Script Editor window is provided by an application called "Convert Script to Markup Code" and can be obtained from http://homepage.mac.com/jonn8/as/

keywords: AppleScript, Apple Script, jpeg, jpg, image processing, graphics, Macintosh, Quicktime, images.