ItemTransform
ItemTransform is the six-number affine matrix (a b c d tx ty) that maps an IDML element's inner space into its parent's space; InDesign writes it everywhere.
ItemTransform is the six-number affine matrix that maps an element's inner space into its parent's space.
In short An item draws its outline in its own space, usually starting at 0, 0.
ItemTransform maps that space into the item's parent: the spread, an enclosing Group,
or the frame the item was pasted into. The value is six numbers, a b c d tx ty, the free
entries of a 2D affine matrix: translation, scale, rotation and shear. 1 0 0 1 0 0 is the
identity. InDesign writes an ItemTransform on every spread, page and page item, identity
included, and does not treat a missing one as the identity.
The six numbers
The value is six numbers separated by spaces. Applied to a point (x, y) of the inner
space, it gives the point in the parent space:
x' = a·x + c·y + tx
y' = b·x + d·y + ty| Entry | Role |
|---|---|
a, d | horizontal and vertical scale (and part of any rotation) |
b, c | shear; together with a and d they express rotation |
tx, ty | translation in points; a positive ty moves down, because Y grows downward |
A rotation by θ is cos θ sin θ -sin θ cos θ tx ty. A horizontal flip is a negative a.
Where it appears
| Element | Maps | Notes |
|---|---|---|
Spread, MasterSpread | the spread onto the pasteboard | InDesign uses the translation to stack spreads down the pasteboard; it cancels out per page. A rotation turns the whole spread. |
Page | the page's GeometricBounds into spread space | puts the left page of a facing spread at negative x; see units & origin |
page items: TextFrame, Rectangle, Oval, GraphicLine, Polygon, Group | the item into its parent | the parent is the spread, a Group, or a host frame |
Image, EPS, PDF inside a frame | the placed content into the frame | how an image is scaled, moved and cropped inside its frame |
Page · MasterPageTransform | the applied master page onto this page | same six numbers; see master items and stamping |
A page item is never a child of a <Page>, so a page is never an item's parent space.
Transforms compose
A parent's transform applies on top of its children's. A rectangle inside a group inside
a spread reaches spread space as group ∘ rectangle: first the rectangle's own matrix,
then the group's. Nesting composes at every level, so a member two groups deep is
outer ∘ inner ∘ member.
The same holds for content pasted into a frame (Paste Into in InDesign). The pasted item
is written as a child element of the host Rectangle, Oval or Polygon, its
ItemTransform is relative to the host, and the host's path clips it. A placed image is
the common case: the frame's transform places the frame, the <Image> transform places
the picture inside it.
Two rectangles in a group. Each member's ItemTransform is relative to the group; the group's ItemTransform moves both.
A shape at the origin, placed by its transform
The rectangle below draws a 300 × 120 outline from 0, 0 and is placed with
ItemTransform="1 0 0 1 150 200": no scale, no rotation, moved 150 pt right and 200 pt
down. Change tx and ty and it moves; change a or d and it scales. The anchors stay
the same.
A rectangle drawn at the origin and placed by the translation of its ItemTransform.
Always write it
InDesign's own packages carry ItemTransform on every <Spread>, <Page> and page item,
even when the value is 1 0 0 1 0 0. InDesign does not read a missing attribute as the
identity: in a measured case, every transform-less item of a facing-page document opened one
page width to the left, leaving the left pages empty, and the same file with
ItemTransform="1 0 0 1 0 0" added to each item opened correctly. A writer should spell it
out every time.
Precision matters as well. The values are decimal text; a writer that rounds them through single-precision floats drifts items by fractions of a point on every save. Writing the value back exactly as read, when it has not changed, avoids that.
In Paged: a missing
Supported · verifiedItemTransformis read as the identity on import, and the exporter always writes one. Spread rotation and scale are applied when rendering.
Frequently asked questions
What do the six numbers in ItemTransform mean?
They are a b c d tx ty of a 2D affine matrix: x' = a·x + c·y + tx and
y' = b·x + d·y + ty. a and d scale, b and c shear or rotate, tx and ty
translate, with a positive ty moving down.
What is an item's ItemTransform relative to? Its parent: the spread for a top-level item, the group for a group member, and the host frame for content pasted into a frame. It is never relative to a page.
Can I leave out ItemTransform when it is the identity?
No. InDesign writes 1 0 0 1 0 0 explicitly and does not read a missing attribute as the
identity. Write it on every spread, page and page item.
How do nested Group transforms combine?
By composition, innermost first: the member's own matrix, then each enclosing group's,
out to the spread. A member two groups deep is outer ∘ inner ∘ member.
Units & origin
IDML measures in points with Y growing downward. Page items use spread coordinates, with the spine at x = 0 and each page placed by its own ItemTransform.
GeometricBounds
GeometricBounds is an IDML element's axis-aligned bounding box in its own space, written in the y-before-x order y1 x1 y2 x2 (top, left, bottom, right).