{"id":31727147,"url":"https://github.com/antilneeraj/huffmancompressor","last_synced_at":"2026-04-14T18:33:48.412Z","repository":{"id":310242008,"uuid":"1037498800","full_name":"antilneeraj/HuffmanCompressor","owner":"antilneeraj","description":"A simple, lossless text file compressor and decompressor built in Java using Huffman Coding. It shrinks files by giving shorter codes to frequent characters, and restores them exactly when decompressed. Features include a command‑line interface, clean modular design, and efficient bit‑level file handling","archived":false,"fork":false,"pushed_at":"2025-08-16T17:47:52.000Z","size":138,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-16T19:14:21.693Z","etag":null,"topics":["algorithms","binary-compression","cli-tool","compression-algorithm","data-compression","education","file-compression","file-io","gradle","huffman-coding","java","lossless-compression","open-source","text-compression"],"latest_commit_sha":null,"homepage":"","language":"Java","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/antilneeraj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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-08-13T17:01:00.000Z","updated_at":"2025-08-16T17:32:53.000Z","dependencies_parsed_at":"2025-08-16T19:14:25.263Z","dependency_job_id":"364575c5-9a1c-480f-b5b1-dae3c1a74735","html_url":"https://github.com/antilneeraj/HuffmanCompressor","commit_stats":null,"previous_names":["antilneeraj/huffmancompressor"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/antilneeraj/HuffmanCompressor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antilneeraj%2FHuffmanCompressor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antilneeraj%2FHuffmanCompressor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antilneeraj%2FHuffmanCompressor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antilneeraj%2FHuffmanCompressor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/antilneeraj","download_url":"https://codeload.github.com/antilneeraj/HuffmanCompressor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antilneeraj%2FHuffmanCompressor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000852,"owners_count":26082950,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["algorithms","binary-compression","cli-tool","compression-algorithm","data-compression","education","file-compression","file-io","gradle","huffman-coding","java","lossless-compression","open-source","text-compression"],"created_at":"2025-10-09T06:18:40.288Z","updated_at":"2025-10-09T06:18:43.127Z","avatar_url":"https://github.com/antilneeraj.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Text File Compression and Decompression Using Huffman Coding\n\n[![Java](https://img.shields.io/badge/Java-21+-orange.svg)](https://www.oracle.com/java/)\n[![Gradle](https://img.shields.io/badge/Gradle-8.14-green.svg)](https://gradle.org/)\n[![License](https://img.shields.io/badge/License-MIT-blue.svg)](#license)\n\n\u003cimg width=\"1232\" height=\"670\" alt=\"Compression Ratio Graph\" src=\"https://github.com/user-attachments/assets/de7d0e24-55fa-48dc-820a-90ba08309fc4\" /\u003e\n\n## Table of Contents\n\n- [Introduction](#introduction)\n- [Highlights](#highlights)\n- [Objective](#objective)\n- [Methodology](#methodology)\n- [Software and Libraries Used](#software-and-libraries-used)\n- [Directory Structure](#directory-structure)\n- [Project Flow Diagram](#project-flow-diagram)\n- [Usage](#usage)\n- [Setup](#setup)\n    - [Prerequisites](#prerequisites)\n    - [Building the Project](#building-the-project)\n    - [Setting up Aliases (Windows)](#setting-up-aliases-windows)\n- [Examples](#examples)\n- [Future Work](#future-work)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Introduction\n\nThis project implements a **lossless text file compression and decompression tool** using the **Huffman Coding algorithm**.\nThe tool can efficiently compress text files by assigning variable-length binary codes to characters based on their\nfrequency of occurrence, achieving compression ratios of typically 40-50% for text files.\n\nHuffman Coding is a greedy algorithm that builds an optimal prefix code tree, ensuring that no code is a prefix of\nanother, making the compressed data uniquely decodable without data loss.\n\n---\n\n## Highlights\n\n✅ **Lossless Compression** - Perfect reconstruction of original files  \n✅ **Variable-Length Encoding** - More frequent characters get shorter codes  \n✅ **Optimal Compression** - Uses Huffman's greedy algorithm for optimal prefix codes  \n✅ **Cross-Platform** - Works on Windows, macOS, and Linux  \n✅ **CLI Interface** - Easy-to-use command-line interface  \n✅ **Modular Design** - Clean separation of concerns with dedicated classes  \n✅ **Comprehensive Tests** - Unit and integration tests for reliability  \n✅ **Optimized File Format** - Minimal header overhead for better compression ratios\n\n---\n\n## Objective\n\nThe primary objectives of this project are to:\n\n1. **Demonstrate the practical implementation** of Huffman Coding algorithm in Java\n2. **Achieve significant compression** of text files while maintaining data integrity\n3. **Provide a user-friendly CLI tool** for file compression and decompression\n4. **Showcase software engineering best practices** including modular design, testing, and documentation\n5. **Create an educational resource** for understanding lossless compression algorithms\n\n---\n\n## Methodology\n\nThe compression process follows these key steps:\n\n### Compression\n\n1. **Frequency Analysis** - Calculate frequency of each character in the input file\n2. **Huffman Tree Construction** - Build optimal binary tree using a min-heap (priority queue)\n3. **Code Generation** - Assign binary codes: '0' for left branches, '1' for right branches\n4. **File Header Creation** - Store character frequencies for decompression\n5. **Bit-Level Encoding** - Replace characters with their Huffman codes and pack into bytes\n\n### Decompression\n\n1. **Header Parsing** - Read character frequencies from compressed file\n2. **Tree Reconstruction** - Rebuild the Huffman tree using stored frequencies\n3. **Bit-by-Bit Decoding** - Traverse tree according to bits until leaf nodes are reached\n4. **Character Output** - Write decoded characters to output file\n\n### Key Algorithms Used\n\n- **Min-Heap (Priority Queue)** - For efficient tree construction\n- **Greedy Algorithm** - Huffman's approach for optimal code assignment\n- **Binary Tree Traversal** - For code generation and decoding\n- **Bit Manipulation** - For efficient binary I/O operations\n\n---\n## Project Flow Diagram\n[![](https://mermaid.ink/img/pako:eNqVVN1u0zAUfhXLF2xIacl_2jB6MZcxLtDQVoREwoWbnLaREqc49lipersH4BF5Ek7idTIS2sAXPv75zt93jr2nRVsCTela8u2GLOa5IDg6vTQHcyjaZiuh66pWkI-yLXBpMP2Ye1lOz8rqlnRqV8ObEwV3avQdVdN-en0yuwZekkucQJLTCwnfNIhiRxZ8WcPLs1eoOsvpV8uin13DUlc1aunVquGCLCSAjQiywehb0YdekvNKdUoCb2xMmC0kvwXZwaBOXgyZlDCgbWD0XAKfZaXA4gE9LhBDVEuutNpqZSVhE0NGoxlmY0RgRGhEZHAgyqPKI9_sKbaZZzJ_L9CtieKiqm1umJ8xXhe65hgz23BJjpRXYKfNguz8KY5Z-Bwt70CA7L0cLTBktyOng9Nf9z97osmNkpVY_63M7B95_4_OYXFmWsIw86lD139GZ4OTzDiwu6iv6QOhNulD0ZipJDOVZKaSLDIiNiKx6kod2oBseFXi49r3FzlVG2ggpykuBWgleZ3TXBwQyrVqb3aioKmSGhwqW73e0HTF6w53elsi0_OKY480j6dbLr60bXNUwS1N9_SOpp7rjoM4mnpR4vmu5we-Q3c0DeNx4vthnCRT18fhHRz6YzDgjifxxI9DbzoJ3ACvIgf_gz7yh2gwI5Cs1UKhdQQ5FMpKtfKD-TuGL-TwG5zoULs?type=png)](https://mermaid.live/edit#pako:eNqVVN1u0zAUfhXLF2xIacl_2jB6MZcxLtDQVoREwoWbnLaREqc49lipersH4BF5Ek7idTIS2sAXPv75zt93jr2nRVsCTela8u2GLOa5IDg6vTQHcyjaZiuh66pWkI-yLXBpMP2Ye1lOz8rqlnRqV8ObEwV3avQdVdN-en0yuwZekkucQJLTCwnfNIhiRxZ8WcPLs1eoOsvpV8uin13DUlc1aunVquGCLCSAjQiywehb0YdekvNKdUoCb2xMmC0kvwXZwaBOXgyZlDCgbWD0XAKfZaXA4gE9LhBDVEuutNpqZSVhE0NGoxlmY0RgRGhEZHAgyqPKI9_sKbaZZzJ_L9CtieKiqm1umJ8xXhe65hgz23BJjpRXYKfNguz8KY5Z-Bwt70CA7L0cLTBktyOng9Nf9z97osmNkpVY_63M7B95_4_OYXFmWsIw86lD139GZ4OTzDiwu6iv6QOhNulD0ZipJDOVZKaSLDIiNiKx6kod2oBseFXi49r3FzlVG2ggpykuBWgleZ3TXBwQyrVqb3aioKmSGhwqW73e0HTF6w53elsi0_OKY480j6dbLr60bXNUwS1N9_SOpp7rjoM4mnpR4vmu5we-Q3c0DeNx4vthnCRT18fhHRz6YzDgjifxxI9DbzoJ3ACvIgf_gz7yh2gwI5Cs1UKhdQQ5FMpKtfKD-TuGL-TwG5zoULs)\n\n---\n\n## Software and Libraries Used\n\n| Technology        | Version  | Purpose                                    |\n|-------------------|----------|--------------------------------------------|\n| **Java**          | 21.0.5   | Core programming language                  |\n| **Gradle**        | 8.14     | Build automation and dependency management |\n| **JUnit 5**       | 5.10.0   | Unit testing framework                     |\n| **IntelliJ IDEA** | 2024.2.6 | Integrated Development Environment         |\n\n### Core Java Libraries\n\n- `java.util.PriorityQueue` - Min-heap for Huffman tree construction\n- `java.util.HashMap` - Frequency counting and code mapping\n- `java.io.*` - File I/O operations\n- `java.nio.file.*` - Modern file handling\n\n---\n\n## Directory Structure\n\n```\nHuffmanCompressor/\n│\n├── build.gradle.kts       # Gradle Kotlin DSL build configuration\n├── settings.gradle.kts    # Gradle project settings (rootProject.name, etc.)\n├── README.md              # Project documentation\n├── .gitignore             # Git ignore rules\n├── out/                   # \u003c-- Gradle build outputs (ignored by git)\n│   ├── classes/\n│   │   ├── java/\n│   │   │   ├── main/              # Compiled main source .class files\n│   │   │   └── test/              # Compiled test .class files\n│   ├── libs/                      # Built JAR files\n│   ├── reports/                   # Test + build reports\n│   └── ...\n│\n├── src/\n│   ├── main/\n│   │   ├── java/\n│   │   │   └── com/\n│   │   │       └── huffman/\n│   │   │           ├── Main.java               # Entry point class\n│   │   │           ├── HuffmanNode.java        # Tree node class\n│   │   │           ├── HuffmanEncoder.java     # Compression engine\n│   │   │           ├── HuffmanDecoder.java     # Decompression engine\n│   │   │           ├── FileHandler.java        # File I/O utilities\n│   │   │           └── BitWriterReader.java    # Bit-level write/read helper\n│   │   └── resources/\n│   │       ├── sample.txt           # Test input file \n│   │\n│   └── test/\n│       ├── java/\n│       │   └── com/\n│       │       └── huffman/\n│       │           ├── HuffmanEncoderTest.java\n│       │           ├── HuffmanDecoderTest.java\n│       │           └── FileHandlerTest.java\n│       └── resources/\n│           └── test_sample.txt\n│\n└── gradle/                 # Gradle wrapper files\n│   └── wrapper/\n│       ├── gradle-wrapper.jar\n│       └── gradle-wrapper.properties\n└── ...\n```\n---\n## Usage\n\n### Command Line Interface\n\n#### Compress a file:\n\n```bash\njava -jar out/libs/HuffmanCompressor-1.0-SNAPSHOT.jar compress input.txt compressed.bin\n```\n\n#### Decompress a file:\n\n```bash\njava -jar out/libs/HuffmanCompressor-1.0-SNAPSHOT.jar decompress compressed.bin restored.txt\n```\n\n### Using Gradle Tasks (Development)\n\n### Compress\n\n```bash\n./gradlew runHuffman --args=\"compress input.txt output.bin\"\n```\n\n### Decompress\n\n```bash\n./gradlew runHuffman --args=\"decompress output.bin restored.txt\"\n```\n\n---\n\n## Setup\n\n### Prerequisites\n\n- **Java Development Kit (JDK) 17 or higher**\n- **Git** (for cloning the repository)\n- **Windows PowerShell** or **Command Prompt** (Windows users)\n\n### Building the Project\n\n1. **Clone the repository:**\n```bash\ngit clone https://github.com/antilneeraj/HuffmanCompressor.git\ncd HuffmanCompressor\n```\n\n2. **Build the project:**\n```bash\n./gradlew clean build\n```\n\n3. **Run tests:**\n```bash\n./gradlew test \n```\n\n4. **The executable JAR will be generated at:** `out/libs/HuffmanCompressor-1.0-SNAPSHOT.jar`\n\n### Setting up Aliases (Windows)\n\nFor convenient usage, set up PowerShell aliases:\n\n1. **Open PowerShell as Administrator**\n\n2. **Create/Edit your PowerShell profile:**\n```bash\nnotepad $profile\n```\n\n3. **Add these functions to the profile:**\n```bash\nfunction huffc {\nparam($inputFile, $outputFile)\njava -jar \"C:\\path\\to\\your\\project\\out\\libs\\HuffmanCompressor-1.0-SNAPSHOT.jar\" compress $inputFile $outputFile\n}\n\nfunction huffd {\nparam($inputFile, $outputFile)\njava -jar \"C:\\path\\to\\your\\project\\out\\libs\\HuffmanCompressor-1.0-SNAPSHOT.jar\" decompress $inputFile $outputFile\n}\n```\n\n*Replace `C:\\path\\to\\your\\project\\` with your actual project path*\n\n4. **Save and reload your profile:**\n```bash\n. $profile\n```\n\n5. **Now you can use short commands:**\n```bash\nhuffc input.txt compressed.bin\nhuffd compressed.bin restored.txt\n```\n\n---\n\n## Examples\n\n### Basic Compression Example\n\n### 1. Create a Sample Text File\n\n```bash\necho \"This is a sample text file for Huffman compression testing.\" \u003e sample.txt\n```\n### Compress the file\n```bash\njava -jar out/libs/HuffmanCompressor-1.0-SNAPSHOT.jar compress sample.txt sample.bin\n```\n### Check compression ratio\n`Original: ~62 bytes, Compressed: ~35-40 bytes (typical 35-45% reduction)`\n\n### Decompress back\n```bash\njava -jar out/libs/HuffmanCompressor-1.0-SNAPSHOT.jar decompress sample.bin recovered.txt\n```\n### Verify integrity\n```bash\nfc sample.txt recovered.txt # Windows\ndiff sample.txt recovered.txt # Linux/macOS\n```\n\n### Performance Characteristics\n- **Compression Ratio:** 35-50% size reduction for typical text files\n- **Time Complexity:** O(n log k) where n = file size, k = unique characters\n- **Space Complexity:** O(k) for storing the Huffman tree\n- **File Types:** Works best with `.txt`, `.java`, `.html`, `.css`, `.js`, etc.\n\n---\n\n## Future Work\n### Planned Enhancements\n- [ ] **GUI Interface** - Develop a user-friendly graphical interface\n- [ ] **Batch Processing** - Support for compressing multiple files at once\n- [ ] **Directory Compression** - Compress entire folders recursively\n- [ ] **Compression Statistics** - Detailed reports on compression ratios and performance\n- [ ] **Advanced Algorithms** - Implement LZ77, LZW, or hybrid compression methods\n- [ ] **Binary File Support** - Extend support to non-text file types\n- [ ] **Progress Indicators** - Show compression/decompression progress for large files\n- [ ] **Compression Level Options** - Different optimization levels for speed vs. ratio trade-offs\n\n### Algorithmic Improvements\n- [ ] **Adaptive Huffman Coding** - Update tree dynamically as file is processed\n- [ ] **Canonical Huffman Codes** - More efficient code representation\n- [ ] **Multi-threading** - Parallel processing for large files\n- [ ] **Memory Optimization** - Streaming compression for files larger than available RAM\n\n---\n\n## Contributing\n\nContributions are welcome! Please feel free to submit issues, suggestions, or pull requests.\n\n### How to Contribute\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Development Guidelines\n- Follow Java coding conventions\n- Write unit tests for new features\n- Update documentation as needed\n- Ensure all tests pass before submitting\n\n---\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE)\n\n---\n\n## Acknowledgments\n\n- **David A. Huffman** - For the Huffman Coding algorithm (1952)\n- **GeeksforGeeks** - For algorithmic reference and inspiration\n- **Java Community** - For excellent documentation and libraries\n\n---\n\n*⭐ If you found this project helpful, please consider giving it a star!*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantilneeraj%2Fhuffmancompressor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fantilneeraj%2Fhuffmancompressor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantilneeraj%2Fhuffmancompressor/lists"}