{"id":28352075,"url":"https://github.com/xy-liao/jp2forge","last_synced_at":"2026-03-12T21:12:10.205Z","repository":{"id":290997635,"uuid":"973029846","full_name":"xy-liao/jp2forge","owner":"xy-liao","description":"JP2Forge is a specialized Python library for high-quality JPEG2000 image conversion with BnF (Bibliothèque nationale de France) compliance. It provides sophisticated compression capabilities including lossless, lossy, and supervised modes with intelligent quality assessment through PSNR and SSIM metrics. ","archived":false,"fork":false,"pushed_at":"2025-08-11T19:45:03.000Z","size":359,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-31T06:27:41.540Z","etag":null,"topics":["bnf-compliance","digital-preservation","image-conversion","image-processing","jpeg2000","python-library"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xy-liao.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-26T05:28:00.000Z","updated_at":"2025-06-21T15:08:51.000Z","dependencies_parsed_at":"2025-05-01T20:23:17.519Z","dependency_job_id":"a10864e2-ffb2-4be0-90a2-e958876da50d","html_url":"https://github.com/xy-liao/jp2forge","commit_stats":null,"previous_names":["xy-liao/jp2forge"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/xy-liao/jp2forge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xy-liao%2Fjp2forge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xy-liao%2Fjp2forge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xy-liao%2Fjp2forge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xy-liao%2Fjp2forge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xy-liao","download_url":"https://codeload.github.com/xy-liao/jp2forge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xy-liao%2Fjp2forge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30444406,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T20:23:30.529Z","status":"ssl_error","status_checked_at":"2026-03-12T20:23:14.027Z","response_time":114,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bnf-compliance","digital-preservation","image-conversion","image-processing","jpeg2000","python-library"],"created_at":"2025-05-27T23:04:45.375Z","updated_at":"2026-03-12T21:12:10.174Z","avatar_url":"https://github.com/xy-liao.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JP2Forge\n\n[![PyPI version](https://badge.fury.io/py/jp2forge.svg)](https://badge.fury.io/py/jp2forge) [![Version: 0.9.7](https://img.shields.io/badge/Version-0.9.7-blue.svg)](https://github.com/xy-liao/jp2forge/releases/tag/v0.9.7) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Python 3.8–3.12](https://img.shields.io/badge/python-3.8--3.12-blue.svg)](https://www.python.org/downloads/) [![Project Status: Active](https://img.shields.io/badge/Project%20Status-Active-green.svg)](https://github.com/xy-liao/jp2forge) [![Security: SonarQube Compliant](https://img.shields.io/badge/Security-SonarQube%20Compliant-brightgreen.svg)](https://www.sonarsource.com/products/sonarqube/)\n\nJP2Forge is a comprehensive Python tool for converting images to JPEG2000 format with support for standard and BnF (Bibliothèque nationale de France) compliant workflows.\n\n**Key capabilities:**\n- High-quality JPEG2000 conversion with multiple compression modes\n- BnF-compliant processing for cultural heritage digitization\n- Parallel processing for efficient batch operations\n- Quality analysis and validation with PSNR/SSIM metrics\n- Multi-page TIFF support with automatic page extraction\n- Comprehensive metadata preservation and XMP integration\n\n## Quick Start\n\n### Installation\n\n#### Option 1: From Source (Recommended for Development)\n\n```bash\n# Clone repository\ngit clone https://github.com/xy-liao/jp2forge.git\ncd jp2forge\n\n# Create and activate virtual environment\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install core dependencies\npip install -r requirements.txt\n\n# Optional: Install benchmarking dependencies\npip install jp2forge[benchmarking]\n\n# Install ExifTool (required for metadata operations)\n# macOS:\nbrew install exiftool\n# Linux:\n# sudo apt-get install libimage-exiftool-perl\n# Windows:\n# Download from https://exiftool.org/ and follow installation instructions\n```\n\n#### Option 2: Via pip (Recommended for Users)\n\n```bash\npip install jp2forge\n# Install ExifTool separately (see above)\n```\n\n### Basic Usage\n\n```bash\n# Convert a single file\npython -m cli.workflow input.tif output_dir/\n\n# Process a directory with parallel processing\npython -m cli.workflow input_dir/ output_dir/ --parallel --max-workers 4\n\n# BnF-compliant conversion\npython -m cli.workflow input_dir/ output_dir/ --bnf-compliant\n```\n\n### Verifying Your Installation\n\nTo verify that everything is set up correctly:\n\n```bash\n# Make the test script executable\nchmod +x test_jp2forge.sh\n\n# Run the test script\n./test_jp2forge.sh\n```\n\nThis test script validates JP2Forge by processing images in three different scenarios and checking the outputs.\n\n## Key Features\n\n- **Multiple Compression Modes**: Lossless, lossy, supervised, and BnF-compliant\n- **BnF Standards Support**: Fixed ratios, standard parameters, XMP metadata in UUID box\n- **Advanced Parallel Processing**: Adaptive worker pool with resource monitoring\n- **Memory-Efficient Processing**: Handles large files via streaming and chunking\n- **Multi-page Document Support**: Automatic handling of multi-page TIFF files\n- **Quality Analysis**: PSNR, SSIM, and MSE measurements\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [User Guide](docs/user_guide.md) | Comprehensive guide for end users |\n| [CLI Reference](docs/cli_reference.md) | Complete command-line interface reference |\n| [Developer Guide](docs/developer_guide.md) | Information for developers and contributors |\n| [API Reference](docs/api_reference.md) | Core classes and functions reference |\n| [BnF Compliance](docs/bnf_compliance.md) | Details about BnF compliance features |\n| [Examples](examples/README.md) | Code examples for API usage |\n\n## Command Reference\n\n### Document Types\n\n```bash\npython -m cli.workflow input_dir/ output_dir/ --document-type photograph\n```\n\n- `photograph`: Standard photographic images (default)\n- `heritage_document`: Historical documents with high-quality settings\n- `color`: General color images\n- `grayscale`: Grayscale images\n\n### Compression Modes\n\n```bash\npython -m cli.workflow input_dir/ output_dir/ --compression-mode supervised\n```\n\n- `supervised`: Quality-controlled compression (default)\n- `lossless`: No data loss\n- `lossy`: Higher compression with data loss\n- `bnf_compliant`: BnF standards with fixed ratios\n\n### BnF Mode\n\n```bash\npython -m cli.workflow input_dir/ output_dir/ --bnf-compliant --metadata bnf_metadata.json\n```\n\n## Common Options\n\nFor a complete list of all options, see the [CLI Reference](docs/cli_reference.md).\n\n| Option | Description |\n|--------|-------------|\n| `--parallel` | Enable parallel processing |\n| `--max-workers N` | Set number of worker threads |\n| `--memory-limit MB` | Set memory limit for large files |\n| `--verbose` | Enable detailed logging |\n| `--log-file PATH` | Save logs to file |\n| `--config PATH` | Use configuration file |\n| `--full-report` | Generate detailed reports with quality metrics |\n\n## Current Status and Roadmap\n\nJP2Forge is production-ready with comprehensive JPEG2000 conversion capabilities. Recent improvements include:\n\n**✅ Completed (v0.9.6+):**\n- Refactored codebase with eliminated code duplication\n- Shared utility modules for better maintainability\n- Enhanced error handling and progress tracking\n- Comprehensive testing infrastructure\n- Publication-ready codebase structure\n\n**🔄 Ongoing Development:**\n- Comprehensive unit test coverage expansion\n- Performance optimization for large datasets\n- Docker containerization support\n- Extended BnF validation features\n\n## Troubleshooting\n\nSee the [Troubleshooting Guide](docs/user_guide.md#11-troubleshooting) for common issues and solutions.\n\n\n## License\n\nJP2Forge is released under the MIT License.\n\n## Related Project\n\n- **[JP2Forge Web](https://github.com/xy-liao/jp2forge_web)**: A web interface for the JP2Forge JPEG2000 conversion library.\n\n## Use Cases\n\nJP2Forge is designed for:\n- **Cultural Heritage Institutions**: Museums, libraries, and archives digitizing collections\n- **Academic Research**: Digital humanities projects requiring high-quality image preservation\n- **BnF Compliance**: Organizations following Bibliothèque nationale de France standards\n- **Batch Processing**: Efficient conversion of large image datasets\n- **Quality Control**: Projects requiring rigorous quality analysis and validation\n\n## Acknowledgments\n\nThis project follows technical requirements described in BnF reference documents:\n- BnF Referential (2015): [PDF](https://www.bnf.fr/sites/default/files/2018-11/ref_num_fichier_image_v2.pdf)\n- BnF Documentation (2021): [PDF](https://www.bnf.fr/sites/default/files/2021-04/politiqueFormatsDePreservationBNF_20210408.pdf)\n\nJP2Forge serves the digital humanities community and cultural heritage institutions worldwide.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxy-liao%2Fjp2forge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxy-liao%2Fjp2forge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxy-liao%2Fjp2forge/lists"}