jp2forge 0.9.8

A comprehensive JPEG2000 processing tool with BnF compatibility

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

Document	Description
User Guide	Comprehensive guide for end users
CLI Reference	Complete command-line interface reference
Developer Guide	Information for developers and contributors
API Reference	Core classes and functions reference
BnF Compliance	Details about BnF compliance features
Examples	Code examples for API usage

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.

Option	Description
--parallel	Enable parallel processing
--max-workers N	Set number of worker threads
--memory-limit MB	Set memory limit for large files
--verbose	Enable detailed logging
--log-file PATH	Save logs to file
--config PATH	Use configuration file
--full-report	Generate detailed reports with quality metrics

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.