pypdfc 0.1.0__tar.gz

pypdfc-0.1.0/PKG-INFO

@@ -0,0 +1,321 @@
+Metadata-Version: 2.4
+Name: pypdfc
+Version: 0.1.0
+Summary: A command line tool for compressing PDF files
+Author: Corvin Gröning
+Keywords: pdf,compress,cli
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: img2pdf>=0.5.0
+Requires-Dist: pdf2image>=1.17.0
+Requires-Dist: Pillow>=11.0.0
+Requires-Dist: PyYAML>=6.0.0
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: rich>=14.0.0
+Requires-Dist: typer>=0.15.0
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0; extra == "dev"
+Requires-Dist: pytest-cov>=7.0; extra == "dev"
+Requires-Dist: coverage>=7.0; extra == "dev"
+
+# `pdfc` – PDF Compressor for the Command Line
+
+A command-line tool for compressing and optimising PDF files using configurable rasterization, colour mode, sharpening and contrast settings.
+
+![Python](https://img.shields.io/badge/python-3.10+-blue.svg)
+![License](https://img.shields.io/badge/license-MIT-green.svg)
+[![PyPI](https://img.shields.io/pypi/v/pdfc)](https://pypi.org/project/pdfc/)
+
+<img src="https://raw.githubusercontent.com/cgroening/py-pdfc/main/images/logo_dark.png" width="200" alt="PDF Compressor Logo">
+
+**Compressing a PDF file:**
+
+![Screenshot](https://raw.githubusercontent.com/cgroening/py-pdfc/main/images/screenshot_1_compress.png)
+
+**Interactive mode:**
+
+![Screenshot](https://raw.githubusercontent.com/cgroening/py-pdfc/main/images/screenshot_2_compress_interactive.png)
+
+**Comparing compression presets:**
+
+![Screenshot](https://raw.githubusercontent.com/cgroening/py-pdfc/main/images/screenshot_3_compare.png)
+
+## Requirements
+
+- Python 3.11+
+- [Poppler](https://poppler.freedesktop.org/) (for `pdf2image`)
+  - macOS: `brew install poppler`
+  - Ubuntu/Debian: `sudo apt install poppler-utils`
+
+## Installation
+
+```zsh
+pip install .
+```
+
+For development (includes pytest, coverage):
+
+```zsh
+pip install ".[dev]"
+```
+
+## Commands
+
+### `compress` – Compress one or more PDF files
+
+```
+pdfc compress [OPTIONS] INPUT_PATH [OUTPUT_PATH]
+```
+
+| Argument / Option | Short | Description |
+|---|---|---|
+| `--interactive` | `-i` | Collect all settings interactively via prompts |
+| `--verbose` | `-v` | Verbose output |
+| `--mode` | `-m` | Colour mode: `color`, `gray` or `bw` |
+| `--dpi` | `-d` | Resolution for rasterization in dots per inch (default: 300) |
+| `--jpeg-quality` | `-q` | JPEG quality 1–100 (default: 30). Mutually exclusive with `--png-compression-level` |
+| `--png-compression-level` | `-p` | PNG compression level 0–9 (default: 6). Mutually exclusive with `--jpeg-quality` |
+| `--threshold` | `-t` | B&W threshold 0–255 (default: 150). Only used in `bw` mode |
+| `--sharpen` | `-s` | Sharpening factor 0.0–3.0 (default: 0.0 = off) |
+| `--contrast` | `-c` | Contrast factor 0.0–3.0 (default: 1.0 = no change) |
+| `--unsharp-mask` | `-u` | Apply PIL UnsharpMask filter |
+| `--tiff-ccitt` | `-T` | Use TIFF CCITT Group 4 as intermediate format (`bw` mode only) |
+| `--no-skip` | | Process all files, including files ending with `-compressed.pdf` (which are skipped by default when input is a directory) |
+| `INPUT_PATH` | | PDF file or directory of PDF files to compress |
+| `OUTPUT_PATH` | | Output file (single-file mode only). Defaults to `<input>-compressed.pdf` |
+
+**Examples:**
+
+```zsh
+# Compress a single file to B&W at 300 DPI
+pdfc compress input.pdf -m bw -d 300
+
+# Compress with a custom output path
+pdfc compress input.pdf output.pdf -m gray -d 200 -q 50
+
+# Compress all PDFs in a folder using defaults (skips *-compressed.pdf files)
+pdfc compress /path/to/folder
+
+# Compress all PDFs in a folder, including already compressed files
+pdfc compress /path/to/folder --no-skip
+
+# Choose settings interactively
+pdfc compress input.pdf -i
+```
+
+### `compare` – Compare compression configurations side by side
+
+Runs all presets defined in `~/.config/pdfc/presets.yaml` against one or more
+PDF files and writes the results into a subdirectory named after each input file.
+
+
+Fields:
+
+| Field name        | Type     | Range                   | Default    | Description                                                                                                           |
+| ----------------- | -------- | ----------------------- | --- | --------------------------------------------------------------------------------------------------------------------- |
+| `name`            | `string` | `[a-zA-Z0-9_-]+`        | `-` | Required. Used as the output file name.                                                                               |
+| `mode`            | `string` | `color`, `gray` or `bw` | `bw`   | Color space of the output: Black & white (1-bit after threshold conversion), Grayscale (8-bit) or Color (RGB, 24-bit) |
+| `dpi`             | `int`    | `> 0`                   | `300`    | Resolution for rasterization. Strongly affects both quality and file size.                                                                                          |
+| `threshold`       | `int`    | `0-255`                 | `150`    | Threshold for B&W conversion. Pixels above the value → white, below → black. Higher value = more white = smaller file.                                                                                                  |
+| `jpeg_quality`    | `int`    | `1-100`                 | `30`    | JPEG quality. Lower values = smaller file, lower image quality. Enables JPEG mode. Cannot be combined with `png_compression`.                                                                  |
+| `png_compression` | `int`    | `0-9`                   | `7`    | PNG compression level. PNG compression level. Higher values lead to smaller files and longer processing times. Enables PNG mode. Cannot be combined with `jpeg_quality`.                                                                                    |
+| `sharpen`         | `float`  | `0.0-3.0`               | `1.0`   | Sharpening filter (PIL ImageEnhance.Sharpness). 0.0 → off, 1.0 → no change, >1.0 → sharper. |
+| `contrast`        | `float`  | `0.0-3.0`               | `1.0`   | Contrast filter (PIL ImageEnhance.Contrast). 1.0 → no change, >1.0 → more contrast.      |
+| `unsharp_mask`    | `bool`   | `true`/`false`          | `false`    | PIL UnsharpMask filter (radius=2, percent=150, threshold=3). Sharpens edges before conversion. |
+| `tiff_ccitt`      | `bool`   | `true`/`false`          | `false`    | Use TIFF CCITT Group 4 intermediate format                                                                            |
+
+
+```
+pdfc compare [OPTIONS] INPUT_PATH
+```
+
+| Option | Short | Description |
+|---|---|---|
+| `--dpi` | `-d` | Resolution for rasterization (default: 300) |
+| `--verbose` | `-v` | Verbose output |
+
+**Examples:**
+
+```zsh
+# Compare all presets for a single file
+pdfc compare input.pdf
+
+# Compare all presets for all PDFs in a folder at 200 DPI
+pdfc compare /path/to/folder --dpi 200
+```
+
+Output is written to a subdirectory next to the input file:
+
+```
+input.pdf
+input/
+  preset-name-1.pdf
+  preset-name-2.pdf
+  ...
+```
+
+## Presets file
+
+The `compare` command reads presets from `~/.config/pdfc/presets.yaml`.
+Each preset defines a named compression configuration.
+
+**Example:**
+
+```yaml
+presets:
+  - name: bw-300
+    mode: bw
+    dpi: 300
+    threshold: 150
+    sharpen: 1.5
+    contrast: 1.5
+
+  - name: gray-150
+    mode: gray
+    dpi: 150
+    jpeg_quality: 40
+
+  - name: color-200
+    mode: color
+    dpi: 200
+    jpeg_quality: 60
+    sharpen: 1.3
+    contrast: 1.3
+```
+
+See `example-presets.yaml` for more presets to try.
+
+Available preset fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | string | Required. Used as the output file name |
+| `mode` | string | `color`, `gray` or `bw` |
+| `dpi` | int | Resolution for rasterization |
+| `threshold` | int | B&W threshold 0–255 |
+| `jpeg_quality` | int | JPEG quality 1–100 |
+| `png_compression` | int | PNG compression level 0–9 |
+| `sharpen` | float | Sharpening factor 0.0–3.0 |
+| `contrast` | float | Contrast factor 0.0–3.0 |
+| `unsharp_mask` | bool | Apply PIL UnsharpMask filter |
+| `tiff_ccitt` | bool | Use TIFF CCITT Group 4 intermediate format |
+
+## Compression modes
+
+| Mode | Description |
+|---|---|
+| `color` | Keeps full colour. Best for photos and colour diagrams |
+| `gray` | Converts to greyscale. Good balance of size and readability |
+| `bw` | Converts to black & white. Smallest file size, best for text-only scans |
+
+## Parameter reference
+
+### Sharpen (`-s` / `--sharpen`)
+
+Range: 0.0 to 3.0 (float)
+
+| Value | Effect | Use case |
+|---|---|---|
+| **0.0** | No sharpening (off) | Default |
+| **0.5** | Slight blur | Noise reduction |
+| **1.0** | Original (no change) | Baseline |
+| **1.2–1.5** | Light sharpening | Recommended for clean documents |
+| **1.5–2.0** | Medium sharpening | Good for text |
+| **2.0–2.5** | Strong sharpening | For blurry scans |
+| **2.5–3.0** | Very strong sharpening | Risk of artefacts |
+| **>3.0** | Extreme (not allowed) | Too much; artefacts likely |
+
+Visual effect:
+
+```
+sharpen = 0.5:  T e x t   (blurry)
+sharpen = 1.0:  Text      (original)
+sharpen = 1.5:  Text      (crisper)
+sharpen = 2.0:  Text      (very sharp)
+sharpen = 3.0:  Text      (over-sharpened, halo artefacts)
+```
+
+**Too much sharpening (> 3.0):**
+- Halos around letters (white/black fringes)
+- Noise amplification (grainy look)
+- Edge artefacts
+- Unnatural appearance
+
+### Contrast (`-c` / `--contrast`)
+
+Range: 0.0 to 3.0 (float)
+
+| Value | Effect | Use case |
+|---|---|---|
+| **0.0** | Flat grey (no contrast) | Not useful |
+| **0.5** | Reduced contrast | Softer images |
+| **1.0** | Original (no change) | Baseline |
+| **1.2–1.5** | Slightly increased contrast | Recommended for clean documents |
+| **1.5–2.0** | Medium contrast | Good for text, clear separation |
+| **2.0–2.5** | Strong contrast | For faded documents |
+| **2.5–3.0** | Very strong contrast | Risk of detail loss |
+| **>3.0** | Extreme (not allowed) | Near binary; details lost |
+
+Visual effect:
+
+```
+contrast = 0.5:  Text  (washed out, grey)
+contrast = 1.0:  Text  (original)
+contrast = 1.5:  Text  (crisper, more defined)
+contrast = 2.0:  Text  (very clear, strong separation)
+contrast = 3.0:  Text  (near binary)
+```
+
+**Too much contrast (> 3.0):**
+- Detail loss (everything becomes black or white)
+- No more grey tones
+- Hard edges without transitions
+- Information loss
+
+### Interaction between contrast and threshold
+
+Contrast is applied before the B&W threshold. A higher contrast value effectively
+makes the threshold more aggressive, since pixel values are pushed further apart
+before the cut-off is applied.
+
+| Scenario | contrast | threshold | Pixel at 140 | Pixel at 160 |
+|---|---|---|---|---|
+| Low contrast | 1.0 | 150 | stays ~140 → black | stays ~160 → white |
+| High contrast | 2.0 | 150 | pushed to ~100 → black | pushed to ~200 → white |
+
+**Rule of thumb:** increase contrast only as much as needed; combine with the
+threshold to control where the black/white boundary falls.
+
+### Recommended combinations
+
+| Document type | sharpen | contrast | Notes |
+|---|---|---|---|
+| Clean, digital documents | 1.3 | 1.3 | Subtle improvement, no risk |
+| Standard scans | 1.5 | 1.5 | Best balance |
+| Blurry or faded scans | 2.0 | 2.0 | Strong improvement, low artefact risk |
+| Very poor scans | 2.5 | 2.5 | Maximum recommended |
+| Last resort | 3.0 | 3.0 | Artefacts likely |
+
+### Recommended parameter ranges (summary)
+
+| Parameter | Minimum | Recommended | Safe maximum | Risky maximum |
+|---|---|---|---|---|
+| Sharpen | 0.0 (off) | 1.3–2.0 | 2.5 | 3.0 |
+| Contrast | 0.0 (grey) | 1.3–2.0 | 2.5 | 3.0 |
+
+## Planned features
+
+### v0.1 – Initial release
+
+- [x] Skip files with the suffix `-compressed.pdf` to avoid re-processing already compressed files, unless flag `--no-skip` is set
+- [ ] Skip presets for color mode if input file is B&W or grayscale
+- [ ] Improve/clean output messages when processing files and presets
+
+### v0.2 – Presets management
+
+- [ ] `presets.yaml`: Field to set one preset as default for `compress` command, warn if missing or multiple defaults
+- [ ] Add `--preset` option to `compress` command to specify a preset from the presets file, e.g. `pdfc compress input.pdf --preset bw-300`
+- [ ] Add command `list-presets` which lets the user interactively view, add, edit and delete presets in the presets file
+- [ ] Add command `preset` which lets the user select a preset from the presets file and applies it to one or more PDF files

pypdfc-0.1.0/README.md

@@ -0,0 +1,299 @@
+# `pdfc` – PDF Compressor for the Command Line
+
+A command-line tool for compressing and optimising PDF files using configurable rasterization, colour mode, sharpening and contrast settings.
+
+![Python](https://img.shields.io/badge/python-3.10+-blue.svg)
+![License](https://img.shields.io/badge/license-MIT-green.svg)
+[![PyPI](https://img.shields.io/pypi/v/pdfc)](https://pypi.org/project/pdfc/)
+
+<img src="https://raw.githubusercontent.com/cgroening/py-pdfc/main/images/logo_dark.png" width="200" alt="PDF Compressor Logo">
+
+**Compressing a PDF file:**
+
+![Screenshot](https://raw.githubusercontent.com/cgroening/py-pdfc/main/images/screenshot_1_compress.png)
+
+**Interactive mode:**
+
+![Screenshot](https://raw.githubusercontent.com/cgroening/py-pdfc/main/images/screenshot_2_compress_interactive.png)
+
+**Comparing compression presets:**
+
+![Screenshot](https://raw.githubusercontent.com/cgroening/py-pdfc/main/images/screenshot_3_compare.png)
+
+## Requirements
+
+- Python 3.11+
+- [Poppler](https://poppler.freedesktop.org/) (for `pdf2image`)
+  - macOS: `brew install poppler`
+  - Ubuntu/Debian: `sudo apt install poppler-utils`
+
+## Installation
+
+```zsh
+pip install .
+```
+
+For development (includes pytest, coverage):
+
+```zsh
+pip install ".[dev]"
+```
+
+## Commands
+
+### `compress` – Compress one or more PDF files
+
+```
+pdfc compress [OPTIONS] INPUT_PATH [OUTPUT_PATH]
+```
+
+| Argument / Option | Short | Description |
+|---|---|---|
+| `--interactive` | `-i` | Collect all settings interactively via prompts |
+| `--verbose` | `-v` | Verbose output |
+| `--mode` | `-m` | Colour mode: `color`, `gray` or `bw` |
+| `--dpi` | `-d` | Resolution for rasterization in dots per inch (default: 300) |
+| `--jpeg-quality` | `-q` | JPEG quality 1–100 (default: 30). Mutually exclusive with `--png-compression-level` |
+| `--png-compression-level` | `-p` | PNG compression level 0–9 (default: 6). Mutually exclusive with `--jpeg-quality` |
+| `--threshold` | `-t` | B&W threshold 0–255 (default: 150). Only used in `bw` mode |
+| `--sharpen` | `-s` | Sharpening factor 0.0–3.0 (default: 0.0 = off) |
+| `--contrast` | `-c` | Contrast factor 0.0–3.0 (default: 1.0 = no change) |
+| `--unsharp-mask` | `-u` | Apply PIL UnsharpMask filter |
+| `--tiff-ccitt` | `-T` | Use TIFF CCITT Group 4 as intermediate format (`bw` mode only) |
+| `--no-skip` | | Process all files, including files ending with `-compressed.pdf` (which are skipped by default when input is a directory) |
+| `INPUT_PATH` | | PDF file or directory of PDF files to compress |
+| `OUTPUT_PATH` | | Output file (single-file mode only). Defaults to `<input>-compressed.pdf` |
+
+**Examples:**
+
+```zsh
+# Compress a single file to B&W at 300 DPI
+pdfc compress input.pdf -m bw -d 300
+
+# Compress with a custom output path
+pdfc compress input.pdf output.pdf -m gray -d 200 -q 50
+
+# Compress all PDFs in a folder using defaults (skips *-compressed.pdf files)
+pdfc compress /path/to/folder
+
+# Compress all PDFs in a folder, including already compressed files
+pdfc compress /path/to/folder --no-skip
+
+# Choose settings interactively
+pdfc compress input.pdf -i
+```
+
+### `compare` – Compare compression configurations side by side
+
+Runs all presets defined in `~/.config/pdfc/presets.yaml` against one or more
+PDF files and writes the results into a subdirectory named after each input file.
+
+
+Fields:
+
+| Field name        | Type     | Range                   | Default    | Description                                                                                                           |
+| ----------------- | -------- | ----------------------- | --- | --------------------------------------------------------------------------------------------------------------------- |
+| `name`            | `string` | `[a-zA-Z0-9_-]+`        | `-` | Required. Used as the output file name.                                                                               |
+| `mode`            | `string` | `color`, `gray` or `bw` | `bw`   | Color space of the output: Black & white (1-bit after threshold conversion), Grayscale (8-bit) or Color (RGB, 24-bit) |
+| `dpi`             | `int`    | `> 0`                   | `300`    | Resolution for rasterization. Strongly affects both quality and file size.                                                                                          |
+| `threshold`       | `int`    | `0-255`                 | `150`    | Threshold for B&W conversion. Pixels above the value → white, below → black. Higher value = more white = smaller file.                                                                                                  |
+| `jpeg_quality`    | `int`    | `1-100`                 | `30`    | JPEG quality. Lower values = smaller file, lower image quality. Enables JPEG mode. Cannot be combined with `png_compression`.                                                                  |
+| `png_compression` | `int`    | `0-9`                   | `7`    | PNG compression level. PNG compression level. Higher values lead to smaller files and longer processing times. Enables PNG mode. Cannot be combined with `jpeg_quality`.                                                                                    |
+| `sharpen`         | `float`  | `0.0-3.0`               | `1.0`   | Sharpening filter (PIL ImageEnhance.Sharpness). 0.0 → off, 1.0 → no change, >1.0 → sharper. |
+| `contrast`        | `float`  | `0.0-3.0`               | `1.0`   | Contrast filter (PIL ImageEnhance.Contrast). 1.0 → no change, >1.0 → more contrast.      |
+| `unsharp_mask`    | `bool`   | `true`/`false`          | `false`    | PIL UnsharpMask filter (radius=2, percent=150, threshold=3). Sharpens edges before conversion. |
+| `tiff_ccitt`      | `bool`   | `true`/`false`          | `false`    | Use TIFF CCITT Group 4 intermediate format                                                                            |
+
+
+```
+pdfc compare [OPTIONS] INPUT_PATH
+```
+
+| Option | Short | Description |
+|---|---|---|
+| `--dpi` | `-d` | Resolution for rasterization (default: 300) |
+| `--verbose` | `-v` | Verbose output |
+
+**Examples:**
+
+```zsh
+# Compare all presets for a single file
+pdfc compare input.pdf
+
+# Compare all presets for all PDFs in a folder at 200 DPI
+pdfc compare /path/to/folder --dpi 200
+```
+
+Output is written to a subdirectory next to the input file:
+
+```
+input.pdf
+input/
+  preset-name-1.pdf
+  preset-name-2.pdf
+  ...
+```
+
+## Presets file
+
+The `compare` command reads presets from `~/.config/pdfc/presets.yaml`.
+Each preset defines a named compression configuration.
+
+**Example:**
+
+```yaml
+presets:
+  - name: bw-300
+    mode: bw
+    dpi: 300
+    threshold: 150
+    sharpen: 1.5
+    contrast: 1.5
+
+  - name: gray-150
+    mode: gray
+    dpi: 150
+    jpeg_quality: 40
+
+  - name: color-200
+    mode: color
+    dpi: 200
+    jpeg_quality: 60
+    sharpen: 1.3
+    contrast: 1.3
+```
+
+See `example-presets.yaml` for more presets to try.
+
+Available preset fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | string | Required. Used as the output file name |
+| `mode` | string | `color`, `gray` or `bw` |
+| `dpi` | int | Resolution for rasterization |
+| `threshold` | int | B&W threshold 0–255 |
+| `jpeg_quality` | int | JPEG quality 1–100 |
+| `png_compression` | int | PNG compression level 0–9 |
+| `sharpen` | float | Sharpening factor 0.0–3.0 |
+| `contrast` | float | Contrast factor 0.0–3.0 |
+| `unsharp_mask` | bool | Apply PIL UnsharpMask filter |
+| `tiff_ccitt` | bool | Use TIFF CCITT Group 4 intermediate format |
+
+## Compression modes
+
+| Mode | Description |
+|---|---|
+| `color` | Keeps full colour. Best for photos and colour diagrams |
+| `gray` | Converts to greyscale. Good balance of size and readability |
+| `bw` | Converts to black & white. Smallest file size, best for text-only scans |
+
+## Parameter reference
+
+### Sharpen (`-s` / `--sharpen`)
+
+Range: 0.0 to 3.0 (float)
+
+| Value | Effect | Use case |
+|---|---|---|
+| **0.0** | No sharpening (off) | Default |
+| **0.5** | Slight blur | Noise reduction |
+| **1.0** | Original (no change) | Baseline |
+| **1.2–1.5** | Light sharpening | Recommended for clean documents |
+| **1.5–2.0** | Medium sharpening | Good for text |
+| **2.0–2.5** | Strong sharpening | For blurry scans |
+| **2.5–3.0** | Very strong sharpening | Risk of artefacts |
+| **>3.0** | Extreme (not allowed) | Too much; artefacts likely |
+
+Visual effect:
+
+```
+sharpen = 0.5:  T e x t   (blurry)
+sharpen = 1.0:  Text      (original)
+sharpen = 1.5:  Text      (crisper)
+sharpen = 2.0:  Text      (very sharp)
+sharpen = 3.0:  Text      (over-sharpened, halo artefacts)
+```
+
+**Too much sharpening (> 3.0):**
+- Halos around letters (white/black fringes)
+- Noise amplification (grainy look)
+- Edge artefacts
+- Unnatural appearance
+
+### Contrast (`-c` / `--contrast`)
+
+Range: 0.0 to 3.0 (float)
+
+| Value | Effect | Use case |
+|---|---|---|
+| **0.0** | Flat grey (no contrast) | Not useful |
+| **0.5** | Reduced contrast | Softer images |
+| **1.0** | Original (no change) | Baseline |
+| **1.2–1.5** | Slightly increased contrast | Recommended for clean documents |
+| **1.5–2.0** | Medium contrast | Good for text, clear separation |
+| **2.0–2.5** | Strong contrast | For faded documents |
+| **2.5–3.0** | Very strong contrast | Risk of detail loss |
+| **>3.0** | Extreme (not allowed) | Near binary; details lost |
+
+Visual effect:
+
+```
+contrast = 0.5:  Text  (washed out, grey)
+contrast = 1.0:  Text  (original)
+contrast = 1.5:  Text  (crisper, more defined)
+contrast = 2.0:  Text  (very clear, strong separation)
+contrast = 3.0:  Text  (near binary)
+```
+
+**Too much contrast (> 3.0):**
+- Detail loss (everything becomes black or white)
+- No more grey tones
+- Hard edges without transitions
+- Information loss
+
+### Interaction between contrast and threshold
+
+Contrast is applied before the B&W threshold. A higher contrast value effectively
+makes the threshold more aggressive, since pixel values are pushed further apart
+before the cut-off is applied.
+
+| Scenario | contrast | threshold | Pixel at 140 | Pixel at 160 |
+|---|---|---|---|---|
+| Low contrast | 1.0 | 150 | stays ~140 → black | stays ~160 → white |
+| High contrast | 2.0 | 150 | pushed to ~100 → black | pushed to ~200 → white |
+
+**Rule of thumb:** increase contrast only as much as needed; combine with the
+threshold to control where the black/white boundary falls.
+
+### Recommended combinations
+
+| Document type | sharpen | contrast | Notes |
+|---|---|---|---|
+| Clean, digital documents | 1.3 | 1.3 | Subtle improvement, no risk |
+| Standard scans | 1.5 | 1.5 | Best balance |
+| Blurry or faded scans | 2.0 | 2.0 | Strong improvement, low artefact risk |
+| Very poor scans | 2.5 | 2.5 | Maximum recommended |
+| Last resort | 3.0 | 3.0 | Artefacts likely |
+
+### Recommended parameter ranges (summary)
+
+| Parameter | Minimum | Recommended | Safe maximum | Risky maximum |
+|---|---|---|---|---|
+| Sharpen | 0.0 (off) | 1.3–2.0 | 2.5 | 3.0 |
+| Contrast | 0.0 (grey) | 1.3–2.0 | 2.5 | 3.0 |
+
+## Planned features
+
+### v0.1 – Initial release
+
+- [x] Skip files with the suffix `-compressed.pdf` to avoid re-processing already compressed files, unless flag `--no-skip` is set
+- [ ] Skip presets for color mode if input file is B&W or grayscale
+- [ ] Improve/clean output messages when processing files and presets
+
+### v0.2 – Presets management
+
+- [ ] `presets.yaml`: Field to set one preset as default for `compress` command, warn if missing or multiple defaults
+- [ ] Add `--preset` option to `compress` command to specify a preset from the presets file, e.g. `pdfc compress input.pdf --preset bw-300`
+- [ ] Add command `list-presets` which lets the user interactively view, add, edit and delete presets in the presets file
+- [ ] Add command `preset` which lets the user select a preset from the presets file and applies it to one or more PDF files

pypdfc-0.1.0/pdfc/__main__.py

@@ -0,0 +1,3 @@
+# For `python -m pdfc ...` to work, this file must exist and call main().
+from pdfc.main import main
+main()

pypdfc-0.1.0/pdfc/main.py

@@ -0,0 +1,141 @@
+import typer
+from pathlib import Path
+from typing import Optional
+
+from pdfc.cli.compress_parameters import CompressRequest
+from pdfc.cli.commands.compress_input import InputView
+from pdfc.cli.commands.compress import CompressCommand
+from pdfc.cli.commands.compare import CompareCommand
+from pdfc.domain.models import CompressionSettings
+from pdfc.services.compression import CompressionService
+from pdfc.storage.pdf_compressor import PdfCompressor
+from pdfc.storage.presets_storage import PresetsStorage
+
+
+app = typer.Typer(
+    help='Compress and optimise PDF files using various algorithms.',
+    no_args_is_help=True,
+)
+
+# Dependency composition (Composition Root)
+_compressor      = PdfCompressor()
+_presets         = PresetsStorage()
+_service         = CompressionService(_compressor, _presets)
+_input_view      = InputView()
+_compress_cmd    = CompressCommand(_service, _input_view)
+_compare_cmd     = CompareCommand(_service,)
+
+
+@app.command()
+def compress(
+    input_path: Path = typer.Argument(
+        ...,
+        help='PDF file or directory of PDF files to compress.',
+        exists=True,
+        file_okay=True,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+    output_path: Optional[Path] = typer.Argument(
+        None,
+        help=(
+            'Output file path (single-file mode only). '
+            'Defaults to <input>-compressed.pdf.'
+        ),
+    ),
+    interactive_mode: bool = typer.Option(
+        False, '-i', '--interactive',
+        help='Collect compression settings interactively.',
+    ),
+    mode: Optional[str] = typer.Option(
+        None, '-m', '--mode',
+        help='Compression mode: color | gray | bw.',
+    ),
+    dpi: Optional[int] = typer.Option(
+        None, '-d', '--dpi',
+        help='Resolution for rasterisation (dots per inch).',
+    ),
+    jpeg_quality: Optional[int] = typer.Option(
+        None, '-q', '--jpeg-quality',
+        help='JPEG quality 1–100. Mutually exclusive with --png-compression-level.',
+    ),
+    png_compression_level: Optional[int] = typer.Option(
+        None, '-p', '--png-compression-level',
+        help='PNG compression level 0–9. Mutually exclusive with --jpeg-quality.',
+    ),
+    threshold: Optional[int] = typer.Option(
+        None, '-t', '--threshold',
+        help='B&W threshold 0–255 (only used in bw mode).',
+    ),
+    sharpen: Optional[float] = typer.Option(
+        None, '-s', '--sharpen',
+        help='Sharpening factor 0.0–3.0 (0 = off).',
+    ),
+    contrast: Optional[float] = typer.Option(
+        None, '-c', '--contrast',
+        help='Contrast factor 0.0–3.0 (1.0 = no change).',
+    ),
+    unsharp_mask: bool = typer.Option(
+        False, '-u', '--unsharp-mask',
+        help='Apply PIL UnsharpMask filter.',
+    ),
+    tiff_ccitt: bool = typer.Option(
+        False, '-T', '--tiff-ccitt',
+        help='Use TIFF CCITT Group 4 as intermediate format (bw mode only).',
+    ),
+    no_skip: bool = typer.Option(
+        False, '--no-skip',
+        help=(
+            'Process all files in the directory, including files ending with '
+            '"-compressed.pdf" (which are skipped by default).'
+        ),
+    ),
+):
+    if jpeg_quality is not None and png_compression_level is not None:
+        raise typer.BadParameter(
+            'Cannot use --jpeg-quality and --png-compression-level at the same time.'
+        )
+
+    compression_settings = CompressionSettings(
+        _mode=mode,
+        _dpi=dpi,
+        _jpeg_quality=jpeg_quality,
+        _png_compression=png_compression_level,
+        _bw_threshold=threshold,
+        _sharpen=sharpen,
+        _contrast=contrast,
+        _unsharp_mask=unsharp_mask,
+        _tiff_ccitt=tiff_ccitt,
+    )
+    compress_request = CompressRequest(
+        interactive_mode=interactive_mode,
+        input_path=input_path,
+        output_path=output_path,
+        compression_settings=compression_settings,
+        no_skip=no_skip,
+    )
+
+    _compress_cmd.run(compress_request)
+
+
+@app.command()
+def compare(
+    input_path: Path = typer.Argument(
+        ...,
+        help='PDF file or directory of PDF files to compare.',
+        exists=True,
+        file_okay=True,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+    dpi: int = typer.Option(
+        300, '-d', '--dpi',
+        help='Resolution for rasterization (dots per inch). Default: 300.',
+    )
+):
+    _compare_cmd.run(input_path=input_path, dpi=dpi)
+
+
+def main() -> None:
+    app()
+

pypdfc-0.1.0/pypdfc.egg-info/PKG-INFO

@@ -0,0 +1,321 @@
+Metadata-Version: 2.4
+Name: pypdfc
+Version: 0.1.0
+Summary: A command line tool for compressing PDF files
+Author: Corvin Gröning
+Keywords: pdf,compress,cli
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: img2pdf>=0.5.0
+Requires-Dist: pdf2image>=1.17.0
+Requires-Dist: Pillow>=11.0.0
+Requires-Dist: PyYAML>=6.0.0
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: rich>=14.0.0
+Requires-Dist: typer>=0.15.0
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0; extra == "dev"
+Requires-Dist: pytest-cov>=7.0; extra == "dev"
+Requires-Dist: coverage>=7.0; extra == "dev"
+
+# `pdfc` – PDF Compressor for the Command Line
+
+A command-line tool for compressing and optimising PDF files using configurable rasterization, colour mode, sharpening and contrast settings.
+
+![Python](https://img.shields.io/badge/python-3.10+-blue.svg)
+![License](https://img.shields.io/badge/license-MIT-green.svg)
+[![PyPI](https://img.shields.io/pypi/v/pdfc)](https://pypi.org/project/pdfc/)
+
+<img src="https://raw.githubusercontent.com/cgroening/py-pdfc/main/images/logo_dark.png" width="200" alt="PDF Compressor Logo">
+
+**Compressing a PDF file:**
+
+![Screenshot](https://raw.githubusercontent.com/cgroening/py-pdfc/main/images/screenshot_1_compress.png)
+
+**Interactive mode:**
+
+![Screenshot](https://raw.githubusercontent.com/cgroening/py-pdfc/main/images/screenshot_2_compress_interactive.png)
+
+**Comparing compression presets:**
+
+![Screenshot](https://raw.githubusercontent.com/cgroening/py-pdfc/main/images/screenshot_3_compare.png)
+
+## Requirements
+
+- Python 3.11+
+- [Poppler](https://poppler.freedesktop.org/) (for `pdf2image`)
+  - macOS: `brew install poppler`
+  - Ubuntu/Debian: `sudo apt install poppler-utils`
+
+## Installation
+
+```zsh
+pip install .
+```
+
+For development (includes pytest, coverage):
+
+```zsh
+pip install ".[dev]"
+```
+
+## Commands
+
+### `compress` – Compress one or more PDF files
+
+```
+pdfc compress [OPTIONS] INPUT_PATH [OUTPUT_PATH]
+```
+
+| Argument / Option | Short | Description |
+|---|---|---|
+| `--interactive` | `-i` | Collect all settings interactively via prompts |
+| `--verbose` | `-v` | Verbose output |
+| `--mode` | `-m` | Colour mode: `color`, `gray` or `bw` |
+| `--dpi` | `-d` | Resolution for rasterization in dots per inch (default: 300) |
+| `--jpeg-quality` | `-q` | JPEG quality 1–100 (default: 30). Mutually exclusive with `--png-compression-level` |
+| `--png-compression-level` | `-p` | PNG compression level 0–9 (default: 6). Mutually exclusive with `--jpeg-quality` |
+| `--threshold` | `-t` | B&W threshold 0–255 (default: 150). Only used in `bw` mode |
+| `--sharpen` | `-s` | Sharpening factor 0.0–3.0 (default: 0.0 = off) |
+| `--contrast` | `-c` | Contrast factor 0.0–3.0 (default: 1.0 = no change) |
+| `--unsharp-mask` | `-u` | Apply PIL UnsharpMask filter |
+| `--tiff-ccitt` | `-T` | Use TIFF CCITT Group 4 as intermediate format (`bw` mode only) |
+| `--no-skip` | | Process all files, including files ending with `-compressed.pdf` (which are skipped by default when input is a directory) |
+| `INPUT_PATH` | | PDF file or directory of PDF files to compress |
+| `OUTPUT_PATH` | | Output file (single-file mode only). Defaults to `<input>-compressed.pdf` |
+
+**Examples:**
+
+```zsh
+# Compress a single file to B&W at 300 DPI
+pdfc compress input.pdf -m bw -d 300
+
+# Compress with a custom output path
+pdfc compress input.pdf output.pdf -m gray -d 200 -q 50
+
+# Compress all PDFs in a folder using defaults (skips *-compressed.pdf files)
+pdfc compress /path/to/folder
+
+# Compress all PDFs in a folder, including already compressed files
+pdfc compress /path/to/folder --no-skip
+
+# Choose settings interactively
+pdfc compress input.pdf -i
+```
+
+### `compare` – Compare compression configurations side by side
+
+Runs all presets defined in `~/.config/pdfc/presets.yaml` against one or more
+PDF files and writes the results into a subdirectory named after each input file.
+
+
+Fields:
+
+| Field name        | Type     | Range                   | Default    | Description                                                                                                           |
+| ----------------- | -------- | ----------------------- | --- | --------------------------------------------------------------------------------------------------------------------- |
+| `name`            | `string` | `[a-zA-Z0-9_-]+`        | `-` | Required. Used as the output file name.                                                                               |
+| `mode`            | `string` | `color`, `gray` or `bw` | `bw`   | Color space of the output: Black & white (1-bit after threshold conversion), Grayscale (8-bit) or Color (RGB, 24-bit) |
+| `dpi`             | `int`    | `> 0`                   | `300`    | Resolution for rasterization. Strongly affects both quality and file size.                                                                                          |
+| `threshold`       | `int`    | `0-255`                 | `150`    | Threshold for B&W conversion. Pixels above the value → white, below → black. Higher value = more white = smaller file.                                                                                                  |
+| `jpeg_quality`    | `int`    | `1-100`                 | `30`    | JPEG quality. Lower values = smaller file, lower image quality. Enables JPEG mode. Cannot be combined with `png_compression`.                                                                  |
+| `png_compression` | `int`    | `0-9`                   | `7`    | PNG compression level. PNG compression level. Higher values lead to smaller files and longer processing times. Enables PNG mode. Cannot be combined with `jpeg_quality`.                                                                                    |
+| `sharpen`         | `float`  | `0.0-3.0`               | `1.0`   | Sharpening filter (PIL ImageEnhance.Sharpness). 0.0 → off, 1.0 → no change, >1.0 → sharper. |
+| `contrast`        | `float`  | `0.0-3.0`               | `1.0`   | Contrast filter (PIL ImageEnhance.Contrast). 1.0 → no change, >1.0 → more contrast.      |
+| `unsharp_mask`    | `bool`   | `true`/`false`          | `false`    | PIL UnsharpMask filter (radius=2, percent=150, threshold=3). Sharpens edges before conversion. |
+| `tiff_ccitt`      | `bool`   | `true`/`false`          | `false`    | Use TIFF CCITT Group 4 intermediate format                                                                            |
+
+
+```
+pdfc compare [OPTIONS] INPUT_PATH
+```
+
+| Option | Short | Description |
+|---|---|---|
+| `--dpi` | `-d` | Resolution for rasterization (default: 300) |
+| `--verbose` | `-v` | Verbose output |
+
+**Examples:**
+
+```zsh
+# Compare all presets for a single file
+pdfc compare input.pdf
+
+# Compare all presets for all PDFs in a folder at 200 DPI
+pdfc compare /path/to/folder --dpi 200
+```
+
+Output is written to a subdirectory next to the input file:
+
+```
+input.pdf
+input/
+  preset-name-1.pdf
+  preset-name-2.pdf
+  ...
+```
+
+## Presets file
+
+The `compare` command reads presets from `~/.config/pdfc/presets.yaml`.
+Each preset defines a named compression configuration.
+
+**Example:**
+
+```yaml
+presets:
+  - name: bw-300
+    mode: bw
+    dpi: 300
+    threshold: 150
+    sharpen: 1.5
+    contrast: 1.5
+
+  - name: gray-150
+    mode: gray
+    dpi: 150
+    jpeg_quality: 40
+
+  - name: color-200
+    mode: color
+    dpi: 200
+    jpeg_quality: 60
+    sharpen: 1.3
+    contrast: 1.3
+```
+
+See `example-presets.yaml` for more presets to try.
+
+Available preset fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | string | Required. Used as the output file name |
+| `mode` | string | `color`, `gray` or `bw` |
+| `dpi` | int | Resolution for rasterization |
+| `threshold` | int | B&W threshold 0–255 |
+| `jpeg_quality` | int | JPEG quality 1–100 |
+| `png_compression` | int | PNG compression level 0–9 |
+| `sharpen` | float | Sharpening factor 0.0–3.0 |
+| `contrast` | float | Contrast factor 0.0–3.0 |
+| `unsharp_mask` | bool | Apply PIL UnsharpMask filter |
+| `tiff_ccitt` | bool | Use TIFF CCITT Group 4 intermediate format |
+
+## Compression modes
+
+| Mode | Description |
+|---|---|
+| `color` | Keeps full colour. Best for photos and colour diagrams |
+| `gray` | Converts to greyscale. Good balance of size and readability |
+| `bw` | Converts to black & white. Smallest file size, best for text-only scans |
+
+## Parameter reference
+
+### Sharpen (`-s` / `--sharpen`)
+
+Range: 0.0 to 3.0 (float)
+
+| Value | Effect | Use case |
+|---|---|---|
+| **0.0** | No sharpening (off) | Default |
+| **0.5** | Slight blur | Noise reduction |
+| **1.0** | Original (no change) | Baseline |
+| **1.2–1.5** | Light sharpening | Recommended for clean documents |
+| **1.5–2.0** | Medium sharpening | Good for text |
+| **2.0–2.5** | Strong sharpening | For blurry scans |
+| **2.5–3.0** | Very strong sharpening | Risk of artefacts |
+| **>3.0** | Extreme (not allowed) | Too much; artefacts likely |
+
+Visual effect:
+
+```
+sharpen = 0.5:  T e x t   (blurry)
+sharpen = 1.0:  Text      (original)
+sharpen = 1.5:  Text      (crisper)
+sharpen = 2.0:  Text      (very sharp)
+sharpen = 3.0:  Text      (over-sharpened, halo artefacts)
+```
+
+**Too much sharpening (> 3.0):**
+- Halos around letters (white/black fringes)
+- Noise amplification (grainy look)
+- Edge artefacts
+- Unnatural appearance
+
+### Contrast (`-c` / `--contrast`)
+
+Range: 0.0 to 3.0 (float)
+
+| Value | Effect | Use case |
+|---|---|---|
+| **0.0** | Flat grey (no contrast) | Not useful |
+| **0.5** | Reduced contrast | Softer images |
+| **1.0** | Original (no change) | Baseline |
+| **1.2–1.5** | Slightly increased contrast | Recommended for clean documents |
+| **1.5–2.0** | Medium contrast | Good for text, clear separation |
+| **2.0–2.5** | Strong contrast | For faded documents |
+| **2.5–3.0** | Very strong contrast | Risk of detail loss |
+| **>3.0** | Extreme (not allowed) | Near binary; details lost |
+
+Visual effect:
+
+```
+contrast = 0.5:  Text  (washed out, grey)
+contrast = 1.0:  Text  (original)
+contrast = 1.5:  Text  (crisper, more defined)
+contrast = 2.0:  Text  (very clear, strong separation)
+contrast = 3.0:  Text  (near binary)
+```
+
+**Too much contrast (> 3.0):**
+- Detail loss (everything becomes black or white)
+- No more grey tones
+- Hard edges without transitions
+- Information loss
+
+### Interaction between contrast and threshold
+
+Contrast is applied before the B&W threshold. A higher contrast value effectively
+makes the threshold more aggressive, since pixel values are pushed further apart
+before the cut-off is applied.
+
+| Scenario | contrast | threshold | Pixel at 140 | Pixel at 160 |
+|---|---|---|---|---|
+| Low contrast | 1.0 | 150 | stays ~140 → black | stays ~160 → white |
+| High contrast | 2.0 | 150 | pushed to ~100 → black | pushed to ~200 → white |
+
+**Rule of thumb:** increase contrast only as much as needed; combine with the
+threshold to control where the black/white boundary falls.
+
+### Recommended combinations
+
+| Document type | sharpen | contrast | Notes |
+|---|---|---|---|
+| Clean, digital documents | 1.3 | 1.3 | Subtle improvement, no risk |
+| Standard scans | 1.5 | 1.5 | Best balance |
+| Blurry or faded scans | 2.0 | 2.0 | Strong improvement, low artefact risk |
+| Very poor scans | 2.5 | 2.5 | Maximum recommended |
+| Last resort | 3.0 | 3.0 | Artefacts likely |
+
+### Recommended parameter ranges (summary)
+
+| Parameter | Minimum | Recommended | Safe maximum | Risky maximum |
+|---|---|---|---|---|
+| Sharpen | 0.0 (off) | 1.3–2.0 | 2.5 | 3.0 |
+| Contrast | 0.0 (grey) | 1.3–2.0 | 2.5 | 3.0 |
+
+## Planned features
+
+### v0.1 – Initial release
+
+- [x] Skip files with the suffix `-compressed.pdf` to avoid re-processing already compressed files, unless flag `--no-skip` is set
+- [ ] Skip presets for color mode if input file is B&W or grayscale
+- [ ] Improve/clean output messages when processing files and presets
+
+### v0.2 – Presets management
+
+- [ ] `presets.yaml`: Field to set one preset as default for `compress` command, warn if missing or multiple defaults
+- [ ] Add `--preset` option to `compress` command to specify a preset from the presets file, e.g. `pdfc compress input.pdf --preset bw-300`
+- [ ] Add command `list-presets` which lets the user interactively view, add, edit and delete presets in the presets file
+- [ ] Add command `preset` which lets the user select a preset from the presets file and applies it to one or more PDF files

pypdfc-0.1.0/pypdfc.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+pdfc/__init__.py
+pdfc/__main__.py
+pdfc/main.py
+pypdfc.egg-info/PKG-INFO
+pypdfc.egg-info/SOURCES.txt
+pypdfc.egg-info/dependency_links.txt
+pypdfc.egg-info/entry_points.txt
+pypdfc.egg-info/requires.txt
+pypdfc.egg-info/top_level.txt

pypdfc-0.1.0/pypdfc.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pypdfc-0.1.0/pypdfc.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pdfc = pdfc.main:main

pypdfc-0.1.0/pypdfc.egg-info/requires.txt

@@ -0,0 +1,12 @@
+img2pdf>=0.5.0
+pdf2image>=1.17.0
+Pillow>=11.0.0
+PyYAML>=6.0.0
+questionary>=2.0.0
+rich>=14.0.0
+typer>=0.15.0
+
+[dev]
+pytest>=9.0
+pytest-cov>=7.0
+coverage>=7.0

pypdfc-0.1.0/pypdfc.egg-info/top_level.txt

@@ -0,0 +1 @@
+pdfc

pypdfc-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "pypdfc"
+version = "0.1.0"
+description = "A command line tool for compressing PDF files"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [
+    { name = "Corvin Gröning" }
+]
+keywords = ["pdf", "compress", "cli"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Environment :: Console",
+]
+dependencies = [
+    "img2pdf>=0.5.0",
+    "pdf2image>=1.17.0",
+    "Pillow>=11.0.0",
+    "PyYAML>=6.0.0",
+    "questionary>=2.0.0",
+    "rich>=14.0.0",
+    "typer>=0.15.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.0",
+    "pytest-cov>=7.0",
+    "coverage>=7.0",
+]
+
+[tool.setuptools]
+packages = ["pdfc"]
+
+[project.scripts]
+pdfc = "pdfc.main:main"
+
+[tool.pytest.ini_options]
+testpaths = ["pdfc/tests"]
+
+[tool.mypy]
+check_untyped_defs = true
+
+[tool.pyright]
+exclude = [
+    "**/.*",
+    "**/__pycache__",
+    "**/*.pyc",
+    ".venv",
+    "venv",
+]
+
+[tool.ruff.lint]
+ignore = ["E702"]

pypdfc-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+