| 1 | # Image Tools |
| 2 | |
| 3 | > **Design boundary**: keep provider credentials explicit, keep in-pipeline |
| 4 | > acquisition manifest-driven, and treat external image references as authoring |
| 5 | > inputs while delivery writes self-contained SVG previews and native PPTX |
| 6 | > media. |
| 7 | |
| 8 | Image tools cover formula rendering, prompt-based AI generation, web image search, image inspection, and Gemini watermark removal. |
| 9 | |
| 10 | ## `latex_render.py` |
| 11 | |
| 12 | Manifest-driven LaTeX formula renderer. Default Generate has Strategist write |
| 13 | `images/formula_manifest.json` after Typography confirmation; Quick Generate |
| 14 | has the current agent write the same resource manifest without confirmation. |
| 15 | This script renders only those declared formulas to transparent PNGs and writes |
| 16 | dimensions back into the manifest. |
| 17 | |
| 18 | ```bash |
| 19 | python3 scripts/latex_render.py <project_path> |
| 20 | python3 scripts/latex_render.py <project_path> --dry-run |
| 21 | python3 scripts/latex_render.py <project_path> --providers codecogs,quicklatex,mathpad,wikimedia |
| 22 | ``` |
| 23 | |
| 24 | Manifest shape: |
| 25 | |
| 26 | ```json |
| 27 | { |
| 28 | "providers": ["codecogs", "quicklatex", "mathpad", "wikimedia"], |
| 29 | "items": [ |
| 30 | { |
| 31 | "id": "formula_001", |
| 32 | "latex": "E = mc^2", |
| 33 | "display": "block", |
| 34 | "color": "#1D1D1F", |
| 35 | "background": "#FFFFFF", |
| 36 | "transparent": true, |
| 37 | "dpi": 300, |
| 38 | "filename": "formula_001.png" |
| 39 | } |
| 40 | ] |
| 41 | } |
| 42 | ``` |
| 43 | |
| 44 | Output files land directly under `project/images/`. Formula filenames should use a shared `formula_` prefix, e.g. `formula_001.png`. The default provider chain is `codecogs,quicklatex,mathpad,wikimedia`; each provider is tried automatically until one succeeds, and the winning provider is recorded back into the manifest. `--providers` or manifest-level `providers` may override the order, but all four are available as no-key fallbacks. Formula PNGs are transparent by default. `background` is the temporary render matte and local background-removal reference; set `transparent: false` only when an opaque final formula asset is intentional. The script does not scan `spec_lock.md` or source documents for `$...$`; formula selection belongs to the active resource owner. |
| 45 | |
| 46 | ## `image_gen.py` |
| 47 | |
| 48 | Unified image generation entry point. |
| 49 | |
| 50 | This script is the **Path A** API/proxy executor for generated images. Default |
| 51 | Generate checks `design_spec.md §I / AI Image Acquisition Path` before manifest |
| 52 | mode: only `api` / `auto` permits Path A; a missing or unknown value fails |
| 53 | closed and returns to Step 4 recovery. Quick Generate has no Design Spec: use |
| 54 | the explicit active-context path when supplied, otherwise `auto` selects the |
| 55 | A → B → C chain defined in |
| 56 | [`image-generator.md`](../../references/image-generator.md) §7 without asking. |
| 57 | In either profile, `host-native` uses the host image tool directly and `manual` |
| 58 | uses the read-only Markdown sidecar. |
| 59 | |
| 60 | ```bash |
| 61 | python3 scripts/image_gen.py "A modern futuristic workspace" |
| 62 | python3 scripts/image_gen.py "Abstract tech background" --aspect_ratio 16:9 --image_size 4K |
| 63 | python3 scripts/image_gen.py "Concept car" -o projects/demo/images |
| 64 | python3 scripts/image_gen.py --list-backends |
| 65 | ``` |
| 66 | |
| 67 | Backends are grouped into Core / Extended / Experimental tiers. Run `python3 scripts/image_gen.py --list-backends` for the current list. |
| 68 | |
| 69 | Backend selection: |
| 70 | |
| 71 | ```bash |
| 72 | python3 scripts/image_gen.py "A cat" --backend openai |
| 73 | python3 scripts/image_gen.py "A cinematic portrait" --backend minimax |
| 74 | python3 scripts/image_gen.py "A product launch hero image" --backend qwen |
| 75 | python3 scripts/image_gen.py "科技感背景图" --backend zhipu |
| 76 | python3 scripts/image_gen.py "A product KV in cinematic style" --backend volcengine |
| 77 | ``` |
| 78 | |
| 79 | Configuration sources: |
| 80 | |
| 81 | 1. Current process environment variables |
| 82 | 2. First `.env` found in this order: |
| 83 | - Current working directory |
| 84 | - Skill directory (e.g. `~/.agents/skills/ppt-master/.env`) |
| 85 | - Clone repo root |
| 86 | - `~/.ppt-master/.env` |
| 87 | |
| 88 | The active backend must always be selected explicitly via `IMAGE_BACKEND`. |
| 89 | |
| 90 | Example `.env`: |
| 91 | |
| 92 | ```env |
| 93 | IMAGE_BACKEND=openai |
| 94 | OPENAI_API_KEY=sk-xxx |
| 95 | OPENAI_MODEL=gpt-image-2 |
| 96 | # Optional proxy |
| 97 | # OPENAI_BASE_URL=http://127.0.0.1:3000/v1 |
| 98 | # OpenAI-compatible provider knobs: |
| 99 | # OPENAI_SIZE_PRESET=auto |
| 100 | # OPENAI_RESPONSE_FORMAT=auto |
| 101 | # OPENAI_QUALITY=auto |
| 102 | # Allowed values: png / jpeg / webp |
| 103 | # OPENAI_OUTPUT_FORMAT=png |
| 104 | # jpeg/webp only, 0-100 |
| 105 | # OPENAI_OUTPUT_COMPRESSION=80 |
| 106 | # gpt-image-2: auto / opaque |
| 107 | # OPENAI_BACKGROUND=auto |
| 108 | # auto / low |
| 109 | # OPENAI_MODERATION=auto |
| 110 | ``` |
| 111 | |
| 112 | Example process environment: |
| 113 | |
| 114 | ```bash |
| 115 | export IMAGE_BACKEND=openai |
| 116 | export OPENAI_API_KEY=sk-xxx |
| 117 | export OPENAI_MODEL=gpt-image-2 |
| 118 | export OPENAI_OUTPUT_FORMAT=png |
| 119 | ``` |
| 120 | |
| 121 | Current process environment wins over `.env`. |
| 122 | |
| 123 | OpenAI backend notes: |
| 124 | - `gpt-image-2` is the default OpenAI model. |
| 125 | - Requests are sent with plain `requests.post()` to improve compatibility with |
| 126 | OpenAI-compatible proxies that block the OpenAI SDK's `httpx` transport. |
| 127 | - For `gpt-image-2`, `image_size=512px` means a low-quality draft preset, not a literal 512px edge. The model requires both edges to be multiples of 16px, a long:short ratio no greater than 3:1, and total pixels between 655,360 and 8,294,400. |
| 128 | - `OPENAI_BACKGROUND=transparent` is not supported by `gpt-image-2`; use `auto` or `opaque`. |
| 129 | - If `OPENAI_OUTPUT_FORMAT=jpeg` or `webp`, generated files use `.jpg` or `.webp` extensions instead of `.png`. |
| 130 | - OpenAI-compatible providers that reject OpenAI-specific fields can use `OPENAI_RESPONSE_FORMAT=omit`, `OPENAI_QUALITY=omit`, and `OPENAI_SIZE_PRESET=<preset>`. Valid response formats are `auto`, `b64_json`, `url`, and `omit`; valid size presets are `auto`, `legacy`, `gpt-image`, `gpt-image-2`, and `dall-e-2`. |
| 131 | |
| 132 | Example `.env` for Agnes AI through the OpenAI-compatible backend: |
| 133 | |
| 134 | ```env |
| 135 | IMAGE_BACKEND=openai |
| 136 | OPENAI_API_KEY=your-agnes-key |
| 137 | OPENAI_MODEL=agnes-image-2.1-flash |
| 138 | OPENAI_BASE_URL=https://apihub.agnes-ai.com/v1 |
| 139 | OPENAI_SIZE_PRESET=gpt-image-2 |
| 140 | OPENAI_RESPONSE_FORMAT=omit |
| 141 | OPENAI_QUALITY=omit |
| 142 | ``` |
| 143 | |
| 144 | Use provider-specific keys only (e.g. `GEMINI_API_KEY`, `OPENAI_API_KEY`). See `.env.example` in clone mode or `${SKILL_DIR}/.env.example` in skill-install mode for the full list per backend. |
| 145 | |
| 146 | `IMAGE_API_KEY`, `IMAGE_MODEL`, and `IMAGE_BASE_URL` are intentionally unsupported. |
| 147 | |
| 148 | If you keep multiple providers in one `.env` or environment, `IMAGE_BACKEND` must explicitly select the active provider. |
| 149 | |
| 150 | Recommendation: |
| 151 | - Default to the Core tier for routine PPT work |
| 152 | - Use Extended only when you need a specific model style |
| 153 | - Treat Experimental backends as opt-in |
| 154 | |
| 155 | Example `.env` for MiniMax image backend: |
| 156 | |
| 157 | ```env |
| 158 | IMAGE_BACKEND=minimax |
| 159 | MINIMAX_API_KEY=your-api-key |
| 160 | # Optional: override base URL (defaults to https://api.minimaxi.com, domestic China endpoint) |
| 161 | # Use https://api.minimax.io for overseas access |
| 162 | # MINIMAX_BASE_URL=https://api.minimax.io |
| 163 | # MINIMAX_MODEL=image-01 |
| 164 | ``` |
| 165 | |
| 166 | ## `analyze_images.py` |
| 167 | |
| 168 | Analyze objective image-file facts in a project directory before writing the |
| 169 | design spec or authoring SVG. |
| 170 | |
| 171 | ```bash |
| 172 | python3 scripts/analyze_images.py <project_path>/images |
| 173 | ``` |
| 174 | |
| 175 | The tool does not resolve a canvas or recommend a left/right, top/bottom, or |
| 176 | other slide layout. Its atomic CSV records EXIF-corrected native dimensions and |
| 177 | `AspectRatio`, the objective aspect-ratio category, optional source |
| 178 | `SourceDisplayRatio`, format, actual transparent-pixel presence, usage count, |
| 179 | and bitmap/vector capability facts. An empty folder rewrites a header-only |
| 180 | report; unreadable supported files still refresh the report and produce a |
| 181 | non-zero exit. |
| 182 | |
| 183 | Use this as the default factual inventory; it does not perform semantic image |
| 184 | understanding or choose composition. Generate planning follows the Strategist's |
| 185 | context-first boundary: source context, captions / alt text / titles, filenames, |
| 186 | user notes, and existing resource records come first. Only an already-selected |
| 187 | provided/web asset whose focal-safe crop, overlay contrast, or quiet region |
| 188 | remains materially ambiguous may be inspected for that placement; this never |
| 189 | reopens selection or provenance, never bulk-opens the image folder, and never |
| 190 | restores routine readback of AI-generated images. |
| 191 | |
| 192 | ## `image_search.py` |
| 193 | |
| 194 | Zero-config web image search across openly-licensed providers. Sister tool to `image_gen.py` — used when the resource list row has `Acquire Via: web`. |
| 195 | |
| 196 | ```bash |
| 197 | python3 scripts/image_search.py "offshore wind farm" \ |
| 198 | --filename cover_bg.jpg --slide 01_cover \ |
| 199 | --orientation landscape -o projects/demo/images |
| 200 | ``` |
| 201 | |
| 202 | For multiple web rows, `--batch images/image_queries.json` searches them concurrently (modest default, `--concurrency N` / `IMAGE_SEARCH_CONCURRENCY` to tune) instead of one call per row — the web sister of `image_gen.py --manifest`. Schema and status semantics: [`image-searcher.md`](../../references/image-searcher.md) §5. |
| 203 | |
| 204 | Providers (Pexels / Pixabay are tried first when keyed; Openverse and Wikimedia are zero-config fallbacks): |
| 205 | |
| 206 | | Provider | Config | Strength | |
| 207 | |---|---|---| |
| 208 | | `pexels` | recommended: `PEXELS_API_KEY` | modern stock photography, people, workplace, lifestyle | |
| 209 | | `pixabay` | recommended: `PIXABAY_API_KEY` | broad type coverage including photos and illustrations | |
| 210 | | `openverse` | zero-config | fallback aggregator: Wikimedia + Flickr + museums + rawpixel | |
| 211 | | `wikimedia` | zero-config | educational, scientific, geographic, historical | |
| 212 | |
| 213 | Default search chain (when `--provider` is unset): configured Pexels, configured Pixabay, Openverse, then Wikimedia. Missing keyed credentials are silently skipped. Keyed providers broaden stock-photo coverage but are optional; zero-config providers remain valid. |
| 214 | |
| 215 | `image_search.py` uses the same `.env` lookup order as `image_gen.py`, so skill installs can keep `PEXELS_API_KEY` / `PIXABAY_API_KEY` in `~/.ppt-master/.env`. |
| 216 | |
| 217 | Query guidance: |
| 218 | |
| 219 | Keep the Design Spec §VIII `Reference` as the full visual/crop intent; write a separate concise provider query for this CLI. Start with the shortest phrase that preserves identity, but retain exact multi-word names and necessary disambiguators beyond four words. |
| 220 | |
| 221 | | Case | Pattern | |
| 222 | |---|---| |
| 223 | | Generic stock concept | `boardroom meeting` | |
| 224 | | China-specific landmark | Precise official place/identity name plus necessary geography | |
| 225 | | Avoid | Negative prompt wording such as `not tourist snapshot` | |
| 226 | |
| 227 | License filter: |
| 228 | |
| 229 | - **Default**: search all providers with `cc0,pdm,pexels,pixabay,cc by,cc by-sa` allowed together. The chosen image may be `no-attribution` or `attribution-required`; Executor adds an inline credit only when needed. |
| 230 | - `--strict-no-attribution` restricts the search to `cc0,pdm,pexels,pixabay` — useful for full-bleed hero images or templates that cannot host a credit element. |
| 231 | |
| 232 | Pin a provider, refuse attribution, or override the manifest path: |
| 233 | |
| 234 | ```bash |
| 235 | # Pin Wikimedia |
| 236 | python3 scripts/image_search.py "Olympics opening ceremony" \ |
| 237 | --filename event.jpg --provider wikimedia \ |
| 238 | --orientation landscape -o projects/demo/images |
| 239 | |
| 240 | # Strict mode — refuse CC BY / CC BY-SA |
| 241 | python3 scripts/image_search.py "abstract gradient" \ |
| 242 | --filename hero.jpg --strict-no-attribution \ |
| 243 | -o projects/demo/images |
| 244 | ``` |
| 245 | |
| 246 | Suitability & manual replacement (a web top hit is metadata-relevant, not guaranteed visually right): |
| 247 | |
| 248 | - By default only the best match is downloaded, plus a downscaled review copy at `images/.review/<stem>.jpg` (the placed asset stays full-resolution). |
| 249 | - For exact subjects (landmarks, people, companies, products), use `--require-terms` or batch `required_terms` so visually plausible but wrong metadata is rejected before ranking. Example: `--require-terms Chongqing --require-terms "Jiefangbei|Liberation Monument"`. Keep proper-name / geography anchors; do not broaden to generic terms like `canyon`, `stone pillar`, or `ancient town` just to improve coverage. |
| 250 | - `--save-candidates` (with `--max-candidates`, default 4) keeps an opt-in escalation pool under `candidates/<stem>/`; review it, then `--promote candidate_03.jpg --filename <name>.jpg`. |
| 251 | - `--from-url <url> --filename <name>.jpg` downloads a user-chosen image URL and replaces the target (recorded `license_tier: manual`) — the model-agnostic manual path; works even without a multimodal model. |
| 252 | |
| 253 | Full review / escalation flow: [`image-searcher.md`](../../references/image-searcher.md) §5. |
| 254 | |
| 255 | Output: |
| 256 | |
| 257 | - Image saved to the specified output directory (auto-converts webp → jpg via Pillow when the filename extension demands) |
| 258 | - `image_sources.json` manifest with full provenance (provider, license, license_tier, author, source URL, dimensions, attribution_text) |
| 259 | - Manifest is idempotent on `filename` and written atomically; damaged existing provenance blocks replacement |
| 260 | |
| 261 | Allowed licenses (default): CC0, Public Domain, Pexels License, Pixabay Content License, CC BY, CC BY-SA. Auto-rejected: CC BY-NC, CC BY-ND, CC BY-NC-SA, CC BY-NC-ND, all rights reserved, unknown. |
| 262 | |
| 263 | The full role-level reference (intent → query translation, on-slide attribution contract) is in [`references/image-searcher.md`](../../references/image-searcher.md). |
| 264 | |
| 265 | ## `gemini_watermark_remover.py` |
| 266 | |
| 267 | Remove Gemini watermark assets after manual download. |
| 268 | |
| 269 | ```bash |
| 270 | python3 scripts/gemini_watermark_remover.py <image_path> |
| 271 | python3 scripts/gemini_watermark_remover.py <image_path> -o output_path.png |
| 272 | python3 scripts/gemini_watermark_remover.py <image_path> -q |
| 273 | ``` |
| 274 | |
| 275 | Notes: |
| 276 | - Requires `scripts/assets/bg_48.png` and `scripts/assets/bg_96.png` |
| 277 | - Best used after downloading “full size” Gemini images |
| 278 | |
| 279 | Dependencies: |
| 280 | |
| 281 | ```bash |
| 282 | pip install Pillow numpy |
| 283 | ``` |
| 284 |