---
name: chapter-image-enhancer
description: Adds freely-licensed maps and photos to textbook chapters by sourcing from Wikimedia Commons and US government archives, then inserting them with captions and proper attribution.
title: chapter-image-enhancer
canonical_url: https://skilld.dev/gh/dmccreary/ibook-skills/chapter-image-enhancer
last_updated: 2026-09-28T17:12:48.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install dmccreary/ibook-skills/chapter-image-enhancer`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/chapter-image-enhancer`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/dmccreary/ibook-skills/chapter-image-enhancer) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/chapter-image-enhancer`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/chapter-image-enhancer --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/chapter-image-enhancer --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Chapter Image Enhancer

Add high-quality, freely-licensed images to intelligent textbook chapters. This skill finds relevant maps and photos from public domain and Creative Commons sources, downloads and optimizes them for web, inserts them at appropriate locations with captions, and adds proper attribution.

## When to Use

- A chapter is text-heavy and would benefit from maps, photos, or diagrams
- The user asks to "add images", "make it more visual", or "find photos for" a chapter
- A chapter covers geographic, scientific, or visual topics where images are essential
- After chapter content is generated but before final publication

## Image Source Priority

The skill uses only images compatible with CC BY-NC-SA 4.0 textbooks. Search in this order:

### Tier 1: US Government (Public Domain — No Restrictions)

US federal government works are public domain and the safest to use:

- **USDA** — hardiness zone maps, soil maps, agricultural photos
- **EPA** — ecoregion maps, environmental data visualizations
- **USGS** — topographic maps, geological surveys, satellite imagery
- **USFWS** — wildlife and habitat photos (Fish & Wildlife Service)
- **US Forest Service** — forest and wilderness photos
- **NOAA** — weather, climate, and ocean imagery
- **NASA** — Earth observation and satellite photos
- **NPS** — National Park Service landscape photos
- **Library of Congress** — historical photos and maps

### Tier 2: Wikimedia Commons (CC BY or CC BY-SA)

Wikimedia Commons hosts millions of freely-licensed educational images:

- **CC BY 2.0/3.0/4.0** — attribution required, fully compatible
- **CC BY-SA 2.0/3.0/4.0** — attribution + share-alike, compatible with CC BY-NC-SA
- **CC0 / Public Domain** — no restrictions

Avoid these licenses (incompatible with CC BY-NC-SA 4.0):

- **CC BY-ND** — No Derivatives conflicts with SA
- **All Rights Reserved** — cannot use without explicit permission
- **CC BY-NC-ND** — No Derivatives is incompatible

### Tier 3: State Government and University Sources

State works are NOT automatically public domain (unlike federal). Check terms of use individually. Many state agencies and universities grant educational use.

## Workflow

### Step 1: Analyze the Chapter

Read the chapter's `index.md` to understand:

- The chapter title and main topic
- Major H2 sections — each is a candidate for an image
- What types of images would be most helpful (maps, photos, diagrams, charts)
- The subject domain (geography, biology, history, etc.) to guide image search

Identify 3-6 insertion points where an image would add the most value. Prioritize:

1. Geographic topics → maps
2. Species or organisms → photos
3. Processes or systems → diagrams
4. Historical topics → archival photos
5. Locations or landmarks → landscape photos

### Step 2: Find Images

For each insertion point, find a suitable image.

**Using the Wikimedia API to get correct download URLs:**

The Wikimedia API reliably returns actual image URLs (direct curl/wget often fails due to hash-path issues):

```python
import urllib.request, json

title = "File:Example_Image.jpg"
api_url = f"https://en.wikipedia.org/w/api.php?action=query&titles={urllib.request.quote(title)}&prop=imageinfo&iiprop=url&iiurlwidth=1280&format=json"
req = urllib.request.Request(api_url, headers={"User-Agent": "TextbookProject/1.0 (Educational; CC-BY-NC-SA)"})
with urllib.request.urlopen(req) as resp:
    data = json.loads(resp.read())
    pages = data["query"]["pages"]
    for pid, page in pages.items():
        if "imageinfo" in page:
            url = page["imageinfo"][0].get("thumburl", page["imageinfo"][0]["url"])
```

The `iiurlwidth=1280` parameter requests a pre-scaled thumbnail — this is faster than downloading the full-resolution original and resizing locally.

**For US Government sources**, direct URLs typically work fine with curl.

**Important**: Always verify the license before downloading. On Wikimedia Commons, check the file page for the license template. For US government images, confirm they come from a federal (not state or contractor) source.

### Step 3: Download Images

Create a directory for the chapter's images:

```
docs/img/chapters/XX-chapter-name/
```

Download with Python's `urllib` (more reliable than curl for Wikimedia):

```python
import urllib.request

headers = {"User-Agent": "TextbookProject/1.0 (Educational)"}
req = urllib.request.Request(url, headers=headers)
with urllib.request.urlopen(req) as resp:
    data = resp.read()
    with open(filepath, "wb") as f:
        f.write(data)
```

Note: Wikimedia rate-limits aggressively. If you get HTTP 429, wait 5 seconds and retry. Download images sequentially, not in parallel.

### Step 4: Optimize for Web

Resize and compress images using Pillow:

```python
from PIL import Image

img = Image.open(path)
max_width = 1200

if img.width > max_width:
    ratio = max_width / img.width
    img = img.resize((max_width, int(img.height * ratio)), Image.LANCZOS)

if path.endswith('.png') and img.mode != 'RGBA':
    # Convert to JPEG for smaller file size (unless transparency needed)
    img.convert('RGB').save(path.replace('.png', '.jpg'), 'JPEG', quality=82, optimize=True)
else:
    img.save(path, optimize=True)
```

Target file sizes:

- Photos: under 500KB (JPEG quality 80-85)
- Maps: under 600KB (JPEG if no transparency, PNG if needed)
- Diagrams: under 300KB (PNG for sharp lines)

### Step 5: Insert Images into the Chapter

Place each image at the identified insertion point using standard Markdown image syntax. Include a caption in italics below the image:

```markdown
![Descriptive alt text for accessibility](../../img/chapters/XX-name/filename.jpg)
*Caption describing the image content and context. Source: Creator Name (License).*
```

**Placement rules:**

- Insert images immediately after the section heading (H2) they relate to, before the first paragraph of text
- One blank line before the image, one blank line after the caption
- The alt text should describe the image content for screen readers
- The caption should explain what the reader is looking at and credit the source

**Caption format:**

```
*[Description of what the image shows]. [Source attribution] ([License]).*
```

Examples:

```markdown
*Big Bluestem grass towering in a tallgrass prairie. Photo: Jennifer Briggs / USFWS (CC BY 2.0).*
*EPA Level III Ecoregions of Minnesota. Source: U.S. Environmental Protection Agency (public domain).*
```

### Step 6: Add Image Credits Section

Add an "Image Credits" section at the bottom of the chapter, before the "See Annotated References" link (or before "## Concepts Covered" if no references link exists):

```markdown
## Image Credits

- [Brief description]: [Creator/Organization] ([License])
- [Brief description]: [Creator/Organization] ([License])
```

This serves as a consolidated attribution block for all images in the chapter, making license compliance easy to verify.

### Step 7: Build and Verify

Run `mkdocs build` (or the project's build command) to verify:

- No broken image paths
- Images render at correct locations
- GLightbox (if installed) enables click-to-zoom
- Page load time is reasonable

## License Compatibility Quick Reference

| Source License | Compatible with CC BY-NC-SA 4.0? | Attribution Required? |
|----------------|----------------------------------|----------------------|
| Public Domain (US Gov) | Yes | No (but good practice) |
| CC0 | Yes | No |
| CC BY 2.0/3.0/4.0 | Yes | Yes |
| CC BY-SA 2.0/3.0/4.0 | Yes | Yes (SA carries through) |
| CC BY-NC 2.0/3.0/4.0 | Yes | Yes |
| CC BY-NC-SA | Yes (same license) | Yes |
| CC BY-ND | **No** | N/A |
| CC BY-NC-ND | **No** | N/A |
| All Rights Reserved | **No** | N/A |

## Common Pitfalls

1. **Wikimedia download URLs**: Never guess the hash path. Always use the Wikimedia API to get the actual URL. The hash path (`/a/ab/File.jpg`) is computed from the filename and is easy to get wrong.

2. **State government images**: Unlike federal works, state government images are NOT automatically public domain. Check each state's terms of use.

3. **Flickr uploads on Commons**: Many Wikimedia Commons photos were uploaded from Flickr. The license shown on Commons is what matters (it was verified at upload time), even if the Flickr page has since changed.

4. **Missing alt text**: Every image must have descriptive alt text for accessibility. Describe what the image shows, not just its title.

5. **Oversized images**: Always resize before committing. A 5MB photo will slow page loads significantly. Target 1200px max width and under 500KB.

6. **Portrait-oriented photos**: Very tall images (portrait orientation) can dominate the page. Consider whether a landscape crop would work better, or use CSS to constrain the height.

## Example Output

For a chapter about Minnesota ecoregions, the skill would produce:

**5 images in** `docs/img/chapters/02-ecoregions/`:

| File | Source | Size |
|------|--------|------|
| mn-ecoregion-map.png | EPA (public domain) | 583 KB |
| usda-hardiness-zones-mn.jpg | USDA-ARS (public domain) | 301 KB |
| tallgrass-prairie.jpg | USFWS via Wikimedia (CC BY 2.0) | 383 KB |
| deciduous-forest.jpg | Wikimedia Commons (CC BY-SA 2.0) | 432 KB |
| boreal-forest-bwca.jpg | US Forest Service (public domain) | 113 KB |

**5 insertions** in the chapter markdown, each with alt text, caption, and attribution.

**1 Image Credits section** at the bottom of the chapter consolidating all attributions.