# Figure-extraction agent contract

You extract the **question figures** from ONE past-paper PDF, crop each one tightly,
name it to match the database, and save it into the shared `Only Images/` folder.
You ONLY read local files and write PNGs into `Only Images/`. You do NOT touch the
database, SSH, git, or the network.

## Input
A paper folder under `docs/past year questions/<LEVEL>/<folder>/`:
- `manifest.json` — `paper.source_prefix` + `questions[]`. For each question you may see
  `n`, `image_needed` (bool), `image_options` (bool), `type_id`, `image_page` (1-based),
  `image_bbox` ([x0,y0,x1,y1] as FRACTIONS of the page, top-left origin).
- `paper.pdf` — the scanned paper.

## Which questions to crop
Crop a figure for every question where **`image_needed` is true AND `type_id` is not 0**.
Skip the rest. (`image_bbox`/`image_page` are HINTS recorded at ingestion — often right,
sometimes loose or wrong; verify visually and correct them.)

## Output naming — must match the DB exactly
`slug` = the source_prefix lowercased with every run of non-alphanumerics turned into a
single `-`, trimmed (e.g. "ACS 2022 P6 Prelim" → `acs-2022-p6-prelim`). For each cropped
question write:

    Only Images/<slug>-q<n>.png

(`<n>` is the manifest question number.) Overwrite if it exists.

## How to crop (visual, iterative)
For each target question:
1. Render its page to inspect it:
   `python _renderpage.py <folder>/paper.pdf <image_page> /tmp/pg.png`
   then Read `/tmp/pg.png` to see the page.
2. Locate the figure for question `n` — the diagram / picture / table / number line /
   shape. Use the manifest `image_bbox` as a starting estimate.
3. Crop with the shared tool (fractions of the page, 0..1):
   `python _cropone.py <folder>/paper.pdf <page> <x0> <y0> <x1> <y1> "Only Images/<slug>-q<n>.png"`
4. Read the saved PNG and check it. **Tighten** so the crop contains ONLY the figure:
   - NO question text, NO the "Qn" / number label, NO answer options, NO neighbouring
     question's content, minimal white margin.
   - If it is cut off or includes junk, adjust the fractions and re-crop until correct.
5. Move on. One PNG per target question.

## Notes
- If a question is marked `image_needed` but you genuinely cannot find any figure on the
  page (mis-tagged), skip it and list it in your summary — do not save a blank/garbage crop.
- For `image_options` questions, crop the QUESTION-STEM figure only (the per-option answer
  images are a separate pass; ignore them here).
- Keep good resolution (the tool already renders at 3x).

## Constraints
- Read ONLY local files. Write ONLY PNGs into `Only Images/`. Create nothing else.
- Do NOT touch the database, SSH, git, or any network resource.

Return a one-paragraph summary: paper, how many figures cropped, and any `image_needed`
questions you skipped because no figure was actually present.