convez.ai
SkillDesenvolvimento WebAvançado
MaoranSun

Paper to Storyboard

MaoranSun/paper-to-storyboard

Transforma PDFs acadêmicos em storyboards visuais interativos

Ver no GitHub
InicialPluginScore · de 0 a 100

Converte artigos acadêmicos em PDF para websites interativos de scroll único, com narrativa visual, figuras extraídas e capa gerada por IA. Mapeia o conteúdo do paper em um arco narrativo de 9 slots, gerando HTML/CSS/JS prontos para servir como site estático.

Instalação

$npx convez-ai MaoranSun/paper-to-storyboard

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
6
Forks
2
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Criar apresentações visuais de pesquisas acadêmicas
  • Gerar websites interativos para divulgação científica
  • Documentar metodologias de papers em formato scrollytelling

Veredito

Ferramenta sofisticada que combina extração de PDFs, processamento de imagens e geração de narrativa com IA. Requer Opus para resultados de qualidade e demanda compreensão técnica tanto de Python quanto do pipeline completo, mas entrega artefatos web profissionais e reutilizáveis.

README

A tradução para o português deste README ainda está na fila.

paper-to-storyboard

A Claude Code skill that turns an academic paper PDF into a single-page scroll-snap website — a "storyboard" of the paper's argument, with extracted figures, a generated cover image, and a fixed editorial chassis you can re-skin per paper.

Title slot of the SCS example — Sun & Bardhan 2024, rendered with cool / light / modern style

Above: title slot of examples/SCS_storyboard/ — Sun & Bardhan 2024 "Identifying Hard-to-Decarbonize houses", rendered with cool / light / modern and an AI-generated cover.

academic PDF  ─►  content.json + figureN.png  ─►  Claude composes storyboard.json  ─►  index.html + style.css + script.js

What it does

  • Extracts the paper's text structure (sections, abstract, DOI, candidate stats, and ruled data tables) with pdfplumber. Tables tagged chart_ready can feed an interactive chart slot with ground-truth values.
  • Pulls embedded figures via PyMuPDF, falls back to page-region crops for composite figures.
  • Removes figure backgrounds (corner flood-fill, or rembg for photos) so they blend into the page.
  • Optionally generates a stylized data-art cover via OpenAI gpt-image-1.
  • Maps the paper onto a 7–9 slot narrative arc (title → hook → problem → method → keyFinding → dataNarrative → secondaryFinding → insight → credits) — Claude writes this from the extracted content.
  • Renders the final site through a fixed HTML/CSS/JS chassis. Only the palette, mode, typography and per-section content vary per paper.

Output

A self-contained directory you can serve as a static site:

out/
├── index.html        # scroll-snap, IntersectionObserver-driven theme switching
├── style.css         # palette + mode + typography injected via CSS variables
├── script.js         # vanilla JS, no framework
├── cover.png         # optional AI-generated title cover
├── figure1.png …     # transparent PNGs from the paper
├── content.json      # raw text extraction
├── figures/          # raw figure extraction + captions
└── storyboard.json   # the editable narrative — re-render after edits

Browseable example outputs live under examples/ — each subdirectory is a self-contained static site (index.html + style.css + script.js + transparent figures + optional cover).

Install

Clone, install Python deps, and install the skill into Claude Code:

git clone https://github.com/MaoranSun/paper-to-storyboard.git
cd paper-to-storyboard

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

./install.sh          # copies ./skill/ to ~/.claude/skills/paper-to-storyboard/
# or
./install.sh --symlink   # live-edits go straight to Claude Code

Then in Claude Code: convert /path/to/paper.pdf to a storyboard.

Run this skill on a strong model (Opus). The hard part isn't the scripts — it's the judgement: mapping a paper onto the 9-slot narrative arc, rewriting body copy to fit display type, picking layouts and a palette, and composing the cover concept. Weaker models (e.g. Sonnet) tend to produce flat narratives, mis-assigned layouts, and verbatim-dumped paragraphs. Switch with /model opus before invoking.

The skill's SKILL.md tells Claude the pipeline to run; you should rarely need to invoke scripts manually.

Style options

KnobValues
palettewarm (heat/energy) · cool (water/climate) · earth (biology/ecology) · clinical (medicine) · tech (CS/AI)
modedark (default, animated gradient + noise) · light (inverted, muted)
typographyeditorial (Playfair + Inter) · modern (Space Grotesk + Inter) · tech (JetBrains Mono + Inter) · academic (Crimson Pro + Source Sans)
layoutstitle, split, split_reverse, split_no_image, stacked, quote, impact, impact_single, stats_grid, chart, comparison, insight, credits

Each section in storyboard.json declares its own layout and theme, so the same chassis can mix big-number panels, pull-quotes, two-column comparisons and side-by-side figure layouts in one page.

Manual usage (without Claude Code)

You can run the pipeline yourself:

PY=.venv/bin/python3
SKILL=./skill
PDF=/path/to/paper.pdf
OUT=./out

$PY $SKILL/scripts/extract_text.py    $PDF $OUT/content.json
$PY $SKILL/scripts/extract_figures.py $PDF $OUT/figures/
for f in $OUT/figures/figure*.png; do
  $PY $SKILL/scripts/make_transparent.py "$f" "$OUT/$(basename "$f")"
done

# Optional cover (requires OPENAI_API_KEY)
$PY $SKILL/scripts/generate_cover.py --concept "..." --palette cool --mode dark --out $OUT/cover.png

# Hand-author $OUT/storyboard.json against skill/schemas/storyboard.schema.json
# (or copy skill/examples/reference_storyboard.json and edit)

$PY $SKILL/scripts/render.py --storyboard $OUT/storyboard.json --palette cool --mode dark --typography academic --out $OUT
$PY $SKILL/scripts/preview.py $OUT 8765

Repo layout

paper-to-storyboard/
├── skill/
│   ├── SKILL.md                  # skill manifest — Claude reads this on invocation
│   ├── templates/                # HTML/CSS/JS templates with {{MUSTACHE}} placeholders
│   ├── scripts/                  # extract_text, extract_figures, make_transparent,
│   │                             # generate_cover, render, preview
│   ├── palettes/themes.json      # 5 palettes × 2 modes + 4 typography presets
│   ├── schemas/storyboard.schema.json
│   └── examples/reference_storyboard.json
├── examples/                     # self-contained rendered storyboards
│   └── <paper-shortname>/        # index.html, style.css, script.js, figures, cover
├── install.sh
├── requirements.txt
├── CLAUDE.md                     # context for Claude Code sessions in this repo
├── LICENSE                       # MIT
└── README.md

Known limitations

  • Figure background removal is imperfect. make_transparent.py uses corner flood-fill, which works well on plot figures with clean near-white backgrounds but can leave visible halos around anti-aliased lines, text edges, or in figures with non-uniform / textured backgrounds (gradients, photographs, dark plots). For these cases you'll likely want to manually clean up the figure in an external editor (Photoshop, GIMP, Affinity, magick, etc.) and drop the corrected figureN.png back into the output directory before re-running render.py. We evaluated rembg (u2net, isnet, birefnet-general) and OpenAI gpt-image-1 image-edit as alternatives — see CLAUDE.md for why flood-fill stayed the default despite the rough edges.
  • Text/figure extraction is brittle on multi-column journal layouts. pdfplumber's section heuristics sometimes fuse running headers or fragment columns; expect to inspect content.json before mapping. Embedded figures usually extract cleanly via PyMuPDF; rasterized-vector composites occasionally need a page-region crop fallback.
  • AI cover images can ignore palette/mode hints. gpt-image-1 interprets the concept loosely; if the cover doesn't fit your section's lighting, regenerate with a more constrained prompt or skip the cover entirely (the title slot has a gradient fallback).

Conventions

  • The chassis is fixed. Per-paper variation is restricted to palette + mode + typography + per-section content + cover image. Never regenerate the HTML/CSS/JS freeform; always go through render.py.
  • Body copy is rewritten for display type. Headline numbers and key definitions are lifted verbatim.
  • fullbleed is reserved for atmospheric photos. Don't use it for paper figures — scientific charts don't read well at viewport scale.
  • Figures must be transparent PNGs. They get composited onto palette-tinted backgrounds; an opaque white background ruins the effect.

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados