figgydeck 1.0.0__tar.gz

figgydeck-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,61 @@
+name: publish
+
+# Build once, then publish to PyPI via Trusted Publishing (OIDC) — no API tokens.
+#   - Publishing a GitHub Release → builds and publishes to PyPI.
+#   - Manual "Run workflow"       → builds and twine-checks only (no publish),
+#                                   a safe dry run of the distribution.
+#
+# One-time setup (required before the first release): on PyPI, add a "pending"
+# Trusted Publisher for project `figgydeck`, owner `gregjoeval`, repo
+# `figgydeck`, workflow `publish.yml`, environment `pypi`; and create a GitHub
+# Environment named `pypi`.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          python -m twine check dist/*
+
+      - name: Upload dist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    # Only publish when a GitHub Release is published. Manual dispatch stops at
+    # the build job above (a distribution dry run).
+    if: github.event_name == 'release'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # OIDC token for Trusted Publishing
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

figgydeck-1.0.0/.github/workflows/tests.yml

@@ -0,0 +1,36 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install poppler
+        run: sudo apt-get update && sudo apt-get install -y poppler-utils
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,pptx]"
+
+      - name: Lint
+        run: ruff check src tests
+
+      - name: Test
+        run: pytest -v --tb=short

figgydeck-1.0.0/.gitignore

@@ -0,0 +1,47 @@
+# Build artifacts
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Python cache
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Generated outputs (never commit decks/images by default — they're per-user)
+out/
+output/
+extracted/
+*.apkg
+*.pptx
+
+# Source PDFs — don't commit copyrighted material
+*.pdf
+tests/fixtures/*.pdf
+examples/*.pdf
+
+# Editor / OS / agent tooling
+.vscode/
+.idea/
+.serena/
+.DS_Store
+*.swp
+*.swo
+
+# Notebook checkpoints
+.ipynb_checkpoints/
+
+/assets/

figgydeck-1.0.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0]
+
+First stable public release on PyPI: `pip install figgydeck`.
+
+Because this is the 1.0 line, the CLI and public Python API are now covered by
+semver. Compared to the pre-release code, the following are **breaking**:
+
+### Changed
+- CLI: the format selector `--out` is renamed to `--format` / `-f`, and is now
+  **required** — there is no default output format. Running without it exits
+  with a non-zero status and a message listing the choices.
+- CLI: the output directory now contains only the built deck(s) by default. The
+  extracted `manifest.json` and `images/` are no longer written there unless you
+  pass the new `--save-manifest` / `--save-images` flags.
+- `manifest.json` gained a schema wrapper: `{"version": 1, "entries": [...]}`
+  instead of a bare array. `figgydeck` still reads legacy bare-array manifests.
+- Public API: `build_combined_apkg` and `build_combined_pptx` now take a list of
+  `Chapter` objects (`figgydeck.Chapter`) instead of `(manifest, images_dir,
+  title)` tuples.
+
+### Fixed
+- Anki deck IDs are now derived with a stable SHA-256 digest instead of the
+  builtin `hash()` (which is salted per process), so re-running `figgydeck`
+  produces the same deck ID and re-imports no longer risk duplicate decks.
+
+### Added
+- `--save-manifest` / `--save-images` flags to opt into keeping the extraction
+  intermediates.
+- `figgydeck.Chapter` is exported from the top-level package.

figgydeck-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,76 @@
+# Contributing to figgydeck
+
+## Quick development setup
+
+```bash
+git clone https://github.com/YOUR_USERNAME/figgydeck.git
+cd figgydeck
+python -m venv .venv
+source .venv/bin/activate    # or `.venv\Scripts\activate` on Windows
+pip install -e ".[dev,pptx]"
+
+# Run tests
+pytest
+
+# Lint
+ruff check src tests
+```
+
+## Repo layout
+
+```
+figgydeck/
+├── src/figgydeck/         ← the package
+│   ├── extract.py         high-level pipeline
+│   ├── layout.py          font/geometry-based label & caption detection
+│   ├── images.py          pdfimages wrapping + table cropping
+│   ├── clean.py           caption text post-processing
+│   ├── pptx.py            .pptx builder (PowerPoint slides)
+│   ├── anki.py            .apkg builder (Anki cards)
+│   └── cli.py             argparse entry point
+├── tests/                 unit + smoke tests
+├── examples/              illustrative scripts
+└── docs/HOW_IT_WORKS.md   pipeline architecture
+```
+
+## Adding support for a new publisher's layout
+
+The font-size constants in `src/figgydeck/layout.py` are the main tunables.
+Test on a representative chapter:
+
+```python
+import pdfplumber
+with pdfplumber.open("chapter.pdf") as pdf:
+    page = pdf.pages[3]
+    fonts = {}
+    for c in page.chars:
+        key = (c["fontname"], round(c["size"], 1))
+        fonts.setdefault(key, []).append(c["text"])
+    for (name, size), sample in sorted(fonts.items(), key=lambda x: -len(x[1])):
+        preview = "".join(sample[:60])
+        print(f"  {name} {size}pt — {len(sample)} chars — {preview!r}")
+```
+
+Look for the font sizes used by:
+- The "FIGURE X.Y" label (typically bold, smaller than body)
+- The caption body text (typically slightly smaller than body)
+- The body text itself (the most common size)
+
+If the publisher uses a layout substantially different from Elsevier
+(e.g. captions to the right of figures rather than below), the geometric
+matcher in `layout.py` will need adjustment too. Open an issue with a
+sample PDF and we'll figure it out together.
+
+## Testing with copyrighted PDFs
+
+The smoke test in `tests/test_chapter1.py` requires a chapter PDF that you own
+at `tests/fixtures/sample_chapter.pdf`. This file is not committed — never commit
+copyrighted material. The test gracefully skips if the file isn't present. Place
+your own copy there to run the smoke test locally.
+
+## Pull requests
+
+- Keep changes focused. One concern per PR.
+- Add a unit test if you fix a bug.
+- Update `docs/HOW_IT_WORKS.md` if you change the extraction pipeline.
+- Run `ruff check src tests` and `pytest` before pushing.

figgydeck-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 figgydeck contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

figgydeck-1.0.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: figgydeck
+Version: 1.0.0
+Summary: Turn textbooks into study decks: extract figures, tables, and captions from chapter PDFs and package them as PowerPoint slides or Anki decks.
+Project-URL: Homepage, https://github.com/gregjoeval/figgydeck
+Project-URL: Repository, https://github.com/gregjoeval/figgydeck
+Project-URL: Issues, https://github.com/gregjoeval/figgydeck/issues
+Author: figgydeck contributors
+License: MIT
+License-File: LICENSE
+Keywords: anki,captions,figures,flashcards,pdf,powerpoint,pptx,slides,study,textbook
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Education
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.10
+Requires-Dist: genanki>=0.13
+Requires-Dist: pdfplumber>=0.10
+Requires-Dist: pillow>=9.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Provides-Extra: pptx
+Requires-Dist: python-pptx>=0.6.21; extra == 'pptx'
+Description-Content-Type: text/markdown
+
+# figgydeck
+
+[![tests](https://github.com/gregjoeval/figgydeck/actions/workflows/tests.yml/badge.svg)](https://github.com/gregjoeval/figgydeck/actions/workflows/tests.yml)
+
+> Turn textbooks into study decks. Extract figures, tables, and their captions from chapter PDFs, then package them as PowerPoint slides or Anki flashcard decks.
+
+`figgydeck` reads a chapter PDF and finds every figure and table along with its
+caption. It gives you one slide or card per figure — the image on the face, and
+the caption plus book/chapter/page metadata attached — the format you actually
+want for visual recall or lecture review.
+
+Two output formats, same extraction:
+
+- **PowerPoint** (`.pptx`) — one slide per figure/table, image centered with its
+  aspect ratio preserved and the metadata in the slide's speaker notes. Opens in
+  PowerPoint, Keynote, or Google Slides.
+- **Anki** (`.apkg`) — one card per figure/table, image on the front and the
+  caption + metadata on the back. Imports straight into Anki.
+
+## Why
+
+Manually building slides or flashcards from a 40-figure chapter takes hours. The two
+hard parts are (1) matching extracted images to their figure numbers — PDF
+stream order is often shuffled — and (2) cleaning captions of running headers
+and footnotes that bleed in. `figgydeck` does both with pure-Python signal
+processing (font sizes, spatial geometry, ruled-line detection); no LLM call
+required for the standard Elsevier textbook layout.
+
+## Install
+
+```bash
+pip install figgydeck
+```
+
+System requirements: `poppler` (for `pdftoppm` and `pdfimages`).
+
+```bash
+# macOS
+brew install poppler
+
+# Debian/Ubuntu
+sudo apt install poppler-utils
+```
+
+PowerPoint output (`--format pptx`) needs an optional extra:
+
+```bash
+pip install "figgydeck[pptx]"
+```
+
+## Usage
+
+```bash
+# One command, chapter PDF → figure deck (figures only by default)
+figgydeck chapter1.pdf \
+    --book "Example Textbook (1st ed., 2020)" \
+    --chapter "Ch. 3: Cell Structure" \
+    --format apkg \
+    --output ./out/
+
+# Output — just the deck (the extracted images are embedded inside it):
+#   out/ExampleTextbook1StEd2020_Ch3CellStructure.apkg     ← import into Anki
+```
+
+Also include table cards (extra `pdftoppm` rasterization per table):
+
+```bash
+figgydeck chapter1.pdf --book "..." --chapter "..." --tables
+```
+
+Choose your output format(s) with `--format`/`-f` (required; repeatable or
+comma-separated):
+
+```bash
+figgydeck chapter1.pdf --book "..." --chapter "..." --format apkg          # only .apkg
+figgydeck chapter1.pdf --book "..." --chapter "..." --format pptx          # only .pptx
+figgydeck chapter1.pdf --book "..." --chapter "..." --format apkg,pptx     # both
+```
+
+`--format` is required — there is no default. PowerPoint output needs the
+optional `[pptx]` extra (see [Install](#install)).
+
+### Keeping the extraction artifacts
+
+By default the output directory holds only the decks; the extracted images are
+embedded inside them. To also keep the raw intermediates, pass `--save-images`
+(writes an `images/` folder) and/or `--save-manifest` (writes `manifest.json`,
+the structured list of everything that was extracted):
+
+```bash
+figgydeck chapter1.pdf --book "..." --chapter "..." --format apkg \
+    --save-manifest --save-images
+#   out/...apkg          ← the deck
+#   out/manifest.json    ← inspect what was extracted
+#   out/images/          ← extracted figures
+```
+
+### Multiple chapters
+
+Pass more than one chapter PDF in a single command. Give one `--chapter` per PDF
+(in order), or omit `--chapter` entirely to derive each title from its filename
+(`ch01.pdf` → "Chapter 1"):
+
+```bash
+# one artifact per chapter (like running figgydeck once per PDF)
+figgydeck ch01.pdf ch02.pdf ch03.pdf --book "..." --format pptx
+
+# --combine merges every chapter into ONE artifact per format
+figgydeck ch01.pdf ch02.pdf ch03.pdf --book "..." --combine --format apkg,pptx
+#   out/<Book>_Combined.pptx   ← one deck: title slide + all figures
+#   out/<Book>_Combined.apkg   ← one Anki package, one subdeck per chapter
+```
+
+With multiple PDFs, when you keep artifacts (`--save-manifest`/`--save-images`)
+each chapter's files go in their own `out/NN_<slug>/` subdir (so identical image
+names don't collide). Slide images keep their native aspect ratio and are
+centered — nothing is stretched or cropped.
+
+## How it works
+
+For an Elsevier-format chapter, `figgydeck`:
+
+1. Extracts all embedded images via `pdfimages`
+2. Walks each PDF page with `pdfplumber`, identifying:
+   - **`FIGURE X.Y` / `TABLE X.Y` labels** by font size (~9 pt label font)
+   - **caption text** by font size (8 pt) within column-aware bounding boxes
+   - **table regions** by horizontal-rule detection
+3. Matches each label to the nearest image whose bottom edge sits just above it
+   in the same column — robust to images appearing in shuffled stream order
+4. Crops table regions from rasterized pages
+5. Cleans captions (strips running headers, decodes ligatures, de-hyphenates
+   line wraps)
+6. Builds your chosen deck(s) — `.apkg` and/or `.pptx` (optionally emitting the
+   intermediate `manifest.json` / `images/` with `--save-manifest` /
+   `--save-images`)
+
+On a well-behaved Elsevier-format chapter this reliably matches every figure to
+its caption and crops tables with their full titles.
+
+## What you get
+
+Both formats carry the same content — the figure or table image plus its
+caption and book/chapter/page metadata — laid out for the way you'll use it.
+
+**PowerPoint slides** (`.pptx`)
+
+- One slide per figure/table, image centered and scaled to fit with its aspect
+  ratio preserved (no cropping)
+- Number, title, caption, book, chapter, and page in the slide's speaker notes
+- A combined deck (`--combine`) opens with a title slide (book + chapter count)
+
+**Anki cards** (`.apkg`)
+
+- A clean two-side layout that's readable in both light and dark mode
+- **Front:** image only, with a small `Fig X.Y` tag below
+- **Back:** type label, caption, and book/chapter/page metadata
+- Stable note GUIDs based on `(book, chapter, type, number)` — re-importing
+  updates existing cards rather than duplicating them
+
+## AI assistance
+
+Built with help from [Claude Code](https://claude.com/claude-code). All code is
+human-reviewed.

figgydeck-1.0.0/README.md

@@ -0,0 +1,163 @@
+# figgydeck
+
+[![tests](https://github.com/gregjoeval/figgydeck/actions/workflows/tests.yml/badge.svg)](https://github.com/gregjoeval/figgydeck/actions/workflows/tests.yml)
+
+> Turn textbooks into study decks. Extract figures, tables, and their captions from chapter PDFs, then package them as PowerPoint slides or Anki flashcard decks.
+
+`figgydeck` reads a chapter PDF and finds every figure and table along with its
+caption. It gives you one slide or card per figure — the image on the face, and
+the caption plus book/chapter/page metadata attached — the format you actually
+want for visual recall or lecture review.
+
+Two output formats, same extraction:
+
+- **PowerPoint** (`.pptx`) — one slide per figure/table, image centered with its
+  aspect ratio preserved and the metadata in the slide's speaker notes. Opens in
+  PowerPoint, Keynote, or Google Slides.
+- **Anki** (`.apkg`) — one card per figure/table, image on the front and the
+  caption + metadata on the back. Imports straight into Anki.
+
+## Why
+
+Manually building slides or flashcards from a 40-figure chapter takes hours. The two
+hard parts are (1) matching extracted images to their figure numbers — PDF
+stream order is often shuffled — and (2) cleaning captions of running headers
+and footnotes that bleed in. `figgydeck` does both with pure-Python signal
+processing (font sizes, spatial geometry, ruled-line detection); no LLM call
+required for the standard Elsevier textbook layout.
+
+## Install
+
+```bash
+pip install figgydeck
+```
+
+System requirements: `poppler` (for `pdftoppm` and `pdfimages`).
+
+```bash
+# macOS
+brew install poppler
+
+# Debian/Ubuntu
+sudo apt install poppler-utils
+```
+
+PowerPoint output (`--format pptx`) needs an optional extra:
+
+```bash
+pip install "figgydeck[pptx]"
+```
+
+## Usage
+
+```bash
+# One command, chapter PDF → figure deck (figures only by default)
+figgydeck chapter1.pdf \
+    --book "Example Textbook (1st ed., 2020)" \
+    --chapter "Ch. 3: Cell Structure" \
+    --format apkg \
+    --output ./out/
+
+# Output — just the deck (the extracted images are embedded inside it):
+#   out/ExampleTextbook1StEd2020_Ch3CellStructure.apkg     ← import into Anki
+```
+
+Also include table cards (extra `pdftoppm` rasterization per table):
+
+```bash
+figgydeck chapter1.pdf --book "..." --chapter "..." --tables
+```
+
+Choose your output format(s) with `--format`/`-f` (required; repeatable or
+comma-separated):
+
+```bash
+figgydeck chapter1.pdf --book "..." --chapter "..." --format apkg          # only .apkg
+figgydeck chapter1.pdf --book "..." --chapter "..." --format pptx          # only .pptx
+figgydeck chapter1.pdf --book "..." --chapter "..." --format apkg,pptx     # both
+```
+
+`--format` is required — there is no default. PowerPoint output needs the
+optional `[pptx]` extra (see [Install](#install)).
+
+### Keeping the extraction artifacts
+
+By default the output directory holds only the decks; the extracted images are
+embedded inside them. To also keep the raw intermediates, pass `--save-images`
+(writes an `images/` folder) and/or `--save-manifest` (writes `manifest.json`,
+the structured list of everything that was extracted):
+
+```bash
+figgydeck chapter1.pdf --book "..." --chapter "..." --format apkg \
+    --save-manifest --save-images
+#   out/...apkg          ← the deck
+#   out/manifest.json    ← inspect what was extracted
+#   out/images/          ← extracted figures
+```
+
+### Multiple chapters
+
+Pass more than one chapter PDF in a single command. Give one `--chapter` per PDF
+(in order), or omit `--chapter` entirely to derive each title from its filename
+(`ch01.pdf` → "Chapter 1"):
+
+```bash
+# one artifact per chapter (like running figgydeck once per PDF)
+figgydeck ch01.pdf ch02.pdf ch03.pdf --book "..." --format pptx
+
+# --combine merges every chapter into ONE artifact per format
+figgydeck ch01.pdf ch02.pdf ch03.pdf --book "..." --combine --format apkg,pptx
+#   out/<Book>_Combined.pptx   ← one deck: title slide + all figures
+#   out/<Book>_Combined.apkg   ← one Anki package, one subdeck per chapter
+```
+
+With multiple PDFs, when you keep artifacts (`--save-manifest`/`--save-images`)
+each chapter's files go in their own `out/NN_<slug>/` subdir (so identical image
+names don't collide). Slide images keep their native aspect ratio and are
+centered — nothing is stretched or cropped.
+
+## How it works
+
+For an Elsevier-format chapter, `figgydeck`:
+
+1. Extracts all embedded images via `pdfimages`
+2. Walks each PDF page with `pdfplumber`, identifying:
+   - **`FIGURE X.Y` / `TABLE X.Y` labels** by font size (~9 pt label font)
+   - **caption text** by font size (8 pt) within column-aware bounding boxes
+   - **table regions** by horizontal-rule detection
+3. Matches each label to the nearest image whose bottom edge sits just above it
+   in the same column — robust to images appearing in shuffled stream order
+4. Crops table regions from rasterized pages
+5. Cleans captions (strips running headers, decodes ligatures, de-hyphenates
+   line wraps)
+6. Builds your chosen deck(s) — `.apkg` and/or `.pptx` (optionally emitting the
+   intermediate `manifest.json` / `images/` with `--save-manifest` /
+   `--save-images`)
+
+On a well-behaved Elsevier-format chapter this reliably matches every figure to
+its caption and crops tables with their full titles.
+
+## What you get
+
+Both formats carry the same content — the figure or table image plus its
+caption and book/chapter/page metadata — laid out for the way you'll use it.
+
+**PowerPoint slides** (`.pptx`)
+
+- One slide per figure/table, image centered and scaled to fit with its aspect
+  ratio preserved (no cropping)
+- Number, title, caption, book, chapter, and page in the slide's speaker notes
+- A combined deck (`--combine`) opens with a title slide (book + chapter count)
+
+**Anki cards** (`.apkg`)
+
+- A clean two-side layout that's readable in both light and dark mode
+- **Front:** image only, with a small `Fig X.Y` tag below
+- **Back:** type label, caption, and book/chapter/page metadata
+- Stable note GUIDs based on `(book, chapter, type, number)` — re-importing
+  updates existing cards rather than duplicating them
+
+## AI assistance
+
+Built with help from [Claude Code](https://claude.com/claude-code). All code is
+human-reviewed.