Skip to content

usage.md

Latest commit

 

History

History
224 lines (169 loc) · 5.51 KB

usage.md

File metadata and controls

224 lines (169 loc) · 5.51 KB

Usage Guide

Basic Usage

The most basic command:

python3 securecompress_cli.py --input input.pdf --output output.pdf --size 5

This compresses input.pdf to approximately 5MB and saves it as output.pdf.

Command-Line Arguments

Required Arguments

  • --input PATH - Input PDF file path
  • --output PATH - Output PDF file path
  • --size MB - Target size in megabytes

Optional Arguments

Quality Settings

  • --dpi DPI - Render DPI (default: 200)

    • Higher DPI = better quality, larger file
    • Recommended: 150-250
    • Example: --dpi 200

  • --mode MODE - Color mode (default: color)

    • color - Full color (RGB)
    • gray - Grayscale
    • bw - Black and white (smallest size)
    • Example: --mode gray

Advanced Options

  • --max-passes N - Maximum compression passes (default: 2)

    • More passes = better size accuracy, longer time
    • Example: --max-passes 3

  • --engine ENGINE - Compression engine (default: auto)

    • auto - Automatically choose best engine
    • object - Object-level compression (best for text)
    • raster - Raster-based compression (best for images)
    • Example: --engine object

  • --content-type TYPE - Content type hint (default: unknown)

    • text - Text-heavy documents
    • scan - Scanned documents
    • unknown - Mixed or unknown content
    • Example: --content-type text

  • --adaptive - Use adaptive per-page compression targets

    • Allocates more space to complex pages
    • Example: --adaptive

  • --quality-check - Enable quality sampling

    • Monitors compression quality using SSIM
    • Example: --quality-check

  • --quality-threshold FLOAT - SSIM quality threshold (default: 0.82)

    • Range: 0.0 to 1.0 (higher = better quality)
    • Example: --quality-threshold 0.85

Logging

  • --log PATH - Log file path
    • Example: --log compression.log

Common Use Cases

1. Email Attachment (< 10MB)

python3 securecompress_cli.py \
  --input document.pdf \
  --output document_email.pdf \
  --size 9

2. Web Upload (< 5MB)

python3 securecompress_cli.py \
  --input document.pdf \
  --output document_web.pdf \
  --size 4.5 \
  --dpi 150

3. Text Document (High Quality)

python3 securecompress_cli.py \
  --input report.pdf \
  --output report_compressed.pdf \
  --size 5 \
  --mode gray \
  --engine object \
  --content-type text

4. Scanned Document (Aggressive)

python3 securecompress_cli.py \
  --input scan.pdf \
  --output scan_compressed.pdf \
  --size 2 \
  --mode bw \
  --dpi 150 \
  --content-type scan

5. Photo-Heavy Document

python3 securecompress_cli.py \
  --input photos.pdf \
  --output photos_compressed.pdf \
  --size 10 \
  --dpi 200 \
  --mode color \
  --adaptive \
  --quality-check

6. Ultra-Aggressive Compression

python3 securecompress_cli.py \
  --input large.pdf \
  --output tiny.pdf \
  --size 1 \
  --dpi 120 \
  --mode gray \
  --max-passes 4

Output Format

The CLI outputs JSON-formatted progress and status messages to stdout:

{"type": "status", "message": "Initializing...", "step": "init"}
{"type": "progress", "current": 1, "total": 10, "percent": 10, "message": "Processing page 1/10"}
{"type": "complete", "output_path": "output.pdf", "final_size_mb": 4.87, "percent": 100}
{"type": "summary", "input_size_mb": 25.3, "final_size_mb": 4.87, "total_pages": 10, ...}

This makes it easy to integrate into other applications and monitor progress.

Tips for Best Results

For Text Documents

  • Use --mode gray to reduce size without losing readability
  • Use --engine object for better text quality
  • Use --content-type text to optimize for text

For Scanned Documents

  • Use --mode bw for black and white scans
  • Use lower DPI (120-150) for acceptable quality
  • Use --content-type scan

For Mixed Content

  • Use --adaptive to allocate space intelligently
  • Use --quality-check to maintain quality
  • Use --max-passes 3 for better size accuracy

For Maximum Quality

  • Use higher DPI (200-250)
  • Use --quality-check --quality-threshold 0.85
  • Use --adaptive for complex documents

For Maximum Compression

  • Use --mode bw or --mode gray
  • Use lower DPI (100-150)
  • Use --max-passes 4
  • Accept that quality will be reduced

Environment Variables

  • SECURECOMPRESS_LOG_PATH - Default log file path 
    export SECURECOMPRESS_LOG_PATH="/tmp/compression.log"
python3 securecompress_cli.py --input in.pdf --output out.pdf --size 5

Exit Codes

  • 0 - Success
  • 1 - General error (file not found, compression failed, etc.)
  • 130 - Cancelled by user (Ctrl+C)

Performance Considerations

  • DPI: Higher DPI = longer processing time
  • Passes: More passes = longer processing time
  • Adaptive: Adds ~10-20% processing time
  • Quality Check: Adds ~5-10% processing time

Typical processing times (on modern hardware):

  • 10-page document: 10-30 seconds
  • 50-page document: 1-3 minutes
  • 100-page document: 3-6 minutes

Limitations

  • Free Version Limits: 25MB input, 20 pages maximum
  • Memory: Large PDFs may require significant RAM
  • Poppler Required: Must have Poppler installed
  • PDF Features: Some advanced PDF features may be lost (forms, annotations, etc.)

Need More Features?

The free CLI version provides core compression functionality. For advanced features like:

  • Drag-and-drop interface
  • Batch processing with queue management
  • Preset configurations
  • No file size/page limits
  • Priority support

Check out QuantPDF Pro (GUI version): https://quantpdf.com