ImageReference

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:

Some properties of the Solid class are relevant for images:

Image Sizing

Although the ImageSizing properties are the value for the imageSizing property (note lowercase i) of the Solid class, they are useful to mention here:

Counting Images

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){})
omnigraffle:///omnijs-run?script=imageCount%20%3D%20images%2Elength%0Atitle%20%3D%20%27IMAGE%20COUNT%27%0Aif%20%28imageCount%20%3D%3D%200%29%7B%0A%09message%20%3D%20%27There%20are%20no%20images%20in%20this%20document%2E%27%0A%7D%20else%20if%20%28imageCount%20%3D%3D%201%29%7B%0A%09message%20%3D%20%27There%20is%20one%20image%20in%20this%20document%2E%27%0A%7D%20else%20%7B%0A%09message%20%3D%20%27There%20are%20%27%20%2B%20imageCount%20%2B%20%27%20images%20in%20this%20document%2E%27%0A%7D%0Anew%20Alert%28title%2C%20message%29%2Eshow%28function%28result%29%7B%7D%29

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){}) } }
omnigraffle:///omnijs-run?script=if%20%28document%2Ewindows%5B0%5D%2Eselection%2Egraphics%2Elength%20%21%3D%201%29%7B%0A%09title%20%3D%20%22SELECTION%20ERROR%22%0A%09message%20%3D%20%22Please%20select%20a%20single%20graphic%2E%22%0A%09new%20Alert%28title%2C%20message%29%2Eshow%28function%28result%29%7B%7D%29%0A%7D%20else%20%7B%0A%09cnvs%20%3D%20document%2Ewindows%5B0%5D%2Eselection%2Ecanvas%0A%09graphic%20%3D%20document%2Ewindows%5B0%5D%2Eselection%2Egraphics%5B0%5D%0A%09if%20%28graphic%2Eimage%20instanceof%20ImageReference%29%7B%0A%09%09%2F%2F%20processing%20code%20goes%20here%0A%09%7D%20else%20%7B%0A%09%09title%20%3D%20%22NO%20IMAGE%22%0A%09%09message%20%3D%20%22The%20graphic%20does%20not%20contain%20an%20image%2E%22%0A%09%09new%20Alert%28title%2C%20message%29%2Eshow%28function%28result%29%7B%7D%29%0A%09%7D%0A%7D

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){}) } }
omnigraffle:///omnijs-run?script=if%20%28document%2Ewindows%5B0%5D%2Eselection%2Esolids%2Elength%20%21%3D%201%29%7B%0A%09title%20%3D%20%22SELECTION%20ERROR%22%0A%09message%20%3D%20%22Please%20select%20a%20single%20solid%2E%22%0A%09new%20Alert%28title%2C%20message%29%2Eshow%28function%28result%29%7B%7D%29%0A%7D%20else%20%7B%0A%09cnvs%20%3D%20document%2Ewindows%5B0%5D%2Eselection%2Ecanvas%0A%09solid%20%3D%20document%2Ewindows%5B0%5D%2Eselection%2Esolids%5B0%5D%0A%09if%20%28solid%2Eimage%20instanceof%20ImageReference%29%7B%0A%09%09newGeometry%20%3D%20solid%2Egeometry%0A%09%09newGeometry%2Esize%20%3D%20solid%2Eimage%2EoriginalSize%0A%09%09solid%2EimageSizing%20%3D%20ImageSizing%2EStretched%0A%09%09solid%2Egeometry%20%3D%20newGeometry%0A%09%7D%20else%20%7B%0A%09%09title%20%3D%20%22NO%20IMAGE%22%0A%09%09message%20%3D%20%22The%20solid%20does%20not%20contain%20an%20image%2E%22%0A%09%09new%20Alert%28title%2C%20message%29%2Eshow%28function%28result%29%7B%7D%29%0A%09%7D%0A%7D

(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 

Image to be sized set with manual scaling

(below) The result of the script with the line containing the imageSizing adjustment (line 11) omitted or set to a value of ImageSizing.Manual

Image container resized without image resizing

(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 

Image container resized with image resizing

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.

scale-dialog
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){}) } }
omnigraffle:///omnijs-run?script=if%20%28document%2Ewindows%5B0%5D%2Eselection%2Esolids%2Elength%20%21%3D%201%29%7B%0A%09title%20%3D%20%22SELECTION%20ERROR%22%0A%09message%20%3D%20%22Please%20select%20a%20single%20solid%2E%22%0A%09new%20Alert%28title%2C%20message%29%2Eshow%28function%28result%29%7B%7D%29%0A%7D%20else%20%7B%0A%09cnvs%20%3D%20document%2Ewindows%5B0%5D%2Eselection%2Ecanvas%0A%09solid%20%3D%20document%2Ewindows%5B0%5D%2Eselection%2Esolids%5B0%5D%0A%09if%20%28solid%2Eimage%20instanceof%20ImageReference%29%7B%0A%09%09newGeometry%20%3D%20solid%2Egeometry%0A%09%09newGeometry%2Esize%20%3D%20solid%2Eimage%2EoriginalSize%0A%09%09solid%2EimageSizing%20%3D%20ImageSizing%2EStretched%0A%09%09solid%2Egeometry%20%3D%20newGeometry%0A%09%09title%20%3D%20%22SCALE%20IMAGE%22%0A%09%09message%20%3D%20%22Scale%20the%20image%20and%20graphic%20to%20which%20percentage%20of%20the%20image%E2%80%99s%20original%20size%3A%22%0A%09%09var%20alert%20%3D%20new%20Alert%28title%2C%20message%29%0A%09%09alert%2EaddOption%28%2250%25%22%29%0A%09%09alert%2EaddOption%28%2225%25%22%29%0A%09%09alert%2EaddOption%28%22Don%E2%80%99t%20Scale%22%29%0A%09%09alert%2Eshow%28function%28result%29%7B%0A%09%09%09newGeometry%20%3D%20solid%2Egeometry%0A%09%09%09currentSize%20%3D%20solid%2Egeometry%2Esize%0A%09%09%09currentWidth%20%3D%20solid%2Egeometry%2Esize%2Ewidth%0A%09%09%09currentHeight%20%3D%20solid%2Egeometry%2Esize%2Eheight%0A%09%09%09if%20%28result%20%3D%3D%200%29%7B%0A%09%09%09%09adjustedSize%20%3D%20new%20Size%28currentWidth%20*%200%2E5%2C%20currentHeight%20*%200%2E5%29%0A%09%09%09%09newGeometry%2Esize%20%3D%20adjustedSize%0A%09%09%09%09solid%2Egeometry%20%3D%20newGeometry%0A%09%09%09%7D%20else%20if%20%28result%20%3D%3D%201%29%7B%0A%09%09%09%09adjustedSize%20%3D%20new%20Size%28currentWidth%20*%200%2E25%2C%20currentHeight%20*%200%2E25%29%0A%09%09%09%09newGeometry%2Esize%20%3D%20adjustedSize%0A%09%09%09%09solid%2Egeometry%20%3D%20newGeometry%0A%09%09%09%7D%20else%20%7B%0A%09%09%09%09%2F%2F%20leave%20at%20100%25%20of%20original%0A%09%09%09%7D%0A%09%09%7D%29%0A%09%7D%20else%20%7B%0A%09%09title%20%3D%20%22NO%20IMAGE%22%0A%09%09message%20%3D%20%22The%20solid%20does%20not%20contain%20an%20image%2E%22%0A%09%09new%20Alert%28title%2C%20message%29%2Eshow%28function%28result%29%7B%7D%29%0A%09%7D%0A%7D

Importing images

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.

imageURL = URL.choose(['public.image']) if (imageURL == null){throw new Error('user cancelled')} urlString = imageURL.string var imageFileName = urlString.substr(urlString.lastIndexOf('/') + 1) imageFileName = decodeURIComponent(imageFileName) imageURL.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]) })
omnigraffle:///omnijs-run?script=imageURL%20%3D%20URL%2Echoose%28%5B%27public%2Eimage%27%5D%29%0Aif%20%28imageURL%20%3D%3D%20null%29%7Bthrow%20new%20Error%28%27user%20cancelled%27%29%7D%0AurlString%20%3D%20imageURL%2Estring%0Avar%20imageFileName%20%3D%20urlString%2Esubstr%28urlString%2ElastIndexOf%28%27%2F%27%29%20%2B%201%29%0AimageFileName%20%3D%20decodeURIComponent%28imageFileName%29%0AimageURL%2Efetch%28function%28data%29%7B%0A%09cnvs%20%3D%20document%2Ewindows%5B0%5D%2Eselection%2Ecanvas%0A%09aGraphic%20%3D%20cnvs%2EnewShape%28%29%0A%09aGraphic%2EstrokeThickness%20%3D%200%0A%09aGraphic%2EshadowColor%20%3D%20null%0A%09aGraphic%2EfillColor%20%3D%20null%0A%09aGraphic%2Eimage%20%3D%20addImage%28data%29%0A%09aGraphic%2Ename%20%3D%20imageFileName%0A%09imageSize%20%3D%20aGraphic%2Eimage%2EoriginalSize%0A%09imgX%20%3D%20imageSize%2Ewidth%0A%09imgY%20%3D%20imageSize%2Eheight%0A%09aRect%20%3D%20new%20Rect%28aGraphic%2Egeometry%2Ex%2C%20aGraphic%2Egeometry%2Ey%2C%20imgX%2C%20imgY%29%0A%09aGraphic%2Egeometry%20%3D%20aRect%0A%09document%2Ewindows%5B0%5D%2Eselection%2Eview%2Eselect%28%5BaGraphic%5D%29%0A%7D%29

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]) })
omnigraffle:///omnijs-run?script=urlString%20%3D%20%22https%3A%2F%2Fomni-automation%2Ecom%2Fgfx%2F18207%2Ejpg%22%0Avar%20imageFileName%20%3D%20urlString%2Esubstr%28urlString%2ElastIndexOf%28%27%2F%27%29%20%2B%201%29%0Avar%20url%20%3D%20URL%2EfromString%28urlString%29%0Aurl%2Efetch%28function%20%28data%29%7B%0A%09cnvs%20%3D%20document%2Ewindows%5B0%5D%2Eselection%2Ecanvas%0A%09aGraphic%20%3D%20cnvs%2EnewShape%28%29%0A%09aGraphic%2EstrokeThickness%20%3D%200%0A%09aGraphic%2EshadowColor%20%3D%20null%0A%09aGraphic%2EfillColor%20%3D%20null%0A%09aGraphic%2Eimage%20%3D%20addImage%28data%29%0A%09aGraphic%2Ename%20%3D%20imageFileName%0A%09imageSize%20%3D%20aGraphic%2Eimage%2EoriginalSize%0A%09imgX%20%3D%20imageSize%2Ewidth%0A%09imgY%20%3D%20imageSize%2Eheight%0A%09aRect%20%3D%20new%20Rect%28aGraphic%2Egeometry%2Ex%2C%20aGraphic%2Egeometry%2Ey%2C%20imgX%2C%20imgY%29%0A%09aGraphic%2Egeometry%20%3D%20aRect%0A%09document%2Ewindows%5B0%5D%2Eselection%2Eview%2Eselect%28%5BaGraphic%5D%29%0A%7D%29

Import Image from Plug-In

This script will import an image file into the current OmniGraffle document from an installed Plugin:

plugin = PlugIn.find("com.NyhthawkProductions.OmniGraffle") var resourceName = "Australia.png" url = plugin.resourceNamed(resourceName) url.fetch(function(data){ aGraphic = canvases[0].newShape() aGraphic.strokeThickness = 0 aGraphic.shadowColor = null aGraphic.fillColor = null aGraphic.image = addImage(data) aGraphic.name = resourceName imageSize = aGraphic.image.originalSize imgX = imageSize.width imgY = imageSize.height aGraphic.geometry = new Rect(aGraphic.geometry.x, aGraphic.geometry.y, imgX, imgY) document.windows[0].selection.view.select([aGraphic]) })
omnigraffle:///omnijs-run?script=plugin%20%3D%20PlugIn.find(%22com.NyhthawkProductions.OmniGraffle%22)%0Avar%20resourceName%20%3D%20%22Australia.png%22%0Aurl%20%3D%20plugin.resourceNamed(resourceName)%0Aurl.fetch(function(data)%7B%0A%09aGraphic%20%3D%20canvases%5B0%5D.newShape()%0A%09aGraphic.strokeThickness%20%3D%200%0A%09aGraphic.shadowColor%20%3D%20null%0A%09aGraphic.fillColor%20%3D%20null%0A%09aGraphic.image%20%3D%20addImage(data)%0A%09aGraphic.name%20%3D%20resourceName%0A%09imageSize%20%3D%20aGraphic.image.originalSize%0A%09imgX%20%3D%20imageSize.width%0A%09imgY%20%3D%20imageSize.height%0A%09aGraphic.geometry%20%3D%20new%20Rect(aGraphic.geometry.x%2C%20aGraphic.geometry.y%2C%20imgX%2C%20imgY)%0A%09document.windows%5B0%5D.selection.view.select(%5BaGraphic%5D)%0A%7D)

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.

1-2-3The 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.

urlString = "https://omni-automation.com/omnigraffle/gfx/1-2-3.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/3) aGraphic.geometry = aRect aGraphic.imageSizing = ImageSizing.Tiled aGraphic.imageOffset = new Point(0, 1) })
omnigraffle:///omnijs-run?script=urlString%20%3D%20%22https%3A%2F%2Fomni-automation%2Ecom%2Fomnigraffle%2Fgfx%2F1-2-3%2Ejpg%22%0Avar%20imageFileName%20%3D%20urlString%2Esubstr%28urlString%2ElastIndexOf%28%27%2F%27%29%20%2B%201%29%0Avar%20url%20%3D%20URL%2EfromString%28urlString%29%0Aurl%2Efetch%28function%20%28data%29%7B%0A%09cnvs%20%3D%20document%2Ewindows%5B0%5D%2Eselection%2Ecanvas%0A%09aGraphic%20%3D%20cnvs%2EnewShape%28%29%0A%09aGraphic%2EstrokeThickness%20%3D%200%0A%09aGraphic%2EshadowColor%20%3D%20null%0A%09aGraphic%2EfillColor%20%3D%20null%0A%09aGraphic%2Eimage%20%3D%20addImage%28data%29%0A%09aGraphic%2Ename%20%3D%20imageFileName%0A%09imageSize%20%3D%20aGraphic%2Eimage%2EoriginalSize%0A%09imgX%20%3D%20imageSize%2Ewidth%0A%09imgY%20%3D%20imageSize%2Eheight%0A%09aRect%20%3D%20new%20Rect%28aGraphic%2Egeometry%2Ex%2C%20aGraphic%2Egeometry%2Ey%2C%20imgX%2C%20imgY%2F3%29%0A%09aGraphic%2Egeometry%20%3D%20aRect%0A%09aGraphic%2EimageSizing%20%3D%20ImageSizing%2ETiled%0A%09aGraphic%2EimageOffset%20%3D%20new%20Point%280%2C%201%29%0A%7D%29
solid = document.windows[0].selection.solids[0] currentVOffset = solid.imageOffset.y if (currentVOffset == -1.0){ newVOffset = 1.0 } else { newVOffset = currentVOffset - 1.0 } solid.imageOffset = new Point(0, newVOffset)
omnigraffle:///omnijs-run?script=solid%20%3D%20document%2Ewindows%5B0%5D%2Eselection%2Esolids%5B0%5D%0AcurrentVOffset%20%3D%20solid%2EimageOffset%2Ey%0Aif%20%28currentVOffset%20%3D%3D%20-1%2E0%29%7B%0A%09newVOffset%20%3D%201%2E0%0A%7D%20else%20%7B%0A%09newVOffset%20%3D%20currentVOffset%20-%201%2E0%0A%7D%0Asolid%2EimageOffset%20%3D%20new%20Point%280%2C%20newVOffset%29
UNDER CONSTRUCTION

This webpage is in the process of being developed. Any content may change and may not be accurate or complete at this time.

DISCLAIMER