Placed images

A placed image is a frame with an <Image> element nested inside it.

In short: In IDML, a picture is a frame — most often a Rectangle, but also an Oval or Polygon — that contains an <Image> child. Nothing on the frame's own start tag marks it as "a graphic frame"; the nested image element is the whole signal. That <Image> carries two things our parser captures: a reference to the picture data, pointed at through a <Link> and LinkResourceURI (or inline bytes), and its own ItemTransform that maps the picture into the frame. This reference page covers the shape of a graphic frame, how the link is read, and why a linked picture and an embedded one look identical to the parser.

A placed image is a frame with an <Image> element inside it. The frame is an ordinary page item — most often a Rectangle, but Oval and Polygon work the same way — and the <Image> child is what turns that frame into a picture container. Nothing on the frame's own start tag marks it as "a graphic frame"; the presence of the nested image element is the whole signal.

The shape of a graphic frame

<Rectangle Self="urect" ItemTransform="…">
  <Properties>
    <PathGeometry>…</PathGeometry>     ← the frame outline, in inner coords
  </Properties>
  <Image Self="uimage" ItemTransform="…">
    <Link LinkResourceURI="file:Links/photo.jpg"/>
  </Image>
</Rectangle>

Two transforms are in play, and keeping them straight is the key to reading any placed image:

• The frame's ItemTransform carries the frame's inner space onto the page — exactly as it does for a frame with no picture.
• The image's ItemTransform (on the <Image> element) maps the picture's natural pixel space into the frame's inner space. The renderer composes the two — frame transform after image transform — so the pixels land inside the outline the path describes.

The parser treats a placed image's pixel grid as 1 pixel ≈ 1 pt at 72 ppi; the image transform is what scales that grid to the size you actually see.

Pointing at the file: <Link> and LinkResourceURI

The reference to the image data is a LinkResourceURI string. It can sit directly on the <Image> element, or on a <Link> child of it — both are read, and when both are present the outer <Image>'s wins (first-write-wins). Our parser also accepts an href attribute as an alias for the URI. Whatever the spelling, the parser captures the string and does nothing else with it: resolving that URI to real bytes is the asset resolver's job at render time.

The same fields appear whether the host is a Rectangle, an Oval, or a Polygon — the parser surfaces image_link and the image transform on all three.

Links and embeds look the same to the parser

InDesign can either link a picture (the IDML carries a URI to a file on disk) or embed it (the IDML carries the image bytes inline, base64-encoded inside a <Contents> element). These are very different on disk, but they converge at the parser: an embedded image's decoded bytes and a linked image's URI are two properties on the same frame, and both routes end at the same render-time image slot. A real-world template can mix the two freely; the parser does not care which one a given frame used.

There is one more flag worth knowing. The parser records that a frame nests an image element at all — separately from whether the link resolved. That lets the renderer tell a plain colour swatch (no image element, just a fill) apart from a graphic frame whose link happens to be unresolvable (an image element, but no usable bytes), so it can draw a missing-image placeholder in the second case instead of falling back to the frame's fill.

A worked graphic frame

The example below is a single Rectangle placed on the page, nesting an <Image> that links an external photo.jpg and carries a half-scale ItemTransform. The package ships no image bytes — by design. It parses cleanly: the frame is read in full, and the missing picture is simply a slot the resolver would fill. Open the tree view and you can see the <Image> and its <Link> hung under the rectangle.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<idPkg:Spread xmlns:idPkg="http://ns.adobe.com/AdobeInDesign/idml/1.0/packaging" DOMVersion="20.0">
  <Spread Self="uspread" PageCount="1" BindingLocation="0" ShowMasterItems="true" AllowPageShuffle="true" ItemTransform="1 0 0 1 0 0">
    <Page Self="upage" Name="1" AppliedMaster="umaster" ItemTransform="1 0 0 1 0 0" GeometricBounds="0 0 841.89 595.276" MasterPageTransform="1 0 0 1 0 0"/>
    <Rectangle Self="urect" ItemTransform="1 0 0 1 150 200" FillColor="Swatch/None" StrokeColor="Swatch/None" StrokeWeight="0">
      <Properties>
        <PathGeometry>
          <GeometryPathType PathOpen="false">
            <PathPointArray>
              <PathPointType Anchor="0 0" LeftDirection="0 0" RightDirection="0 0"/>
              <PathPointType Anchor="0 200" LeftDirection="0 200" RightDirection="0 200"/>
              <PathPointType Anchor="300 200" LeftDirection="300 200" RightDirection="300 200"/>
              <PathPointType Anchor="300 0" LeftDirection="300 0" RightDirection="300 0"/>
            </PathPointArray>
          </GeometryPathType>
        </PathGeometry>
      </Properties>
      <Image Self="uimage" ItemTransform="0.5 0 0 0.5 0 0">
        <Properties>
          <GraphicBounds Left="0" Top="0" Right="600" Bottom="400"/>
        </Properties>
        <Link Self="ulink" LinkResourceURI="file:Links/photo.jpg"/>
      </Image>
    </Rectangle>
    <TextFrame Self="uframe" ParentStory="ustory" PreviousTextFrame="n" NextTextFrame="n" ContentType="TextType" AppliedObjectStyle="ObjectStyle/$ID/[None]" Visible="true" Name="$ID/" ItemTransform="1 0 0 1 57.638 145.8237" FillColor="Swatch/None" StrokeColor="Swatch/None" StrokeWeight="0">
      <Properties>
        <PathGeometry>
          <GeometryPathType PathOpen="false">
            <PathPointArray>
              <PathPointType Anchor="0 0" LeftDirection="0 0" RightDirection="0 0"/>
              <PathPointType Anchor="0 400" LeftDirection="0 400" RightDirection="0 400"/>
              <PathPointType Anchor="480 400" LeftDirection="480 400" RightDirection="480 400"/>
              <PathPointType Anchor="480 0" LeftDirection="480 0" RightDirection="480 0"/>
            </PathPointArray>
          </GeometryPathType>
        </PathGeometry>
      </Properties>
    </TextFrame>
  </Spread>
</idPkg:Spread>

Because no bytes are embedded and no file is supplied, there is nothing for a renderer to draw inside the frame — so this example is intentionally structural, not a live render. What it shows is the shape of a placed image: the frame, the nested <Image>, the link, and the image's own transform. How the picture would actually be found, decoded, and cropped is the subject of formats & clipping.

Frequently asked questions

How is an image linked to a file in IDML? The reference is a LinkResourceURI string, which can sit directly on the <Image> element or on a <Link> child of it — both are read, and when both are present the outer <Image>'s value wins (first-write-wins). Our parser also accepts an href attribute as an alias; whatever the spelling, it captures the string and defers resolving it to real bytes until render time.

What is the difference between a linked and an embedded image? A linked image stores a URI pointing at a file on disk, while an embedded image stores the picture's bytes inline as base64 inside a <Contents> element. They differ on disk, but converge at the parser: both become properties on the same frame and end at the same render-time image slot, and a single template can mix the two freely. When both a URI and inline bytes are present, the inline bytes take precedence.

How does the renderer tell a missing graphic frame from a plain colour swatch? The parser records that a frame nests an image element separately from whether its link resolved. That lets the renderer distinguish a plain colour swatch (no image element, just a fill) from a graphic frame whose link is unresolvable (an image element, but no usable bytes) — so it can draw a missing-image placeholder in the second case instead of falling back to the frame's fill.