amos689/academic-figure-generator-openai

Academic Figure Generator OpenAI Edition · Research Figure Workbench From source passages to visual drafts and editable diagrams. English · 简体中文

See it in action · Quick start · Workflow · Configuration · Codex skills

A local-first, bilingual workspace for research figures. Import a paper, choose its source sections, review an English drawing prompt, and generate or edit an image. For supported framework diagrams, inspect the source-linked FigureSpec and export real editable SVG, draw.io, or vector PDF.

See It in Action

A published paper becomes a 4800 × 1920 pastel method figure. This example reads Section 3 of Masked Autoencoders Are Scalable Vision Learners (He et al., CVPR 2022) and visualizes its asymmetric encoder-decoder: 75% masking, visible-only encoding, mask-token insertion, and reconstruction loss on missing patches.

1. Read the paper. Upload the official PDF, select 3. Approach, and choose Pastel, Quality, and the ML TopConf (Seaborn Deep) palette.
2. Shape the drawing prompt. gpt-6-astra with max reasoning connects the method to concrete image patches, labeled features, and explicit supervision paths.
3. Generate the figure. gpt-image-2.5-sunburst renders the reviewed prompt at maximum quality, 16:9, 4K.
4. Finish the layout. The example’s local composition script arranges the artwork on a wider 5:2 canvas with aligned modules and precise connections.

View the full-resolution PNG · Read the paper · Read the full prompt · Settings and usage

The walkthrough includes the exact generation request, both prompt stages, method notes, and the semantic graph. Follow the same bicycle image through the diagram: its patches carry the explanation, not decorative icons.

Why This Workbench

The interface supports English and Chinese, with English as the default. No account, external database, Redis, or separate worker service is required.

Quick Start

Requirements: Python 3.12+, uv, Node.js 24 LTS with npm, and an OpenAI API key with access to the configured models. The commands below target macOS/Linux. Install uv using its official instructions.

git clone https://github.com/amos689/Academic-Figure-Generator-OpenAI.git
cd Academic-Figure-Generator-OpenAI

1. Start the Backend

Set the key in the terminal that starts the backend. An already-exported system key is sufficient; there is no need to put it in the code.

export OPENAI_API_KEY="your-openai-api-key"
cd backend
uv sync --locked
uv run --locked uvicorn app.main:app --host 127.0.0.1 --port 8000

The first launch creates the SQLite schema and bundled palettes. Run one web worker per database. Development --reload is optional, but a reload interrupts running jobs; avoid it during billed generation.

2. Start the Frontend

In a second terminal at the repository root:

cd frontend
npm ci
npm run dev -- --host localhost --port 5173

Open localhost:5173. The development server proxies /api to port 8000. API documentation is available at localhost:8000/docs when DEBUG=true.

Workflow

1. Create a project and upload PDF, DOCX, or TXT. Wait for the parse job to finish, then select the document.
2. Choose evidence and style. Use the entire document or selected sections; choose classic/pastel, palette, figure type, and quality/draft.
3. Generate and review prompts. Inspect sources, labels, relationships, and available FigureSpec. Save edits; stale revisions are not silently overwritten.
4. Generate an image. Choose aspect ratio and 1K/2K/4K size tier. Jobs remain visible while the provider works.
5. Compare and refine. Inspect the full image, favorite/select versions, or create an edit with a reference and optional mask. Every edit keeps its parent.
6. Export a diagram. In the FigureSpec tab, review the JSON and source quotes, save changes, then export SVG/PDF/draw.io. Existing prompts without a spec can request a separate paid derivation.

Use Direct generation when you already have a drawing prompt. Use the bundled Codex skills when you only need prompt text and do not want to run the application.

Configuration

Credential priority: process environment → backend/.env → root .env → the empty placeholder in config.py. Blank keys do not hide a populated lower-priority key. Real keys must never be committed.

These are explicit defaults, not moving “latest” aliases. See the official text-model and image-model references. Existing environment overrides continue to win after upgrades. Restart the backend when settings change; Settings displays the effective values and offers an explicit, non-generative model-access check.

Quality, Cost, and Size

• Quality uses the configured effort and quality, both max by default. Draft explicitly uses medium for both. Neither profile silently changes the selected models.
• The text output limit includes reasoning and final JSON. It is a budget, not a guarantee of quality or completion. Responses requests explicitly use Standard processing (service_tier=default).
• Image size defaults to 2K. The tiers target pixel area, not a fixed width: 16:9 produces 1360×768, 2720×1536, or 3840×2160. The 4K tier is within the API limits but above the image guide’s standard-size range; review large outputs carefully. See size limits.
• Generation and editing consume your API balance. Reported tokens and duration are not an account-wide bill. Unknown usage remains unknown. Review current pricing and your usage dashboard.
• Started requests are never automatically resubmitted. A network interruption may still have incurred a charge; inspect usage before retrying. Only queued jobs can be cancelled.

All optional settings are illustrated in .env.example. Never place an API key in VITE_*: those variables are exposed to browsers.

Privacy and Upgrades

Local-first is not offline generation. Parsing, vector export, and fixture evaluation are local. Requested prompt/image operations send selected source excerpts, prompts, and any reference/mask images to the configured OpenAI endpoint.

.env, data directories, virtual environments, and local runtime files are ignored. If you override DATA_DIR or DATABASE_PATH, keep those locations outside version control too. Exports may include source quotes in SVG/draw.io metadata or PDF attachments; review them before sharing.

Single-user, localhost only. There is no authentication or tenant isolation. Host/origin checks are not a substitute for access control. Do not publish the development server through a public tunnel or expose it on a LAN.

To upgrade: stop generation, back up local data, pull the code, run uv sync --locked in backend/ and npm ci in frontend/, then restart. Alembic preserves existing records and creates a SQLite backup before an unapplied migration. Previously running jobs become interrupted, not silently re-run.

Codex Skills

The general skill and pastel skill work independently of the backend. Install them from the repository root:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R academic-figure-prompt "${CODEX_HOME:-$HOME/.codex}/skills/"
cp -R academic-figure-prompt-pastel "${CODEX_HOME:-$HOME/.codex}/skills/"

Then ask Codex:

Read this paper and generate a detailed academic figure prompt.
pastel风格论文配图
modern ML figure prompt

Skill-only use produces prompt text in the agent. It does not start this server or automatically call its image API. The backend reuses these skills as template material without depending on a Claude runtime.

Limits Worth Knowing

• Scanned/image-only papers need external OCR first. PDF extraction is heuristic; DOCX retains ordered paragraphs and tables, not page-perfect layout.
• Source-quote checks establish that a quote exists in supplied text, not that it logically supports every claim. Review generated labels, arrows, notation, and numeric content.
• FigureSpec supports bounded node/edge/group diagrams. It is not arbitrary raster-to-vector conversion, a freeform graphical editor, or an editable reconstruction of every illustration.
• Masks guide the image model and can affect unmasked regions. Image outputs may still contain routing or text errors, including at maximum settings.
• This release does not provide public multi-user hosting, distributed workers, PPTX export, or automatic aesthetic scoring.

Development

# backend/
uv sync --locked --extra dev
uv run --locked pytest -q
uv run --locked ruff check app tests

# frontend/
npm ci
npm test
npm run lint
npm run build

CI runs these offline checks without API credentials. Fixed evaluation fixtures test structure, quotes, and allowed numeric wording; they do not claim to measure aesthetic or general scientific quality.

Implementation map: backend · frontend · API contract · technical design · upgrade roadmap.

Acknowledgements

This project is developed from LigphiDonk/academic-figure-generator. We thank the original author for all contributions to the project’s design, implementation, and open-source release.

License

MIT.