An image inside an OmniGraffle document. The image can be part of the fill for more than one Solid graphic, and all of them will refer to the same ImageReference.
Instance Properties
As with other classes of object, images have properties whose values define its display and use. Here are the standard image properties:
data (Data or nil r/o) • The image data bytes.
originalSize (Size r/o) • Original size of the image in pixels.
uniqueID (Number r/o) • A unique (within this document) identifier for this image reference.
Some properties of the Solid class are relevant for images:
image (ImageReference or nil) • Image fill for this graphic, if any.
imageOffset (Point) • Positioning offset of the image fill. This is the difference between the image origin and the graphic origin. Note that this value is in percents, with 1 equivalent to 100%.
imageOpacity (Number) • Opacity percentage for the image fill for this graphic.
imagePage (Number) • Page number to display for the given image, if relevant. Mainly useful for PDF images, which are potentially multiple pages.
imageSizing (ImageSizing) • Type of sizing behavior for the image, if any. ImageSizing.Manual, ImageSizing.Stretched, ImageSizing.Tiled
Getting Graphics with Images
Here's a script for creating an array of references to all graphics containing images on the current canvas:
cnvs = document.windows[0].selection.canvas
var graphicImages = new Array()
cnvs.graphics.forEach(function(grfx){
if(grfx instanceof Shape && grfx.image instanceof ImageReference){
graphicImages.push(grfx)
}
})
Since the image class is an element of the “implied document” portfolio class, determining the number of images in a document is simply a process of getting the value of the length property of the class:
imageCount = images.length
title = 'IMAGE COUNT'
if (imageCount == 0){
message = 'There are no images in this document.'
} else if (imageCount == 1){
message = 'There is one image in this document.'
} else {
message = 'There are ' + imageCount + ' images in this document.'
}
new Alert(title, message).show(function(result){})
message = 'There are ' + imageCount + ' images in this document.'
09
}
10
newAlert(title, message).show(function(result){})
Checking for Single Selected Image
It’s a common practice in creating automation tools to create scripts that focus on a single selected object, such as an image. Insert your processing code into the following script outline to create a script for manipulating a selected shape containing an image:
if (document.windows[0].selection.solids.length != 1){
title = "SELECTION ERROR"
message = "Please select a single solid."
new Alert(title, message).show(function(result){})
} else {
cnvs = document.windows[0].selection.canvas
solid = document.windows[0].selection.solids[0]
if (solid.image instanceof ImageReference){
// processing code goes here
} else {
title = "NO IMAGE"
message = "The solid does not contain an image."
new Alert(title, message).show(function(result){})
}
}
if (document.windows[0].selection.solids.length != 1){
02
title = "SELECTION ERROR"
03
message = "Please select a single solid."
04
newAlert(title, message).show(function(result){})
05
} else {
06
cnvs = document.windows[0].selection.canvas
07
solid = document.windows[0].selection.solids[0]
08
if (solid.imageinstanceofImageReference){
09
// processing code goes here
10
} else {
11
title = "NO IMAGE"
12
message = "The solid does not contain an image."
13
newAlert(title, message).show(function(result){})
14
}
15
}
Sizing Containing Graphic to Fit Image
A common task when importing an image into a document, is to size the graphic container to fit the actual dimensions of the imported image. To accomplish this, the value of the originalSize property of the image instance (line 10) is used in conjunction with the imageSizing property (line 11) of the containing graphic (solid). The value of the containing graphic’s imageSizing property should be set to ImageSizing.Stretched. See the images below for an explanation of why that is the proper setting.
if (document.windows[0].selection.solids.length != 1){
title = "SELECTION ERROR"
message = "Please select a single solid."
new Alert(title, message).show(function(result){})
} else {
cnvs = document.windows[0].selection.canvas
solid = document.windows[0].selection.solids[0]
if (solid.image instanceof ImageReference){
newGeometry = solid.geometry
newGeometry.size = solid.image.originalSize
solid.imageSizing = ImageSizing.Stretched
solid.geometry = newGeometry
} else {
title = "NO IMAGE"
message = "The solid does not contain an image."
new Alert(title, message).show(function(result){})
}
}
if (document.windows[0].selection.solids.length != 1){
02
title = "SELECTION ERROR"
03
message = "Please select a single solid."
04
newAlert(title, message).show(function(result){})
05
} else {
06
cnvs = document.windows[0].selection.canvas
07
solid = document.windows[0].selection.solids[0]
08
if (solid.imageinstanceofImageReference){
09
newGeometry = solid.geometry
10
newGeometry.size = solid.image.originalSize
11
solid.imageSizing = ImageSizing.Stretched
12
solid.geometry = newGeometry
13
} else {
14
title = "NO IMAGE"
15
message = "The solid does not contain an image."
16
newAlert(title, message).show(function(result){})
17
}
18
}
(below) The image and container prior to adjustment. Note the image resizing method is set to manual 1 and that the current scale of the image is 50% horizontal 2 and 50% vertical 3
(below) The result of the script with the line containing the imageSizing adjustment (line 11) omitted or set to a value of ImageSizing.Manual
(below) The image and graphic correctly resized to the actual dimensions of the image. Note that image resizing method is set to stretched 1 and that the resulting scale percentages of the image are 100% horizontal 2 and 100% vertical 3
Scaling the Image
Once the image and graphic have been resized to the image’s original size, they can be scaled to a size that is a percentage of the original size.
The following script is variation of the previous script that adds the option to scale the image to either 50% or 25% of the image’s original dimensions. Note that both the graphic and image are scaled when the graphic is resized, because the value of imageSizing property of the graphic is set to ImageSizing.Stretched.
if (document.windows[0].selection.solids.length != 1){
title = "SELECTION ERROR"
message = "Please select a single solid."
new Alert(title, message).show(function(result){})
} else {
cnvs = document.windows[0].selection.canvas
solid = document.windows[0].selection.solids[0]
if (solid.image instanceof ImageReference){
newGeometry = solid.geometry
newGeometry.size = solid.image.originalSize
solid.imageSizing = ImageSizing.Stretched
solid.geometry = newGeometry
title = "SCALE IMAGE"
message = "Scale the image and graphic to which percentage of the image’s original size:"
var alert = new Alert(title, message)
alert.addOption("50%")
alert.addOption("25%")
alert.addOption("Don’t Scale")
alert.show(function(result){
newGeometry = solid.geometry
currentSize = solid.geometry.size
currentWidth = solid.geometry.size.width
currentHeight = solid.geometry.size.height
if (result == 0){
adjustedSize = new Size(currentWidth * 0.5, currentHeight * 0.5)
newGeometry.size = adjustedSize
solid.geometry = newGeometry
} else if (result == 1){
adjustedSize = new Size(currentWidth * 0.25, currentHeight * 0.25)
newGeometry.size = adjustedSize
solid.geometry = newGeometry
} else {
// leave at 100% of original
}
})
} else {
title = "NO IMAGE"
message = "The solid does not contain an image."
new Alert(title, message).show(function(result){})
}
}
Sometimes images are represented by their image data rather than by a path to a file containing the image data. base64 is a text-based format commonly used on the internet for representing or transporting image data, especially within webpages and URLs. For example, this small image of an iPad represents data not from a file, but to a base64 string of text embedded in this webpage.
Using the fromBase64() method of the Data class, and the addImage() method of the Portfolio class, the following script demonstrates how to add an new base64-derived image to the current canvas. In this example, the containing graphic is sized to fit the original size of the image:
Adding images to documents is a common task that is ofte automated. The importation of the image file into the document is accomplished by using the fetch() method of the URL class. The following examples demonstrate how to use the fetch() method to import and image file; import a network image; and how to import a resource image from an Omni Automation plug-in.
Import a Chosen Image File
The following example script demonstrates how to import a chosen image file into an OmniGraffle document.
The dialog presented by the choose() method (line 1) is “modal,” which means the script will not continue until the user has either selected a file or performed a tap|click on the dialog’s Cancel button. A positive selection returns the related URL object, and a cancellation returns a null value, that may be used as an indication to throw an error in order to stop the script (line 2).
The passed parameter for the choose() method of the URL class is an array of one or more Uniform Type Identifiers for indicating the kind of files from which you want to be chosen by the user. For example, the type identifier "public.image" is the generic identifier for any image file. To have the user only select JPEG images, use the type identifier "public.jpeg" to limit the selection to only JPEG image files.
Lines 3 through 5 of the script are designed to extract a URL string from the URL object, and to derive the unencoded file name of the chosen image.
The importation of the image file into the document is accomplished by using the fetch() method (line 6 — 18), an asynchronous handler that employs a call-back function to provide the means for dealing with the imported image. In other words, the fetch process runs separate from any remaining script statements, and when done with its import, executes the call-back function passed to it as its direct parameter. The call-back function contains the code for creating and manipulating the graphic that contains the image.
Note the use of the addImage() method (line 11) to insert the image data passed to the call-back function by the fetch() method, into the graphic object previously created using the newShape() method (line 7). The created graphic is named to match the image file name (line 12), and then its dimensions are adjusted to match the default size of the imported image (lines 13 — 16).
The last script statement selects the created image graphic in the document (line 17).
Importing an Image from the Internet
Using Omni Automation, image files located on networks, such as the internet, can be imported into documents using the fetch() method as shown in the previous script.
// Download image from internet and add to document
urlString = "https://omni-automation.com/gfx/18207.jpg"
var imageFileName = urlString.substr(urlString.lastIndexOf('/') + 1)
var url = URL.fromString(urlString)
url.fetch(function (data){
cnvs = document.windows[0].selection.canvas
aGraphic = cnvs.newShape()
aGraphic.strokeThickness = 0
aGraphic.shadowColor = null
aGraphic.fillColor = null
aGraphic.image = addImage(data)
aGraphic.name = imageFileName
imageSize = aGraphic.image.originalSize
imgX = imageSize.width
imgY = imageSize.height
aRect = new Rect(aGraphic.geometry.x, aGraphic.geometry.y, imgX, imgY)
aGraphic.geometry = aRect
document.windows[0].selection.view.select([aGraphic])
})
Iterating Display using Image Sizing and Image Offset
Here’s an intersting scenario where the section of an image that is displayed can be changed dynamically by altering the value of its imageOffset property via an attached action.
The animation is created by positioning an image within its containing graphic. The image is 3-times as tall as it is wide. The width and height of its containing graphic match the width of the image, forming a square shape.
The image is moved within its containing graphic by a script that changes the value of the image’s imageOffset property. This script is converted into an Omni Automation URL, and assigned to the graphic as an “Open a URL” action that executes when the graphic is clicked|tapped using the Browse tool.
The animation is created by positioning an image within its containing graphic. The image is 3-times as tall as it is wide. The width and height of its containing graphic match the width of the image, forming a square shape.