Place an image in a frame

An image in IDML is a Rectangle with an <Image> nested inside it — there is no dedicated "image frame" element.

In short: you place a picture by nesting an <Image> inside an ordinary Rectangle, the same rectangle a colored shape uses. The presence of the Image child is what turns the rectangle into a graphic frame; the image carries its own ItemTransform and GraphicBounds, plus a <Link> whose LinkResourceURI names the file on disk. This recipe places a linked photo in a frame on a page.

The recipe

1. Draw the frame as a Rectangle. On a spread's Page, add a Rectangle with an ItemTransform that positions it (in the example, 1 0 0 1 150 200 shifts it 150 across and 200 down) and a PathGeometry whose four PathPointType anchors trace the frame's outline. Nothing about the rectangle yet says "image."
2. Nest an <Image> inside it. The presence of the Image child — not any attribute on the rectangle — is what makes the rectangle a graphic frame.
3. Give the image its own ItemTransform. This maps the picture's natural pixel space into the frame's coordinate space. The example uses 0.5 0 0 0.5 0 0, a half-scale; the frame's own transform then carries that onto the page.
4. Declare the image's bounds. Inside the image's <Properties>, a <GraphicBounds> gives the picture's extent (Left/Top/Right/Bottom) in its own space — here 0 0 600 400, a 600×400 source.
5. Link the file with <Link>. Add a <Link> whose LinkResourceURI names the external file, e.g. file:Links/photo.jpg. The parser captures the URI string and defers the actual lookup to an asset resolver at render time — so the path just has to be resolvable when you render, not when you author.

Worked over a placed photo

The Spreads/Spread_uspread.xml part below holds a Rectangle with an Image nested inside it, the image's ItemTransform and GraphicBounds, and the Link that points at the file. Read it top to bottom and the recipe is right there.

<?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>

Things to get right

• The Image makes the frame, not an attribute. A bare Rectangle is a shape; the same rectangle with an <Image> child is a graphic frame. Don't look for a "ContentType" or frame flag — there isn't one.
• Two transforms compose. The image's ItemTransform places the picture inside the frame; the frame's ItemTransform places the frame on the page. To move the whole thing, edit the frame's transform; to crop or scale the picture within it, edit the image's.
• A missing file doesn't fail the parse. LinkResourceURI is just a captured string — the parser opens the document fine without the asset present. The picture only goes missing at render time, when the resolver can't find it.
• Links and embeds parse alike. Whether the picture is linked by URI or embedded as a <Contents> payload, it reaches the parser the same way; the recipe above uses a link.

For the full picture — supported formats, clipping, and how the asset resolver works at render time — see Images & graphics and the placed images reference.

Frequently asked questions

What makes a Rectangle an image frame rather than a shape? The nested <Image> child, and nothing else. A bare Rectangle is a shape; the same rectangle with an <Image> inside it is a graphic frame. There is no ContentType attribute or frame flag to set — don't look for one.

Why does an image have two transforms? The image's own ItemTransform maps its natural pixel space into the frame's coordinate space (the example uses 0.5 0 0 0.5 0 0, a half-scale), while the frame's ItemTransform places the frame on the page. They compose: edit the frame's transform to move the whole thing, and the image's transform to crop or scale the picture within it.

Does a missing image file break the parse? No. LinkResourceURI is captured as a plain string, so the document opens fine even when the asset isn't present. The parser defers the actual lookup to an asset resolver at render time — the path only needs to resolve when you render, not when you author.

Can the picture be embedded instead of linked? Yes. A picture can be linked by URI or embedded as a <Contents> payload, and both reach the parser the same way. This recipe uses a link; the placed images reference covers embedding.