Pictures

Use the Picture class to display images. The most common usage is to set the Picture.source property with a URL string, along with the GraphObject.desiredSize or the GraphObject.width and GraphObject.height.

If the URL is just a simple constant string, you can pass the string directly as an argument, rather than assign the "source:" property. Both techniques have the same effect.

For more sophisticated control, you can set the Picture.element to an HTMLImageElement or an HTMLCanvasElement.

In these simplistic demonstrations, the code programmatically creates a Node and adds it to the Diagram. Once you learn about models and data binding you will generally not create parts (nodes or links) programmatically.

Simple icons Using fonts

Note: for showing simple icons you may want to use an icon font. See the example using a TextBlock rather than a Picture at: Icon Fonts

Sizing

If you do not set the GraphObject.desiredSize of a Picture, it will get the picture's natural size. But when you set the desiredSize to be something different than the natural size, the picture may be stretched or compressed to fit.

The following Picture elements all show a picture of apples that is 320x240 pixels.

• The first picture shows the image at its natural size.
• The second picture also shows the image at its natural size, but has its width and height set explicitly.
• The third picture increases the size of the Picture, causing the image to be expanded evenly.
• The fourth picture squeezes the 320x240 image into a 160x120 space -- half size. This also maintains the original aspect ratio of the image.
• The last picture sets the picture size to be 320x480, which changes the aspect ratio to be taller and thinner than the original.

Note that it may take a while for the media to load. Until the time that the media has loaded sufficiently to know its natural size, the Picture may have the wrong size, such as 0x0. We recommend that you specify the desiredSize (or width and height) so that the Panel(s) holding the Picture will not have to rearrange themselves once the media has loaded.

However, for the times when you cannot know the natural size ahead of time, there are alternative ways of stretching images to fit in a given space:

ImageStretch

Instead of always stretching or compressing to fill the desiredSize, you can set the Picture.imageStretch property to control the size and aspect ratio of the drawn image.

The following pictures demonstrate the four possible values for Picture.imageStretch. The first four Pictures have size 200x400 and show the same 330x330 JPG file. They have a light gray background to show the space that may be left unused but is still part of the Picture's bounds.

• "Fill" demonstrates the default behavior (stretching in both directions). In this case, the image is distorted to be narrower than its natural size, but the entire image is visible and it fully fills the space.
• "None" uses an imageStretch of ImageStretch.None. Because the desiredSize is smaller than the natural size of the image, parts of it are clipped.
• "Uniform" shows how setting imageStretch to ImageStretch.Uniform ensures the whole image is shown at the largest scale such that its aspect ratio is maintained. This leaves the remaining space empty.
• "UniformToFill" shows how setting imageStretch to ImageStretch.UniformToFill ensures the image fills the whole space by scaling it until the area is completely covered and then clipping any excess.
• The last node contains the original image in its natural size for comparison for comparison.

Clipping

If you have a Picture that must be clipped to a certain geometry, you can add it to a Spot that has a main Shape of the desired geometry and set Panel.isClipping to true. This allows the filled area of the main Shape to serve as a clipping region instead of a drawn shape. Only the drawn part of the Picture will be pickable, but it does not actually change its area.

Examples of both follow:

When images are clipped, you can control what part of the image is drawn by using the Picture.imageAlignment property. The default value is Spot.Center. However, this property is only consulted when the Picture.imageStretch property is not set to its default value of ImageStretch.Fill. In the example below, the same rectangular picture is clipped by a circular frame, one with imageAlignment set to its default and one with it set to Spot.Top:

Flipping

You can flip image sources horizontally and vertically with the Picture.flip property:

Cross origin Pictures

Since Pictures are backed by HTMLImageElements, they must abide by the same Cross-origin (CORS) rules that apply to images. If you are using images that apply to CORS rules, you may need to set the Picture.sourceCrossOrigin property to a function that returns an appropriate value. If sourceCrossOrigin is supplied, the value returned by the function is used as the value of any constructed image.crossOrigin. Example:

Common values to return are "use-credentials" and "anonymous", but other situations may call for other values or conditional values. We suggest researching cross-origin resource sharing to determine what is right for your situation.

If you are using Diagram.makeImage, Diagram.makeImageData, or Diagram.makeSvg, and you are seeing blank or missing images, CORS-related problems are the first thing to investigate.

Using SVG as a Picture source

All modern browsers accept SVG files as a Picture source, but you must assign width and height attributes to the SVG element. These values should be integers.

This first SVG file has a width and height specified in its SVG element, and also has its desired size set.

The following SVG file does not specify width and height attributes in its SVG element, and as a result, some browsers may not render it correctly:

Error handling

If an image source fails to load, the Picture.errorFunction property can be set to call a function in response. This can be helpful in cases such as user input when an image can't be guaranteed to work. This error function can then set the source to a known value.