GeoCool PolyPress

Version française

GeoCool PolyPress is a small Python tool for generating print-ready A4 course handouts from a folder of figures and, optionally, a simple Markdown course plan.

It is designed for teaching documents that must remain readable when printed in black and white, with automatic figure placement, mirrored margins for duplex printing, headers/footers, and an optional first page containing the title, summary, keywords and session plan.

Main features

• reads PNG, JPEG, TIFF, WEBP and BMP figures;
• automatically crops white margins around figures;
• converts figures to grayscale for print-oriented output;
• estimates visual complexity to adapt figure size;
• automatically arranges figures on A4 pages;
• supports mirrored inner/outer margins for duplex printing;
• can reserve page 1 for title, summary, keywords and course schedule;
• supports dates, times and rooms for teaching sessions;
• generates JSON configuration files from a simple Markdown master file;
• produces a PDF ready for printing or reprography.

Requirements

• Python 3.10 or newer
• Pillow
• ReportLab

Installation from a Git clone

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

Check the installation:

polypress --version
polyconfig --version

Quick start

A typical course directory can look like this:

my-course/
├── cours.md
├── config/
│ └── part1/
├── source/
│ └── part1/
│ ├── 001.png
│ ├── 002.png
│ └── 003.png
└── pdf/

Generate the JSON configuration from cours.md:

polyconfig cours.md

Then generate a handout:

polypress source/part1 \
-c config/part1/config.json \
-o pdf/part1.pdf

The scripts can also be run directly without installation:

python3 polyconfig.py cours.md
python3 polypress.py source/part1 -c config/part1/config.json -o pdf/part1.pdf

Markdown course format

Example:

# part1
pages: 4
header: Introduction to Earth resources
title: Energy and geological resources
subtitle: Example course
summary: Introduction to resources, energy flows and the organization of the course.
keywords: energy ; resources ; geology
## Lecture 1
Resources and energy
date: 15 September 2026
horaire: 10:00–12:00
salle: Room 101
- Definition of a geological resource
- Energy and power
- Primary and secondary resources
## Tutorial 1
Energy balances
- Units and orders of magnitude
- Worked examples

See docs/COURSE_FORMAT.md for the complete syntax.

Commands

polypress [IMAGE_FOLDER] [-c CONFIG.json] [-o OUTPUT.pdf]
polypress IMAGE_FOLDER --create-config
polypress --version
polyconfig [COURSE.md]
polyconfig COURSE.md --part part2
polyconfig --version

Project status

GeoCool PolyPress is currently an early public release (0.1.0). The core PDF-generation workflow is already usable, but the public interface and configuration format may still evolve.

Development

Run the local checks with:

make check

The smoke test creates temporary figures, generates a PDF and verifies that the resulting file is non-empty.

License

MIT License. See LICENSE.

Website

GeoCool: https://geocool.fr