Place an image in a frame

An image in IDML is an <Image> nested inside a frame — usually a Rectangle — with its own transform and a link to the file.

In short There is no dedicated image-frame element. A graphic frame is a Rectangle (or Oval, or Polygon) with an <Image> child, and InDesign marks such a frame ContentType="GraphicType". The image carries its own ItemTransform, which maps the picture's pixels into the frame, a GraphicBounds giving the picture's pixel box, and a <Link> whose LinkResourceURI names the file. Download the sample.

The recipe

1. Draw the frame. Add a Rectangle to the spread with an ItemTransform that places it (in the example, 1 0 0 1 150 200: 150 pt across, 200 pt down) and a PathGeometry tracing its outline. Mark it ContentType="GraphicType", as InDesign does for every frame that holds a picture.
2. Nest an <Image> inside it. The Image child is what holds the picture; the frame clips it.
3. Give the image its own ItemTransform. It maps the picture's pixel space into the frame's space. The example uses 0.5 0 0 0.5 0 0, a half-scale; the frame's transform then carries the result onto the spread.
4. Declare the picture's box. In the image's <Properties>, <GraphicBounds> gives the picture's extent in its own pixel space, Left/Top/Right/Bottom — here 0 0 600 400, a 600 × 400 pixel picture.
5. Link the file. Add a <Link> whose LinkResourceURI names it. InDesign writes an absolute file: URI with one slash after the scheme and reserved characters percent-encoded, such as file:/Users/me/Links/photo.jpg or file:C:/Projects/Links/CODE%201.jpg.

<?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 holds the picture; ContentType labels the frame. In InDesign's packages, every frame with an Image, PDF, EPS or ImportedPage child carries ContentType="GraphicType", and an empty frame meant for a picture does too. The sample's frame leaves the attribute out, which a reader keyed on the child does not notice.
• Two transforms compose. The image's ItemTransform places the picture inside the frame; the frame's places the frame on the spread. Move the whole thing with the frame's transform; crop or scale the picture with the image's.
• GraphicBounds is the pixel box. Write 0 0 width height in pixels and let the image's ItemTransform do the scaling. A frame-sized GraphicBounds combined with an explicit transform puts the picture in the wrong place in InDesign.
• Use an absolute link. InDesign 20.0.1 resolves a relative LinkResourceURI to nothing: the frame opens empty. The sample's file:Links/photo.jpg is relative and is reported as missing; with the picture missing, InDesign keeps the frame, its geometry and its crop, and shows a missing-link placeholder.
• A picture can be embedded instead. An <Image> can carry its pixels in a <Contents> child rather than linking them; see placed images.

In Paged: placed images are read from the nested Image, positioned through the two transforms, and drawn from bytes the host supplies for the link; a link with no bytes is drawn as InDesign's missing-image placeholder. GraphicBounds and ContentType are carried but not used. Supported · verified

Frequently asked questions

What makes a frame an image frame? The nested <Image> (or PDF, EPS, ImportedPage) child holds the picture. InDesign also marks the frame ContentType="GraphicType", including an empty frame meant for a picture.

Why does an image have two transforms? The image's ItemTransform maps its pixels into the frame (the example uses a half-scale), and the frame's ItemTransform places the frame on the spread. Edit the frame's to move the whole thing, the image's to crop or scale the picture inside it.

Which form of LinkResourceURI does InDesign resolve? An absolute file: URI, written with one slash after the scheme and percent-encoded reserved characters, such as file:/Users/me/Links/photo.jpg. A relative URI resolves to nothing in InDesign 20.0.1.

Can the picture be embedded instead of linked? Yes, as a <Contents> payload inside the <Image>. The placed images reference covers it.