JP2Forge

JP2Forge is a comprehensive Python tool for converting images to JPEG2000 format with support for standard and BnF (Bibliothèque nationale de France) compliant workflows.

Key capabilities:

• High-quality JPEG2000 conversion with multiple compression modes
• BnF-compliant processing for cultural heritage digitization
• Parallel processing for efficient batch operations
• Quality analysis and validation with PSNR/SSIM metrics
• Multi-page TIFF support with automatic page extraction
• Comprehensive metadata preservation and XMP integration

Quick Start

Installation

Option 1: From Source (Recommended for Development)

# Clone repository
git clone https://github.com/xy-liao/jp2forge.git
cd jp2forge

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install core dependencies
pip install -r requirements.txt

# Optional: Install benchmarking dependencies
pip install jp2forge[benchmarking]

# Install ExifTool (required for metadata operations)
# macOS:
brew install exiftool
# Linux:
# sudo apt-get install libimage-exiftool-perl
# Windows:
# Download from https://exiftool.org/ and follow installation instructions

Option 2: Via pip (Recommended for Users)

pip install jp2forge
# Install ExifTool separately (see above)

Basic Usage

# Convert a single file
python -m cli.workflow input.tif output_dir/

# Process a directory with parallel processing
python -m cli.workflow input_dir/ output_dir/ --parallel --max-workers 4

# BnF-compliant conversion
python -m cli.workflow input_dir/ output_dir/ --bnf-compliant

Verifying Your Installation

To verify that everything is set up correctly:

# Make the test script executable
chmod +x test_jp2forge.sh

# Run the test script
./test_jp2forge.sh

This test script validates JP2Forge by processing images in three different scenarios and checking the outputs.

Key Features

• Multiple Compression Modes: Lossless, lossy, supervised, and BnF-compliant
• BnF Standards Support: Fixed ratios, standard parameters, XMP metadata in UUID box
• Advanced Parallel Processing: High-throughput persistent worker pool with resource monitoring
• Memory-Efficient Processing: Handles large files via single-pass crop-and-paste chunking
• Multi-page Document Support: Automatic handling of multi-page TIFF files
• Quality Analysis: PSNR, SSIM, and MSE measurements

Documentation

Command Reference

Document Types

python -m cli.workflow input_dir/ output_dir/ --document-type photograph

• photograph: Standard photographic images (default)
• heritage_document: Historical documents with high-quality settings
• color: General color images
• grayscale: Grayscale images

Compression Modes

python -m cli.workflow input_dir/ output_dir/ --compression-mode supervised

• supervised: Quality-controlled compression (default)
• lossless: No data loss
• lossy: Higher compression with data loss
• bnf_compliant: BnF standards with fixed ratios

BnF Mode

python -m cli.workflow input_dir/ output_dir/ --bnf-compliant --metadata bnf_metadata.json

Common Options

For a complete list of all options, see the CLI Reference.

Current Status and Roadmap

JP2Forge is production-ready with comprehensive JPEG2000 conversion capabilities. Recent improvements include:

✅ Completed (v0.9.6+):

• Refactored codebase with eliminated code duplication
• Shared utility modules for better maintainability
• Enhanced error handling and progress tracking
• Comprehensive testing infrastructure
• Publication-ready codebase structure

🔄 Ongoing Development:

• Comprehensive unit test coverage expansion
• Performance optimization for large datasets
• Docker containerization support
• Extended BnF validation features

Troubleshooting

See the Troubleshooting Guide for common issues and solutions.

License

JP2Forge is released under the MIT License.

Related Project

• JP2Forge Web: A web interface for the JP2Forge JPEG2000 conversion library.

Use Cases

JP2Forge is designed for:

• Cultural Heritage Institutions: Museums, libraries, and archives digitizing collections
• Academic Research: Digital humanities projects requiring high-quality image preservation
• BnF Compliance: Organizations following Bibliothèque nationale de France standards
• Batch Processing: Efficient conversion of large image datasets
• Quality Control: Projects requiring rigorous quality analysis and validation

Acknowledgments

This project follows technical requirements described in BnF reference documents:

• BnF Referential (2015): PDF
• BnF Documentation (2021): PDF

JP2Forge serves the digital humanities community and cultural heritage institutions worldwide.