pptxforge 0.1.0

Generate beautiful PowerPoint decks programmatically with native 3D models, cinematic transitions, and themed layouts.

pptxforge

Generate beautiful PowerPoint decks programmatically — with native 3D models, cinematic transitions, and themed layouts.

Why pptxforge?

Most Python tools for PowerPoint focus on filling in templates. pptxforge focuses on producing beautiful decks: 10 themed designs, native embedded 3D models that PowerPoint can morph between, four cinematic transition helpers, and content-aware visual primitives that make slides look hand-designed.

Themed primitives that stay aligned	Repulsion-based label scales	Cinematic morph helpers

Install

pip install pptxforge

Python 3.10 or later. Generated .pptx files open in PowerPoint Desktop, PowerPoint Online, Keynote, and LibreOffice Impress.

Quickstart

from pptxforge import Card, CardGrid, Deck, themes

deck = Deck(theme=themes.MIDNIGHT_EXECUTIVE, title="Hello, world")

deck.add_title_slide(
    title="Hello, pptxforge",
    subtitle="Your first deck in six lines of Python",
)

deck.add_content_slide(
    title="Three things pptxforge does",
    layout=CardGrid(
        [
            Card(number="1", title="Themes", body="10 production themes, light and dark."),
            Card(number="2", title="Native 3D", body="Embed GLB models PowerPoint can morph between."),
            Card(number="3", title="Cinematic", body="Zoom, pan, reveal, and shape-transform helpers."),
        ],
        columns=3,
    ),
)

deck.save("hello-world/")

That's it. You now have hello-world/deck.pptx. Open it in PowerPoint.

A complete runnable version lives in examples/hello_world/build.py.

Features

• 10 themes — Pacific Deep, Midnight Executive, Forest Moss, Coral Energy, Slate Minimalist, Royal Plum, Monochrome Ink, Amber Editorial, Sunrise Citrus, Berry Bold.
• Native 3D models — embed GLB files, with auto-fit cameras and morph between camera angles using PowerPoint's native morph engine.
• Cinematic transitions — cinematic_zoom, prezi_canvas, number_reveal, shape_transform, plus model3d_flight for multi-waypoint camera tours.
• Visual primitives — LabeledScale (with collision-avoiding labels), CardGrid, Callout, StatRow.
• Image fetching — fetch_image("modern coffee shop") works zero-config via Wikimedia Commons; Unsplash and Pexels supported with optional API keys.
• Layout-variation validator — catches three-in-a-row identical layouts and other anti-patterns at build time.
• 3D annotations — ModelAnnotation with auto-projected leader lines that point at the right pixel from any camera angle.

Examples

The examples/ directory has runnable scripts demonstrating each feature:

Example	What it shows
hello_world/build.py	Minimal deck, no external assets
cinematic/build.py	All four cinematic helpers in one deck
cinematic_flight/build.py	5-waypoint helmet camera tour
transitions/build.py	Every transition type
fetch_image_quickstart.py	Zero-config image fetching via Wikimedia
citrem_mayonnaise/build.py	Full real-world demo with 3D molecules

Run any of them from the repo root:

python examples/hello_world/build.py

Image fetching

pptxforge.images.fetch_image("Eiffel Tower") works on first install — Wikimedia Commons is the zero-config default (no key, no signup, public-domain catalogue). For higher-quality photography:

from pptxforge.images import setup_wizard
setup_wizard("unsplash")   # opens browser, prompts for the key, takes ~3 minutes

fetch_image reads keys from the env first, then from the config file the wizard writes (%APPDATA%\pptxforge\config.toml on Windows / ~/.config/pptxforge/config.toml on POSIX). With any key set, source="auto" automatically prefers the paid source over Wikimedia.

Documentation

• SKILL.md — comprehensive usage guide with the decision tree for picking primitives. Originally written for AI coding agents; useful for humans too.
• ARCHITECTURE.md — public-API contract, module layout, data flow, extension points.
• DECISIONS.md — dated log of non-obvious technical choices and tradeoffs.

How it works

pptxforge wraps python-pptx with a higher-level API focused on visual quality. It generates standard .pptx files that any major presentation tool can open.

3D models are embedded as native PowerPoint 3D objects (not images). Morph transitions between 3D slides use PowerPoint's native morph engine, with shape pairing keyed by a16:creationId so the model interpolates smoothly across waypoints. Image fetching uses the Wikimedia Commons API by default; Unsplash and Pexels are supported with optional API keys.

Limitations

• PowerPoint Online and LibreOffice Impress render PowerPoint's native 3D differently than Desktop — Desktop is the gold target.
• Some PowerPoint features (notably easing on transitions) aren't exposed because the OOXML spec doesn't expose them.
• The library focuses on programmatic generation; it isn't an editor.
• Speaker notes are supported (notes= on every add_*_slide) but not generated automatically.

Contributing

Issues and pull requests welcome at github.com/GA16-24/pptxforge.

To set up a development checkout:

git clone https://github.com/GA16-24/pptxforge
cd pptxforge
python -m pip install -e '.[dev]'

# All four CI gates:
ruff check src tests
ruff format --check src tests
mypy
pytest -n auto

License

MIT — see LICENSE.