# Images

Reference for the image domain: `image(action: "add-picture", ...)` inserts a picture into a slide.
The image domain provides 16 actions: picture insertion, appearance controls, scalar and crop-frame
cropping, transparency, and image compression.

## Actions

| Tool | Action | Parameters | Notes |
|------|--------|------------|-------|
| `image` | `add-picture` | `presentation_session_id`, `slide_index`, `image_path`, `left`, `top`, `width`, `height`, optional `link_to_file`, `save_with_document`, `compression` | Embeds by default. Set `link_to_file=true` for a linked picture. Compression is `default`, `compress`, or `preserve`. |
| `image` | `set-brightness-contrast` | `presentation_session_id`, `slide_index`, `shape_index`, `brightness`, `contrast` | `brightness`/`contrast` are floats in `[0, 1]` (PowerPoint default is `0.5` for both). |
| `image` | `get-brightness-contrast` | `presentation_session_id`, `slide_index`, `shape_index` | Returns current `brightness`/`contrast`. |
| `image` | `set-recolor` | `presentation_session_id`, `slide_index`, `shape_index`, `color_type` | `color_type` is one of `msoPictureAutomatic` (default/no recolor), `msoPictureGrayscale`, `msoPictureBlackAndWhite`, `msoPictureWatermark`. Unrecognized names fail with `Success=false`. |
| `image` | `get-recolor` | `presentation_session_id`, `slide_index`, `shape_index` | Returns current `color_type`. |
| `image` | `set-crop` | `presentation_session_id`, `slide_index`, `shape_index`, `crop_left`, `crop_top`, `crop_right`, `crop_bottom` | Crop edges in points from the picture's edges (L-T-R-B order). Negative values expand the displayed image. Requires a properly sized source image for meaningful geometry. |
| `image` | `get-crop` | `presentation_session_id`, `slide_index`, `shape_index` | Returns current crop offsets in points (L-T-R-B). A fresh picture with no crop applied returns 0.0 for all four values. |
| `image` | `increment-brightness` | `presentation_session_id`, `slide_index`, `shape_index`, `increment` | Changes brightness by a relative amount; PowerPoint clamps the result to `[0, 1]`. |
| `image` | `increment-contrast` | `presentation_session_id`, `slide_index`, `shape_index`, `increment` | Changes contrast by a relative amount; PowerPoint clamps the result to `[0, 1]`. |
| `image` | `set-transparency-color` | `presentation_session_id`, `slide_index`, `shape_index`, `color_rgb` | Sets the color key using PowerPoint's RGB integer order (`0xBBGGRR`). |
| `image` | `get-transparency-color` | `presentation_session_id`, `slide_index`, `shape_index` | Reads the picture's color key. |
| `image` | `set-transparent-background` | `presentation_session_id`, `slide_index`, `shape_index`, `enabled` | Enables or disables color-key transparency; behavior depends on the image format. |
| `image` | `get-transparent-background` | `presentation_session_id`, `slide_index`, `shape_index` | Reads whether color-key transparency is enabled. |
| `image` | `set-crop-frame` | `presentation_session_id`, `slide_index`, `shape_index`, `picture_width`, `picture_height`, `picture_offset_x`, `picture_offset_y`, `frame_left`, `frame_top`, `frame_width`, `frame_height` | Sets the full source-picture and visible-frame geometry in points. |
| `image` | `get-crop-frame` | `presentation_session_id`, `slide_index`, `shape_index` | Reads source-picture size/offsets and visible-frame position/size in points. |
| `image` | `compress-pictures` | `presentation_session_id`, optional `slide_index`, `shape_index`, `resolution`, `delete_cropped_areas` | Compresses one picture, a slide, or the presentation. |

## Crop Behavior

When using `set-crop`, all four values are relative crop distances in points from the picture's
edges. A positive value crops inward (hides content); a negative value expands the visible area
outward (revealing areas beyond the original picture bounds in PowerPoint's rendering). PowerPoint
allows negative crop values as a valid expansion mechanism.

**Important:** Meaningful crop geometry requires a properly sized source image. The legacy test anomaly
of a 1×1 pixel image should **never** be treated as normal user behavior — it is a degenerate case
used only for testing framework integration and produces unintuitive crop results. Always use real,
properly sized source images (e.g., 100×100 pixels minimum) when working with crop operations.

Results from `get-crop` expose `cropLeft`, `cropTop`, `cropRight`, `cropBottom` as numeric
floats (in points). A fresh picture with no crop applied returns 0.0 for all four values.
These result fields are absent (null in JSON) only when the result comes from a non-crop operation
(e.g., `get-recolor`) — they are never null simply because no crop has been applied.

## PictureFormat Coverage

The image domain exposes these `Microsoft.Office.Interop.PowerPoint.PictureFormat` properties and methods:

| Member | Type | Status | Action | Notes |
|--------|------|--------|--------|-------|
| `Brightness` | Property | ✓ Exposed | `set-brightness-contrast`, `get-brightness-contrast` | Float [0, 1] scale. Default 0.5. |
| `Contrast` | Property | ✓ Exposed | `set-brightness-contrast`, `get-brightness-contrast` | Float [0, 1] scale. Default 0.5. |
| `ColorType` | Property | ✓ Exposed | `set-recolor`, `get-recolor` | MsoPictureColorType enum. |
| `CropLeft` | Property | ✓ Exposed | `set-crop`, `get-crop` | Direct scalar property, in points from left edge. |
| `CropTop` | Property | ✓ Exposed | `set-crop`, `get-crop` | Direct scalar property, in points from top edge. |
| `CropRight` | Property | ✓ Exposed | `set-crop`, `get-crop` | Direct scalar property, in points from right edge. |
| `CropBottom` | Property | ✓ Exposed | `set-crop`, `get-crop` | Direct scalar property, in points from bottom edge. |
| `Crop` | Object | ✓ Exposed | `set-crop-frame`, `get-crop-frame` | Exposes the source picture dimensions, offsets, and visible frame geometry in points. |
| `IncrementBrightness` | Method | ✓ Exposed | `increment-brightness` | Relative adjustment; PowerPoint clamps brightness to `[0, 1]`. |
| `IncrementContrast` | Method | ✓ Exposed | `increment-contrast` | Relative adjustment; PowerPoint clamps contrast to `[0, 1]`. |
| `TransparencyColor` | Property | ✓ Exposed | `set/get-transparency-color` | Uses PowerPoint's RGB integer order (`0xBBGGRR`); results depend on image format and color-key mode. |
| `TransparentBackground` | Property | ✓ Exposed | `set/get-transparent-background` | Enables or disables color-key transparency; defaults vary by image format. |
| `Application` | Property | ⊘ Not exposed | — | Read-only, non-actionable object reference. |
| `Creator` | Property | ⊘ Not exposed | — | Read-only, non-actionable object reference. |
| `Parent` | Property | ⊘ Not exposed | — | Read-only, non-actionable object reference. |

## Picture Compression

`compress-pictures` can target one picture by supplying both indexes, every picture on one slide by
supplying only `slide_index`, or all slides by omitting both. `shape_index` without `slide_index`
is invalid. The resolution presets are `high-fidelity` (do not reduce pixel dimensions), `hd`
(330 PPI), `print` (220 PPI), `web` (150 PPI), and `email` (96 PPI). Set
`delete_cropped_areas=true` to permanently remove pixels hidden by crop settings.

Compression requires a saved `.pptx` or `.pptm` file and Windows. Embedded PNG, JPEG, BMP, GIF,
and TIFF pictures are processed automatically. Linked, vector, animated, and unsupported pictures
are left unchanged and listed in `skippedPictures`. The operation saves and reopens the active
presentation as part of the update; verify important slides visually afterward. Counts and byte
totals in the result describe pictures actually changed, not every selected picture.

## Requirements

- `image_path` must be a **full Windows path** to a local, existing image file (e.g.
  `C:\Assets\logo.png`). There is no URL/remote-fetch parameter — download or generate the image
  to local disk first if it doesn't already exist there.
- The default is embedded: `link_to_file=false`, `save_with_document=true`. The presentation
  remains valid if the original file is moved or deleted.
- A linked-only picture uses `link_to_file=true`, `save_with_document=false` and depends on the
  full source path remaining available. `true/true` keeps the link and also saves picture data in
  the presentation. `false/false` is rejected because PowerPoint would have no picture data.
- `width`/`height` are explicit — this action does not auto-detect or preserve the source image's
  native aspect ratio. If the aspect ratio matters (logos, photos), compute `width`/`height` to
  match the source image's ratio yourself before calling, or the image will appear stretched or
  squashed.

## Placement Guidance

- Logos: small, corner-anchored, e.g. `width=80, height=80` near `left=20, top=20` (top-left) or
  `left=860, top=460` (bottom-right on a 960×540pt slide).
- Full-slide product shots/photos: leave a title band at the top (`top ≥ 80`) unless the image is

  intentionally full-bleed.
- Diagrams/screenshots next to explanatory text: place the image in one half of the slide
  (`width ≈ 420` on a 960pt-wide slide) with a text box in the other half.

## Verify After Adding

Always `export(action: "export-slide-to-image", ...)` after `image(action: "add-picture", ...)`
to confirm: the image loaded (not a broken placeholder), the aspect ratio looks correct, and it
doesn't overlap other shapes on the slide (see `export-and-verify.md`).

## Limited Editing After Insert

Post-insert adjustments available: `shape(action: "set-position", ...)`, `shape(action:
"set-size", ...)` (see `slides-and-shapes.md`), and the appearance, transparency, crop-frame, and
compression actions described above.

## Linked Picture Lifecycle

Use the `shape` tool after adding a linked picture:

1. `shape(action: "get-link-info", ...)` returns `linkSourceFullName`. `linkAutoUpdate` is null
   because some PowerPoint builds reject reads of the typed automatic-update property.
2. `shape(action: "set-link-auto-update", ..., auto_update: false)` switches between automatic
   and manual refresh. If the installed PowerPoint build rejects this typed operation, the MCP or
   CLI boundary returns the PowerPoint error rather than a successful or validation-shaped result.
3. `shape(action: "update-link", ...)` refreshes immediately and fails cleanly if the source file
   is missing.
4. `shape(action: "break-link", ...)` permanently embeds the current image and removes the file
   dependency. The picture shape remains in the slide.

These actions require a linked picture shape. Calling them on an embedded picture or ordinary
shape returns a validation error rather than attempting an invalid COM operation.