Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

fix(svg-to-pptx): preserve unmodified raster bytes in cap mode

hugohe39b7a342841fd
diff --git a/skills/ppt-master/references/svg-image-embedding.md b/skills/ppt-master/references/svg-image-embedding.md
index ed5e85ee..7261f14a 100644
--- a/skills/ppt-master/references/svg-image-embedding.md
+++ b/skills/ppt-master/references/svg-image-embedding.md
@@ -149,14 +149,15 @@ aliases only when invoked through `finalize_svg.py --only`.
## Best Practices
-### Image Optimization
+### Native PPTX Image Export
-Compress before embedding to reduce file size:
+**Default — preserve unmodified image bytes**: `svg_to_pptx.py` uses `--image-sizing cap`. It keeps original bytes when an image needs neither resizing nor EXIF geometry normalization, and re-encodes only images that require one of those transformations. Use the explicit compact command only when a compact export is requested.
-```bash
-convert input.png -quality 85 -resize 1920x1080\> output.png # ImageMagick
-pngquant --quality=65-80 input.png -o output.png # pngquant (recommended)
-```
+| Need | Command |
+|---|---|
+| Normal native export | `python3 scripts/svg_to_pptx.py <project_path>` |
+| Explicit compact export | `python3 scripts/svg_to_pptx.py <project_path> --image-sizing display --image-scale 2 --image-quality 85` |
+| Force original bytes | `python3 scripts/svg_to_pptx.py <project_path> --no-image-optimize` |
### File Organization
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index 3e3add8f..9c098daf 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -256,7 +256,7 @@ python3 scripts/finalize_svg.py <project_path>
python3 scripts/svg_to_pptx.py <project_path>
```
-`finalize_svg.py` optimizes ordinary raster images by default using `2x` display pixels and max `2560px`; validated nested crop transports retain source pixel dimensions because their inner `1×1` image is source-unit geometry rather than a rendered-pixel budget. Native `svg_to_pptx.py` defaults to `--image-sizing cap`: oversized full sources normally reduce toward `2560px`, but cropped or stretched placements (including imported picture crops) retain enough source pixels to avoid undersupplying the visible frame. Use `svg_to_pptx.py --image-sizing display --image-scale 2` only for aggressive size reduction, or `--no-image-optimize` when the native PPTX must embed original image bytes.
+`finalize_svg.py` optimizes ordinary raster images by default using `2x` display pixels and max `2560px`; validated nested crop transports retain source pixel dimensions because their inner `1×1` image is source-unit geometry rather than a rendered-pixel budget. Native `svg_to_pptx.py` defaults to `--image-sizing cap`: images that need neither resizing nor EXIF geometry normalization retain their original bytes, while oversized single-frame raster sources are re-encoded after resizing toward `2560px`. Cropped or stretched placements (including imported picture crops) retain enough source pixels to avoid undersupplying the visible frame. Use `svg_to_pptx.py --image-sizing display --image-scale 2 --image-quality 85` for an explicit compact export, or `--no-image-optimize` to force original image bytes.
`finalize_svg.py` remains mandatory because it creates the self-contained `svg_final/` visual preview. Those SVGs may be opened directly or inserted into PowerPoint as SVG pictures. The only supported generated-PPTX path is `svg_output/` through the project SVG-to-DrawingML converter; `-s final` is diagnostic-only, and PowerPoint's manual Convert-to-Shape operation is unsupported.
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index c96158ec..c76e46a1 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -506,6 +506,10 @@ Convert project SVGs into PPTX.
```bash
python3 scripts/svg_to_pptx.py <project_path>
+# Explicit compact image export:
+python3 scripts/svg_to_pptx.py <project_path> --image-sizing display --image-scale 2 --image-quality 85
+# Force original image bytes:
+python3 scripts/svg_to_pptx.py <project_path> --no-image-optimize
python3 scripts/svg_to_pptx.py <project_path> --native-charts-and-tables
python3 scripts/svg_to_pptx.py <project_path> --pptx-structure structured # deck/layout template override
python3 scripts/svg_to_pptx.py <project_path> --pptx-structure flat # free-design/brand-only override
@@ -523,6 +527,12 @@ python3 scripts/svg_to_pptx.py <project_path> --recorded-narration audio --anima
python3 scripts/svg_to_pptx.py <project_path> --recorded-narration audio --no-animations
```
+Native image export defaults to `--image-sizing cap`: it preserves source bytes
+when no resize or EXIF geometry normalization is required, and re-encodes only
+images that require one of those transformations. The `display` command above
+is an explicit compact export; `--no-image-optimize` disables all native image
+optimization and forces original bytes.
+
The normal command reads `pptx_structure.mode` from `spec_lock.md`. For legacy
projects whose lock exists but predates that field, export emits one compatibility
warning and uses `flat`; no SVG regeneration is required. A missing `spec_lock.md`,
diff --git a/skills/ppt-master/scripts/svg_to_pptx/drawingml/elements.py b/skills/ppt-master/scripts/svg_to_pptx/drawingml/elements.py
index 99461a90..52c60cf6 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/drawingml/elements.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/drawingml/elements.py
@@ -4037,6 +4037,12 @@ def _optimize_image_for_pptx(
original_size = img.size
img = _resize_for_target(img, target_w, target_h)
resized = img.size != original_size
+ if (
+ ctx.image_sizing == 'cap'
+ and not geometry_normalized
+ and not resized
+ ):
+ return img_data, img_format
# Preserve source semantics: only an original JPEG stays lossy. PNG and
# other static raster formats use lossless PNG after any resize.
prefer_jpeg = img_format.lower() in {'jpg', 'jpeg'}
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/builder.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/builder.py
index bdffb4e8..410202ca 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/builder.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/builder.py
@@ -4662,12 +4662,12 @@ def create_pptx_with_native_svg(
narration_audio: Optional dict mapping SVG stem to narration audio file.
use_narration_timings: Whether to set slide auto-advance from audio duration.
narration_padding: Extra seconds added after each narration before advancing.
- image_optimize: Whether native export downscales oversized raster images.
- image_max_dimension: Maximum optimized image dimension in pixels.
- image_sizing: ``cap`` only limits source dimensions; ``display`` sizes
- from rendered SVG boxes.
+ image_optimize: Whether native export optimizes raster images when needed.
+ image_max_dimension: Preferred optimized image dimension cap in pixels.
+ image_sizing: ``cap`` preserves unchanged source bytes and limits
+ oversized sources; ``display`` sizes from rendered SVG boxes.
image_scale: Target image pixels per SVG display pixel.
- image_quality: JPEG quality used for opaque optimized rasters.
+ image_quality: JPEG quality used when opaque rasters are re-encoded.
native_objects: Replace explicit ``data-pptx-replace-with`` chart/table
fallback groups with native PowerPoint Chart/Table objects. Default off.
conversion_trace_path: Optional JSON path for native conversion diagnostics.
@@ -4884,16 +4884,19 @@ def create_pptx_with_native_svg(
if image_sizing == 'display':
image_mode = (
f"display scale {image_scale:g}, "
- f"max {image_max_dimension or 'unlimited'} px"
+ f"preferred max {image_max_dimension or 'unlimited'} px"
)
else:
- image_mode = f"cap max {image_max_dimension or 'unlimited'} px"
+ image_mode = (
+ f"preferred cap {image_max_dimension or 'unlimited'} px, "
+ "unchanged bytes preserved"
+ )
print(
" Image optimization: Enabled "
- f"({image_mode}, JPEG q{image_quality})"
+ f"({image_mode}, JPEG q{image_quality} when re-encoded)"
)
else:
- print(" Image optimization: Disabled")
+ print(" Image optimization: Disabled (original bytes)")
elif use_compat_mode:
print(f" Compatibility mode: Enabled (PNG + SVG dual format)")
print(f" PNG renderer: {renderer_name} {renderer_status}")
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py
index 0e98c431..a854dd20 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py
@@ -855,19 +855,23 @@ Recorded narration:
),
)
parser.add_argument('--no-image-optimize', action='store_true',
- help='Disable native PPTX raster image optimization; embeds original image bytes.')
+ help='Disable native PPTX raster image optimization and always embed '
+ 'the original image bytes.')
parser.add_argument('--image-max-dimension', type=int, default=2560,
- help='Preferred optimized raster cap in pixels; cap mode may retain more '
- 'for cropped/stretched effective resolution (default: 2560).')
+ help='Preferred raster cap in pixels. Cap mode re-encodes only images '
+ 'that require resizing or EXIF geometry normalization, and may '
+ 'retain more pixels for cropped/stretched visible resolution '
+ '(default: 2560).')
parser.add_argument('--image-sizing', choices=['cap', 'display'], default='cap',
- help='Raster sizing mode: cap limits source dimensions without '
- 'undersupplying cropped/stretched visible pixels; '
- 'display sizes from the SVG rendered box (default: cap).')
+ help='Raster sizing mode: cap preserves original bytes unless resizing '
+ 'or EXIF geometry normalization is required; display targets the '
+ 'SVG rendered box for explicit compaction (default: cap).')
parser.add_argument('--image-scale', type=float, default=2.0,
help='Target optimized image pixels per SVG display pixel '
'when --image-sizing=display (default: 2.0).')
parser.add_argument('--image-quality', type=int, default=85,
- help='JPEG quality for optimized opaque raster images, 1-100 (default: 85).')
+ help='JPEG quality for raster images re-encoded during optimization, '
+ '1-100 (default: 85).')
def non_negative_float(value: str) -> float:
try: