iofficeai--officecli/examples/word/pictures.md

Word Pictures

This demo consists of several files that work together:

• pictures.sh — CLI script that synthesizes two sample PNGs (a square logo, a wide banner) and drives officecli to build the document.
• pictures.py — Python SDK twin of pictures.sh; produces an equivalent pictures.docx.
• pictures.docx — The generated document (inline, cropped, alt-text, watermark, wrapped, positioned, and clickable pictures).
• pictures-logo.png / pictures-banner.png — The generated sample images, embedded into the document.
• pictures.md — This file. Maps each section to the picture features it demonstrates.

Regenerate

cd examples/word
pip install Pillow   # required for sample image generation
bash pictures.sh
# → pictures.docx  (+ pictures-logo.png, pictures-banner.png)

How docx pictures are addressed

A picture in Word is a run inside a paragraph. So you add --type picture to a paragraph path (/body/p[N] or /body/p[@paraId=X]), and the picture's own path is that paragraph plus a run index (/body/p[@paraId=X]/r[N]).

• Inline (default) — the picture sits in the text flow like a large glyph.
• Floating — pass --prop anchor=true to unlock wrap, behindText, hAlign / vAlign, hPosition / vPosition, hRelative / vRelative.

Sections

1 — Inline Picture

An inline picture flows with the paragraph text; only width / height (always unit-qualified) apply.

officecli add pictures.docx /body --type paragraph --prop text="1. Inline Picture" --prop style=Heading1
officecli add pictures.docx /body --type paragraph --prop text="An inline picture flows with the paragraph text ..."
officecli add pictures.docx /body --type paragraph --prop text=""
officecli add pictures.docx '/body/p[3]' --type picture \
  --prop src=pictures-logo.png \
  --prop width=3cm --prop height=3cm

Features: --type picture, src (file path / URL / data-URI), width / height (unit-qualified — always pass cm/in/pt; a bare number is raw EMU)

---

2 — Cropped Picture

crop=L,T,R,B trims each edge by a percentage of the source image.

officecli add pictures.docx '/body/p[6]' --type picture \
  --prop src=pictures-banner.png \
  --prop crop=10,5,15,8 \
  --prop width=10cm --prop height=2.5cm

Features: crop (1 value = symmetric, or 4 values L,T,R,B = per-edge percent); per-edge cropLeft / cropTop / cropRight / cropBottom accepted on add/set. Get folds all sides into the canonical 4-value crop key.

---

3 — Alt Text (Accessibility)

alt= writes the DocProperties description that screen readers announce.

officecli add pictures.docx '/body/p[9]' --type picture \
  --prop src=pictures-logo.png \
  --prop width=3cm --prop height=3cm \
  --prop alt="Company logo: a blue circle enclosing a yellow triangle"

Features: alt (alternative text; aliases altText, description). When omitted, no description is written (an auto-filled filename is worse than none for screen readers).

---

4 — Behind-Text Watermark

A floating picture with wrap=none + behindText=true sits behind the text like a watermark, centered on the page margins.

officecli add pictures.docx '/body/p[11]' --type picture \
  --prop src=pictures-banner.png \
  --prop anchor=true --prop wrap=none --prop behindText=true \
  --prop hAlign=center --prop vAlign=center \
  --prop hRelative=margin --prop vRelative=margin \
  --prop width=12cm --prop height=3cm \
  --prop alt="Decorative watermark banner"

Features: anchor=true (floating), wrap=none + behindText=true (behind-text z-order), hAlign / vAlign (relative alignment keyword), hRelative / vRelative (reference frame)

---

5 — Square Text Wrap

With wrap=square, surrounding text flows around the picture's bounding box. Here the picture is right-aligned to the margin so the paragraph wraps down its left side.

officecli add pictures.docx '/body/p[13]' --type picture \
  --prop src=pictures-logo.png \
  --prop anchor=true --prop wrap=square \
  --prop hAlign=right --prop hRelative=margin --prop vRelative=paragraph \
  --prop width=3.5cm --prop height=3.5cm \
  --prop alt="Logo floated right with square wrap"

Features: wrap (none, square, tight, topandbottom, through), hAlign=right relative to the margin frame

---

6 — Absolute Position (hPosition / vPosition)

Instead of relative alignment, pin a floating picture to an absolute offset from its reference frame. wrap=tight makes text hug the boundary.

officecli add pictures.docx '/body/p[15]' --type picture \
  --prop src=pictures-logo.png \
  --prop anchor=true --prop wrap=tight \
  --prop hPosition=2cm --prop vPosition=1cm \
  --prop hRelative=margin --prop vRelative=paragraph \
  --prop width=3cm --prop height=3cm \
  --prop alt="Logo at absolute 2cm,1cm offset with tight wrap"

Features: hPosition / vPosition (absolute offset — always unit-qualified; a bare number is raw EMU), wrap=tight

---

7 — Clickable Picture (link)

link= wraps the picture in a click hyperlink.

officecli add pictures.docx '/body/p[18]' --type picture \
  --prop src=pictures-banner.png \
  --prop width=10cm --prop height=2.5cm \
  --prop link="https://example.com" \
  --prop alt="Banner linking to example.com"

Features: link (absolute URL → external relationship; #anchor or bookmark name → internal jump)

---

8 — Decorative Picture (accessibility)

decorative=true marks the image as decorative: screen readers skip it entirely (no alt text is announced). Stored as an adec:decorative extension under the picture's <wp:docPr>.

officecli add pictures.docx '/body/p[21]' --type picture \
  --prop src=pictures-banner.png \
  --prop width=10cm --prop height=2.5cm \
  --prop decorative=true

get reports decorative=true (only when the flag is set). decorative also works via set. Use it for purely ornamental images that carry no information.

Features: decorative (accessibility — screen readers skip the image)

---

Complete Feature Coverage

Feature	Section
inline picture: default text-flow placement	1
width / height: unit-qualified sizing	1–7
src=: file path (also URL / data-URI)	1–7
crop=L,T,R,B: per-edge crop percent	2
cropLeft / cropTop / cropRight / cropBottom: named per-edge (add/set)	2
alt=: accessibility description	3
anchor=true: floating picture	4–6
wrap=none + behindText: behind-text watermark	4
hAlign / vAlign: relative alignment keyword	4, 5
hRelative / vRelative: reference frame	4–6
wrap=square: text flows around bounding box	5
wrap=tight: text hugs boundary	6
hPosition / vPosition: absolute offset	6
link=: clickable image hyperlink	7
decorative=true: mark decorative (screen readers skip)	8

Inspect the Generated File

# List every picture with its stable run path and key props
officecli query pictures.docx picture

# Inline picture (section 1) — width/height/wrap=inline
officecli get pictures.docx '/body/p[3]/r[2]'

# Cropped banner (section 2) — crop=10,5,15,8
officecli get pictures.docx '/body/p[6]/r[2]'

# Alt text (section 3)
officecli get pictures.docx '/body/p[9]/r[2]'

# Behind-text watermark (section 4) — anchor/behindText/hAlign/vAlign
officecli get pictures.docx '/body/p[11]/r[2]'

# Square wrap, right-aligned (section 5)
officecli get pictures.docx '/body/p[13]/r[2]'

# Absolute position + tight wrap (section 6) — hPosition/vPosition
officecli get pictures.docx '/body/p[15]/r[2]'

# Clickable banner (section 7) — link=
officecli get pictures.docx '/body/p[18]/r[2]'

Note on paths: the /body/p[N]/r[2] positional paths above assume a freshly generated file. officecli query pictures.docx picture prints the authoritative @paraId paths, which are stable across edits.