[Epic] Pictures, SVG & Picture Effects — replace_image, picture-fill, recolor, transparency

[MHoroszowski]

Problem

The picture API is half-built. The most-asked feature is Picture.replace_image() (scanny/python-pptx#116, 23 comments) — replace a picture's blob in-place while preserving its size, position, crop, and shape effects. SVG embedding is unsupported despite being native PowerPoint since 2016 (scanny/python-pptx#1112, scanny/python-pptx#1115) — two independent forks have implemented it, signalling real demand. Picture-fill on shapes (scanny/python-pptx#234, #419) round-trips on read but has no setter on FillFormat. Recolor, transparency, and artistic effects (blur, paint, etc.) are entirely absent.

Sub-features

• Picture.replace_image(image_file) — swap the blob, keep the position/size/crop/effects
• FillFormat.picture(image_file, ...) setter mirroring solid() / gradient() / pattern() for shape fills
• Native SVG embedding via <asvg:svgBlip> extension (auto-fallback PNG)
• Picture transparency: Picture.transparency = 0.5 emitting <a:alphaModFix amt=>
• Picture recolor: Picture.recolor(luminance=, brightness=, contrast=, color=) mapping to <a:lum>, <a:duotone>
• Picture artistic effects (read+round-trip preservation; write API in Phase B): <a14:imgEffectLst> for blur, paint strokes, etc.
• MPO-encoded JPEG handling (iPhone HDR), TIFF support
• PicturePlaceholder fit-to-placeholder semantics (closes #176)

Prior art

• Open PRs: scanny/python-pptx#1115 SVG support (kameronbrooks 2026; clean diff, ~300 LOC). scanny/python-pptx#1075 MPO JPEG (lovelock 2025; one-line). scanny/python-pptx#581 resize-in-placeholder (dinitak; fixes Fitting images to placeholder scanny/python-pptx#176). scanny/python-pptx#439 crop+vcenter (aatwork). scanny/python-pptx#757 PicturePlaceholder.insert_picture.
• Forks:
  • kameronbrooks/python-pptx — SVG (basis of feat: add SVG image support scanny/python-pptx#1115).
  • e-rus/python-pptx — independent SVG patch.
  • Force1ess/python-pptx — blipFill image extract + rId setter (PPTAgent companion).
  • OscarPellicer/python-pptx — TIFF support.
• User issues this would close: #41, #62, #116, #165, #176, #234, #419, #508, #553, #635, #652, #787, #806, #834, #885, #915, #1020, #1112.
• OOXML: DrawingML §20.1.8.14 <a:blipFill>, §20.1.8.55 <a:lum>, §20.1.8.x <a:duotone>, §20.1.8.10 <a:alphaModFix>, <a14:imgEffectLst> extension, <asvg:svgBlip> (http://schemas.microsoft.com/office/drawing/2016/SVG/main).
• Code paths: src/pptx/parts/image.py, src/pptx/oxml/shapes/picture.py, src/pptx/dml/fill.py, src/pptx/shapes/picture.py.

Acceptance criteria

• Picture.replace_image() preserves size/position/crop/effects exactly (test by image-blob diff + XPath assertions).
• An SVG inserted via add_picture("logo.svg") opens as native SVG in PowerPoint Mac/Win (verify with file → save-as XML and check for <asvg:svgBlip>).
• FillFormat.picture("texture.jpg") sets a shape fill to a tiled or stretched picture.
• 25+ behave scenarios.
• File-size regression test: replacing a 5MB image with a 100KB image actually shrinks the package.

Effort: M