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 to GraphObject.make, rather than assign the "source:" property. Both techniques have the same effect.

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

  diagram.add(
    $(go.Part,
      $(go.Picture, "images/100x65.png")
    ));

However for more sophisticated control you can set the Picture.element to an HTMLImageElement or an HTMLCanvasElement.

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 pictures all show a picture of kittens that is 100x65 pixels.

  diagram.add(
    $(go.Part, "Table",
      $(go.Picture, { source: "images/100x65.png", column: 0,
                      margin: 2 }),
      $(go.TextBlock, "natural", { row: 1, column: 0 }),
      $(go.Picture, { source: "images/100x65.png", column: 1,
                      width: 100, height: 65, margin: 2 }),
      $(go.TextBlock, "same size", { row: 1, column: 1 }),
      $(go.Picture, { source: "images/100x65.png", column: 2,
                      width: 200, height: 130, margin: 2 }),
      $(go.TextBlock, "bigger", { row: 1, column: 2 }),
      $(go.Picture, { source: "images/100x65.png", column: 3,
                      width: 50, height: 32.5, margin: 2 }),
      $(go.TextBlock, "smaller", { row: 1, column: 3 }),
      $(go.Picture, { source: "images/100x65.png", column: 4,
                      width: 50, height: 70, margin: 2 }),
      $(go.TextBlock, "stretched", { row: 1, column: 4 })
    ));

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.

Image Stretch

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. All four Pictures here have the size 60x80 and show the same 100x65 PNG file. The Pictures also have a light green background, to show the space available that may be left unused, but is still part of the Picture's bounds.

  diagram.add(
    $(go.Part, "Table",
      $(go.Picture, "images/100x65.png",
        { column: 0, width: 60, height: 80, margin: 2, background: "chartreuse",
          imageStretch: go.GraphObject.Fill }),
      $(go.TextBlock, "Fill", { row: 1, column: 0 }),
      $(go.Picture, "images/100x65.png",
        { column: 1, width: 60, height: 80, margin: 2, background: "chartreuse",
          imageStretch: go.GraphObject.None }),
      $(go.TextBlock, "None", { row: 1, column: 1 }),
      $(go.Picture, "images/100x65.png",
        { column: 2, width: 60, height: 80, margin: 2, background: "chartreuse",
          imageStretch: go.GraphObject.Uniform }),
      $(go.TextBlock, "Uniform", { row: 1, column: 2 }),
      $(go.Picture, "images/100x65.png",
        { column: 3, width: 60, height: 80, margin: 2, background: "chartreuse",
          imageStretch: go.GraphObject.UniformToFill }),
      $(go.TextBlock, "UniformToFill", { row: 1, column: 3 })
    ));

  // The original image sized naturally, for comparison
  diagram.add(
    $(go.Part, "Vertical",
      $(go.Picture, "images/100x65.png"),
      $(go.TextBlock, "Original image,\nsized naturally")
    ));

When images are clipped you can control what part of the image is drawn by using the Picture.imageAlignment property.

Clipping

If you have a Picture that must be clipped to a geometry, such as to produce a circular image, there are two options. The first is to use a "frame" geometry to hide part of the image. Typically this frame is the same color as the Diagram background or the background of the Node. This method does not change the area of the Picture, does not allow for true transparency, and clicking anywhere in the bounds will always pick the picture.

A second method uses Panel.isClipping. This property on a "Spot" Panel allows the filled area of the main Shape to serve as a clipping region instead of a drawn shape. This method does not change the area of the Picture, but does allow for transparency It affects object picking so that only the resultant drawn area is pickable; areas of the image that are not drawn cannot be "hit".

Examples of both follow:


  diagram.layout = $(go.GridLayout);
  diagram.initialContentAlignment = go.Spot.Center;

  // Using a black "frame" geometry to hide part of the image.
  // Typically this frame is the same color as the Diagram background or the background of the Node.
  diagram.add(
    $(go.Part, "Spot",
      { scale: 2 },
      $(go.Picture, "../samples/images/55x55.png",
        {
          name: 'Picture',
          desiredSize: new go.Size(55, 55),
          background: 'red'
        }
      ),
      $(go.Shape,
      {
        strokeWidth: 0,
        stroke: null,
        geometryString: "f M0 0 L100 0 L100 100 L0 100 z M5,50a45,45 0 1,0 90,0a45,45 0 1,0 -90,0 z",
        width: 56,
        height: 56,
        fill: 'black'
      })
    )
  );

  // Using Panel.isClipping
  diagram.add(
    $(go.Part, "Spot",
      { isClipping: true, scale: 2  },
      $(go.Shape, "Circle", { width: 55, strokeWidth: 0 } ),
      $(go.Picture, "../samples/images/55x55.png",
        { width: 55, height: 55 }
       )
    )
  );

  // Using Panel.isClipping and also having a surrounding panel
  diagram.add(
    $(go.Part, "Spot",
      { scale: 2 },
      $(go.Shape, "Circle", { width: 65, strokeWidth: 0, fill: 'red' } ),
      $(go.Panel, "Spot",
        { isClipping: true  },
        $(go.Shape, "Circle", { width: 55, strokeWidth: 0 } ),
        $(go.Picture, "../samples/images/55x55.png",
          { width: 55, height: 55 }
         )
      )
    )
  );

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:

   $(go.Picture,
     { width: 64, height: 64 },
     { sourceCrossOrigin: function(pict) { return "use-credentials"; } },
     new go.Binding("source", "path"))

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

Almost all browsers accept SVG files as a Picture source, but in many browsers you must:

This first SVG element has a width and height specified in its SVG element, and also has its desired size set. It should display in most browsers:

<svg xmlns="http://www.w3.org/2000/svg"
     xmlns:xlink="http://www.w3.org/1999/xlink"
     width="580" height="580">
  ...
  diagram.add(
    $(go.Part, "Vertical",
      $(go.Picture, { desiredSize: new go.Size(580, 580), source: "images/tiger.svg" })
    ));
  diagram.scale = 0.5;

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

<svg xmlns="http://www.w3.org/2000/svg"
     xmlns:xlink="http://www.w3.org/1999/xlink">
  ...
  diagram.add(
    $(go.Part, "Vertical",
      $(go.Picture, { source: "images/tiger-noWidthHeightSpecified.svg" })
    ));
  diagram.scale = 0.5;