| 1 | > See [`shared-standards-core.md`](./shared-standards-core.md) for common technical constraints. |
| 2 | |
| 3 | # SVG Image Embedding Guide |
| 4 | |
| 5 | Technical spec and workflow for adding images to SVG files. |
| 6 | |
| 7 | --- |
| 8 | |
| 9 | ## Image Resource List Format |
| 10 | |
| 11 | Each image carries an `Acquire Via` field plus a status annotation. This file |
| 12 | owns status names, resource lifecycle, and embedding workflow; |
| 13 | [`svg-effects.md`](./svg-effects.md) §6.5 owns native carrier, crop transport, |
| 14 | and filter/clip contracts. |
| 15 | |
| 16 | | Mode | Resource authority and preparation timing | |
| 17 | |---|---| |
| 18 | | Default Generate | `design_spec.md §VIII` plus its lock projection; when user-provided images are selected, run `analyze_images.py` after Strategist confirmation and complete the list before Executor | |
| 19 | | Quick Generate | Current main agent's active-context resource decisions; materialize explicit user paths first, resolve unspecified acquisition decisions automatically, and finish user/ai/web/slice preparation before SVG authoring without confirmation or a persisted roster | |
| 20 | |
| 21 | ```markdown |
| 22 | | Filename | Dimensions | Purpose | Type | Layout pattern | Crop Policy | Acquire Via | Status | Reference | |
| 23 | |----------|------------|---------|------|----------------|-------------|-------------|--------|-----------| |
| 24 | | team.jpg | 800x600 | Team photo | Photography | `Put faces behind the hiring claim; #P1-02 + #M2-08 fading the photo edge into the page so copy meets it without a frame` | adaptive | web | Pending | Diverse engineering team in modern office | |
| 25 | ``` |
| 26 | |
| 27 | ### Image Status Enum |
| 28 | |
| 29 | | Status | Meaning | Executor Handling | |
| 30 | |--------|---------|-------------------| |
| 31 | | **Pending** | Acquisition or declared derivation is needed; not yet attempted | Step 5 consumes this; must not remain afterward | |
| 32 | | **Failed** | The latest automatic acquisition attempt failed; this is retryable and non-terminal | Step 5 reruns the owning manifest or explicitly resolves the row to `Needs-Manual`; Executor must never treat `Failed` as usable content | |
| 33 | | **Needs-Selection** | Web search produced one bounded thumbnail-only candidate page; no original or provenance exists yet | Step 5 reviews/promotes one candidate, advances to `next_candidate_page`, or after pool exhaustion materially changes the query and returns the row to `Pending`; Executor must never consume this intermediate state | |
| 34 | | **Generated** | AI/slice output exists | Reference from `../images/`; manifest records govern attribution. An `Illustration Sheet` stays in §VIII only as an unplaced slice source | |
| 35 | | **Sourced** | Web-sourced file exists at expected path | Reference from `../images/`; check `image_sources.json` for `license_tier` — if `attribution-required`, render an inline credit element on the slide (see [`executor-web-image.md`](./executor-web-image.md) §1 and [`image-searcher.md`](./image-searcher.md) §7 for the attribution contract) | |
| 36 | | **Needs-Manual** | The owning source path requires manual fulfillment; for `slice`, the parent sheet is unavailable | Default Generate may use a dashed placeholder until its readiness gate. Quick Generate blocks every required row still in this status, even if an unverified candidate file exists; validate a supplied replacement and reconcile it to `Existing`, `Generated`, or `Sourced` first. Quick automated AI exhaustion never creates this status: [`image-generator.md`](./image-generator.md) §7 removes the affected AI/dependent-slice jobs through its declared no-AI replan. For a retained manual `slice`, supply the parent sheet and rerun `slice_images.py`; do not hand-place individual element files. | |
| 37 | | **Existing** | User already has image (`Acquire Via: user`) | Place in `images/`, reference with `<image>` | |
| 38 | | **Placeholder** | Intentionally not prepared yet (`Acquire Via: placeholder`) | Dashed border placeholder; replace later | |
| 39 | |
| 40 | --- |
| 41 | |
| 42 | ## Workflow |
| 43 | |
| 44 | ``` |
| 45 | 1. Resolve image needs: |
| 46 | - Default Generate → Strategist-owned resource list + lock projection |
| 47 | - Quick Generate → current main agent resolves the required resource in active context; explicit user paths/URLs/choices win, unspecified choices use automatic resolution, no interaction or persisted roster |
| 48 | 2. Prepare project-local resources before SVG authoring: |
| 49 | - user → materialize the explicit source under project/images/ → Existing |
| 50 | - Pending prepared derivative → follow [`image-base.md`](./image-base.md) §3 before ordinary `Acquire Via` dispatch |
| 51 | - Pending / Failed + ai → Image_Generator executes the selected path → Generated, Default recovery decision, or Quick no-AI replan |
| 52 | - Pending / Failed + web + vision → Image_Searcher saves at most 8 ranked previews → Needs-Selection → promote one original or fetch the next page → Sourced / Needs-Manual |
| 53 | - Pending / Failed + web without vision → Image_Searcher accepts only a strict metadata-ranked best-only candidate and records that method → Sourced or Needs-Manual |
| 54 | - Pending + slice → after parent AI sheet is Generated, slice_images.py cuts element files → Generated |
| 55 | 3. SVG authoring consumes only prepared resources (Executor in Default Generate; current main agent in Quick Generate) |
| 56 | ├── Existing / Generated → <image href="../images/xxx.png" .../> |
| 57 | ├── Sourced + license_tier=no-attribution → <image href=...> only |
| 58 | ├── Sourced + license_tier=attribution-required → <image href=...> + small <text> credit element on the slide |
| 59 | ├── Sourced + license_tier=manual → <image href=...> only (user-supplied --from-url; rights/credit are user responsibility) |
| 60 | └── Placeholder / Needs-Manual → Dashed border + description text until a supplied file is validated and status is reconciled |
| 61 | 4. Preview: python3 -m http.server -d <project_path> 8000 → /svg_output/<filename>.svg |
| 62 | 5. Export: |
| 63 | - Default Generate → follow [`generate-pptx.md`](../workflows/generate-pptx.md) Step 7 |
| 64 | - Quick Generate → after every required resource has a validated expected file/provenance and usable status, run the profile's final checker, then its `--quick-generate` export |
| 65 | ``` |
| 66 | |
| 67 | > Keep external references in `svg_output/` during generation. Default Generate uses `finalize_svg.py` to embed images into the mandatory `svg_final/` visual preview. Quick Generate omits that preview artifact. Both native PPTX exports independently read image references from `svg_output/`. |
| 68 | |
| 69 | **Hard rule — export boundary**: `svg_final/` is a self-contained SVG preview for embeddable raster/SVG assets and may be manually inserted into PowerPoint as an SVG picture. EMF/WMF assets retain the documented external-reference exception for lossless native passthrough. The only supported generated-PPTX route is `svg_output/` through the project SVG-to-DrawingML converter. PowerPoint's manual Convert-to-Shape operation is unsupported. |
| 70 | |
| 71 | --- |
| 72 | |
| 73 | ## External Reference vs Base64 Embedding |
| 74 | |
| 75 | | Method | Pros | Cons | Suitable For | |
| 76 | |--------|------|------|-------------| |
| 77 | | **External reference** | Small file size, fast iteration, easy to replace | Preview requires HTTP server from project root | `svg_output/` development phase | |
| 78 | | **Base64 embedding** | Self-contained file, stable direct preview / SVG-picture insertion | Large file size | `svg_final/` preview phase | |
| 79 | |
| 80 | --- |
| 81 | |
| 82 | ## Method 1: External Reference (Recommended for Generation Phase) |
| 83 | |
| 84 | ### Syntax |
| 85 | |
| 86 | ```xml |
| 87 | <image href="../images/image.png" x="0" y="0" width="1280" height="720" |
| 88 | preserveAspectRatio="xMidYMid slice"/> |
| 89 | ``` |
| 90 | |
| 91 | ### Key Attributes |
| 92 | |
| 93 | | Attribute | Description | Example | |
| 94 | |-----------|-------------|---------| |
| 95 | | `href` | Image path (relative or absolute) | `"../images/cover.png"` | |
| 96 | | `x`, `y` | Image top-left corner position | `x="0" y="0"` | |
| 97 | | `width`, `height` | Image display dimensions | `width="1280" height="720"` | |
| 98 | | `preserveAspectRatio` | Scaling mode | `"xMidYMid slice"` | |
| 99 | |
| 100 | ### preserveAspectRatio Common Values |
| 101 | |
| 102 | | Value | Effect | |
| 103 | |-------|--------| |
| 104 | | `xMidYMid slice` | Center crop (similar to CSS `cover`) | |
| 105 | | `xMidYMid meet` | Complete display (similar to CSS `contain`) | |
| 106 | | `none` | Stretch to fill, no aspect ratio preservation | |
| 107 | |
| 108 | ### Preview Method |
| 109 | |
| 110 | Browser security blocks external images on directly opened SVGs. Serve via HTTP from the project root: |
| 111 | |
| 112 | ```bash |
| 113 | python3 -m http.server -d <project_path> 8000 |
| 114 | # Visit http://localhost:8000/svg_output/your_file.svg |
| 115 | ``` |
| 116 | |
| 117 | --- |
| 118 | |
| 119 | ## Method 2: Base64 Embedding (Recommended for Preview Phase) |
| 120 | |
| 121 | ### Syntax |
| 122 | |
| 123 | ```xml |
| 124 | <image href="data:image/png;base64,iVBORw0KGgo..." x="0" y="0" width="1280" height="720"/> |
| 125 | ``` |
| 126 | |
| 127 | ### MIME Types |
| 128 | |
| 129 | | MIME Type | File Format | |
| 130 | |-----------|-------------| |
| 131 | | `image/png` | PNG | |
| 132 | | `image/jpeg` | JPG/JPEG | |
| 133 | | `image/gif` | GIF | |
| 134 | | `image/webp` | WebP | |
| 135 | | `image/svg+xml` | SVG | |
| 136 | |
| 137 | --- |
| 138 | |
| 139 | ## Conversion Process |
| 140 | |
| 141 | Default Generate follows [`generate-pptx.md`](../workflows/generate-pptx.md) |
| 142 | Step 7; it owns the serial post-processing and export commands. Quick Generate |
| 143 | follows [`quick-generate.md`](../workflows/profiles/quick-generate.md) after its |
| 144 | required-resource gate. The native PPTX converter reads `svg_output/` and maps |
| 145 | its project-local image references directly to DrawingML in both modes. |
| 146 | |
| 147 | ### Standalone: align_embed_images.py (advanced) |
| 148 | |
| 149 | For processing specific SVGs without the full pipeline: |
| 150 | |
| 151 | ```bash |
| 152 | python3 scripts/svg_finalize/align_embed_images.py <svg_file> |
| 153 | python3 scripts/svg_finalize/align_embed_images.py --dry-run <svg_file> |
| 154 | ``` |
| 155 | |
| 156 | Use `finalize_svg.py --only align-images` for project-level batches. The old |
| 157 | `crop-images`, `fix-aspect`, and `embed-images` step names are compatibility |
| 158 | aliases only when invoked through `finalize_svg.py --only`. |
| 159 | |
| 160 | --- |
| 161 | |
| 162 | ## Best Practices |
| 163 | |
| 164 | ### Native PPTX Image Export |
| 165 | |
| 166 | **Default — preserve unmodified image bytes**: `svg_to_pptx.py` uses `--image-sizing cap`. It keeps original bytes when an image needs neither resizing nor EXIF geometry normalization, and re-encodes only images that require one of those transformations. Use the explicit compact command only when a compact export is requested. |
| 167 | |
| 168 | | Need | Command | |
| 169 | |---|---| |
| 170 | | Normal native export | `python3 scripts/svg_to_pptx.py <project_path>` | |
| 171 | | Explicit compact export | `python3 scripts/svg_to_pptx.py <project_path> --image-sizing display --image-scale 2 --image-quality 85` | |
| 172 | | Force original bytes | `python3 scripts/svg_to_pptx.py <project_path> --no-image-optimize` | |
| 173 | |
| 174 | ### File Organization |
| 175 | |
| 176 | ``` |
| 177 | project/ |
| 178 | ├── images/ # Image assets |
| 179 | ├── sources/ # Source files and their accompanying images |
| 180 | │ └── article_files/ |
| 181 | ├── svg_output/ # Raw version (external references) |
| 182 | └── svg_final/ # Derived self-contained visual preview (images embedded) |
| 183 | ``` |
| 184 | |
| 185 | ### Rounded Corner / Non-rectangular Image Cropping |
| 186 | |
| 187 | `clipPath` **on `<image>` elements** is conditionally allowed — authoritative constraints in [`shared-standards-core.md`](./shared-standards-core.md) §1.2; do not restate or relax here. |
| 188 | |
| 189 | Fallback when `clipPath` doesn't fit: bake rounded corners into the source image (PNG with alpha) before embedding. |
| 190 | |
| 191 | --- |
| 192 | |
| 193 | ## FAQ |
| 194 | |
| 195 | **Q: Can't see images when opening SVG directly?** |
| 196 | Browser security blocks cross-directory requests. Serve via HTTP from project root, or run `finalize_svg.py` first and view from `svg_final/`. |
| 197 | |
| 198 | **Q: Base64 file too large?** |
| 199 | Compress the source, use JPEG, reduce resolution to match actual display dimensions. |
| 200 | |
| 201 | **Q: How to reverse-extract a Base64 image?** |
| 202 | ```bash |
| 203 | base64 -d image.b64 > image.png |
| 204 | ``` |
| 205 |