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(image-pipeline): close fidelity and transaction gaps

hugohe3f438ff6c5f8d
diff --git a/skills/ppt-master/scripts/finalize_svg.py b/skills/ppt-master/scripts/finalize_svg.py
index 9e3fd38d..ffc88d45 100644
--- a/skills/ppt-master/scripts/finalize_svg.py
+++ b/skills/ppt-master/scripts/finalize_svg.py
@@ -39,6 +39,7 @@ import sys
import shutil
import argparse
from pathlib import Path
+from typing import TextIO
from xml.etree import ElementTree as ET
from console_encoding import configure_utf8_stdio
@@ -63,10 +64,11 @@ from svg_to_pptx.use_expander import (
)
-def safe_print(text: str) -> None:
+def safe_print(text: str, *, file: TextIO | None = None) -> None:
"""Print text while tolerating Windows terminal encoding limits."""
+ stream = file or sys.stdout
try:
- print(text)
+ print(text, file=stream)
except UnicodeEncodeError:
replacements = {
chr(0x23F3): "[..]",
@@ -79,7 +81,7 @@ def safe_print(text: str) -> None:
}
for source, target in replacements.items():
text = text.replace(source, target)
- print(text)
+ print(text, file=stream)
def process_flatten_text(svg_file: Path, verbose: bool = False) -> bool:
@@ -236,11 +238,17 @@ def finalize_project(
)
img_count += count
img_errors += errs
+ if img_errors:
+ safe_print(
+ f"[ERROR] Image alignment/embedding failed for "
+ f"{img_errors} image(s); svg_final was not published",
+ file=sys.stderr,
+ )
+ shutil.rmtree(svg_final, ignore_errors=True)
+ return False
if not quiet:
if img_count > 0:
msg = f" {img_count} image(s) aligned + embedded"
- if img_errors:
- msg += f" ({img_errors} error(s))"
safe_print(msg)
if office_vector_count:
safe_print(
diff --git a/skills/ppt-master/scripts/image_gen.py b/skills/ppt-master/scripts/image_gen.py
index 00558d47..ce01a34f 100644
--- a/skills/ppt-master/scripts/image_gen.py
+++ b/skills/ppt-master/scripts/image_gen.py
@@ -464,6 +464,34 @@ VALID_IMAGE_TYPES = (
)
+def _validate_bare_output_name(
+ value: str,
+ *,
+ field_name: str,
+ require_extension: bool = False,
+ reject_parent_marker: bool = False,
+) -> Path:
+ """Require one cross-platform-safe basename, optionally with an extension."""
+ value_path = Path(value)
+ if (
+ not value.strip()
+ or value in {".", ".."}
+ or reject_parent_marker and ".." in value
+ or "/" in value
+ or "\\" in value
+ or ":" in value
+ or value_path.is_absolute()
+ or value_path.name != value
+ ):
+ raise ValueError(
+ f"{field_name} must be a bare filename without path components, "
+ f"got {value!r}"
+ )
+ if require_extension and not value_path.suffix:
+ raise ValueError(f"{field_name} must include an extension, got {value!r}")
+ return value_path
+
+
def load_manifest(path: str) -> dict:
"""Load and validate an `image_prompts.json` manifest.
@@ -531,7 +559,7 @@ def load_manifest(path: str) -> dict:
if not isinstance(items, list) or not items:
raise ValueError(f"{path}: 'items' must be a non-empty array")
- seen_filenames: set[str] = set()
+ claimed_outputs: dict[str, str] = {}
seen_stems: set[str] = set()
missing_page_role = 0
missing_text_policy = 0
@@ -614,6 +642,7 @@ def load_manifest(path: str) -> dict:
raise ValueError(f"{prefix} field 'last_error' must be a string")
has_slice_grid = "slice_grid" in item
has_slice_names = "slice_names" in item
+ slice_outputs: list[str] = []
if has_slice_grid != has_slice_names:
raise ValueError(
f"{prefix} fields 'slice_grid' and 'slice_names' must appear together"
@@ -647,20 +676,11 @@ def load_manifest(path: str) -> dict:
)
normalized_outputs: set[str] = set()
for name in names:
- name_path = Path(name)
- if (
- name in {".", ".."}
- or ".." in name
- or "/" in name
- or "\\" in name
- or ":" in name
- or name_path.is_absolute()
- or name_path.name != name
- ):
- raise ValueError(
- f"{prefix} slice output name {name!r} must be a safe "
- "bare filename"
- )
+ name_path = _validate_bare_output_name(
+ name,
+ field_name=f"{prefix} slice output name",
+ reject_parent_marker=True,
+ )
if name_path.suffix and name_path.suffix.lower() != ".png":
raise ValueError(
f"{prefix} slice output name {name!r} must omit its "
@@ -675,33 +695,40 @@ def load_manifest(path: str) -> dict:
f"{output_name!r}"
)
normalized_outputs.add(output_name)
+ slice_outputs.append(output_name)
fname = item["filename"]
- filename_path = Path(fname)
- if (
- filename_path.is_absolute()
- or filename_path.name != fname
- or "/" in fname
- or "\\" in fname
- or fname in {".", ".."}
- ):
- raise ValueError(
- f"{prefix} field 'filename' must be one basename, got '{fname}'"
- )
- if not filename_path.suffix:
+ filename_path = _validate_bare_output_name(
+ fname,
+ field_name=f"{prefix} field 'filename'",
+ require_extension=True,
+ )
+ normalized_filename = fname.casefold()
+ if normalized_filename in claimed_outputs:
raise ValueError(
- f"{prefix} field 'filename' must include an extension, got '{fname}'"
+ f"{prefix} output filename {fname!r} conflicts with "
+ f"{claimed_outputs[normalized_filename]} (case-insensitive)"
)
- if fname in seen_filenames:
- raise ValueError(f"{prefix} duplicate filename '{fname}'")
- seen_filenames.add(fname)
- stem = filename_path.stem
+ claimed_outputs[normalized_filename] = f"manifest output {fname!r}"
+
+ stem = filename_path.stem.casefold()
if stem in seen_stems:
raise ValueError(
- f"{prefix} duplicate filename stem '{stem}' would reuse backend output"
+ f"{prefix} duplicate filename stem '{filename_path.stem}' "
+ "would reuse backend output"
)
seen_stems.add(stem)
+ for output_name in slice_outputs:
+ if output_name in claimed_outputs:
+ raise ValueError(
+ f"{prefix} slice output {output_name!r} conflicts with "
+ f"{claimed_outputs[output_name]} (case-insensitive)"
+ )
+ claimed_outputs[output_name] = (
+ f"slice output {output_name!r} from items[{i}]"
+ )
+
legacy_parts = []
if missing_page_role:
legacy_parts.append(
@@ -791,6 +818,14 @@ def _run_manifest(manifest: dict, manifest_path: str, backend_module, *,
Returns (ok_count, failed_count, skipped_count).
"""
+ manifest_output_dir = Path(manifest_path).resolve().parent
+ if Path(output_dir).resolve() != manifest_output_dir:
+ raise ValueError(
+ "Manifest outputs must stay beside image_prompts.json: "
+ f"expected {manifest_output_dir}, got {Path(output_dir).resolve()}"
+ )
+ output_dir = str(manifest_output_dir)
+
from image_backends.backend_common import (
is_rate_limit_error,
validate_image_file,
@@ -1144,6 +1179,15 @@ def main() -> None:
args = parser.parse_args()
+ if args.filename is not None:
+ try:
+ _validate_bare_output_name(
+ args.filename,
+ field_name="--filename",
+ )
+ except ValueError as exc:
+ parser.error(str(exc))
+
if args.reference_image is not None:
# Reference editing is a single-image-only enhancement; keep it out of
# the manifest / sidecar / list surfaces entirely.
@@ -1185,8 +1229,25 @@ def main() -> None:
print(f"Rendered Markdown sidecar: {md_path}")
return
+ manifest = None
+ manifest_output_dir = None
if args.manifest:
+ if not os.path.isfile(args.manifest):
+ print(f"Error: manifest file not found: {args.manifest}")
+ sys.exit(1)
_guard_confirmed_non_api_path(args.manifest)
+ try:
+ manifest = load_manifest(args.manifest)
+ except ValueError as e:
+ print(f"Error: {e}")
+ sys.exit(1)
+ manifest_output_dir = Path(args.manifest).resolve().parent
+ if args.output and Path(args.output).resolve() != manifest_output_dir:
+ print(
+ "Error: --output cannot redirect manifest items outside the "
+ f"manifest directory ({manifest_output_dir})"
+ )
+ sys.exit(1)
try:
_load_image_env_file()
@@ -1203,22 +1264,13 @@ def main() -> None:
print(f"Using backend: {backend_name}\n")
if args.manifest:
- if not os.path.isfile(args.manifest):
- print(f"Error: manifest file not found: {args.manifest}")
- sys.exit(1)
- try:
- manifest = load_manifest(args.manifest)
- except ValueError as e:
- print(f"Error: {e}")
- sys.exit(1)
-
concurrency = _resolve_concurrency(args.concurrency)
try:
_, failed, _ = _run_manifest(
manifest, args.manifest, backend,
initial_concurrency=concurrency,
image_size=args.image_size,
- output_dir=args.output or str(Path(args.manifest).parent),
+ output_dir=str(manifest_output_dir),
model=args.model,
)
except KeyboardInterrupt:
diff --git a/skills/ppt-master/scripts/image_search.py b/skills/ppt-master/scripts/image_search.py
index 0eb7bc57..0dac009f 100644
--- a/skills/ppt-master/scripts/image_search.py
+++ b/skills/ppt-master/scripts/image_search.py
@@ -46,9 +46,10 @@ import os
import sys
import tempfile
import threading
+from dataclasses import dataclass
from datetime import datetime, timezone
from pathlib import Path
-from typing import Optional
+from typing import Callable, Optional
import requests
@@ -113,6 +114,8 @@ SEARCH_VALID_STATUSES = {
# (see image-searcher.md §8); only Pending/Failed rows are retried on re-run.
SEARCH_RETRYABLE_STATUSES = {SEARCH_STATUS_PENDING, SEARCH_STATUS_FAILED}
SEARCH_REQUIRED_ITEM_FIELDS = ("filename", "query", "status")
+SEARCH_FAILURE_NO_MATCH = "no-match"
+SEARCH_FAILURE_RETRYABLE = "retryable"
_WEAK_REQUIRED_TERM_PARTS = frozenset({
"ancient town",
@@ -232,48 +235,103 @@ def _is_keyed_provider_unconfigured(provider_name: str, exc: Exception) -> bool:
return "API_KEY" in str(exc)
+@dataclass
+class SearchDownloadResult:
+ """Carry one search result without collapsing no-match and retryable failures."""
+
+ candidate: Optional[AssetCandidate] = None
+ provider_name: Optional[str] = None
+ stage: Optional[str] = None
+ actual_dimensions: Optional[tuple[int, int]] = None
+ staged_path: Optional[Path] = None
+ output_path: Optional[Path] = None
+ failure_kind: Optional[str] = None
+ error: Optional[str] = None
+
+
+class DownloadQualityError(ValueError):
+ """Signal a readable candidate that fails the requested image contract."""
+
+
+def _is_pillow_decompression_error(exc: BaseException) -> bool:
+ """Recognize Pillow's safety exception without making Pillow a hard import."""
+ cls = type(exc)
+ return (
+ cls.__name__ == "DecompressionBombError"
+ and cls.__module__.startswith("PIL.")
+ )
+
+
+def _is_recoverable_image_error(exc: BaseException) -> bool:
+ """Return whether a provider/download/image failure can be reported cleanly."""
+ return isinstance(
+ exc,
+ (
+ requests.RequestException,
+ OSError,
+ RuntimeError,
+ SyntaxError,
+ ValueError,
+ ),
+ ) or _is_pillow_decompression_error(exc)
+
+
def _try_provider(
name: str,
request: ImageSearchRequest,
license_tier_filter: str,
-) -> Optional[list[AssetCandidate]]:
- """Run one provider; print and swallow recoverable errors, return None
- so the dispatcher can try the next provider."""
+) -> tuple[Optional[list[AssetCandidate]], Optional[str]]:
+ """Run one provider while preserving whether it errored or returned no rows."""
try:
module = _load_provider(name)
- return module.search(request, license_tier_filter=license_tier_filter)
+ return module.search(request, license_tier_filter=license_tier_filter), None
except RuntimeError as exc:
if _is_keyed_provider_unconfigured(name, exc):
print(
f" [{name}] skipped: {exc}",
file=sys.stderr,
)
+ return None, None
else:
print(f" [{name}] error: {exc}", file=sys.stderr)
- return None
- except (requests.RequestException, ValueError) as exc:
+ return None, f"{name}: {exc}"
+ except (requests.RequestException, OSError, ValueError) as exc:
print(f" [{name}] error: {exc}", file=sys.stderr)
- return None
+ return None, f"{name}: {exc}"
+ except ImportError as exc:
+ print(f" [{name}] error: {exc}", file=sys.stderr)
+ return None, f"{name}: provider import failed: {exc}"
# ---------------------------------------------------------------------------
# Post-download quality validation
# ---------------------------------------------------------------------------
-_MIN_DOWNLOAD_PIXELS = 800 * 600 # reject anything below ~480K px
+_MIN_DOWNLOAD_PIXELS = 800 * 600 # preserve the existing absolute thumbnail floor
-def _validate_downloaded_quality(path: Path) -> bool:
- """Reject images that are too small after download.
+def _validate_downloaded_quality(
+ path: Path,
+ *,
+ min_width: int = 0,
+ min_height: int = 0,
+ enforce_thumbnail_floor: bool = True,
+) -> bool:
+ """Reject unreadable images and actual EXIF-oriented dimensions below contract.
Upstream metadata can be inaccurate (e.g. Openverse aggregates rawpixel
which only exposes a preview). This function checks what was actually
- written to disk and rejects thumbnails / previews.
+ written to disk. Automated paths also reject thumbnails/previews; explicit
+ manual paths may disable that absolute floor while retaining their own
+ requested dimensions.
"""
try:
from PIL import Image, ImageOps # type: ignore
- except ImportError:
- return True # can't check without Pillow; assume OK
+ except ImportError as exc:
+ raise RuntimeError(
+ "Pillow is required to validate downloaded image dimensions. "
+ "Install it with: pip install Pillow"
+ ) from exc
try:
with Image.open(path) as im:
oriented = ImageOps.exif_transpose(im)
@@ -281,7 +339,14 @@ def _validate_downloaded_quality(path: Path) -> bool:
w, h = oriented.size
if oriented is not im:
oriented.close()
- if w * h < _MIN_DOWNLOAD_PIXELS:
+ if w < min_width or h < min_height:
+ print(
+ f" rejected: downloaded image dimensions {w}x{h} are below "
+ f"the requested minimum {min_width}x{min_height}",
+ file=sys.stderr,
+ )
+ return False
+ if enforce_thumbnail_floor and w * h < _MIN_DOWNLOAD_PIXELS:
print(
f" rejected: downloaded image too small "
f"({w}x{h} = {w*h:,} px < {_MIN_DOWNLOAD_PIXELS:,} px minimum)",
@@ -289,7 +354,9 @@ def _validate_downloaded_quality(path: Path) -> bool:
)
return False
return True
- except (OSError, SyntaxError, ValueError) as exc:
+ except Exception as exc:
+ if not _is_recoverable_image_error(exc):
+ raise
print(
f" rejected: downloaded file is not a readable image ({exc})",
file=sys.stderr,
@@ -297,6 +364,118 @@ def _validate_downloaded_quality(path: Path) -> bool:
return False
+def _stage_validated_image(
+ url: str,
+ output_path: Path,
+ *,
+ min_width: int,
+ min_height: int,
+ enforce_thumbnail_floor: bool = True,
+) -> tuple[Path, tuple[int, int]]:
+ """Download and validate beside the target without changing the canonical."""
+ output_path.parent.mkdir(parents=True, exist_ok=True)
+ fd, temp_name = tempfile.mkstemp(
+ prefix=f".{output_path.stem}.",
+ suffix=output_path.suffix,
+ dir=str(output_path.parent),
+ )
+ os.close(fd)
+ temp_path = Path(temp_name)
+ keep_temp = False
+ try:
+ download_image(
+ url,
+ str(temp_path),
+ headers={"User-Agent": USER_AGENT},
+ )
+ if not _validate_downloaded_quality(
+ temp_path,
+ min_width=min_width,
+ min_height=min_height,
+ enforce_thumbnail_floor=enforce_thumbnail_floor,
+ ):
+ raise DownloadQualityError(
+ "downloaded image did not satisfy the requested dimensions/readability"
+ )
+ actual_dimensions = _measure_actual_image(temp_path)
+ if actual_dimensions is None:
+ raise DownloadQualityError(
+ "downloaded image dimensions could not be measured"
+ )
+ keep_temp = True
+ return temp_path, actual_dimensions
+ finally:
+ if not keep_temp:
+ try:
+ temp_path.unlink(missing_ok=True)
+ except OSError:
+ pass
+
+
+def _commit_staged_image(
+ staged_path: Path,
+ target_path: Path,
+ manifest_writer: Callable[[], Path],
+) -> Path:
+ """Install a staged image and roll it back if provenance cannot be written."""
+ target_path.parent.mkdir(parents=True, exist_ok=True)
+ backup_path: Optional[Path] = None
+ installed = False
+
+ try:
+ if target_path.exists():
+ if not target_path.is_file():
+ raise RuntimeError(
+ f"image target exists but is not a regular file: {target_path}"
+ )
+ fd, backup_name = tempfile.mkstemp(
+ prefix=f".{target_path.stem}.backup.",
+ suffix=target_path.suffix,
+ dir=str(target_path.parent),
+ )
+ os.close(fd)
+ reserved_backup_path = Path(backup_name)
+ reserved_backup_path.unlink()
+ os.replace(target_path, reserved_backup_path)
+ backup_path = reserved_backup_path
+
+ os.replace(staged_path, target_path)
+ installed = True
+ written = manifest_writer()
+ except Exception as exc:
+ rollback_errors: list[str] = []
+ if installed:
+ try:
+ target_path.unlink(missing_ok=True)
+ except OSError as rollback_exc:
+ rollback_errors.append(f"cannot remove new target: {rollback_exc}")
+ if backup_path is not None and backup_path.exists():
+ try:
+ os.replace(backup_path, target_path)
+ except OSError as rollback_exc:
+ rollback_errors.append(f"cannot restore prior target: {rollback_exc}")
+ if rollback_errors:
+ raise RuntimeError(
+ f"{exc}; image rollback also failed: {'; '.join(rollback_errors)}"
+ ) from exc
+ raise
+ else:
+ if backup_path is not None:
+ try:
+ backup_path.unlink(missing_ok=True)
+ except OSError as exc:
+ print(
+ f" warning: could not remove image backup {backup_path}: {exc}",
+ file=sys.stderr,
+ )
+ return written
+ finally:
+ try:
+ staged_path.unlink(missing_ok=True)
+ except OSError:
+ pass
+
+
def _write_review_copy(
src: Path, dest_dir: Path, name: str, max_side: int = 1024
) -> Optional[Path]:
@@ -311,6 +490,7 @@ def _write_review_copy(
from PIL import Image, ImageOps # type: ignore
except ImportError:
return None
+ review_path: Optional[Path] = None
try:
dest_dir.mkdir(parents=True, exist_ok=True)
review_path = dest_dir / f"{Path(name).stem}.jpg"
@@ -323,7 +503,14 @@ def _write_review_copy(
if oriented is not im:
oriented.close()
return review_path
- except (OSError, ValueError):
+ except Exception as exc:
+ if not _is_recoverable_image_error(exc):
+ raise
+ if review_path is not None:
+ try:
+ review_path.unlink(missing_ok=True)
+ except OSError:
+ pass
return None
@@ -332,6 +519,8 @@ def _save_candidates_pool(
output_dir: Path,
stem: str,
selected_filename: str,
+ min_width: int,
+ min_height: int,
max_candidates: int = 4,
) -> None:
"""Download top-N candidates into ``candidates/<stem>/`` and write
@@ -347,38 +536,60 @@ def _save_candidates_pool(
suffix = Path(candidate.download_url.split("?")[0]).suffix or ".jpg"
cand_filename = f"candidate_{idx + 1:02d}{suffix}"
cand_path = cand_dir / cand_filename
+ keep_candidate = False
try:
download_image(
candidate.download_url,
str(cand_path),
headers={"User-Agent": USER_AGENT},
)
- if not _validate_downloaded_quality(cand_path):
- cand_path.unlink(missing_ok=True)
+ if not _validate_downloaded_quality(
+ cand_path,
+ min_width=min_width,
+ min_height=min_height,
+ ):
continue
- except (requests.RequestException, OSError, RuntimeError, ValueError):
+ actual_dim = _measure_actual_image(cand_path)
+ review_path = _write_review_copy(
+ cand_path,
+ cand_dir / "review",
+ cand_filename,
+ )
+ idx += 1
+ pool.append({
+ "rank": idx,
+ "score": round(score, 2),
+ "filename": cand_filename,
+ "review": f"review/{review_path.name}" if review_path else None,
+ "provider": provider_name,
+ "title": candidate.title,
+ "author": candidate.author,
+ "source_page_url": candidate.source_page_url,
+ "download_url": candidate.download_url,
+ "license_name": candidate.license_name,
+ "license_url": candidate.license_url,
+ "license_tier": candidate.license_tier,
+ "attribution_required": (
+ candidate.license_tier == "attribution-required"
+ ),
+ "attribution_text": build_attribution_text(
+ selected_filename,
+ candidate,
+ ),
+ "width": actual_dim[0] if actual_dim else candidate.width,
+ "height": actual_dim[1] if actual_dim else candidate.height,
+ })
+ keep_candidate = True
+ except Exception as exc:
+ if not _is_recoverable_image_error(exc):
+ raise
continue
- idx += 1
- actual_dim = _measure_actual_image(cand_path)
- review_path = _write_review_copy(cand_path, cand_dir / "review", cand_filename)
- pool.append({
- "rank": idx,
- "score": round(score, 2),
- "filename": cand_filename,
- "review": f"review/{review_path.name}" if review_path else None,
- "provider": provider_name,
- "title": candidate.title,
- "author": candidate.author,
- "source_page_url": candidate.source_page_url,
- "download_url": candidate.download_url,
- "license_name": candidate.license_name,
- "license_url": candidate.license_url,
- "license_tier": candidate.license_tier,
- "attribution_required": candidate.license_tier == "attribution-required",
- "attribution_text": build_attribution_text(selected_filename, candidate),
- "width": actual_dim[0] if actual_dim else candidate.width,
- "height": actual_dim[1] if actual_dim else candidate.height,
- })
+ finally:
+ if not keep_candidate:
+ try:
+ cand_path.unlink(missing_ok=True)
+ except OSError:
+ pass
if pool:
meta = {
@@ -388,10 +599,7 @@ def _save_candidates_pool(
"candidates": pool,
}
meta_path = cand_dir / "candidates.json"
- meta_path.write_text(
- json.dumps(meta, indent=2, ensure_ascii=False) + "\n",
- encoding="utf-8",
- )
+ _write_json_atomic(meta_path, meta)
print(f" candidates: {cand_dir}/ ({len(pool)} saved)", file=sys.stderr)
@@ -403,7 +611,7 @@ def search_and_download(
strict_no_attribution: bool,
save_candidates: bool = False,
max_candidates: int = 4,
-) -> tuple[Optional[AssetCandidate], Optional[str], Optional[str]]:
+) -> SearchDownloadResult:
"""Find a candidate AND successfully download it.
By default only the best match is downloaded. When ``save_candidates``
@@ -411,19 +619,24 @@ def search_and_download(
``candidates/<stem>/`` so the agent can review and ``--promote`` a
better fit when the best match does not pass visual confirmation.
- Returns ``(candidate, provider_name, stage)`` for the successfully
- downloaded image, or ``(None, None, None)`` if every combination
- failed.
+ Returns a structured result so batch mode can keep transient/provider
+ failures retryable while treating a complete no-match as terminal.
"""
license_filters: list[str] = (
["no-attribution-only"] if strict_no_attribution else ["all"]
)
+ provider_errors: list[str] = []
+ download_errors: list[str] = []
+ quality_rejections = 0
+
for stage in license_filters:
ranked: list[tuple[float, str, AssetCandidate]] = []
for provider_name in providers:
print(f" -> trying {provider_name} ({stage}) ...", file=sys.stderr)
- candidates = _try_provider(provider_name, request, stage)
+ candidates, provider_error = _try_provider(provider_name, request, stage)
+ if provider_error:
+ provider_errors.append(provider_error)
if not candidates:
continue
@@ -449,10 +662,23 @@ def search_and_download(
# --- Save candidate pool (before picking the winner) ---
if save_candidates and sorted_ranked:
stem = Path(output_path).stem
- _save_candidates_pool(
- sorted_ranked, output_path.parent, stem, output_path.name,
- max_candidates=max_candidates,
- )
+ try:
+ _save_candidates_pool(
+ sorted_ranked,
+ output_path.parent,
+ stem,
+ output_path.name,
+ request.min_width,
+ request.min_height,
+ max_candidates=max_candidates,
+ )
+ except Exception as exc:
+ if not _is_recoverable_image_error(exc):
+ raise
+ print(
+ f" warning: candidate pool could not be saved: {exc}",
+ file=sys.stderr,
+ )
# --- Pick the best downloadable candidate ---
for _score, provider_name, candidate in sorted_ranked:
@@ -460,28 +686,47 @@ def search_and_download(
# exist in the candidates dir — but we still need the
# primary copy at output_path.
try:
- download_image(
+ staged_path, actual_dimensions = _stage_validated_image(
candidate.download_url,
- str(output_path),
- headers={"User-Agent": USER_AGENT},
+ output_path,
+ min_width=request.min_width,
+ min_height=request.min_height,
)
- if not _validate_downloaded_quality(output_path):
- output_path.unlink(missing_ok=True)
- continue
- review = _write_review_copy(
- output_path, output_path.parent / ".review", output_path.name
+ return SearchDownloadResult(
+ candidate=candidate,
+ provider_name=provider_name,
+ stage=stage,
+ actual_dimensions=actual_dimensions,
+ staged_path=staged_path,
+ output_path=output_path,
)
- if review is not None:
- print(f" review copy: {review}", file=sys.stderr)
- return candidate, provider_name, stage
- except (requests.RequestException, OSError, RuntimeError, ValueError) as exc:
+ except DownloadQualityError:
+ quality_rejections += 1
+ continue
+ except Exception as exc:
+ if not _is_recoverable_image_error(exc):
+ raise
print(
f" download failed for {candidate.title!r}: {exc}",
file=sys.stderr,
)
+ download_errors.append(f"{provider_name}/{candidate.title}: {exc}")
continue
- return None, None, None
+ retryable_errors = provider_errors + download_errors
+ if retryable_errors:
+ return SearchDownloadResult(
+ failure_kind=SEARCH_FAILURE_RETRYABLE,
+ error="; ".join(retryable_errors)[:500],
+ )
+
+ detail = "no acceptable candidate across all providers/stages"
+ if quality_rejections:
+ detail += f" ({quality_rejections} candidate(s) failed actual-size/readability gates)"
+ return SearchDownloadResult(
+ failure_kind=SEARCH_FAILURE_NO_MATCH,
+ error=detail,
+ )
# ---------------------------------------------------------------------------
@@ -533,7 +778,9 @@ def _measure_actual_image(path: Path) -> Optional[tuple[int, int]]:
finally:
if oriented is not im:
oriented.close()
- except (OSError, ValueError):
+ except Exception as exc:
+ if not _is_recoverable_image_error(exc):
+ raise
return None
@@ -624,7 +871,7 @@ def _read_existing_manifest(path: Path) -> dict:
raise RuntimeError(
f"existing image sources manifest contains a non-object item: {path}"
)
- seen_filenames: set[str] = set()
+ seen_filenames: dict[str, str] = {}
for index, item in enumerate(items):
filename = item.get("filename")
if not isinstance(filename, str):
@@ -638,12 +885,14 @@ def _read_existing_manifest(path: Path) -> dict:
raise RuntimeError(
f"existing image sources manifest items[{index}]: {exc}: {path}"
) from exc
- if filename in seen_filenames:
+ normalized_filename = filename.casefold()
+ if normalized_filename in seen_filenames:
raise RuntimeError(
- f"existing image sources manifest contains duplicate filename "
- f"{filename!r}: {path}"
+ f"existing image sources manifest filename {filename!r} conflicts "
+ f"with {seen_filenames[normalized_filename]!r} "
+ f"(case-insensitive): {path}"
)
- seen_filenames.add(filename)
+ seen_filenames[normalized_filename] = filename
return payload
@@ -672,9 +921,37 @@ def write_sources_manifest(path: Path, item: dict) -> Path:
entry that targets the same filename."""
manifest_path = Path(path)
payload = _read_existing_manifest(manifest_path)
+ filename = item.get("filename")
+ if not isinstance(filename, str):
+ raise RuntimeError("new image source item requires a string filename")
+ try:
+ _validate_bare_filename(filename)
+ except ValueError as exc:
+ raise RuntimeError(f"new image source item: {exc}") from exc
items: list[dict] = list(payload.get("items") or [])
- items = [i for i in items if i.get("filename") != item["filename"]]
+ normalized_filename = filename.casefold()
+ differently_cased = next(
+ (
+ existing["filename"]
+ for existing in items
+ if isinstance(existing.get("filename"), str)
+ and existing["filename"].casefold() == normalized_filename
+ and existing["filename"] != filename
+ ),
+ None,
+ )
+ if differently_cased is not None:
+ raise RuntimeError(
+ f"new image source filename {filename!r} conflicts with existing "
+ f"{differently_cased!r} (case-insensitive)"
+ )
+ items = [
+ i
+ for i in items
+ if not isinstance(i.get("filename"), str)
+ or i["filename"].casefold() != normalized_filename
+ ]
items.append(item)
payload["items"] = items
@@ -701,9 +978,9 @@ def promote_candidate(
"""Replace the primary image with a candidate from the pool.
Steps:
- 1. Copy ``candidates/<stem>/<candidate_filename>`` → ``<target_filename>``
- 2. Update ``candidates.json`` selected field
- 3. Update ``image_sources.json`` with the candidate's metadata
+ 1. Stage and validate ``candidates/<stem>/<candidate_filename>``
+ 2. Replace the canonical image and its provenance as one rollback unit
+ 3. Advance ``candidates.json`` only after provenance succeeds
"""
import shutil
@@ -724,16 +1001,38 @@ def promote_candidate(
cand_dir = output_dir / "candidates" / stem
cand_meta_path = cand_dir / "candidates.json"
- if not cand_meta_path.exists():
+ if not cand_meta_path.is_file():
print(f"Error: {cand_meta_path} not found.", file=sys.stderr)
return 1
- meta = json.loads(cand_meta_path.read_text(encoding="utf-8"))
+ try:
+ meta = json.loads(cand_meta_path.read_text(encoding="utf-8"))
+ except (OSError, json.JSONDecodeError) as exc:
+ print(f"Error: cannot read {cand_meta_path}: {exc}", file=sys.stderr)
+ return 1
+ if not isinstance(meta, dict) or not isinstance(meta.get("candidates"), list):
+ print(
+ f"Error: {cand_meta_path} must contain a candidates array.",
+ file=sys.stderr,
+ )
+ return 1
candidates = meta.get("candidates", [])
- entry = next((c for c in candidates if c["filename"] == candidate_filename), None)
+ entry = next(
+ (
+ candidate
+ for candidate in candidates
+ if isinstance(candidate, dict)
+ and candidate.get("filename") == candidate_filename
+ ),
+ None,
+ )
if entry is None:
- names = [c["filename"] for c in candidates]
+ names = [
+ str(candidate.get("filename"))
+ for candidate in candidates
+ if isinstance(candidate, dict) and candidate.get("filename")
+ ]
print(
f"Error: '{candidate_filename}' not found. Available: {', '.join(names)}",
file=sys.stderr,
@@ -742,63 +1041,135 @@ def promote_candidate(
src_path = cand_dir / candidate_filename
dst_path = output_dir / target_filename
- if not src_path.exists():
+ if not src_path.is_file():
print(f"Error: {src_path} does not exist on disk.", file=sys.stderr)
return 1
- shutil.copy2(str(src_path), str(dst_path))
- print(f" promoted: {candidate_filename} → {target_filename}", file=sys.stderr)
- review = _write_review_copy(dst_path, output_dir / ".review", target_filename)
- if review is not None:
- print(f" review copy: {review}", file=sys.stderr)
-
- # Update candidates.json
- meta["selected"] = candidate_filename
- _write_json_atomic(cand_meta_path, meta)
-
- # Update image_sources.json
- actual_dim = _measure_actual_image(dst_path)
- w = actual_dim[0] if actual_dim else entry.get("width", 0)
- h = actual_dim[1] if actual_dim else entry.get("height", 0)
-
items: list[dict] = list(manifest.get("items") or [])
+ target_item: Optional[dict] = None
for item in items:
- if item.get("filename") == target_filename:
- item["provider"] = entry["provider"]
- item["title"] = entry["title"]
- item["author"] = entry["author"]
- item["source_page_url"] = entry["source_page_url"]
- item["download_url"] = entry["download_url"]
- item["license_name"] = entry["license_name"]
- item["license_url"] = entry.get("license_url", "")
- item["license_tier"] = entry["license_tier"]
- item["attribution_required"] = entry.get("attribution_required", False)
- # Recompute the credit from the promoted candidate — never carry the
- # replaced image's attribution_text (wrong author/title/source).
- item["attribution_text"] = build_attribution_text(
- target_filename,
- AssetCandidate(
- provider=entry.get("provider", ""),
- title=entry.get("title", ""),
- source_page_url=entry.get("source_page_url", ""),
- license_name=entry.get("license_name", ""),
- license_url=entry.get("license_url", ""),
- license_tier=entry.get("license_tier", ""),
- width=w,
- height=h,
- download_url=entry.get("download_url", ""),
- author=entry.get("author", ""),
- ),
- )
- item["width"] = w
- item["height"] = h
- item.pop("metadata_dimensions", None)
- item["status"] = "promoted"
+ filename = item.get("filename")
+ if (
+ isinstance(filename, str)
+ and filename.casefold() == target_filename.casefold()
+ ):
+ target_item = item
break
- manifest["items"] = items
- manifest["generated_at"] = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
- _write_json_atomic(mpath, manifest)
+ if target_item is None:
+ print(
+ f"Error: {mpath} has no provenance entry for {target_filename!r}.",
+ file=sys.stderr,
+ )
+ return 1
+ if target_item["filename"] != target_filename:
+ print(
+ f"Error: target filename casing {target_filename!r} conflicts with "
+ f"provenance filename {target_item['filename']!r}.",
+ file=sys.stderr,
+ )
+ return 1
+
+ output_dir.mkdir(parents=True, exist_ok=True)
+ fd, staged_name = tempfile.mkstemp(
+ prefix=f".{dst_path.stem}.promote.",
+ suffix=dst_path.suffix,
+ dir=str(dst_path.parent),
+ )
+ os.close(fd)
+ staged_path = Path(staged_name)
+ try:
+ shutil.copy2(src_path, staged_path)
+ if not _validate_downloaded_quality(
+ staged_path,
+ enforce_thumbnail_floor=False,
+ ):
+ raise DownloadQualityError(
+ "candidate image did not satisfy the readability/size gate"
+ )
+ actual_dim = _measure_actual_image(staged_path)
+ if actual_dim is None:
+ raise DownloadQualityError("candidate dimensions could not be measured")
+ w, h = actual_dim
+ if w < 1 or h < 1:
+ raise DownloadQualityError("candidate dimensions must be positive")
+ if w * h < _MIN_DOWNLOAD_PIXELS:
+ print(
+ f" warning: explicitly promoted image is low resolution ({w}x{h})",
+ file=sys.stderr,
+ )
+
+ target_item["provider"] = entry.get("provider", "")
+ target_item["title"] = entry.get("title", "")
+ target_item["author"] = entry.get("author", "")
+ target_item["source_page_url"] = entry.get("source_page_url", "")
+ target_item["download_url"] = entry.get("download_url", "")
+ target_item["license_name"] = entry.get("license_name", "")
+ target_item["license_url"] = entry.get("license_url", "")
+ target_item["license_tier"] = entry.get("license_tier", "")
+ target_item["attribution_required"] = entry.get(
+ "attribution_required",
+ False,
+ )
+ # Recompute the credit from the promoted candidate — never carry the
+ # replaced image's attribution_text (wrong author/title/source).
+ target_item["attribution_text"] = build_attribution_text(
+ target_filename,
+ AssetCandidate(
+ provider=entry.get("provider", ""),
+ title=entry.get("title", ""),
+ source_page_url=entry.get("source_page_url", ""),
+ license_name=entry.get("license_name", ""),
+ license_url=entry.get("license_url", ""),
+ license_tier=entry.get("license_tier", ""),
+ width=w,
+ height=h,
+ download_url=entry.get("download_url", ""),
+ author=entry.get("author", ""),
+ ),
+ )
+ target_item["width"] = w
+ target_item["height"] = h
+ target_item.pop("metadata_dimensions", None)
+ target_item["status"] = "promoted"
+ manifest["items"] = items
+ manifest["generated_at"] = (
+ datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+ )
+
+ _commit_staged_image(
+ staged_path,
+ dst_path,
+ lambda: _write_json_atomic(mpath, manifest),
+ )
+ except Exception as exc:
+ if not _is_recoverable_image_error(exc):
+ raise
+ print(f"Error: candidate promotion failed: {exc}", file=sys.stderr)
+ return 1
+ finally:
+ try:
+ staged_path.unlink(missing_ok=True)
+ except OSError:
+ pass
+
+ print(f" promoted: {candidate_filename} → {target_filename}", file=sys.stderr)
print(f" manifest updated: {mpath}", file=sys.stderr)
+
+ # The selection marker must never move ahead of canonical provenance.
+ meta["selected"] = candidate_filename
+ try:
+ _write_json_atomic(cand_meta_path, meta)
+ except OSError as exc:
+ print(
+ f"Error: image was promoted, but {cand_meta_path} could not be updated: "
+ f"{exc}",
+ file=sys.stderr,
+ )
+ return 1
+
+ review = _write_review_copy(dst_path, output_dir / ".review", target_filename)
+ if review is not None:
+ print(f" review copy: {review}", file=sys.stderr)
return 0
@@ -818,6 +1189,8 @@ def fetch_url_replace(
search_query: str = "",
orientation: str = "",
required_terms: tuple[str, ...] = (),
+ min_width: int = 1200,
+ min_height: int = 800,
) -> int:
"""Download a user-supplied image URL into the target and record it.
@@ -840,28 +1213,50 @@ def fetch_url_replace(
(
item
for item in existing_manifest.get("items", [])
- if item.get("filename") == target_filename
+ if isinstance(item.get("filename"), str)
+ and item["filename"].casefold() == target_filename.casefold()
),
{},
)
+ if prior and prior["filename"] != target_filename:
+ print(
+ f"Error: target filename casing {target_filename!r} conflicts with "
+ f"provenance filename {prior['filename']!r}.",
+ file=sys.stderr,
+ )
+ return 1
+ try:
+ inherited_required_terms = _parse_required_terms(
+ prior.get("required_terms")
+ )
+ except ValueError as exc:
+ print(
+ f"Error: existing provenance has invalid required_terms: {exc}",
+ file=sys.stderr,
+ )
+ return 1
+ final_required_terms = inherited_required_terms or required_terms
output_dir.mkdir(parents=True, exist_ok=True)
dst_path = output_dir / target_filename
try:
- download_image(url, str(dst_path), headers={"User-Agent": USER_AGENT})
- except (requests.RequestException, OSError, RuntimeError, ValueError) as exc:
+ staged_path, actual_dim = _stage_validated_image(
+ url,
+ dst_path,
+ min_width=min_width,
+ min_height=min_height,
+ enforce_thumbnail_floor=False,
+ )
+ except (
+ DownloadQualityError,
+ requests.RequestException,
+ OSError,
+ RuntimeError,
+ ValueError,
+ ) as exc:
print(f"Error: failed to download {url}: {exc}", file=sys.stderr)
return 1
- if not dst_path.exists():
- print(f"Error: download produced no file at {dst_path}", file=sys.stderr)
- return 1
-
- print(f" fetched: {url} -> {target_filename}", file=sys.stderr)
- review = _write_review_copy(dst_path, output_dir / ".review", target_filename)
- if review is not None:
- print(f" review copy: {review}", file=sys.stderr)
- actual_dim = _measure_actual_image(dst_path)
# Inherit page context (which slide / purpose / query this image serves)
# from the entry being replaced; override only source / license / size /
# status so the audit trail survives a manual swap.
@@ -880,18 +1275,45 @@ def fetch_url_replace(
"license_url": "",
"license_tier": "manual",
"attribution_required": False,
- "width": actual_dim[0] if actual_dim else 0,
- "height": actual_dim[1] if actual_dim else 0,
+ "width": actual_dim[0],
+ "height": actual_dim[1],
"attribution_text": "",
"status": "manual",
- "note": "Manually supplied image URL; verifying usage rights is the user's responsibility.",
+ "note": (
+ "Manually supplied image URL; verifying usage rights is the user's "
+ "responsibility."
+ ),
}
- inherited_required_terms = _parse_required_terms(prior.get("required_terms"))
- final_required_terms = inherited_required_terms or required_terms
if final_required_terms:
item["required_terms"] = list(final_required_terms)
- written = write_sources_manifest(mpath, item)
+
+ try:
+ written = _commit_staged_image(
+ staged_path,
+ dst_path,
+ lambda: write_sources_manifest(mpath, item),
+ )
+ except (
+ OSError,
+ RuntimeError,
+ ValueError,
+ ) as exc:
+ print(
+ f"Error: failed to replace {target_filename} and record provenance: {exc}",
+ file=sys.stderr,
+ )
+ return 1
+ finally:
+ try:
+ staged_path.unlink(missing_ok=True)
+ except OSError:
+ pass
+
+ print(f" fetched: {url} -> {target_filename}", file=sys.stderr)
print(f" manifest updated: {written}", file=sys.stderr)
+ review = _write_review_copy(dst_path, output_dir / ".review", target_filename)
+ if review is not None:
+ print(f" review copy: {review}", file=sys.stderr)
return 0
@@ -910,6 +1332,8 @@ def load_search_manifest(path: str) -> dict:
"""
try:
data = json.loads(Path(path).read_text(encoding="utf-8"))
+ except OSError as exc:
+ raise ValueError(f"Cannot read {path}: {exc}") from exc
except json.JSONDecodeError as exc:
raise ValueError(
f"Invalid JSON in {path}: {exc.msg} "
@@ -925,7 +1349,7 @@ def load_search_manifest(path: str) -> dict:
if not isinstance(items, list) or not items:
raise ValueError(f"{path}: 'items' must be a non-empty array")
- seen_filenames: set[str] = set()
+ seen_filenames: dict[str, str] = {}
for i, item in enumerate(items):
prefix = f"{path}: items[{i}]"
if not isinstance(item, dict):
@@ -947,21 +1371,42 @@ def load_search_manifest(path: str) -> dict:
_parse_required_terms(item["required_terms"])
except ValueError as exc:
raise ValueError(f"{prefix} {exc}") from exc
+ for dimension_field in ("min_width", "min_height"):
+ if dimension_field not in item:
+ continue
+ value = item[dimension_field]
+ if (
+ not isinstance(value, int)
+ or isinstance(value, bool)
+ or value < 1
+ ):
+ raise ValueError(
+ f"{prefix} field '{dimension_field}' must be a positive integer"
+ )
fname = item["filename"]
try:
_validate_bare_filename(fname)
except ValueError as exc:
raise ValueError(f"{prefix} {exc}") from exc
- if fname in seen_filenames:
- raise ValueError(f"{prefix} duplicate filename '{fname}'")
- seen_filenames.add(fname)
+ normalized_filename = fname.casefold()
+ if normalized_filename in seen_filenames:
+ raise ValueError(
+ f"{prefix} filename {fname!r} conflicts with "
+ f"{seen_filenames[normalized_filename]!r} (case-insensitive)"
+ )
+ seen_filenames[normalized_filename] = fname
return data
def save_search_manifest(path: str, data: dict) -> None:
"""Atomically write the batch manifest back (tmp file + rename)."""
- _write_json_atomic(path, data)
+ try:
+ _write_json_atomic(path, data)
+ except OSError as exc:
+ raise RuntimeError(
+ f"cannot update image query manifest {path}: {exc}"
+ ) from exc
def _resolve_search_concurrency(cli_value: Optional[int]) -> int:
@@ -984,11 +1429,18 @@ def _search_one_item(
default_strict: bool,
default_min_width: int,
default_min_height: int,
-) -> tuple[Optional[dict], Optional[str]]:
+) -> tuple[
+ Optional[dict],
+ Optional[str],
+ bool,
+ Optional[Path],
+ Optional[Path],
+]:
"""Run the full search + download for one batch item (thread worker).
- Returns ``(manifest_item, error)``. Only the network/disk work happens
- here; all manifest writes are serialized by the caller.
+ Returns ``(manifest_item, error, retryable, staged_path, output_path)``.
+ Only network and staged-file work happens here; canonical replacement and
+ all manifest writes are serialized by the caller.
"""
filename = _validate_bare_filename(item["filename"])
orientation = item.get("orientation", "any") or "any"
@@ -1010,7 +1462,7 @@ def _search_one_item(
providers = [pinned] if pinned else _default_provider_chain()
output_path = output_dir / filename
- candidate, provider_name, stage = search_and_download(
+ result = search_and_download(
providers,
request,
output_path=output_path,
@@ -1018,26 +1470,53 @@ def _search_one_item(
save_candidates=save_candidates,
max_candidates=max_candidates,
)
- if candidate is None:
- return None, "no acceptable candidate across all providers/stages"
+ if result.candidate is None:
+ return (
+ None,
+ result.error or "search failed",
+ result.failure_kind == SEARCH_FAILURE_RETRYABLE,
+ None,
+ None,
+ )
+ if result.staged_path is None or result.output_path is None:
+ return (
+ None,
+ "search succeeded without a staged output",
+ True,
+ None,
+ None,
+ )
- actual_dimensions = _measure_actual_image(output_path)
- item_args = argparse.Namespace(
- filename=filename,
- slide=item.get("slide", ""),
- purpose=item.get("purpose", ""),
- query=item["query"],
- orientation=orientation,
- required_terms=request.required_terms,
- )
- manifest_item = _candidate_to_manifest_item(
- candidate,
- item_args,
- provider_name=provider_name,
- stage=stage,
- actual_dimensions=actual_dimensions,
- )
- return manifest_item, None
+ try:
+ item_args = argparse.Namespace(
+ filename=filename,
+ slide=item.get("slide", ""),
+ purpose=item.get("purpose", ""),
+ query=item["query"],
+ orientation=orientation,
+ required_terms=request.required_terms,
+ )
+ manifest_item = _candidate_to_manifest_item(
+ result.candidate,
+ item_args,
+ provider_name=result.provider_name or "",
+ stage=result.stage or "",
+ actual_dimensions=result.actual_dimensions,
+ )
+ return (
+ manifest_item,
+ None,
+ False,
+ result.staged_path,
+ result.output_path,
+ )
+ except Exception:
+ if result.staged_path is not None:
+ try:
+ result.staged_path.unlink(missing_ok=True)
+ except OSError:
+ pass
+ raise
def run_search_manifest(
@@ -1053,17 +1532,66 @@ def run_search_manifest(
default_strict: bool,
default_min_width: int,
default_min_height: int,
-) -> tuple[int, int, int]:
+) -> tuple[int, int, int, int]:
"""Process all Pending/Failed rows concurrently with a bounded pool.
On success the rich provenance entry is appended to ``image_sources.json``
(the credit source of truth) and the row's status flips to ``Sourced``.
A row that exhausts the provider/stage chain becomes ``Needs-Manual``
(terminal). Status is written back after each completion, so an interrupt
- preserves finished rows. Returns ``(sourced, needs_manual, skipped)``.
+ preserves finished rows. Returns ``(sourced, needs_manual, failed, skipped)``.
"""
- _read_existing_manifest(sources_manifest_path)
+ sources_manifest = _read_existing_manifest(sources_manifest_path)
items = manifest["items"]
+
+ provenance_filenames = {
+ item["filename"].casefold(): item["filename"]
+ for item in sources_manifest.get("items", [])
+ if isinstance(item.get("filename"), str)
+ }
+ repaired_sourced = False
+ for item in items:
+ if item["status"] != SEARCH_STATUS_SOURCED:
+ continue
+ filename = item["filename"]
+ target_path = output_dir / filename
+ reasons: list[str] = []
+ provenance_filename = provenance_filenames.get(filename.casefold())
+ if provenance_filename is None:
+ reasons.append("image_sources.json has no matching provenance entry")
+ elif provenance_filename != filename:
+ reasons.append(
+ "image_sources.json filename casing does not match "
+ f"({provenance_filename!r} vs {filename!r})"
+ )
+ if not target_path.is_file():
+ reasons.append("target file is missing")
+ else:
+ min_width = int(item.get("min_width", default_min_width))
+ min_height = int(item.get("min_height", default_min_height))
+ try:
+ target_is_valid = _validate_downloaded_quality(
+ target_path,
+ min_width=min_width,
+ min_height=min_height,
+ )
+ except RuntimeError as exc:
+ reasons.append(f"target validation unavailable: {exc}")
+ else:
+ if not target_is_valid:
+ reasons.append(
+ "target file is unreadable or below requested dimensions"
+ )
+ if reasons:
+ item["status"] = SEARCH_STATUS_FAILED
+ item["last_error"] = (
+ "Sourced state validation failed: " + "; ".join(reasons)
+ )[:500]
+ repaired_sourced = True
+ print(f" [RETRY] {filename} — {item['last_error']}")
+ if repaired_sourced:
+ save_search_manifest(manifest_path, manifest)
+
pending_idx = [
i for i, it in enumerate(items)
if it["status"] in SEARCH_RETRYABLE_STATUSES
@@ -1076,7 +1604,7 @@ def run_search_manifest(
f"[Batch] Nothing to do — all {len(items)} row(s) already in a "
"terminal state (Sourced / Needs-Manual)."
)
- return 0, 0, skipped
+ return 0, 0, 0, skipped
print(
f"\n[Batch] {total} row(s) to search, {skipped} already done. "
@@ -1085,50 +1613,137 @@ def run_search_manifest(
sourced_count = 0
needs_manual_count = 0
+ failed_count = 0
write_lock = threading.Lock()
def _one(idx: int):
try:
- manifest_item, error = _search_one_item(
- items[idx],
- output_dir=output_dir,
- save_candidates=save_candidates,
- max_candidates=max_candidates,
- default_provider=default_provider,
- default_strict=default_strict,
- default_min_width=default_min_width,
- default_min_height=default_min_height,
+ manifest_item, error, retryable, staged_path, target_path = (
+ _search_one_item(
+ items[idx],
+ output_dir=output_dir,
+ save_candidates=save_candidates,
+ max_candidates=max_candidates,
+ default_provider=default_provider,
+ default_strict=default_strict,
+ default_min_width=default_min_width,
+ default_min_height=default_min_height,
+ )
+ )
+ return (
+ idx,
+ manifest_item,
+ error,
+ retryable,
+ staged_path,
+ target_path,
)
- return idx, manifest_item, error
except Exception as exc: # noqa: BLE001 — provider code raises freely
- return idx, None, str(exc)[:500]
-
- with concurrent.futures.ThreadPoolExecutor(max_workers=concurrency) as ex:
- futures = [ex.submit(_one, i) for i in pending_idx]
- for fut in concurrent.futures.as_completed(futures):
- idx, manifest_item, error = fut.result()
- item = items[idx]
- with write_lock:
- if manifest_item is not None:
- write_sources_manifest(sources_manifest_path, manifest_item)
- item["status"] = SEARCH_STATUS_SOURCED
- item["provider"] = manifest_item.get("provider", "")
- item["license_tier"] = manifest_item.get("license_tier", "")
- item.pop("last_error", None)
- sourced_count += 1
- print(f" [OK] {item['filename']} ({item['provider']})")
- else:
- item["status"] = SEARCH_STATUS_NEEDS_MANUAL
- item["last_error"] = error or "search failed"
- needs_manual_count += 1
- print(f" [MANUAL] {item['filename']} — {item['last_error']}")
- save_search_manifest(manifest_path, manifest)
+ return idx, None, str(exc)[:500], True, None, None
+
+ futures: list[concurrent.futures.Future] = []
+ try:
+ with concurrent.futures.ThreadPoolExecutor(max_workers=concurrency) as ex:
+ futures = [ex.submit(_one, i) for i in pending_idx]
+ for fut in concurrent.futures.as_completed(futures):
+ (
+ idx,
+ manifest_item,
+ error,
+ retryable,
+ staged_path,
+ target_path,
+ ) = fut.result()
+ item = items[idx]
+ with write_lock:
+ if (
+ manifest_item is not None
+ and staged_path is not None
+ and target_path is not None
+ ):
+ try:
+ _commit_staged_image(
+ staged_path,
+ target_path,
+ lambda: write_sources_manifest(
+ sources_manifest_path,
+ manifest_item,
+ ),
+ )
+ except Exception as exc:
+ if not _is_recoverable_image_error(exc):
+ raise
+ item["status"] = SEARCH_STATUS_FAILED
+ item["last_error"] = (
+ f"canonical/provenance commit failed: {exc}"
+ )[:500]
+ failed_count += 1
+ print(
+ f" [FAIL] {item['filename']} — "
+ f"{item['last_error']}"
+ )
+ else:
+ item["status"] = SEARCH_STATUS_SOURCED
+ item["provider"] = manifest_item.get("provider", "")
+ item["license_tier"] = manifest_item.get(
+ "license_tier",
+ "",
+ )
+ item.pop("last_error", None)
+ sourced_count += 1
+ review = _write_review_copy(
+ target_path,
+ output_dir / ".review",
+ target_path.name,
+ )
+ if review is not None:
+ print(
+ f" review copy: {review}",
+ file=sys.stderr,
+ )
+ print(
+ f" [OK] {item['filename']} "
+ f"({item['provider']})"
+ )
+ elif retryable:
+ item["status"] = SEARCH_STATUS_FAILED
+ item["last_error"] = error or "provider/download failure"
+ failed_count += 1
+ print(
+ f" [FAIL] {item['filename']} — {item['last_error']}"
+ )
+ else:
+ item["status"] = SEARCH_STATUS_NEEDS_MANUAL
+ item["last_error"] = error or "search failed"
+ needs_manual_count += 1
+ print(
+ f" [MANUAL] {item['filename']} — "
+ f"{item['last_error']}"
+ )
+ save_search_manifest(manifest_path, manifest)
+ finally:
+ # Workers only stage files. Any result not committed because of an
+ # interrupt or a later manifest error must not leave candidate residue.
+ for future in futures:
+ if not future.done():
+ continue
+ try:
+ outcome = future.result()
+ except BaseException:
+ continue
+ staged_path = outcome[4]
+ if staged_path is not None:
+ try:
+ staged_path.unlink(missing_ok=True)
+ except OSError:
+ pass
print(
- f"\n[Batch] Done: {sourced_count} sourced / {needs_manual_count} "
- f"needs-manual ({skipped} pre-skipped). Manifest: {manifest_path}"
+ f"\n[Batch] Done: {sourced_count} sourced / {failed_count} failed / "
+ f"{needs_manual_count} needs-manual ({skipped} pre-skipped). "
+ f"Manifest: {manifest_path}"
)
- return sourced_count, needs_manual_count, skipped
+ return sourced_count, needs_manual_count, failed_count, skipped
# ---------------------------------------------------------------------------
@@ -1313,6 +1928,8 @@ def main(argv: Optional[list[str]] = None) -> int:
)
except ValueError as exc:
parser.error(str(exc))
+ if args.min_width < 1 or args.min_height < 1:
+ parser.error("--min-width and --min-height must both be positive integers")
output_dir = Path(args.output)
@@ -1341,6 +1958,8 @@ def main(argv: Optional[list[str]] = None) -> int:
search_query=args.query or "",
orientation="" if args.orientation == "any" else args.orientation,
required_terms=_parse_required_terms(args.require_terms),
+ min_width=args.min_width,
+ min_height=args.min_height,
)
# --- Batch mode ---
@@ -1362,7 +1981,7 @@ def main(argv: Optional[list[str]] = None) -> int:
else default_manifest_path(str(batch_output_dir))
)
try:
- _, needs_manual, _ = run_search_manifest(
+ _, needs_manual, failed, _ = run_search_manifest(
manifest,
args.batch,
output_dir=batch_output_dir,
@@ -1381,10 +2000,9 @@ def main(argv: Optional[list[str]] = None) -> int:
except RuntimeError as exc:
print(f"Error: {exc}", file=sys.stderr)
return 1
- # Mirror image_gen.py: a non-zero code flags rows that need manual
- # attention. It is a signal, not a halt — the workflow (image-base.md
- # §6) surfaces Needs-Manual rows and continues regardless.
- return 1 if needs_manual else 0
+ # Mirror image_gen.py: any unresolved retryable or manual row keeps the
+ # command non-zero. It is a gate signal, not a request to hide progress.
+ return 1 if needs_manual or failed else 0
# --- Single-query search mode ---
if not args.query:
@@ -1419,7 +2037,7 @@ def main(argv: Optional[list[str]] = None) -> int:
output_path = output_dir / args.filename
print(f"Searching providers: {', '.join(providers)}", file=sys.stderr)
- candidate, provider_name, stage = search_and_download(
+ result = search_and_download(
providers,
request,
output_path=output_path,
@@ -1428,57 +2046,81 @@ def main(argv: Optional[list[str]] = None) -> int:
max_candidates=args.max_candidates,
)
- if candidate is None:
+ if result.candidate is None:
print(
- "No acceptable candidates could be downloaded across all "
- "providers/filters. Try a shorter query, use default attribution "
- "mode if strict mode is enabled, or set an API key for a keyed provider.",
+ f"{result.error or 'Image search failed'}. "
+ "Try a shorter query, use default attribution mode if strict mode "
+ "is enabled, or set an API key for a keyed provider.",
file=sys.stderr,
)
return 1
print(
- f" picked: {candidate.title!r} from {provider_name} "
- f"({candidate.license_name or 'no license string'}, "
- f"{candidate.license_tier})",
+ f" picked: {result.candidate.title!r} from {result.provider_name} "
+ f"({result.candidate.license_name or 'no license string'}, "
+ f"{result.candidate.license_tier})",
file=sys.stderr,
)
- # Measure what was actually written to disk; upstream metadata can be
+ # The staged file has already been measured; upstream metadata can still be
# off (e.g. Openverse aggregates rawpixel which only exposes previews).
- actual_dimensions = _measure_actual_image(output_path)
+ actual_dimensions = result.actual_dimensions
if (
actual_dimensions is not None
- and candidate.width
- and candidate.height
+ and result.candidate.width
+ and result.candidate.height
and actual_dimensions[0] * actual_dimensions[1]
- < 0.5 * candidate.width * candidate.height
+ < 0.5 * result.candidate.width * result.candidate.height
):
print(
f"\n[!] Downloaded image is much smaller than upstream metadata "
f"({actual_dimensions[0]}x{actual_dimensions[1]} vs "
- f"{candidate.width}x{candidate.height}). The provider likely "
- f"only exposes a preview here. Layout based on the manifest's "
+ f"{result.candidate.width}x{result.candidate.height}). The provider "
+ f"likely only exposes a preview here. Layout based on the manifest's "
f"width/height will be accurate; the metadata_dimensions field "
f"is preserved for reference.",
file=sys.stderr,
)
- item = _candidate_to_manifest_item(
- candidate,
- args,
- provider_name=provider_name,
- stage=stage,
- actual_dimensions=actual_dimensions,
- )
+ if result.staged_path is None or result.output_path is None:
+ print("Error: image search returned no staged output.", file=sys.stderr)
+ if result.staged_path is not None:
+ try:
+ result.staged_path.unlink(missing_ok=True)
+ except OSError:
+ pass
+ return 1
try:
- write_sources_manifest(manifest_path, item)
- except RuntimeError as exc:
+ item = _candidate_to_manifest_item(
+ result.candidate,
+ args,
+ provider_name=result.provider_name or "",
+ stage=result.stage or "",
+ actual_dimensions=actual_dimensions,
+ )
+ written = _commit_staged_image(
+ result.staged_path,
+ result.output_path,
+ lambda: write_sources_manifest(manifest_path, item),
+ )
+ except (OSError, RuntimeError, ValueError) as exc:
print(f"Error: {exc}", file=sys.stderr)
return 1
- print(f" manifest: {manifest_path}", file=sys.stderr)
+ finally:
+ try:
+ result.staged_path.unlink(missing_ok=True)
+ except OSError:
+ pass
+ print(f" manifest: {written}", file=sys.stderr)
+ review = _write_review_copy(
+ result.output_path,
+ result.output_path.parent / ".review",
+ result.output_path.name,
+ )
+ if review is not None:
+ print(f" review copy: {review}", file=sys.stderr)
- if candidate.license_tier == "attribution-required":
+ if result.candidate.license_tier == "attribution-required":
print(
"\n[!] This image requires on-slide attribution. "
"Executor should add a small credit element to the slide using "
diff --git a/skills/ppt-master/scripts/project_manager.py b/skills/ppt-master/scripts/project_manager.py
index 231eb1d8..57638a65 100644
--- a/skills/ppt-master/scripts/project_manager.py
+++ b/skills/ppt-master/scripts/project_manager.py
@@ -22,6 +22,7 @@ import re
import shutil
import subprocess
import sys
+import tempfile
from datetime import datetime
from pathlib import Path
from urllib.parse import urlparse
@@ -86,6 +87,82 @@ IMAGE_ASSET_SUFFIXES = BITMAP_IMAGE_SUFFIXES | {
configure_utf8_stdio()
+def _validate_image_manifest(
+ payload: object,
+ path: Path,
+) -> list[dict]:
+ """Require a safe, case-insensitively unique image manifest payload."""
+ if not isinstance(payload, list):
+ raise RuntimeError(
+ f"Image manifest must be a JSON array: {path}"
+ )
+
+ seen_filenames: dict[str, str] = {}
+ for index, item in enumerate(payload):
+ if not isinstance(item, dict):
+ raise RuntimeError(
+ f"Existing image manifest item {index} must be an object: {path}"
+ )
+ filename = item.get("filename")
+ if (
+ not isinstance(filename, str)
+ or not filename.strip()
+ or filename in {".", ".."}
+ or "/" in filename
+ or "\\" in filename
+ or ":" in filename
+ or Path(filename).is_absolute()
+ or Path(filename).name != filename
+ ):
+ raise RuntimeError(
+ f"Image manifest item {index} has no safe bare filename: {path}"
+ )
+ normalized_filename = filename.casefold()
+ if normalized_filename in seen_filenames:
+ raise RuntimeError(
+ f"Image manifest filename {filename!r} conflicts with "
+ f"{seen_filenames[normalized_filename]!r} (case-insensitive): {path}"
+ )
+ seen_filenames[normalized_filename] = filename
+ return payload
+
+
+def _read_existing_image_manifest(path: Path) -> list[dict]:
+ """Load an existing project image manifest or fail closed on corruption."""
+ if not path.exists():
+ return []
+ if not path.is_file():
+ raise RuntimeError(f"Existing image manifest is not a regular file: {path}")
+ try:
+ payload = json.loads(path.read_text(encoding="utf-8"))
+ except (OSError, json.JSONDecodeError) as exc:
+ raise RuntimeError(
+ f"Existing image manifest is unreadable: {path} ({exc}); "
+ "repair or restore it before importing more assets"
+ ) from exc
+ return _validate_image_manifest(payload, path)
+
+
+def _write_json_atomic(path: Path, payload: object) -> None:
+ """Write JSON through a same-directory temporary file and atomic rename."""
+ fd, temp_name = tempfile.mkstemp(
+ prefix=f"{path.stem}.",
+ suffix=".tmp",
+ dir=str(path.parent),
+ )
+ try:
+ with os.fdopen(fd, "w", encoding="utf-8") as handle:
+ json.dump(payload, handle, ensure_ascii=False, indent=2)
+ handle.write("\n")
+ os.replace(temp_name, path)
+ except Exception:
+ try:
+ os.unlink(temp_name)
+ except OSError:
+ pass
+ raise
+
+
def is_url(value: str) -> bool:
"""Return whether a string looks like an HTTP(S) URL."""
parsed = urlparse(value)
@@ -407,16 +484,8 @@ class ProjectManager:
def _merge_image_manifest(self, source_items: list[dict], destination_manifest: Path) -> None:
"""Merge per-source manifest items into the project-level manifest, keyed by filename."""
- existing_data: list[object] = []
- if destination_manifest.is_file():
- try:
- loaded = json.loads(destination_manifest.read_text(encoding="utf-8"))
- if isinstance(loaded, list):
- existing_data = loaded
- else:
- print(f"[WARN] Replacing non-list image manifest: {destination_manifest}")
- except (OSError, json.JSONDecodeError) as exc:
- print(f"[WARN] Replacing unreadable image manifest {destination_manifest}: {exc}")
+ _validate_image_manifest(source_items, destination_manifest)
+ existing_data = _read_existing_image_manifest(destination_manifest)
new_by_filename: dict[str, dict] = {}
new_order: list[str] = []
@@ -424,9 +493,10 @@ class ProjectManager:
filename = item.get("filename")
if not isinstance(filename, str):
continue
- if filename not in new_by_filename:
- new_order.append(filename)
- new_by_filename[filename] = item
+ normalized_filename = filename.casefold()
+ if normalized_filename not in new_by_filename:
+ new_order.append(normalized_filename)
+ new_by_filename[normalized_filename] = item
merged: list[dict] = []
seen: set[str] = set()
@@ -436,20 +506,19 @@ class ProjectManager:
filename = item.get("filename")
if not isinstance(filename, str):
continue
- if filename in new_by_filename:
- merged.append(new_by_filename[filename])
+ normalized_filename = filename.casefold()
+ if normalized_filename in new_by_filename:
+ merged.append(new_by_filename[normalized_filename])
else:
merged.append(item)
- seen.add(filename)
+ seen.add(normalized_filename)
- for filename in new_order:
- if filename not in seen:
- merged.append(new_by_filename[filename])
+ for normalized_filename in new_order:
+ if normalized_filename not in seen:
+ merged.append(new_by_filename[normalized_filename])
- destination_manifest.write_text(
- json.dumps(merged, ensure_ascii=False, indent=2) + "\n",
- encoding="utf-8",
- )
+ _validate_image_manifest(merged, destination_manifest)
+ _write_json_atomic(destination_manifest, merged)
@staticmethod
def _namespace_from_asset_dir(asset_dir: Path) -> str:
@@ -464,10 +533,11 @@ class ProjectManager:
source_file: Path,
namespace: str,
existing_manifest: dict[str, dict],
+ occupied_names: set[str],
) -> str:
"""Return a short unique image filename for the runtime image pool."""
candidate = images_dir / source_file.name
- if not candidate.exists():
+ if candidate.name.casefold() not in occupied_names:
return source_file.name
try:
meta = existing_manifest.get(candidate.name, {})
@@ -485,7 +555,7 @@ class ProjectManager:
counter = 2
while True:
candidate = images_dir / f"{stem}_{counter}{suffix}"
- if not candidate.exists():
+ if candidate.name.casefold() not in occupied_names:
return candidate.name
try:
meta = existing_manifest.get(candidate.name, {})
@@ -511,31 +581,31 @@ class ProjectManager:
return
try:
- source_data = json.loads(manifest_path.read_text(encoding="utf-8"))
+ source_payload = json.loads(manifest_path.read_text(encoding="utf-8"))
except (OSError, json.JSONDecodeError) as exc:
print(f"[WARN] Cannot read image manifest {manifest_path}: {exc}")
return
- if not isinstance(source_data, list):
- print(f"[WARN] Ignoring non-list image manifest: {manifest_path}")
+ try:
+ source_data = _validate_image_manifest(source_payload, manifest_path)
+ except RuntimeError as exc:
+ print(f"[WARN] {exc}")
return
images_dir = project_dir / "images"
- images_dir.mkdir(parents=True, exist_ok=True)
-
namespace = self._namespace_from_asset_dir(asset_dir)
- existing_manifest: dict[str, dict] = {}
destination_manifest = images_dir / "image_manifest.json"
- if destination_manifest.is_file():
- try:
- data = json.loads(destination_manifest.read_text(encoding="utf-8"))
- if isinstance(data, list):
- existing_manifest = {
- item["filename"]: item
- for item in data
- if isinstance(item, dict) and isinstance(item.get("filename"), str)
- }
- except (OSError, json.JSONDecodeError):
- existing_manifest = {}
+ existing_data = _read_existing_image_manifest(destination_manifest)
+ images_dir.mkdir(parents=True, exist_ok=True)
+
+ existing_manifest = {
+ item["filename"]: item
+ for item in existing_data
+ }
+ occupied_names = {
+ path.name.casefold()
+ for path in images_dir.iterdir()
+ if path.is_file()
+ }
rename_map: dict[str, str] = {}
copied_count = 0
@@ -549,10 +619,12 @@ class ProjectManager:
source_file,
namespace,
existing_manifest,
+ occupied_names,
)
destination = images_dir / new_name
if source_file.resolve() != destination.resolve():
shutil.copy2(source_file, destination)
+ occupied_names.add(new_name.casefold())
rename_map[source_file.name] = new_name
copied_count += 1
diff --git a/skills/ppt-master/scripts/project_specs.py b/skills/ppt-master/scripts/project_specs.py
index 3bfa521c..9f6f1d60 100644
--- a/skills/ppt-master/scripts/project_specs.py
+++ b/skills/ppt-master/scripts/project_specs.py
@@ -71,7 +71,30 @@ _MARKDOWN_DATA_LINE_RE = re.compile(
re.MULTILINE,
)
_IMAGE_PATH_SUFFIXES = frozenset(
- {".bmp", ".gif", ".jpeg", ".jpg", ".png", ".svg", ".tif", ".tiff", ".webp"}
+ {
+ ".bmp",
+ ".emf",
+ ".gif",
+ ".jpeg",
+ ".jpg",
+ ".png",
+ ".svg",
+ ".tif",
+ ".tiff",
+ ".webp",
+ ".wmf",
+ }
+)
+_IMAGE_ACQUISITION_SOURCES = frozenset(
+ {"ai", "web", "user", "formula", "placeholder", "slice"}
+)
+_IMAGE_CROP_POLICIES = frozenset({"adaptive", "no-crop"})
+_LEGACY_IMAGE_METADATA_KEYS = frozenset(
+ {
+ "image_rendering",
+ "image_rendering_behavior",
+ "image_rendering_references",
+ }
)
_LEGACY_SPEC_LOCK_FORBIDDEN = frozenset({"Mixing icon libraries"})
_SCAFFOLD_TOKEN_RE = re.compile(r"\{\{[A-Z_]+\}\}")
@@ -176,6 +199,109 @@ def _looks_like_image_path(raw: str) -> bool:
return bool(token) and Path(token).suffix.casefold() in _IMAGE_PATH_SUFFIXES
+def parse_spec_lock_image_value(key: str, value: str) -> dict[str, str]:
+ """Parse one image-lock row while preserving supported legacy rows.
+
+ Current rows use ``<path> | source=... | pattern=... | crop=...``. Legacy
+ rows remain readable, but any row that starts using named metadata must
+ provide the complete current contract.
+ """
+ normalized_key = str(key).strip()
+ normalized_value = str(value).strip()
+ parts = [part.strip() for part in normalized_value.split("|")]
+ path_part = parts[0] if parts else ""
+
+ if _looks_like_image_path(normalized_key) and not _looks_like_image_path(path_part):
+ parts.insert(0, normalized_key)
+ path_part = normalized_key
+ elif (
+ len(parts) >= 2
+ and parts[0].casefold() in _IMAGE_ACQUISITION_SOURCES
+ and _looks_like_image_path(parts[1])
+ ):
+ path_part = parts[1]
+
+ metadata_parts = [part for part in parts[1:] if "=" in part]
+ if not metadata_parts:
+ legacy_crop = (
+ "no-crop"
+ if any(
+ re.search(r"(?<![a-z])no-crop(?![a-z])", part, re.IGNORECASE)
+ for part in parts[1:]
+ )
+ else ""
+ )
+ return {
+ "path": path_part,
+ "source": "",
+ "pattern": "",
+ "crop": legacy_crop,
+ "legacy": "true",
+ }
+
+ metadata: dict[str, str] = {}
+ unsupported_parts: list[str] = []
+ for part in parts[1:]:
+ field, separator, raw = part.partition("=")
+ if not separator:
+ unsupported_parts.append(part)
+ continue
+ field = field.strip().casefold()
+ if field in metadata:
+ raise ValueError(f"repeats metadata field {field!r}")
+ metadata[field] = raw.strip()
+
+ expected_fields = {"source", "pattern", "crop"}
+ unknown_fields = sorted(set(metadata) - expected_fields)
+ missing_fields = sorted(expected_fields - set(metadata))
+ if unsupported_parts:
+ shown = ", ".join(repr(part) for part in unsupported_parts)
+ raise ValueError(f"has unsupported metadata token(s) {shown}")
+ if unknown_fields:
+ raise ValueError(
+ f"has unknown metadata field(s) {', '.join(unknown_fields)}"
+ )
+ if missing_fields:
+ raise ValueError(
+ f"misses metadata field(s) {', '.join(missing_fields)}"
+ )
+ if not _looks_like_image_path(path_part):
+ raise ValueError(f"has invalid image path {path_part!r}")
+
+ normalized_path = path_part.replace("\\", "/")
+ path = Path(normalized_path)
+ if (
+ path.is_absolute()
+ or len(path.parts) != 2
+ or path.parts[0] != "images"
+ or path.name in {"", ".", ".."}
+ or ":" in path.name
+ or normalized_path != f"images/{path.name}"
+ ):
+ raise ValueError(
+ f"must use canonical project path images/<filename>, got {path_part!r}"
+ )
+
+ source = metadata["source"].casefold()
+ if source not in _IMAGE_ACQUISITION_SOURCES:
+ allowed = ", ".join(sorted(_IMAGE_ACQUISITION_SOURCES))
+ raise ValueError(f"source must be one of {allowed}, got {metadata['source']!r}")
+ if not metadata["pattern"]:
+ raise ValueError("pattern must be non-empty")
+ crop = metadata["crop"].casefold()
+ if crop not in _IMAGE_CROP_POLICIES:
+ allowed = ", ".join(sorted(_IMAGE_CROP_POLICIES))
+ raise ValueError(f"crop must be one of {allowed}, got {metadata['crop']!r}")
+
+ return {
+ "path": normalized_path,
+ "source": source,
+ "pattern": metadata["pattern"],
+ "crop": crop,
+ "legacy": "false",
+ }
+
+
def parse_spec_lock_artifact(
lock_path: Path,
*,
@@ -873,6 +999,16 @@ def _validate_spec_lock_relations(
f"unknown catalog id '{reference}'"
)
+ for key, value in fields("images").items():
+ if key.strip().casefold() in _LEGACY_IMAGE_METADATA_KEYS:
+ continue
+ try:
+ parse_spec_lock_image_value(key, value)
+ except ValueError as exc:
+ errors.append(
+ f"{markdown_name} schema: images row {key!r} {exc}"
+ )
+
rhythm = fields("page_rhythm")
layouts = fields("pptx_layouts")
page_pptx_layouts = fields("page_pptx_layouts")
diff --git a/skills/ppt-master/scripts/resource_paths.py b/skills/ppt-master/scripts/resource_paths.py
index 1d6f3e29..fa81c898 100644
--- a/skills/ppt-master/scripts/resource_paths.py
+++ b/skills/ppt-master/scripts/resource_paths.py
@@ -1,15 +1,16 @@
#!/usr/bin/env python3
"""
-PPT Master - Shared SVG Resource Path Helpers
+PPT Master - Shared SVG Resource Helpers
-Centralizes project-relative SVG resource lookup used by the checker,
-finalizer, and SVG-to-PPTX exporter.
+Centralizes project-relative resource lookup and nested-SVG closure validation
+used by the checker, finalizer, and SVG-to-PPTX exporter.
Usage:
Imported by scripts; not intended as a standalone CLI.
Examples:
from resource_paths import resolve_external_image_reference
+ from resource_paths import svg_image_payload_error
Dependencies:
None
@@ -17,13 +18,45 @@ Dependencies:
from __future__ import annotations
+import base64
+import binascii
+import re
from pathlib import Path
-from urllib.parse import unquote, urlsplit
+from urllib.parse import unquote, unquote_to_bytes, urlsplit
+from xml.etree import ElementTree as ET
SVG_WORK_DIR_NAMES = frozenset({'svg_output', 'svg_final', 'svg-flat', 'svg_flat'})
TEMPLATE_SOURCE_DIR_NAME = 'templates'
TEMPLATE_SPEC_FILENAME = 'design_spec.md'
+_SVG_NAMESPACE = 'http://www.w3.org/2000/svg'
+_SVG_URL_REFERENCE_RE = re.compile(r'url\(\s*([^)]+?)\s*\)', re.IGNORECASE)
+_SVG_CSS_URL_ATTRIBUTES = frozenset({
+ 'background',
+ 'background-image',
+ 'clip-path',
+ 'color-profile',
+ 'cursor',
+ 'fill',
+ 'filter',
+ 'marker',
+ 'marker-end',
+ 'marker-mid',
+ 'marker-start',
+ 'mask',
+ 'stroke',
+ 'style',
+})
+_SVG_DIRECT_RESOURCE_ATTRIBUTES = frozenset({'poster', 'src'})
+_SVG_DATA_URI_DEPTH_LIMIT = 8
+_SVG_EXTERNAL_DOCTYPE_RE = re.compile(
+ br'<!DOCTYPE\b[^>]*\b(?:PUBLIC|SYSTEM)\b',
+ re.IGNORECASE | re.DOTALL,
+)
+_XML_STYLESHEET_HREF_RE = re.compile(
+ r'\bhref\s*=\s*([\'"])(.*?)\1',
+ re.IGNORECASE | re.DOTALL,
+)
def project_root_for_svg_path(svg_path: Path) -> Path:
@@ -59,6 +92,146 @@ def icon_search_dirs_for_svg(svg_path: Path) -> tuple[Path, Path | None]:
return icon_search_dirs_for_project(project_root_for_svg_path(svg_path))
+def _decode_svg_data_uri(raw: str) -> tuple[bytes | None, str | None]:
+ """Decode an SVG data URI; return ``(None, None)`` for other media."""
+ value = raw.strip().strip('\'"')
+ if not value.lower().startswith('data:'):
+ return None, None
+ header, separator, payload = value.partition(',')
+ media_type = header[5:].split(';', 1)[0].strip().lower()
+ if media_type != 'image/svg+xml':
+ return None, None
+ if not separator:
+ return None, 'invalid embedded SVG data URI'
+ is_base64 = any(
+ token.strip().lower() == 'base64'
+ for token in header.split(';')[1:]
+ )
+ try:
+ decoded = (
+ base64.b64decode(payload, validate=True)
+ if is_base64
+ else unquote_to_bytes(payload)
+ )
+ except (ValueError, binascii.Error):
+ return None, 'invalid embedded SVG data URI'
+ return decoded, None
+
+
+def _svg_reference_error(raw: str, depth: int) -> str | None:
+ """Return an external or recursively embedded SVG resource error."""
+ value = raw.strip().strip('\'"')
+ if not value:
+ return 'empty resource reference'
+ if value.startswith('#'):
+ return None
+ if not value.lower().startswith('data:'):
+ return f'unpackaged external resource {value!r}'
+
+ nested_svg, decode_error = _decode_svg_data_uri(value)
+ if decode_error is not None:
+ return decode_error
+ if nested_svg is None:
+ return None
+ if depth >= _SVG_DATA_URI_DEPTH_LIMIT:
+ return 'embedded SVG resource nesting exceeds the safety limit'
+ nested_error = _svg_image_payload_error(nested_svg, depth + 1)
+ if nested_error is None:
+ return None
+ return f'embedded SVG resource is not closed: {nested_error}'
+
+
+def _xml_stylesheet_error(raw_bytes: bytes, depth: int) -> str | None:
+ """Return an external XML stylesheet processing-instruction error."""
+ parser = ET.XMLPullParser(events=('pi',))
+ try:
+ parser.feed(raw_bytes)
+ parser.close()
+ except ET.ParseError:
+ return None
+ for _event, instruction in parser.read_events():
+ text = (instruction.text or '').strip()
+ if not text.lower().startswith('xml-stylesheet'):
+ continue
+ match = _XML_STYLESHEET_HREF_RE.search(text)
+ if match is None:
+ return 'XML stylesheet processing instruction lacks href'
+ reference_error = _svg_reference_error(match.group(2), depth)
+ if reference_error is not None:
+ return f'XML stylesheet is not closed: {reference_error}'
+ return None
+
+
+def _svg_image_payload_error(raw_bytes: bytes, depth: int) -> str | None:
+ """Return why one SVG image payload is not a closed packaged resource."""
+ if _SVG_EXTERNAL_DOCTYPE_RE.search(raw_bytes):
+ return 'unpackaged external XML doctype'
+ try:
+ root = ET.fromstring(raw_bytes)
+ except ET.ParseError as exc:
+ return f'invalid SVG XML: {exc}'
+ if root.tag != f'{{{_SVG_NAMESPACE}}}svg':
+ return 'root must use the SVG namespace'
+
+ stylesheet_error = _xml_stylesheet_error(raw_bytes, depth)
+ if stylesheet_error is not None:
+ return stylesheet_error
+ for elem in root.iter():
+ tag = str(elem.tag).rsplit('}', 1)[-1]
+ for raw_name, raw_value in elem.attrib.items():
+ name = raw_name.rsplit('}', 1)[-1]
+ if name == 'href' and tag != 'a':
+ reference_error = _svg_reference_error(raw_value, depth)
+ if reference_error is not None:
+ return reference_error
+ elif name in _SVG_DIRECT_RESOURCE_ATTRIBUTES:
+ reference_error = _svg_reference_error(raw_value, depth)
+ if reference_error is not None:
+ return reference_error
+ elif name == 'data' and tag == 'object':
+ reference_error = _svg_reference_error(raw_value, depth)
+ if reference_error is not None:
+ return reference_error
+ elif name == 'srcset' and raw_value.strip():
+ return 'srcset resource lists are not closed SVG resources'
+
+ if name not in _SVG_CSS_URL_ATTRIBUTES:
+ continue
+ for match in _SVG_URL_REFERENCE_RE.finditer(raw_value):
+ reference_error = _svg_reference_error(match.group(1), depth)
+ if reference_error is not None:
+ return f'url() resource is not closed: {reference_error}'
+
+ if tag != 'style':
+ continue
+ style_text = ''.join(elem.itertext())
+ if re.search(r'@import\b', style_text, flags=re.IGNORECASE):
+ return 'unpackaged CSS import'
+ for match in _SVG_URL_REFERENCE_RE.finditer(style_text):
+ reference_error = _svg_reference_error(match.group(1), depth)
+ if reference_error is not None:
+ return f'url() resource is not closed: {reference_error}'
+ return None
+
+
+def svg_image_payload_error(raw_bytes: bytes) -> str | None:
+ """Return why a nested SVG image is not a closed packaged resource."""
+ return _svg_image_payload_error(raw_bytes, 0)
+
+
+def svg_data_uri_payload_error(raw: str) -> str | None:
+ """Return why an inline SVG image data URI is not a closed resource."""
+ nested_svg, decode_error = _decode_svg_data_uri(raw)
+ if decode_error is not None:
+ return decode_error
+ if nested_svg is None:
+ return None
+ nested_error = _svg_image_payload_error(nested_svg, 0)
+ if nested_error is None:
+ return None
+ return f'inline SVG data URI is not closed: {nested_error}'
+
+
def external_image_reference_candidates(svg_dir: Path, href: str) -> list[Path]:
"""Return candidate paths for a non-data-URI SVG image href."""
parsed = urlsplit(href)
diff --git a/skills/ppt-master/scripts/slice_images.py b/skills/ppt-master/scripts/slice_images.py
index eed4ff07..2bfe79c7 100644
--- a/skills/ppt-master/scripts/slice_images.py
+++ b/skills/ppt-master/scripts/slice_images.py
@@ -175,6 +175,17 @@ def slice_sheet(
f"{total_cells} cells; provide exactly one name per cell"
)
safe_names = [_safe_basename(n) for n in names] if names else None
+ if safe_names:
+ seen_outputs: set[str] = set()
+ for name in safe_names:
+ output_name = name if Path(name).suffix else f"{name}.png"
+ normalized_output = output_name.casefold()
+ if normalized_output in seen_outputs:
+ raise ValueError(
+ f"--names repeats output filename {output_name!r} "
+ "(case-insensitive)"
+ )
+ seen_outputs.add(normalized_output)
if alpha and safe_names:
for name in safe_names:
suffix = Path(name).suffix.lower()
diff --git a/skills/ppt-master/scripts/svg_finalize/align_embed_images.py b/skills/ppt-master/scripts/svg_finalize/align_embed_images.py
index 4190251d..d30ed99d 100644
--- a/skills/ppt-master/scripts/svg_finalize/align_embed_images.py
+++ b/skills/ppt-master/scripts/svg_finalize/align_embed_images.py
@@ -46,6 +46,7 @@ from __future__ import annotations
import base64
import io
+import math
import os
import re
import sys
@@ -58,7 +59,11 @@ if str(_SCRIPTS_DIR) not in sys.path:
sys.path.insert(0, str(_SCRIPTS_DIR))
from console_encoding import configure_utf8_stdio # noqa: E402
-from resource_paths import resolve_external_image_reference # noqa: E402
+from resource_paths import ( # noqa: E402
+ resolve_external_image_reference,
+ svg_data_uri_payload_error,
+ svg_image_payload_error,
+)
configure_utf8_stdio()
@@ -223,6 +228,8 @@ def _target_size(
def _downscale_to_target(img: 'PILImage', target_w: int, target_h: int) -> tuple['PILImage', bool]:
"""Downscale without upsampling."""
width, height = img.size
+ if width <= 0 or height <= 0:
+ return img, False
ratio = min(target_w / width, target_h / height, 1.0)
if ratio >= 1.0:
return img, False
@@ -327,7 +334,10 @@ def _process_one_image(
href = _get_href(image)
if not href:
return False, None
- if href.startswith('data:'):
+ if href.lower().startswith('data:'):
+ payload_error = svg_data_uri_payload_error(href)
+ if payload_error is not None:
+ return False, payload_error
return False, None # already inline
img_path = _resolve_image_path(href, svg_dir)
@@ -346,6 +356,9 @@ def _process_one_image(
return False, None
if _is_svg_image(img_path, raw_bytes):
+ payload_error = svg_image_payload_error(raw_bytes)
+ if payload_error is not None:
+ return False, f'{img_path.name}: {payload_error}'
_embed_raw_image(image, img_path, raw_bytes)
if verbose:
print(f' [OK] {img_path.name} (svg, embedded as-is)')
@@ -379,7 +392,12 @@ def _process_one_image(
box_y = _parse_float(image.get('y'))
box_w = _parse_float(image.get('width'))
box_h = _parse_float(image.get('height'))
- if box_w <= 0 or box_h <= 0:
+ if (
+ not math.isfinite(box_w)
+ or not math.isfinite(box_h)
+ or box_w <= 0
+ or box_h <= 0
+ ):
return False, 'zero-sized box'
par_attr = image.get('preserveAspectRatio') or ''
@@ -392,6 +410,8 @@ def _process_one_image(
new_x, new_y, new_w, new_h = box_x, box_y, box_w, box_h
transformed = geometry_normalized
target_box_w, target_box_h = box_w, box_h
+ preserve_stretch = False
+ preserve_slice = False
if not par_attr:
# No preserveAspectRatio at all. The previous pipeline's fix-aspect
@@ -403,14 +423,20 @@ def _process_one_image(
align, mode = parse_preserve_aspect_ratio(par_attr)
if align == 'none':
# Author wants stretch-to-box; preserve geometry, embed bytes.
- pass
+ preserve_stretch = True
elif mode == 'slice':
x_anchor, y_anchor = get_crop_anchor(align)
cropped_img = crop_image_to_size(
- img, int(box_w), int(box_h), x_anchor, y_anchor
+ img, box_w, box_h, x_anchor, y_anchor
)
final_img = cropped_img
transformed = True
+ preserve_slice = not math.isclose(
+ cropped_img.size[0] / cropped_img.size[1],
+ box_w / box_h,
+ rel_tol=1e-6,
+ abs_tol=1e-9,
+ )
else: # meet (or any other mode → treat as meet)
new_w_calc, new_h_calc, off_x, off_y = calculate_fitted_dimensions(
img.size[0], img.size[1], box_w, box_h, mode='meet',
@@ -449,7 +475,11 @@ def _process_one_image(
image.set('y', _format_number(new_y))
image.set('width', _format_number(new_w))
image.set('height', _format_number(new_h))
- if 'preserveAspectRatio' in image.attrib:
+ if preserve_stretch:
+ image.set('preserveAspectRatio', 'none')
+ elif preserve_slice:
+ image.set('preserveAspectRatio', par_attr)
+ elif 'preserveAspectRatio' in image.attrib:
del image.attrib['preserveAspectRatio']
if verbose:
@@ -505,8 +535,10 @@ def align_and_embed_images_in_svg(
try:
tree = ET.parse(svg_path)
except ET.ParseError as exc:
- if verbose:
- print(f' [ERROR] {svg_path.name}: parse failed ({exc})')
+ print(
+ f' [ERROR] {svg_path.name}: parse failed ({exc})',
+ file=sys.stderr,
+ )
return (0, 1)
root = tree.getroot()
@@ -535,10 +567,9 @@ def align_and_embed_images_in_svg(
processed += 1
elif err:
errors += 1
- if verbose:
- print(f' [WARN] {svg_path.name}: {err}')
+ print(f' [ERROR] {svg_path.name}: {err}', file=sys.stderr)
- if processed > 0 and not dry_run:
+ if processed > 0 and errors == 0 and not dry_run:
tree.write(svg_path, encoding='utf-8', xml_declaration=False)
return (processed, errors)
diff --git a/skills/ppt-master/scripts/svg_finalize/crop_images.py b/skills/ppt-master/scripts/svg_finalize/crop_images.py
index 09b1f7f3..028bc319 100644
--- a/skills/ppt-master/scripts/svg_finalize/crop_images.py
+++ b/skills/ppt-master/scripts/svg_finalize/crop_images.py
@@ -86,8 +86,8 @@ def get_crop_anchor(align: str) -> tuple[float, float]:
def crop_image_to_size(
img: Image.Image,
- target_width: int,
- target_height: int,
+ target_width: float,
+ target_height: float,
x_anchor: float = 0.5,
y_anchor: float = 0.5,
) -> Image.Image:
@@ -108,6 +108,10 @@ def crop_image_to_size(
Cropped PIL Image object (preserving original resolution)
"""
img_width, img_height = img.size
+ if img_width <= 0 or img_height <= 0:
+ raise ValueError('source image dimensions must be positive')
+ if target_width <= 0 or target_height <= 0:
+ raise ValueError('target image dimensions must be positive')
# Calculate target aspect ratio
target_ratio = target_width / target_height
@@ -117,11 +121,11 @@ def crop_image_to_size(
if img_ratio > target_ratio:
# Original image is wider; crop left and right sides
crop_height = img_height
- crop_width = int(img_height * target_ratio)
+ crop_width = max(1, min(img_width, int(round(img_height * target_ratio))))
else:
# Original image is taller; crop top and bottom sides
crop_width = img_width
- crop_height = int(img_width / target_ratio)
+ crop_height = max(1, min(img_height, int(round(img_width / target_ratio))))
# Calculate crop position based on anchor point
extra_width = img_width - crop_width
diff --git a/skills/ppt-master/scripts/svg_quality_checker.py b/skills/ppt-master/scripts/svg_quality_checker.py
index 784d3b61..34228bb2 100644
--- a/skills/ppt-master/scripts/svg_quality_checker.py
+++ b/skills/ppt-master/scripts/svg_quality_checker.py
@@ -53,9 +53,13 @@ from svg_to_pptx.canvas_contract import (
)
try:
- from project_specs import parse_spec_lock as _parse_spec_lock
+ from project_specs import (
+ parse_spec_lock as _parse_spec_lock,
+ parse_spec_lock_image_value as _parse_spec_lock_image_value,
+ )
except ImportError:
_parse_spec_lock = None # spec_lock anchor comparison will be skipped
+ _parse_spec_lock_image_value = None
try:
from svg_to_pptx.animation_config import (
@@ -2248,13 +2252,15 @@ class SVGQualityChecker:
'frames or media'
)
return
- result['errors'].extend(
- _project_image_errors(
- root,
- svg_path.parent,
- allow_template_placeholders=self.template_mode,
+ _working_root, _parent_by_id, images = self._visible_image_elements(root)
+ for image in images:
+ result['errors'].extend(
+ _project_image_errors(
+ image,
+ svg_path.parent,
+ allow_template_placeholders=self.template_mode,
+ )
)
- )
def _check_freeform_geometry_values(
self,
@@ -3227,23 +3233,95 @@ class SVGQualityChecker:
parent_by_id: Dict[int, ET.Element],
) -> bool:
"""Return whether inherited display or visibility hides an element."""
- display = (
+ current: ET.Element | None = element
+ while current is not None:
+ style_values = (
+ _parse_inline_style(current.get('style'))
+ if _parse_inline_style is not None
+ else {}
+ )
+ display = style_values.get('display')
+ if display is None:
+ display = current.get('display')
+ if display and display.strip().lower() == 'none':
+ return True
+ current = parent_by_id.get(id(current))
+ visibility = (
_effective_presentation_value(
element,
- 'display',
+ 'visibility',
parent_by_id,
)
or ''
).strip().lower()
- visibility = (
- _effective_presentation_value(
+ return visibility in {'hidden', 'collapse'}
+
+ @staticmethod
+ def _has_zero_opacity(
+ element: ET.Element,
+ parent_by_id: Dict[int, ET.Element],
+ ) -> bool:
+ """Return whether an element or ancestor has zero effective opacity."""
+ current: ET.Element | None = element
+ while current is not None:
+ style_values = (
+ _parse_inline_style(current.get('style'))
+ if _parse_inline_style is not None
+ else {}
+ )
+ raw = style_values.get('opacity')
+ if raw is None:
+ raw = current.get('opacity')
+ if raw is not None:
+ value = raw.strip()
+ try:
+ opacity = (
+ float(value[:-1]) / 100
+ if value.endswith('%')
+ else float(value)
+ )
+ except ValueError:
+ pass
+ else:
+ if opacity <= 0:
+ return True
+ current = parent_by_id.get(id(current))
+ return False
+
+ @classmethod
+ def _visible_image_elements(
+ cls,
+ root: ET.Element,
+ ) -> Tuple[ET.Element, Dict[int, ET.Element], List[ET.Element]]:
+ """Return rendered image instances after expanding static local uses."""
+ working_root = copy.deepcopy(root)
+ if (
+ _expand_local_use_references is not None
+ and _UseExpansionError is not None
+ ):
+ try:
+ _expand_local_use_references(working_root)
+ except _UseExpansionError:
+ # The local-reference validator owns the actionable failure.
+ working_root = copy.deepcopy(root)
+
+ parent_by_id = {
+ id(child): parent
+ for parent in working_root.iter()
+ for child in list(parent)
+ }
+ images = [
+ element
+ for element in working_root.iter(f'{{{SVG_NS}}}image')
+ if not cls._is_hidden_element(element, parent_by_id)
+ and not cls._has_non_visual_ancestor(
element,
- 'visibility',
+ working_root,
parent_by_id,
)
- or ''
- ).strip().lower()
- return display == 'none' or visibility in {'hidden', 'collapse'}
+ and not cls._has_zero_opacity(element, parent_by_id)
+ ]
+ return working_root, parent_by_id, images
@staticmethod
def _has_non_visual_ancestor(
@@ -3657,16 +3735,9 @@ class SVGQualityChecker:
def _check_image_references(self, root: ET.Element, svg_path: Path, result: Dict):
"""Check image file existence and effective rendered resolution."""
svg_dir = svg_path.parent
- parent_by_id = {
- id(child): parent
- for parent in root.iter()
- for child in list(parent)
- }
-
- for image in root.iter():
- if image.tag != f'{{{SVG_NS}}}image':
- continue
+ working_root, parent_by_id, images = self._visible_image_elements(root)
+ for image in images:
href = image.get('href') or image.get(f'{{{XLINK_NS}}}href')
if not href or href.startswith('data:'):
continue
@@ -3691,7 +3762,7 @@ class SVGQualityChecker:
parent = parent_by_id.get(id(image))
if (
parent is not None
- and parent is not root
+ and parent is not working_root
and parent.tag == f'{{{SVG_NS}}}svg'
):
# Imported crops use a unit-frame inner image. Quality advice
@@ -5427,11 +5498,10 @@ class SVGQualityChecker:
@classmethod
def _referenced_image_basenames(cls, root: ET.Element) -> set[str]:
- """Return external image basenames referenced by one parsed SVG."""
+ """Return external image basenames rendered by one parsed SVG."""
filenames = set()
- for elem in root.iter():
- if elem.tag != f'{{{SVG_NS}}}image':
- continue
+ _working_root, _parent_by_id, images = cls._visible_image_elements(root)
+ for elem in images:
href = elem.get('href') or elem.get(f'{{{XLINK_NS}}}href')
filename = cls._external_image_reference_basename(href or '')
if filename:
@@ -5497,45 +5567,31 @@ class SVGQualityChecker:
@classmethod
def _visible_svg_text_blocks(cls, root: ET.Element) -> List[str]:
"""Return rendered text blocks, excluding hidden/non-visual content."""
+ working_root = copy.deepcopy(root)
+ if (
+ _expand_local_use_references is not None
+ and _UseExpansionError is not None
+ ):
+ try:
+ _expand_local_use_references(working_root)
+ except _UseExpansionError:
+ working_root = copy.deepcopy(root)
parent_by_id = {
id(child): parent
- for parent in root.iter()
+ for parent in working_root.iter()
for child in list(parent)
}
- def has_zero_opacity(element: ET.Element) -> bool:
- current: ET.Element | None = element
- while current is not None:
- style_values = (
- _parse_inline_style(current.get('style'))
- if _parse_inline_style is not None
- else {}
- )
- raw = style_values.get('opacity')
- if raw is None:
- raw = current.get('opacity')
- if raw is not None:
- value = raw.strip()
- try:
- opacity = (
- float(value[:-1]) / 100
- if value.endswith('%')
- else float(value)
- )
- except ValueError:
- pass
- else:
- if opacity <= 0:
- return True
- current = parent_by_id.get(id(current))
- return False
-
blocks: List[str] = []
- for element in root.iter(f'{{{SVG_NS}}}text'):
+ for element in working_root.iter(f'{{{SVG_NS}}}text'):
if (
cls._is_hidden_element(element, parent_by_id)
- or cls._has_non_visual_ancestor(element, root, parent_by_id)
- or has_zero_opacity(element)
+ or cls._has_non_visual_ancestor(
+ element,
+ working_root,
+ parent_by_id,
+ )
+ or cls._has_zero_opacity(element, parent_by_id)
):
continue
text = re.sub(r'\s+', ' ', ' '.join(element.itertext())).strip()
@@ -6248,7 +6304,7 @@ class SVGQualityChecker:
)
lock_images = set(lock_entries)
svg_texts = self._load_project_svg_texts(project_path)
- svg_references, inline_image_counts = (
+ svg_references, inline_image_counts, image_placements = (
self._load_project_svg_image_references(project_path)
)
all_svg_references = (
@@ -6309,6 +6365,7 @@ class SVGQualityChecker:
lock_error,
svg_references,
inline_image_counts,
+ image_placements,
)
else:
for row in slice_rows:
@@ -6423,6 +6480,23 @@ class SVGQualityChecker:
def _row_layout(row: Dict[str, str]) -> str:
return row.get('Layout pattern', '').strip()
+ @staticmethod
+ def _row_crop(row: Dict[str, str]) -> str:
+ return row.get('Crop Policy', '').strip().lower()
+
+ @staticmethod
+ def _layout_projection_matches(left: str, right: str) -> bool:
+ """Compare one Strategist recommendation without locking its wording."""
+ left_ids = re.findall(r'#([0-9]+)(?![0-9])', left)
+ right_ids = re.findall(r'#([0-9]+)(?![0-9])', right)
+ if left_ids or right_ids:
+ return left_ids == right_ids
+
+ def normalize(value: str) -> str:
+ return re.sub(r'\s+', ' ', value.replace('`', '')).strip()
+
+ return normalize(left) == normalize(right)
+
def _load_project_lock_image_entries(
self,
project_path: Path,
@@ -6433,6 +6507,8 @@ class SVGQualityChecker:
return {}, f"{lock_path} does not exist"
if _parse_spec_lock is None:
return {}, "spec_lock parser is unavailable"
+ if _parse_spec_lock_image_value is None:
+ return {}, "spec_lock image parser is unavailable"
try:
lock = _parse_spec_lock(lock_path)
except Exception as exc:
@@ -6444,42 +6520,33 @@ class SVGQualityChecker:
'image_rendering_references',
'image_rendering_behavior',
}
- acquisition_sources = {
- 'ai',
- 'web',
- 'user',
- 'formula',
- 'placeholder',
- 'slice',
- }
+ errors: List[str] = []
for key, value in lock.get('images', {}).items():
if str(key).strip().lower() in legacy_metadata_keys:
continue
- parts = [part.strip() for part in value.split('|')]
- path_part = parts[0] if parts else ''
- if (
- len(parts) >= 2
- and parts[0].lower() in acquisition_sources
- and parts[1]
- and not urlsplit(parts[1]).scheme
- ):
- # Legacy key-first rows spell `<source> | <path> | ...`.
- path_part = parts[1]
+ try:
+ parsed = _parse_spec_lock_image_value(str(key), str(value))
+ except ValueError as exc:
+ errors.append(f"images row {key!r} {exc}")
+ continue
+ path_part = parsed['path']
filename = Path(path_part).name
if not filename:
continue
- metadata = {
- field: raw
- for part in parts[1:]
- if '=' in part
- for field, raw in [part.split('=', 1)]
- }
entries[filename].append({
'key': str(key),
'path': path_part,
- **metadata,
+ 'source': parsed['source'],
+ 'pattern': parsed['pattern'],
+ 'crop': parsed['crop'],
+ 'legacy': parsed['legacy'],
})
- return dict(entries), None
+ error = (
+ f"{lock_path}: " + "; ".join(errors)
+ if errors
+ else None
+ )
+ return dict(entries), error
def _load_project_lock_images(self, project_path: Path) -> set[str]:
"""Return filenames listed under spec_lock.md images."""
@@ -6504,21 +6571,30 @@ class SVGQualityChecker:
def _load_project_svg_image_references(
cls,
project_path: Path,
- ) -> Tuple[Dict[Path, Dict[str, set[Path]]], Dict[Path, int]]:
- """Parse external image paths and count inline images in generated SVGs."""
+ ) -> Tuple[
+ Dict[Path, Dict[str, set[Path]]],
+ Dict[Path, int],
+ Dict[str, List[Tuple[Path, str, Tuple[str, ...]]]],
+ ]:
+ """Parse rendered image instances, paths, and crop mechanisms."""
svg_dir = project_path / 'svg_output'
if not svg_dir.exists():
- return {}, {}
+ return {}, {}, {}
out: Dict[Path, Dict[str, set[Path]]] = {}
inline_counts: Dict[Path, int] = {}
+ placements: Dict[
+ str,
+ List[Tuple[Path, str, Tuple[str, ...]]],
+ ] = defaultdict(list)
for svg_path in sorted(svg_dir.glob('*.svg')):
try:
root = ET.parse(svg_path).getroot()
except (OSError, ET.ParseError):
continue
+ working_root, parent_by_id, images = cls._visible_image_elements(root)
references: Dict[str, set[Path]] = defaultdict(set)
inline_count = 0
- for element in root.iter(f'{{{SVG_NS}}}image'):
+ for element in images:
href = (
element.get('href')
or element.get(f'{{{XLINK_NS}}}href')
@@ -6531,6 +6607,15 @@ class SVGQualityChecker:
if not filename:
continue
references.setdefault(filename, set())
+ placements[filename].append((
+ svg_path,
+ element.get('preserveAspectRatio') or '',
+ cls._image_crop_mechanisms(
+ element,
+ working_root,
+ parent_by_id,
+ ),
+ ))
if _resolve_external_image_reference is not None:
resolved = _resolve_external_image_reference(
svg_path.parent,
@@ -6541,7 +6626,39 @@ class SVGQualityChecker:
out[svg_path] = dict(references)
if inline_count:
inline_counts[svg_path] = inline_count
- return out, inline_counts
+ return out, inline_counts, dict(placements)
+
+ @staticmethod
+ def _image_crop_mechanisms(
+ image: ET.Element,
+ root: ET.Element,
+ parent_by_id: Dict[int, ET.Element],
+ ) -> Tuple[str, ...]:
+ """Return objective clipping mechanisms affecting one image instance."""
+ mechanisms: List[str] = []
+ current: ET.Element | None = image
+ while current is not None:
+ tag = _local_name(current)
+ style_values = (
+ _parse_inline_style(current.get('style'))
+ if _parse_inline_style is not None
+ else {}
+ )
+ for property_name in ('clip-path', 'mask'):
+ value = style_values.get(property_name)
+ if value is None:
+ value = current.get(property_name)
+ if value and value.strip().lower() != 'none':
+ mechanisms.append(f"<{tag}> {property_name}")
+ overflow = style_values.get('overflow')
+ if overflow is None:
+ overflow = current.get('overflow')
+ if overflow and overflow.strip().lower() in {'hidden', 'clip'}:
+ mechanisms.append(f"<{tag}> overflow={overflow.strip()!r}")
+ if current is not root and tag == 'svg':
+ mechanisms.append('nested <svg> viewport')
+ current = parent_by_id.get(id(current))
+ return tuple(dict.fromkeys(mechanisms))
def _check_planned_image_closure(
self,
@@ -6551,6 +6668,10 @@ class SVGQualityChecker:
lock_error: str | None,
svg_references: Dict[Path, Dict[str, set[Path]]],
inline_image_counts: Dict[Path, int],
+ image_placements: Dict[
+ str,
+ List[Tuple[Path, str, Tuple[str, ...]]],
+ ],
) -> None:
"""Close Design Spec, execution lock, files, SVGs, and provenance."""
project_root = project_path.resolve()
@@ -6594,12 +6715,22 @@ class SVGQualityChecker:
'placeholder': {'placeholder'},
'slice': {'generated', 'needs-manual'},
}
+ current_image_contract = (
+ any('Crop Policy' in row for row in rows)
+ or any(
+ entry.get('legacy') == 'false'
+ for entries in lock_entries.values()
+ for entry in entries
+ )
+ )
seen_filenames: set[str] = set()
for row in rows:
raw_filename = self._row_raw_filename(row)
filename = self._row_filename(row)
acquire = self._row_acquire(row)
status = self._row_status(row)
+ layout = self._row_layout(row)
+ crop = self._row_crop(row)
filename_is_bare = bool(filename) and (
filename not in {'.', '..'}
and '/' not in filename
@@ -6628,6 +6759,24 @@ class SVGQualityChecker:
else:
seen_filenames.add(filename)
+ if current_image_contract and not layout:
+ self._illustration_issues.append((
+ 'error',
+ 'planned_image_missing_pattern',
+ f"{filename or '(missing filename)'} has an empty Design "
+ "Spec §VIII Layout pattern; preserve one non-empty "
+ "Strategist recommendation without locking SVG geometry.",
+ ))
+ if current_image_contract and crop not in {'adaptive', 'no-crop'}:
+ self._illustration_issues.append((
+ 'error',
+ 'planned_image_invalid_crop_policy',
+ f"{filename or '(missing filename)'} has invalid Design "
+ f"Spec §VIII Crop Policy "
+ f"{row.get('Crop Policy', '').strip()!r}; use adaptive "
+ "or no-crop.",
+ ))
+
if acquire not in valid_acquisitions:
self._illustration_issues.append((
'error',
@@ -6695,6 +6844,18 @@ class SVGQualityChecker:
f"{filename} is a placed Design Spec image row but is "
"absent from spec_lock.md images.",
))
+ continue
+ if current_image_contract and any(
+ entry.get('legacy') != 'false'
+ for entry in lock_entries[filename]
+ ):
+ self._illustration_issues.append((
+ 'error',
+ 'planned_image_legacy_lock_projection',
+ f"{filename} uses the current Design Spec image contract "
+ "but its spec_lock.md row does not provide complete "
+ "source=..., pattern=..., and crop=... metadata.",
+ ))
for filename in sorted(referenced - set(rows_by_filename)):
lock_note = (
@@ -6722,6 +6883,51 @@ class SVGQualityChecker:
acquire = self._row_acquire(row)
status = self._row_status(row)
+ layout_pattern = self._row_layout(row)
+ crop_policy = self._row_crop(row)
+ if len(entries) > 1:
+ keys = ', '.join(repr(entry.get('key', '')) for entry in entries)
+ self._illustration_issues.append((
+ 'error',
+ 'locked_image_duplicate_entries',
+ f"{filename} appears in multiple spec_lock.md image rows "
+ f"({keys}); one resource must have one authoritative row.",
+ ))
+ for entry in entries:
+ if entry.get('legacy') != 'false':
+ continue
+ if entry.get('source') != acquire:
+ self._illustration_issues.append((
+ 'error',
+ 'locked_image_source_mismatch',
+ f"{filename} spec_lock source={entry.get('source')!r} "
+ f"does not match Design Spec §VIII Acquire Via "
+ f"{acquire!r}.",
+ ))
+ if entry.get('crop') != crop_policy:
+ self._illustration_issues.append((
+ 'error',
+ 'locked_image_crop_mismatch',
+ f"{filename} spec_lock crop={entry.get('crop')!r} "
+ f"does not match Design Spec §VIII Crop Policy "
+ f"{crop_policy!r}.",
+ ))
+ if not self._layout_projection_matches(
+ entry.get('pattern', ''),
+ layout_pattern,
+ ):
+ self._illustration_issues.append((
+ 'error',
+ 'locked_image_pattern_mismatch',
+ f"{filename} spec_lock pattern="
+ f"{entry.get('pattern')!r} does not preserve the "
+ "Design Spec §VIII Layout pattern recommendation "
+ f"{layout_pattern!r}. This Design Spec-to-spec_lock "
+ "projection check compares ordered catalog ids when "
+ "present, otherwise normalized text; it does not "
+ "compare SVG geometry or restrict the Executor's "
+ "realization.",
+ ))
candidate_paths: List[Path] = []
for entry in entries:
raw_path = entry.get('path', '')
@@ -6825,6 +7031,44 @@ class SVGQualityChecker:
"file is not referenced by any svg_output <image> element.",
))
+ effective_no_crop = (
+ crop_policy == 'no-crop'
+ or acquire == 'formula'
+ or any(entry.get('crop') == 'no-crop' for entry in entries)
+ )
+ if effective_no_crop:
+ for svg_path, raw_aspect, mechanisms in image_placements.get(
+ filename,
+ [],
+ ):
+ try:
+ align, mode = (
+ _parse_project_image_aspect_ratio(raw_aspect or None)
+ if _parse_project_image_aspect_ratio is not None
+ else ('', '')
+ )
+ except ValueError:
+ # The per-SVG aspect-ratio validator owns malformed syntax.
+ continue
+ if align != 'xMidYMid' or mode != 'meet':
+ actual = raw_aspect or '(implicit xMidYMid meet)'
+ self._illustration_issues.append((
+ 'error',
+ 'no_crop_image_fit_mismatch',
+ f"{svg_path.name}: {filename} is no-crop but its "
+ f"rendered placement uses "
+ f"preserveAspectRatio={actual!r}; use xMidYMid meet.",
+ ))
+ if mechanisms:
+ self._illustration_issues.append((
+ 'error',
+ 'no_crop_image_clipped',
+ f"{svg_path.name}: {filename} is no-crop but its "
+ "rendered placement is affected by "
+ f"{', '.join(mechanisms)}; remove clipping so every "
+ "source pixel remains visible.",
+ ))
+
self._check_sourced_image_provenance(
rows_by_filename,
project_path,
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 23832376..2c262709 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/drawingml/elements.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/drawingml/elements.py
@@ -25,7 +25,10 @@ from pptx_shapes import (
)
from pptx_effects import EFFECT_REASON_ATTR, EFFECT_STATUS_ATTR
from pptx_to_svg.preset_authoring import AUTHORING_ATTR, AUTHORING_VALUE
-from resource_paths import resolve_external_image_reference
+from resource_paths import (
+ resolve_external_image_reference,
+ svg_image_payload_error,
+)
from .context import ConvertContext, ShapeResult
from .theme_colors import color_node_xml
@@ -259,11 +262,7 @@ def _valid_project_image_payload(img_format: str, img_data: bytes) -> bool:
if not img_data:
return False
if img_format == 'svg':
- try:
- root = ET.fromstring(img_data)
- except ET.ParseError:
- return False
- return root.tag == f'{{{SVG_NS}}}svg'
+ return svg_image_payload_error(img_data) is None
if img_format == 'emf':
return _valid_emf_payload(img_data)
if img_format == 'wmf':
@@ -3494,16 +3493,94 @@ def _picture_xfrm_from_svg_rect(
return _picture_xfrm_from_rect(ctx, resolved_x, resolved_y, resolved_w, resolved_h)
-def _read_image_size(data: bytes) -> tuple[int | None, int | None]:
+def _picture_rendered_frame_size(
+ ctx: ConvertContext,
+ raw_x: float,
+ raw_y: float,
+ raw_w: float,
+ raw_h: float,
+ resolved_x: float,
+ resolved_y: float,
+ resolved_w: float,
+ resolved_h: float,
+ transform: str | None,
+) -> tuple[float, float]:
+ """Return final DrawingML picture-axis lengths in rendered SVG pixels."""
+ _attr, _x, _y, ext_cx, ext_cy, _bounds = _picture_xfrm_from_svg_rect(
+ ctx,
+ raw_x,
+ raw_y,
+ raw_w,
+ raw_h,
+ resolved_x,
+ resolved_y,
+ resolved_w,
+ resolved_h,
+ transform,
+ )
+ emu_per_px = px_to_emu(1.0)
+ return ext_cx / emu_per_px, ext_cy / emu_per_px
+
+
+def _read_svg_image_size(data: bytes) -> tuple[float, float] | None:
+ """Read an SVG image's viewport ratio from root dimensions or viewBox."""
+ try:
+ root = ET.fromstring(data)
+ except ET.ParseError:
+ return None
+ if root.tag != f'{{{SVG_NS}}}svg':
+ return None
+
+ try:
+ width = parse_svg_length(root.get('width'))
+ height = parse_svg_length(root.get('height'))
+ except ValueError:
+ width = 0.0
+ height = 0.0
+ if (
+ width > 0
+ and height > 0
+ and math.isfinite(width)
+ and math.isfinite(height)
+ ):
+ return width, height
+
+ view_box = root.get('viewBox')
+ if view_box:
+ parts = [
+ part for part in re.split(r'[\s,]+', view_box.strip())
+ if part
+ ]
+ try:
+ values = [float(part) for part in parts]
+ except ValueError:
+ values = []
+ if (
+ len(values) == 4
+ and all(math.isfinite(value) for value in values)
+ and values[2] > 0
+ and values[3] > 0
+ ):
+ return values[2], values[3]
+ return None
+
+
+def _read_image_size(data: bytes) -> tuple[float | None, float | None]:
"""Read intrinsic image dimensions (width, height) from raw bytes.
Used by ``convert_image`` to translate SVG ``preserveAspectRatio`` into
DrawingML ``<a:srcRect>`` so the original image is preserved and remains
croppable inside PowerPoint.
- Returns ``(None, None)`` on any failure — callers fall back to the
- legacy stretch behaviour.
+ SVG images use valid root ``width`` / ``height`` as the viewport ratio and
+ fall back to ``viewBox`` when either dimension is unavailable. Raster
+ images use EXIF-normalized pixel dimensions. Returns ``(None, None)`` on
+ any failure.
"""
+ svg_size = _read_svg_image_size(data)
+ if svg_size is not None:
+ return svg_size
+
try:
from PIL import Image, ImageOps, UnidentifiedImageError # type: ignore
except ImportError:
@@ -3578,58 +3655,119 @@ def _image_target_size(
return target_w, target_h
+def _visible_source_scale_floor(
+ img_w: int,
+ img_h: int,
+ display_w: float,
+ display_h: float,
+ visible_source_fraction: tuple[float, float],
+) -> float:
+ """Keep each rendered axis at or below its visible source pixels."""
+ fraction_w, fraction_h = visible_source_fraction
+ visible_w = img_w * fraction_w
+ visible_h = img_h * fraction_h
+ if visible_w <= 0 or visible_h <= 0:
+ return 1.0
+ return min(1.0, max(display_w / visible_w, display_h / visible_h))
+
+
def _fit_full_image_target(
img_w: int,
img_h: int,
- box_w: float,
- box_h: float,
- align: str,
- mode: str,
+ display_w: float,
+ display_h: float,
*,
sizing: str,
max_dimension: int | None,
scale: float,
+ visible_source_fraction: tuple[float, float] | None = None,
) -> tuple[int, int]:
"""Size the full source image; never crop pixels.
- ``cap`` mode only limits oversized source images by maximum dimension.
- ``display`` mode sizes to the rendered SVG box budget.
+ ``cap`` mode limits oversized sources unless that would leave a cropped
+ or stretched picture with fewer visible source pixels than its final
+ rendered frame. ``display`` mode targets the configured rendered-frame
+ scale while retaining the same one-source-pixel-per-display-pixel floor.
"""
if img_w <= 0 or img_h <= 0:
return (1, 1)
+ enforce_visible_floor = visible_source_fraction is not None
+ if enforce_visible_floor and (
+ any(
+ not math.isfinite(fraction) or fraction <= 0
+ for fraction in visible_source_fraction
+ )
+ ):
+ return (img_w, img_h)
+
if sizing == 'cap':
- target_w, target_h = img_w, img_h
- if max_dimension and max(target_w, target_h) > max_dimension:
- ratio = max_dimension / max(target_w, target_h)
- target_w = max(1, int(round(target_w * ratio)))
- target_h = max(1, int(round(target_h * ratio)))
+ ratio = 1.0
+ if max_dimension and max(img_w, img_h) > max_dimension:
+ ratio = max_dimension / max(img_w, img_h)
+ if enforce_visible_floor:
+ ratio = max(
+ ratio,
+ _visible_source_scale_floor(
+ img_w,
+ img_h,
+ display_w,
+ display_h,
+ visible_source_fraction,
+ ),
+ )
+ ratio = min(1.0, ratio)
+ target_w = max(1, int(math.ceil(img_w * ratio)))
+ target_h = max(1, int(math.ceil(img_h * ratio)))
return target_w, target_h
- target_box_w, target_box_h = _image_target_size(
- box_w,
- box_h,
+ target_display_w, target_display_h = _image_target_size(
+ display_w,
+ display_h,
max_dimension=None,
scale=scale,
)
- img_ratio = img_w / img_h
- box_ratio = box_w / box_h if box_h else img_ratio
- if align != 'none' and mode == 'slice':
- if box_ratio >= img_ratio:
- target_w = target_box_w
- target_h = int(round(target_w / img_ratio))
- else:
- target_h = target_box_h
- target_w = int(round(target_h * img_ratio))
+ if enforce_visible_floor:
+ fraction_w, fraction_h = visible_source_fraction
+ preferred_scale = min(
+ 1.0,
+ max(
+ target_display_w / (img_w * fraction_w),
+ target_display_h / (img_h * fraction_h),
+ ),
+ )
+ visible_floor = _visible_source_scale_floor(
+ img_w,
+ img_h,
+ display_w,
+ display_h,
+ visible_source_fraction,
+ )
+ resize_scale = preferred_scale
+ if max_dimension and max(img_w, img_h) * resize_scale > max_dimension:
+ resize_scale = max(
+ visible_floor,
+ max_dimension / max(img_w, img_h),
+ )
+ target_w = int(math.ceil(img_w * resize_scale))
+ target_h = int(math.ceil(img_h * resize_scale))
else:
- ratio = min(target_box_w / img_w, target_box_h / img_h, 1.0)
+ ratio = min(
+ target_display_w / img_w,
+ target_display_h / img_h,
+ 1.0,
+ )
target_w = int(round(img_w * ratio))
target_h = int(round(img_h * ratio))
target_w = max(1, target_w)
target_h = max(1, target_h)
- if max_dimension and max(target_w, target_h) > max_dimension:
+ if (
+ not enforce_visible_floor
+ and max_dimension
+ and max(target_w, target_h) > max_dimension
+ ):
ratio = max_dimension / max(target_w, target_h)
target_w = max(1, int(round(target_w * ratio)))
target_h = max(1, int(round(target_h * ratio)))
@@ -3648,7 +3786,10 @@ def _resize_for_target(img: Any, target_w: int, target_h: int) -> Any:
from PIL import Image # type: ignore
except ImportError:
return img
- new_size = (max(1, int(round(width * ratio))), max(1, int(round(height * ratio))))
+ new_size = (
+ max(1, int(math.ceil(width * ratio))),
+ max(1, int(math.ceil(height * ratio))),
+ )
return img.resize(new_size, Image.Resampling.LANCZOS)
@@ -3672,12 +3813,13 @@ def _encode_optimized_image(img: Any, *, prefer_jpeg: bool, quality: int) -> tup
def _optimize_image_for_pptx(
- elem: ET.Element,
ctx: ConvertContext,
img_data: bytes,
img_format: str,
- box_w: float,
- box_h: float,
+ display_w: float,
+ display_h: float,
+ *,
+ visible_source_fraction: tuple[float, float] | None = None,
) -> tuple[bytes, str]:
"""Optimize full raster image bytes for native PPTX embedding."""
if not ctx.image_optimize:
@@ -3706,19 +3848,15 @@ def _optimize_image_for_pptx(
geometry_normalized = _has_exif_geometry_transform(img)
img = _prepare_raster_for_geometry(img)
- align, mode = parse_project_image_aspect_ratio(
- elem.get('preserveAspectRatio')
- )
target_w, target_h = _fit_full_image_target(
img.size[0],
img.size[1],
- box_w,
- box_h,
- align,
- mode,
+ display_w,
+ display_h,
sizing=ctx.image_sizing,
max_dimension=ctx.image_max_dimension,
scale=ctx.image_scale,
+ visible_source_fraction=visible_source_fraction,
)
original_size = img.size
@@ -3766,35 +3904,37 @@ def _compute_slice_src_rect(
visible_w = box_w / scale # ≤ img_w
visible_h = box_h / scale # ≤ img_h
- if abs(visible_w - img_w) < 0.5 and abs(visible_h - img_h) < 0.5:
+ if (
+ math.isclose(visible_w, img_w, rel_tol=1e-9, abs_tol=1e-9)
+ and math.isclose(visible_h, img_h, rel_tol=1e-9, abs_tol=1e-9)
+ ):
return None # No crop needed
- crop_w_total = max(0.0, img_w - visible_w)
- crop_h_total = max(0.0, img_h - visible_h)
-
x_anchor, y_anchor = PROJECT_IMAGE_ASPECT_RATIO_ANCHORS[align]
-
- crop_l = crop_w_total * x_anchor
- crop_r = crop_w_total - crop_l
- crop_t = crop_h_total * y_anchor
- crop_b = crop_h_total - crop_t
-
- l = max(0, min(100000, int(round(crop_l / img_w * 100000))))
- t = max(0, min(100000, int(round(crop_t / img_h * 100000))))
- r = max(0, min(100000, int(round(crop_r / img_w * 100000))))
- b = max(0, min(100000, int(round(crop_b / img_h * 100000))))
+ crop_w_total = max(
+ 0,
+ min(99999, int(round((1.0 - visible_w / img_w) * 100000))),
+ )
+ crop_h_total = max(
+ 0,
+ min(99999, int(round((1.0 - visible_h / img_h) * 100000))),
+ )
+ l = max(0, min(crop_w_total, int(round(crop_w_total * x_anchor))))
+ t = max(0, min(crop_h_total, int(round(crop_h_total * y_anchor))))
+ r = crop_w_total - l
+ b = crop_h_total - t
+ if not any((l, t, r, b)):
+ return None
return (l, t, r, b)
-def _resolve_image_src_rect(
+def _resolve_image_src_rect_values(
elem: ET.Element,
img_data: bytes,
box_w: float, box_h: float,
-) -> str:
- """Build ``<a:srcRect .../>`` XML for an SVG <image> based on its
- preserveAspectRatio. Returns an empty string when no srcRect is needed
- (meet mode, none mode, or already-aligned content).
+) -> tuple[int, int, int, int] | None:
+ """Resolve DrawingML source-crop values for an SVG slice image.
Slice mode is resolved into a srcRect so the original image is embedded
intact and PowerPoint's crop tool / "Reset Picture" continue to work.
@@ -3807,16 +3947,25 @@ def _resolve_image_src_rect(
)
if align == 'none' or mode != 'slice':
- return '' # meet handled by frame fit; none → stretch is correct per SVG spec
+ return None
img_w, img_h = _read_image_size(img_data)
if img_w is None or img_h is None:
- return ''
+ return None
- rect = _compute_slice_src_rect(float(img_w), float(img_h), box_w, box_h, align)
+ return _compute_slice_src_rect(
+ float(img_w),
+ float(img_h),
+ box_w,
+ box_h,
+ align,
+ )
+
+
+def _src_rect_xml(rect: tuple[int, int, int, int] | None) -> str:
+ """Serialize an optional DrawingML source crop."""
if rect is None:
return ''
-
l, t, r, b = rect
return f'<a:srcRect l="{l}" t="{t}" r="{r}" b="{b}"/>'
@@ -3914,8 +4063,47 @@ def convert_image(elem: ET.Element, ctx: ConvertContext) -> ShapeResult | None:
img_format = source.img_format
img_data = source.img_data
+ transform = elem.get('transform')
+ rendered_w, rendered_h = _picture_rendered_frame_size(
+ ctx,
+ raw_x,
+ raw_y,
+ raw_w,
+ raw_h,
+ x,
+ y,
+ w,
+ h,
+ transform,
+ )
+ align, mode = parse_project_image_aspect_ratio(
+ elem.get('preserveAspectRatio')
+ )
+ src_rect = _resolve_image_src_rect_values(
+ elem,
+ img_data,
+ raw_w,
+ raw_h,
+ )
+ visible_source_fraction = None
+ if align == 'none':
+ visible_source_fraction = (1.0, 1.0)
+ elif mode == 'slice':
+ if src_rect is None:
+ visible_source_fraction = (1.0, 1.0)
+ else:
+ src_l, src_t, src_r, src_b = src_rect
+ visible_source_fraction = (
+ 1.0 - (src_l + src_r) / 100000.0,
+ 1.0 - (src_t + src_b) / 100000.0,
+ )
img_data, img_format = _optimize_image_for_pptx(
- elem, ctx, img_data, img_format, w, h,
+ ctx,
+ img_data,
+ img_format,
+ rendered_w,
+ rendered_h,
+ visible_source_fraction=visible_source_fraction,
)
img_idx = len(ctx.media_files) + 1
@@ -3929,15 +4117,13 @@ def convert_image(elem: ET.Element, ctx: ConvertContext) -> ShapeResult | None:
'target': f'../media/{img_filename}',
})
- transform = elem.get('transform')
-
# Resolve clip-path → DrawingML geometry
clip_geom = _resolve_clip_geometry(elem, ctx, raw_x, raw_y, raw_w, raw_h)
# Resolve preserveAspectRatio="<align> slice" as DrawingML crop metadata.
# Image optimization only downscales the full source image; it never crops
# pixels out of the embedded media.
- src_rect_xml = _resolve_image_src_rect(elem, img_data, w, h)
+ src_rect_xml = _src_rect_xml(src_rect)
blip_xml = _build_image_blip_xml(r_id, get_element_opacity(elem, ctx))
# Resolve preserveAspectRatio="<align> meet" by shrinking the picture
@@ -4403,8 +4589,29 @@ def convert_nested_svg(elem: ET.Element, ctx: ConvertContext) -> ShapeResult:
img_format = source.img_format
img_data = source.img_data
+ transform = elem.get('transform')
+ rendered_w, rendered_h = _picture_rendered_frame_size(
+ ctx,
+ svg_x,
+ svg_y,
+ svg_w,
+ svg_h,
+ x,
+ y,
+ w,
+ h,
+ transform,
+ )
img_data, img_format = _optimize_image_for_pptx(
- image_elem, ctx, img_data, img_format, w, h,
+ ctx,
+ img_data,
+ img_format,
+ rendered_w,
+ rendered_h,
+ visible_source_fraction=(
+ 1.0 - (crop.src_l + crop.src_r) / 100000.0,
+ 1.0 - (crop.src_t + crop.src_b) / 100000.0,
+ ),
)
img_idx = len(ctx.media_files) + 1
@@ -4418,8 +4625,6 @@ def convert_nested_svg(elem: ET.Element, ctx: ConvertContext) -> ShapeResult:
'target': f'../media/{img_filename}',
})
- transform = elem.get('transform')
-
shape_id = _claim_element_shape_id(elem, ctx)
xfrm_attr, off_x, off_y, ext_cx, ext_cy, bounds_emu = _picture_xfrm_from_svg_rect(
ctx,
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 dcb1674f..1c07a6fa 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
@@ -857,9 +857,11 @@ Recorded narration:
parser.add_argument('--no-image-optimize', action='store_true',
help='Disable native PPTX raster image optimization; embeds original image bytes.')
parser.add_argument('--image-max-dimension', type=int, default=2560,
- help='Maximum optimized raster image dimension in pixels (default: 2560).')
+ help='Preferred optimized raster cap in pixels; cap mode may retain more '
+ 'for cropped/stretched effective resolution (default: 2560).')
parser.add_argument('--image-sizing', choices=['cap', 'display'], default='cap',
- help='Raster sizing mode: cap only limits source dimensions; '
+ help='Raster sizing mode: cap limits source dimensions without '
+ 'undersupplying cropped/stretched visible pixels; '
'display sizes from the SVG rendered box (default: cap).')
parser.add_argument('--image-scale', type=float, default=2.0,
help='Target optimized image pixels per SVG display pixel '