Skip to content
Back to search

NaturePanelForge

NaturePanelForge is a code-first workflow for turning scientific figure images and open-access Nature-family papers into panel-level, executable plotting-code reconstruction tasks.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/littlepeachs--naturepanelforge/badge.svg)](/listings/littlepeachs--naturepanelforge)

HTML

<a href="/listings/littlepeachs--naturepanelforge"><img src="/api/listings/littlepeachs--naturepanelforge/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The quick start has two simple paths:

**Mode 1. Direct Code Mode**

**Run the checked-in plotting code directly.** This is the fastest path: no Codex loop and no skill installation.

<table> <tr> <td width="50%" align="center"><b>Direct Code Mode Target</b></td> <td width="50%" align="center"><b>Direct Code Mode Reproduction</b></td> </tr> <tr> <td><img src="docs/demo/quick_start_bubble_plot/target.png" alt="Direct code mode target GO enrichment bubble plot panel" width="100%"/></td> <td><img src="docs/demo/quick_start_bubble_plot/reproduce_panel.png" alt="Direct code mode reproduced GO enrichment bubble plot panel" width="100%"/></td> </tr> </table>

One command:

bash scripts/run_quick_start_demo.sh

It rerenders the checked-in script and images:

docs/demo/quick_start_bubble_plot/reproduce_panel.py
docs/demo/quick_start_bubble_plot/reproduce_panel.png
docs/demo/quick_start_bubble_plot/reproduce_panel.pdf

**Mode 2. Install Codex Skill Mode**

**Install the bundled Code Skill, then paste the full System Prompt inside Codex.** Codex uses `codex-panel-reproduce` to read the target image, write editable Python/matplotlib code, render the reproduction image/PDF, and save review files.

<table> <tr> <td width="50%" align="center"><b>Codex Skill Mode Target</b></td> <td width="50%" align="center"><b>Codex Skill Mode Reproduction</b></td> </tr> <tr> <td><img src="docs/demo/quick_start_skill_bubble_plot/target.png" alt="Codex Skill mode target GO enrichment bubble plot panel" width="100%"/></td> <td><img src="docs/demo/quick_start_skill_bubble_plot/reproduce_panel.png" alt="Codex Skill mode reproduced GO enrichment bubble plot panel" width="100%"/></td> </tr> </table>

**Install Skill Prompt:**

Install the NaturePanelForge Codex skill for me: https://github.com/littlepeachs/NaturePanelForge

Codex will read the repository, install the bundled `codex-panel-reproduce` skill, and verify that it is available locally.

**English System Prompt:**

Please use the installed codex-panel-reproduce skill to reproduce this scientific paper panel as editable Python/matplotlib code.

Target image: docs/demo/quick_start_skill_bubble_plot/target.png
Optional PDF: docs/demo/quick_start_skill_bubble_plot/target.pdf
Output root: UserRuns/my_skill_test
Panel id: my_skill_test
Chart type: bubble_plot
Caption: A faceted GO enrichment bubble plot with Human and Mouse columns, biological process labels on the left, x axis as -log10(p.value), bubble size encoding log10(count), and colors encoding biological groups.

Requirements:
1. Use the codex-panel-reproduce skill.
2. Do not use Qwen scoring; this is a local user-supplied image.
3. Do not manually modify images; generate executable plotting code only.
4. Run the NaturePanelForge single-panel reproduction workflow.
5. Generate reproduce_panel.py, reproduce_panel.png, and reproduce_panel.pdf.
6. Generate review notes, review summary, and run log.
7. Finally report the output directory, review_passed, contract_passed, final PNG size, and rerender command.

**中文 System Prompt:**

请使用已安装的 codex-panel-reproduce skill,帮我复现这个科学论文 panel 图像为可编辑的 Python/matplotlib 代码。

目标图像:docs/demo/quick_start_skill_bubble_plot/target.png
可选 PDF:docs/demo/quick_start_skill_bubble_plot/target.pdf
输出根目录:UserRuns/my_skill_test
panel id:my_skill_test
图类型:bubble_plot
caption:A faceted GO enrichment bubble plot with Human and Mouse columns, biological process labels on the left, x axis as -log10(p.value), bubble size encoding log10(count), and colors encoding biological groups.

要求:
1. 使用 codex-panel-reproduce skill。
2. 不要使用 Qwen scoring,这是本地用户提供的图片。
3. 不要手工修改图片,只生成可执行绘图代码。
4. 运行 NaturePanelForge 的单图复现 workflow。
5. 生成 reproduce_panel.py、reproduce_panel.png、reproduce_panel.pdf。
6. 生成 review notes、review summary、run log。
7. 最后告诉我输出目录、review_passed、contract_passed、最终 PNG 尺寸和重新渲染命令。

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 520 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <h1 align="center">
  2. <img src="docs/assets/icon.png" alt="NaturePanelForge icon" width="180"><br/>
  3. NaturePanelForge
  4. </h1>
  5. <p align="center">
  6. <b>Forge Nature-level scientific panels into executable plotting code.</b><br/>
  7. Retrieve open-access papers, split full figures into reviewed panels, classify them with Qwen, and reproduce statistical panels with Codex agent loops.
  8. </p>
  9. <p align="center">
  10. <a href="https://littlepeachs.github.io/NaturePanelForge/"><img alt="Project page" src="https://img.shields.io/badge/Project%20Page-GitHub%20Pages-111827?style=flat&logo=githubpages&logoColor=white"></a>
  11. <a href="https://uu543493-83c1-74a94416.nma1.seetacloud.com:8448/"><img alt="Gallery live demo" src="https://img.shields.io/badge/Gallery-live%20demo-2563eb?style=flat&logo=googlechrome&logoColor=white"></a>
  12. <a href="#usage"><img alt="Usage four modes" src="https://img.shields.io/badge/Usage-4%20modes-0f766e?style=flat&logo=python&logoColor=white"></a>
  13. <a href="#agent-workflow"><img alt="Agent loop refine" src="https://img.shields.io/badge/Agent%20Loop-reproduce%20%2B%20refine-ea580c?style=flat&logo=openai&logoColor=white"></a>
  14. <a href="docs/intro_and_methods.md"><img alt="Method and stats" src="https://img.shields.io/badge/Method-stats%20%2B%20dataset-7c3aed?style=flat&logo=readme&logoColor=white"></a>
  15. <a href="#install-the-codex-skill"><img alt="Codex skill install" src="https://img.shields.io/badge/Codex%20Skill-installable-0891b2?style=flat&logo=gnubash&logoColor=white"></a>
  16. </p>
  17. <p align="center">
  18. <img src="docs/assets/diagram.png" alt="NaturePanelForge input-output schematic: target scientific panel and optional metadata are converted into runnable Python plotting code." width="100%">
  19. </p>
  20. <p align="center">
  21. <a href="#usage">Usage</a> |
  22. <a href="#quick-start-demo">Quick Start Demo</a> |
  23. <a href="#agent-workflow">Agent Workflow</a> |
  24. <a href="#zero-shot-benchmark">Zero-Shot Benchmark</a> |
  25. <a href="#codex-reproduction-examples">Examples</a> |
  26. <a href="#setup">Setup</a> |
  27. <a href="docs/intro_and_methods.md">Method</a> |
  28. <a href="TUTORIAL.md">Tutorial</a>
  29. </p>
  30. <p align="center">
  31. <b>English</b> | <a href="README.zh-CN.md">中文</a>
  32. </p>
  33. NaturePanelForge is a code-first workflow for turning scientific figure images and open-access Nature-family papers into panel-level, executable plotting-code reconstruction tasks. The repository does not depend on the hosted gallery demo.
  34. ![NaturePanelForge gallery walkthrough](docs/assets/show_preview.gif)
  35. [![Watch walkthrough video](docs/assets/watch_walkthrough_button.svg)](docs/assets/show_compressed.mp4)
  36. ![NaturePanelForge gallery home](docs/assets/nature_panel_forge_web1.png)
  37. ![NaturePanelForge gallery catalog](docs/assets/nature_panel_forge_web2.png)
  38. For the project introduction, methods, current dataset counts, Qwen score distributions, and Codex refine complexity distribution, see [Introduction and Methods](docs/intro_and_methods.md).
  39. ## Quick Start Demo
  40. The quick start has two simple paths:
  41. ### **Mode 1. Direct Code Mode**
  42. **Run the checked-in plotting code directly.** This is the fastest path: no Codex loop and no skill installation.
  43. <table>
  44. <tr>
  45. <td width="50%" align="center"><b>Direct Code Mode Target</b></td>
  46. <td width="50%" align="center"><b>Direct Code Mode Reproduction</b></td>
  47. </tr>
  48. <tr>
  49. <td><img src="docs/demo/quick_start_bubble_plot/target.png" alt="Direct code mode target GO enrichment bubble plot panel" width="100%"/></td>
  50. <td><img src="docs/demo/quick_start_bubble_plot/reproduce_panel.png" alt="Direct code mode reproduced GO enrichment bubble plot panel" width="100%"/></td>
  51. </tr>
  52. </table>
  53. One command:
  54. ```bash
  55. bash scripts/run_quick_start_demo.sh
  56. ```
  57. It rerenders the checked-in script and images:
  58. ```text
  59. docs/demo/quick_start_bubble_plot/reproduce_panel.py
  60. docs/demo/quick_start_bubble_plot/reproduce_panel.png
  61. docs/demo/quick_start_bubble_plot/reproduce_panel.pdf
  62. ```
  63. ### **Mode 2. Install Codex Skill Mode**
  64. **Install the bundled Code Skill, then paste the full System Prompt inside Codex.** Codex uses `codex-panel-reproduce` to read the target image, write editable Python/matplotlib code, render the reproduction image/PDF, and save review files.
  65. <table>
  66. <tr>
  67. <td width="50%" align="center"><b>Codex Skill Mode Target</b></td>
  68. <td width="50%" align="center"><b>Codex Skill Mode Reproduction</b></td>
  69. </tr>
  70. <tr>
  71. <td><img src="docs/demo/quick_start_skill_bubble_plot/target.png" alt="Codex Skill mode target GO enrichment bubble plot panel" width="100%"/></td>
  72. <td><img src="docs/demo/quick_start_skill_bubble_plot/reproduce_panel.png" alt="Codex Skill mode reproduced GO enrichment bubble plot panel" width="100%"/></td>
  73. </tr>
  74. </table>
  75. **Install Skill Prompt:**
  76. ```text
  77. Install the NaturePanelForge Codex skill for me: https://github.com/littlepeachs/NaturePanelForge
  78. ```
  79. Codex will read the repository, install the bundled `codex-panel-reproduce` skill, and verify that it is available locally.
  80. **English System Prompt:**
  81. ```text
  82. Please use the installed codex-panel-reproduce skill to reproduce this scientific paper panel as editable Python/matplotlib code.
  83. Target image: docs/demo/quick_start_skill_bubble_plot/target.png
  84. Optional PDF: docs/demo/quick_start_skill_bubble_plot/target.pdf
  85. Output root: UserRuns/my_skill_test
  86. Panel id: my_skill_test
  87. Chart type: bubble_plot
  88. Caption: A faceted GO enrichment bubble plot with Human and Mouse columns, biological process labels on the left, x axis as -log10(p.value), bubble size encoding log10(count), and colors encoding biological groups.
  89. Requirements:
  90. 1. Use the codex-panel-reproduce skill.
  91. 2. Do not use Qwen scoring; this is a local user-supplied image.
  92. 3. Do not manually modify images; generate executable plotting code only.
  93. 4. Run the NaturePanelForge single-panel reproduction workflow.
  94. 5. Generate reproduce_panel.py, reproduce_panel.png, and reproduce_panel.pdf.
  95. 6. Generate review notes, review summary, and run log.
  96. 7. Finally report the output directory, review_passed, contract_passed, final PNG size, and rerender command.
  97. ```
  98. **中文 System Prompt:**
  99. ```text
  100. 请使用已安装的 codex-panel-reproduce skill,帮我复现这个科学论文 panel 图像为可编辑的 Python/matplotlib 代码。
  101. 目标图像:docs/demo/quick_start_skill_bubble_plot/target.png
  102. 可选 PDF:docs/demo/quick_start_skill_bubble_plot/target.pdf
  103. 输出根目录:UserRuns/my_skill_test
  104. panel id:my_skill_test
  105. 图类型:bubble_plot
  106. caption:A faceted GO enrichment bubble plot with Human and Mouse columns, biological process labels on the left, x axis as -log10(p.value), bubble size encoding log10(count), and colors encoding biological groups.
  107. 要求:
  108. 1. 使用 codex-panel-reproduce skill。
  109. 2. 不要使用 Qwen scoring,这是本地用户提供的图片。
  110. 3. 不要手工修改图片,只生成可执行绘图代码。
  111. 4. 运行 NaturePanelForge 的单图复现 workflow。
  112. 5. 生成 reproduce_panel.py、reproduce_panel.png、reproduce_panel.pdf。
  113. 6. 生成 review notes、review summary、run log。
  114. 7. 最后告诉我输出目录、review_passed、contract_passed、最终 PNG 尺寸和重新渲染命令。
  115. ```
  116. The target image is the input, and the reproduction image is the expected editable-code output. For the full prompts saved as files, see [English prompt](docs/demo/quick_start_skill_bubble_plot/prompt.en.md) and [中文 prompt](docs/demo/quick_start_skill_bubble_plot/prompt.zh-CN.md).
  117. Offline rerender for the checked-in Skill Mode result:
  118. ```bash
  119. DEMO_CASE=quick_start_skill_bubble_plot bash scripts/run_quick_start_demo.sh
  120. ```
  121. To use your own data in the same visual style, edit the data arrays and labels in one of the demo `reproduce_panel.py` scripts, then rerun it. If your goal is specifically “take a reference plot style and redraw my new data in that style,” FigMirror is the more product-like path; NaturePanelForge focuses on building scientific panel-to-code benchmark examples from real papers.
  122. ## Agent Workflow
  123. NaturePanelForge uses three executable agent stages. Each stage writes machine-checkable artifacts and can be resumed.
  124. ![NaturePanelForge complete workflow](docs/assets/nature_panel_forge_overview.png)
  125. **Panel Split** converts a compound full figure into complete panel crops. A split agent writes executable crop/spec logic, and a review agent checks panel letters, axis labels, ticks, legends, colorbars, titles, annotations, and edge visibility.
  126. **Code Reproduce** turns a target panel into `reproduce_panel.py`, `reproduce_panel.png`, and `reproduce_panel.pdf`. A code-writing agent renders the plot, and a review agent compares the output against `target.png`; fixable issues trigger code edits and rerendering.
  127. **Final Refine** starts from first-pass reproductions that already passed review. A polish agent edits the existing code, while an audit agent checks Arial typography, label/tick/legend overlap, scientific symbols, edge clipping, compactness, complexity score, and caption-based description.
  128. ![Agent loops for high-fidelity panel-to-code reproduction](docs/assets/agent_loop.png)
  129. This loop is the core mechanism for high-quality panel-to-code reproduction: each stage separates execution from review, records artifacts on disk, and iterates until the panel split, executable reproduction, or final refine result passes the corresponding audit.
  130. ## Dataset Refinement
  131. NaturePanelForge uses a refined paper-to-panel-to-code workflow to build benchmark-ready scientific chart samples:
  132. ```text
  133. open-access paper figures -> reviewed panel crops -> Qwen panel scoring ->
  134. Codex code reproduction -> Final Refine -> clean-sample audit -> benchmark manifests
  135. ```
  136. The current SciFigure2Code release manifest contains 6,740 clean benchmark candidates from an 8,385-panel formal gallery. Clean samples include the original target PNG/PDF, refined reproduced PNG/PDF, editable `reproduce_panel.py`, description metadata, chart subtype, scientific domain, and complexity label.
  137. The GitHub repository keeps only the small smoke manifest under:
  138. ```text
  139. SciFigure2Code/benchmark_ready/
  140. ```
  141. Use subsets by cost:
  142. | Manifest | Use |
  143. |---|---|
  144. | `clean_tiny100.json` | checked-in quick smoke / pilot |
  145. | `clean_mini500.json` | download from the Hugging Face dataset release |
  146. | `clean_dev1000.json` | download from the Hugging Face dataset release |
  147. | `clean_samples.json` | download from the Hugging Face dataset release |
  148. For the full refinement procedure and audit criteria, see [Dataset Refinement Workflow](docs/dataset_refinement.md).
  149. ## Zero-Shot Benchmark
  150. The repository includes the zero-shot SciFigure2Code evaluator and wrappers for the fixed 11-model benchmark. The evaluator generates plotting code from a target panel image, executes the code, saves candidate PNG/PDF artifacts, and reports P0/P1/P2 metrics.
  151. Prepare the environment:
  152. ```bash
  153. cd NaturePanelForge
  154. python3 -m venv .venv
  155. source .venv/bin/activate
  156. pip install -r requirements.txt
  157. source configs/zeroshot.env.example
  158. ```
  159. Download the SciPanelForge dataset from Hugging Face:
  160. ```bash
  161. export HF_TOKEN="${HF_TOKEN:-}" # optional for public files; required for private/gated access
  162. python - <<'PY'
  163. import os
  164. from huggingface_hub import snapshot_download
  165. snapshot_download(
  166. repo_id="littlepeachs/SciPanelForge",
  167. repo_type="dataset",
  168. local_dir=".data/SciPanelForge",
  169. token=os.environ.get("HF_TOKEN") or None,
  170. )
  171. PY
  172. ```
  173. If you need the Hugging Face mirror endpoint, set `HF_ENDPOINT` before running the same code:
  174. ```bash
  175. export HF_ENDPOINT=https://hf-mirror.com
  176. export HF_TOKEN="${HF_TOKEN:-}"
  177. python - <<'PY'
  178. import os
  179. from huggingface_hub import snapshot_download
  180. snapshot_download(
  181. repo_id="littlepeachs/SciPanelForge",
  182. repo_type="dataset",
  183. local_dir=".data/SciPanelForge",
  184. token=os.environ.get("HF_TOKEN") or None,
  185. endpoint="https://hf-mirror.com",
  186. )
  187. PY
  188. ```
  189. The helper script wraps the same `snapshot_download` call and prints the detected manifests:
  190. ```bash
  191. bash scripts/download_benchmark_dataset.sh
  192. export SCIFIGURE_DATASET="${PWD}/.data/SciPanelForge/clean_tiny100.json"
  193. ```
  194. Download ChartIDE-8B:
  195. ```bash
  196. export HF_TOKEN="${HF_TOKEN:-}"
  197. export VLM_ROOT="${PWD}/.models"
  198. export VLM_MODEL_ROOT="${VLM_ROOT}/models"
  199. python - <<'PY'
  200. import os
  201. from huggingface_hub import snapshot_download
  202. snapshot_download(
  203. repo_id="Fengx1nn/CharTide-8B",
  204. repo_type="model",
  205. local_dir=".models/models/Fengx1nn/CharTide-8B",
  206. token=os.environ.get("HF_TOKEN") or None,
  207. )
  208. PY
  209. ```
  210. Mirror endpoint version:
  211. ```bash
  212. export HF_ENDPOINT=https://hf-mirror.com
  213. export HF_TOKEN="${HF_TOKEN:-}"
  214. python - <<'PY'
  215. import os
  216. from huggingface_hub import snapshot_download
  217. snapshot_download(
  218. repo_id="Fengx1nn/CharTide-8B",
  219. repo_type="model",
  220. local_dir=".models/models/Fengx1nn/CharTide-8B",
  221. token=os.environ.get("HF_TOKEN") or None,
  222. endpoint="https://hf-mirror.com",
  223. )
  224. PY
  225. ```
  226. Or use the model helper:
  227. ```bash
  228. bash scripts/download_zeroshot_models.sh chartide_8b
  229. ```
  230. List or download the fixed 11-model roster:
  231. ```bash
  232. bash scripts/download_zeroshot_models.sh --list
  233. bash scripts/download_zeroshot_models.sh chartide_8b
  234. # Or download all 11 model repositories:
  235. bash scripts/download_zeroshot_models.sh
  236. ```
  237. Run one model on `clean_tiny100`. This is the recommended single-model entry
  238. point for checking a new setup:
  239. ```bash
  240. export SCIFIGURE_DATASET="${PWD}/SciFigure2Code/benchmark_ready/clean_tiny100.json"
  241. export TRANSFORMERS_OFFLINE=1
  242. export HF_HUB_OFFLINE=1
  243. bash scripts/run_zeroshot_model.sh chartide_8b 0 100 "${SCIFIGURE_DATASET}"
  244. ```
  245. Equivalent direct Python entry:
  246. ```bash
  247. CUDA_VISIBLE_DEVICES=0 python -m SciFigure2Code.evaluation \
  248. --dataset "${SCIFIGURE_DATASET}" \
  249. --model-id chartide_8b \
  250. --benchmark-mode zeroshot \
  251. --prompt-style short \
  252. --limit 100 \
  253. --max-new-tokens 2048 \
  254. --gpus 0 \
  255. --resume \
  256. --output-dir BenchmarkRuns/chartide_8b_zeroshot_100
  257. ```
  258. Run all 11 models:
  259. ```bash
  260. export GPU_IDS=0
  261. export LIMIT=100
  262. bash scripts/run_zeroshot_11models.sh
  263. ```
  264. For multi-GPU launch:
  265. ```bash
  266. export GPU_IDS=0,1,2,3
  267. export RUN_PARALLEL=1
  268. bash scripts/run_zeroshot_11models.sh
  269. ```
  270. Current `clean_tiny100` zero-shot smoke result:
  271. | Group | Model | Valid | Visual | Type | Layout | Data | Text | Axis | Clarity | Avg. Score |
  272. |---|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
  273. | General VLM | Intern-S2-Preview | 84.00 | 47.51 | 64.24 | 45.83 | 47.51 | 47.51 | 47.38 | 42.76 | 51.99 |
  274. | General VLM | GLM-4.5V | 81.00 | 44.68 | 63.73 | 43.23 | 44.68 | 44.68 | 44.70 | 40.21 | 49.48 |
  275. | General VLM | LLaVA-OneVision-72B | 79.00 | 41.43 | 55.24 | 40.43 | 41.43 | 41.43 | 41.01 | 37.29 | 45.87 |
  276. | General VLM | Ovis2-6-80B-A3B | 71.00 | 38.85 | 53.96 | 37.51 | 38.85 | 38.85 | 39.06 | 34.96 | 42.96 |
  277. | General VLM | Phi-4-Reasoning-Vision-15B | 71.00 | 37.47 | 50.76 | 36.80 | 37.47 | 37.47 | 37.89 | 33.72 | 41.73 |
  278. | General VLM | Molmo-72B | 68.00 | 33.90 | 47.95 | 33.29 | 33.90 | 33.90 | 34.55 | 30.51 | 38.38 |
  279. | General VLM | Qwen3.5-122B-A10B | 66.00 | 38.06 | 50.68 | 37.23 | 38.06 | 38.06 | 38.06 | 34.26 | 41.57 |
  280. | General VLM | Gemma-4-31B-IT | 58.00 | 35.38 | 45.15 | 33.81 | 35.38 | 35.38 | 35.16 | 31.84 | 37.91 |
  281. | General VLM | Pixtral-12B | 32.00 | 16.69 | 22.25 | 16.19 | 16.69 | 16.69 | 16.60 | 15.02 | 18.49 |
  282. | Finetuned ChartVLM | ChartCoder | 54.00 | 28.64 | 40.75 | 27.65 | 28.64 | 28.64 | 28.80 | 25.77 | 31.93 |
  283. | Finetuned ChartVLM | ChartIDE-8B | 82.00 | 48.30 | 62.22 | 46.63 | 48.30 | 48.30 | 48.38 | 43.47 | 52.26 |
  284. `Avg. Score` is the mean of available P0 core metrics after execution gating. Full instructions, model paths, metric definitions, dry-run commands, and summary commands are in [Zero-Shot SciFigure2Code Benchmark](docs/zeroshot_benchmark.md). The CSV copy is [zeroshot_11models_clean_tiny100.csv](docs/assets/benchmark/zeroshot_11models_clean_tiny100.csv).
  285. ## Codex Reproduction Examples
  286. Target panels from real paper figures are shown beside Codex-rendered outputs. Each reproduction is generated from executable plotting code, not manual image editing.
  287. ![Target panels beside Codex reproductions](docs/assets/reproduction_examples/codex_reproduction_pairs.png)
  288. ## Usage
  289. Use `forge.py` for the four public workflows. Each mode can be started with one command.
  290. 1. **Single cropped panel image -> plotting code**
  291. ```bash
  292. python3 forge.py single-panel-image --image /path/to/target_panel.png --panel-id demo_panel --chart-type bar --caption "A grouped bar chart with error bars and a legend." --out-root UserRuns/panel_demo --model gpt-5.4 --reasoning-effort medium --review-rounds 4 --skip-existing
  293. ```
  294. 2. **Single full figure image -> reviewed panel crops**
  295. ```bash
  296. python3 forge.py single-full-image --image /path/to/full_figure.png --paper-id demo_paper --caption "A complete multi-panel scientific figure." --out-root UserRuns/full_demo --model gpt-5.4 --reasoning-effort medium --review-rounds 4 --skip-existing
  297. ```
  298. 3. **Single paper -> paper metadata and full figures**
  299. ```bash
  300. python3 forge.py single-paper --doi 10.1038/s41467-025-12345-6 --subject biology --topic AI_biology --figures-per-paper 5 --download-only
  301. ```
  302. 4. **Batched papers -> full paper-to-panel-to-code workflow**
  303. ```bash
  304. python3 forge.py batched-paper --subject materials --topic AI_materials --target-papers 20 --batch-size 20 --figures-per-paper 5 --years 2024,2025,2026 --codex-model gpt-5.4 --codex-jobs 8
  305. ```
  306. The repository root intentionally keeps only one Python entry point, `forge.py`. Internal pipeline modules live under `nature_panel_forge/`, while stage wrappers live under `scripts/`.
  307. `single-panel-image` is the direct user-facing image-to-code path. A live run returns:
  308. ```text
  309. target.png
  310. metadata.json
  311. qwen_score.json
  312. reproduce_panel.py
  313. reproduce_panel.png
  314. reproduce_panel.pdf
  315. user_reproduce_summary.json
  316. result.json
  317. ```
  318. `user_reproduce_summary.json` and `result.json` include the generated code text, output paths, review status, missing-output checks, and whether the live contract passed. Dry-runs intentionally set `live_contract_checked=false` and `contract_passed=false`.
  319. ## Setup
  320. ```bash
  321. cd NaturePanelForge
  322. python3 -m venv .venv
  323. source .venv/bin/activate
  324. pip install -r requirements.txt
  325. cp configs/demo.env.example .env
  326. source .env
  327. ```
  328. Required external pieces:
  329. - network access for paper and figure download
  330. - Codex CLI for panel splitting, reproduction, and refine
  331. - local Qwen vision model for panel classification/scoring
  332. Check Codex:
  333. ```bash
  334. codex --version
  335. ```
  336. Set Qwen:
  337. ```bash
  338. export QWEN_MODEL_PATH=/path/to/Qwen3.6-27B
  339. export CUDA_VISIBLE_DEVICES=0
  340. ```
  341. The default Qwen path is local `transformers` loading through `--qwen-backend transformers`. `--qwen-backend openai` is only an optional compatibility hook for users who intentionally run an OpenAI-compatible vision endpoint.
  342. ## Install The Codex Skill
  343. The easiest way is to let Codex install it from this GitHub repository. Already inside Codex? Paste this prompt:
  344. **Install Skill Prompt:**
  345. ```text
  346. Install the NaturePanelForge Codex skill for me: https://github.com/littlepeachs/NaturePanelForge
  347. ```
  348. Codex should clone or open the repository, install `skills/codex-panel-reproduce/SKILL.md` into the local Codex skills directory, and verify that this file exists:
  349. ```text
  350. ${CODEX_HOME:-$HOME/.codex}/skills/codex-panel-reproduce/SKILL.md
  351. ```
  352. After installation, use the full English or Chinese System Prompt shown in Quick Start Mode 2.
  353. Local Codex can then follow the single-panel reproduction/refine workflow without re-learning the prompt structure from scratch.
  354. ## Repository Layout
  355. ```text
  356. forge.py # single public Python CLI entry point
  357. nature_panel_forge/ # internal paper, figure, export, refine, and image-to-code modules
  358. agent_loop/ # Codex panel splitting, manifest building, Qwen scoring
  359. SciFigure2Code/evaluation/ # zero-shot chart-to-code evaluator and P0/P1/P2 metrics
  360. SciFigure2Code/benchmark_ready/ # clean benchmark manifests and release statistics
  361. examples/ # Codex reproduction and final-refine batch drivers
  362. scripts/ # portable stage wrappers and skill installer
  363. gallery/ # static gallery shell and catalog builder
  364. skills/ # local Codex skill packages
  365. configs/ # environment templates
  366. docs/ # architecture, methods, and visual assets
  367. prompts/ # agent prompt blueprints
  368. ```
  369. Generated run directories look like:
  370. ```text
  371. PipelineRuns/<subject>/<topic>/run_YYYYMMDD_HHMMSS_batch001/
  372. Papers/
  373. FullFigures/full_figures.csv
  374. Panels_codex_full/
  375. PanelReviews_codex_full/
  376. QwenPanelScore/
  377. Final_Schematic/
  378. Reproduce_Statistical/
  379. Reproduce_Statistical_Reviews/
  380. Reproduce_Statistical_Refined/
  381. ```
  382. ## More Documentation
  383. - [Tutorial](TUTORIAL.md)
  384. - [Architecture](docs/architecture.md)
  385. - [Introduction and Methods](docs/intro_and_methods.md)
  386. - [Dataset Refinement Workflow](docs/dataset_refinement.md)
  387. - [Zero-Shot SciFigure2Code Benchmark](docs/zeroshot_benchmark.md)
  388. ## Citation
  389. If you use this workflow in a paper or benchmark, cite the project repository and describe the exact paper sources, model versions, scoring thresholds, and Codex review-round settings used in your run.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.