Images & graphics

A picture in an IDML layout is never free-floating — it is always placed inside a frame.

In short: A graphic in an InDesign layout lives inside a frame, the same kind of frame that can hold a colour or a story. The frame owns the geometry — where the picture sits, how big it is, and what shape crops it — while the picture adds only a pointer to some image data and a small transform that says how its pixels land inside that frame. Our parser reads all of that and then stops: it does not load the image bytes, leaving the file lookup and decoding to a separate component at render time. This chapter explains how placed images are structured, what the parser captures, and why the asset lookup is deferred.

A picture in an InDesign layout is never a free-floating thing. It is always placed — it lives inside a frame, the same kind of frame that can hold a colour or a story. The frame owns the geometry: where the picture sits on the page, how big it is, and what shape crops it. The picture itself only adds a pointer to some image data and a small transform that says how its pixels land inside that frame.

That split is the whole reason this chapter comes after frames & paths and geometry & coordinates. A placed image is a frame you already understand, with two extra things hung off it: a reference to the image, and the image's own ItemTransform. Read those chapters first and a graphic frame holds no surprises — it is a Rectangle (or Oval, or Polygon) that happens to nest an <Image>.

What the parser captures, and what it doesn't

The single most important idea in this chapter is that our parser does not load images. It reads the frame, it reads the reference string (a URI, or inline bytes), it reads the image's transform — and then it stops. The actual job of finding the file, decoding the JPEG or PNG, and turning it into pixels happens later, at render time, through a separate component called the asset resolver.

This is deliberate. The same parsed document can be rendered by a host that has all the linked files on disk, by one that has none of them, or by one that substitutes its own. The parser's output is identical in every case; only the resolver differs. So when you parse a package whose images are missing, nothing fails — you get a perfectly good description of every frame, with the picture slots simply left for the resolver to fill or leave empty.

What this chapter covers

• Placed images — the reference page. How a frame nests an <Image>, how it points at a file through <Link> / LinkResourceURI, the image's own transform, and why a linked picture and an embedded one look the same to the parser.
• Formats & clipping — which image formats the resolver can decode, how the frame's path crops the picture, and where the current gaps are (decoding deferred to the resolver, clipping precision, vector formats like EPS and PDF).

Throughout, "graphic frame" just means a frame with a picture in it. The frame machinery is unchanged from the frames chapter; everything new here is the picture and how it attaches.

Frequently asked questions

What is a placed image in IDML? A placed image is a frame — usually a Rectangle, but also an Oval or Polygon — that nests an <Image> element. The frame owns the geometry and the crop shape, while the nested image carries a reference to the picture data and its own transform; the presence of that nested image element is what turns an ordinary frame into a graphic frame.

Does the IDML parser load and decode the picture? No. The parser reads the frame, the reference string (a URI or inline bytes), and the image's transform, then stops. Finding the file and decoding the JPEG, PNG, or other format happens later at render time, through a separate component called the asset resolver.

What happens when a placed image's file is missing? Nothing fails. Because the parser never tries to load the bytes, parsing a package whose images are missing still produces a complete description of every frame; the picture slots are simply left for the resolver to fill or leave empty.