{"id":51536636,"url":"https://github.com/jeiel85/minimal-zip-concept","last_synced_at":"2026-07-09T09:01:20.899Z","repository":{"id":362387171,"uuid":"1258341927","full_name":"jeiel85/minimal-zip-concept","owner":"jeiel85","description":"Minimal Zip Concept (MZC) - Learning-oriented lossless compression engine in Rust featuring RLE, Dictionary, LZ77, BCJ, Delta, and Dynamic Huffman Coding with a real-time GUI plot dashboard.","archived":false,"fork":false,"pushed_at":"2026-06-18T02:51:49.000Z","size":3873,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-18T04:25:02.916Z","etag":null,"topics":["ans","compression","context-mixing","egui","gui","huffman-coding","learning-by-doing","lossless-compression","lz77","plots-dashboard","preprocessors","rust","simd","visualizer","wasm"],"latest_commit_sha":null,"homepage":"https://jeiel85.github.io/minimal-zip-concept/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jeiel85.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-03T13:43:37.000Z","updated_at":"2026-06-18T02:51:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jeiel85/minimal-zip-concept","commit_stats":null,"previous_names":["jeiel85/minimal-zip-concept"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jeiel85/minimal-zip-concept","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeiel85%2Fminimal-zip-concept","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeiel85%2Fminimal-zip-concept/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeiel85%2Fminimal-zip-concept/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeiel85%2Fminimal-zip-concept/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jeiel85","download_url":"https://codeload.github.com/jeiel85/minimal-zip-concept/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeiel85%2Fminimal-zip-concept/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35293217,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-09T02:00:07.329Z","response_time":57,"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":["ans","compression","context-mixing","egui","gui","huffman-coding","learning-by-doing","lossless-compression","lz77","plots-dashboard","preprocessors","rust","simd","visualizer","wasm"],"created_at":"2026-07-09T09:01:19.743Z","updated_at":"2026-07-09T09:01:20.890Z","avatar_url":"https://github.com/jeiel85.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MZC (Minimal Zip Concept)\n\n\u003cdiv align=\"center\"\u003e\n  \u003ch3\u003e\u003ca href=\"README.md\"\u003e🇰🇷 한국어\u003c/a\u003e | \u003ca href=\"README_EN.md\"\u003e🌐 English\u003c/a\u003e\u003c/h3\u003e\n\u003c/div\u003e\n\nMZC는 Rust 학습과 압축 알고리즘 작동 원리의 이해를 병행하기 위해 직접 설계한 무손실 압축 포맷 및 CLI/GUI 도구입니다.\n상용 압축 알고리즘(ZIP, Zstandard, Brotli 등)을 능가하는 것이 목표가 아니라, 바이트 정합성과 무손실 복원의 원리를 명확하게 구현하고 점진적인 포맷 고도화 단계를 실습하는 데 초점을 맞추었습니다.\n\n\u003cdiv align=\"center\"\u003e\n\n[![Try it in your browser](https://img.shields.io/badge/Try%20it%20in%20your%20browser-WASM%20Demo-brightgreen?style=for-the-badge\u0026logo=webassembly\u0026logoColor=white)](https://jeiel85.github.io/minimal-zip-concept/)\n[![Crates.io](https://img.shields.io/crates/v/mzc.svg?style=for-the-badge\u0026color=orange)](https://crates.io/crates/mzc)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge)](https://github.com/jeiel85/minimal-zip-concept)\n[![Codecov](https://img.shields.io/codecov/c/github/jeiel85/minimal-zip-concept?style=for-the-badge\u0026logo=codecov)](https://codecov.io/gh/jeiel85/minimal-zip-concept)\n\n\u003cbr/\u003e\n\n### 🚀 **[Try MZC Interactive LZ77 Visualizer \u0026 WASM Demo! (웹 브라우저에서 바로 해보기)](https://jeiel85.github.io/minimal-zip-concept/)**\n\n![MZC Interactive LZ77 sliding window visualizer](assets/mzc_lz77_visualizer.png)\n\n*MZC Web Demo - Interactive LZ77 Sliding Window Visualizer*\n\n\u003c/div\u003e\n\n---\n\n## 1. MZC 아키텍처 및 마일스톤 변천사 (MZC1 ~ MZC7)\n\nMZC는 단순한 RLE 압축기로 시작하여 최상위 비트 레벨 패킹 및 컨텍스트 믹싱 사양까지 점진적으로 진화해 왔습니다.\n\n### 1.1 MZC1 (Retro RLE Spec)\n- **알고리즘**: 단순 Run-Length Encoding\n- **헤더 규격**: 54바이트 고정 헤더\n- **동작**: 연속적으로 4번 이상 반복되는 바이트 흐름을 `Value`와 `Count` 조합으로 단순 기록. 데이터의 비압축 불규칙 흐름은 `Literal Block`으로 처리.\n\n### 1.2 MZC2 (Parallel Dictionary Spec)\n- **알고리즘**: Dictionary Hybrid + Rayon 멀티스레드 병렬화\n- **헤더 규격**: 56바이트 고정 헤더 (사전 테이블 크기 정보 2바이트 추가)\n- **동작**: 파일을 1MB 청크 단위로 나누어 멀티스레드로 각 스레드에서 병렬 압축. 자주 등장하는 바이트 시퀀스를 사전에 수집하여 토큰 인덱스로 대치 압축.\n\n### 1.3 MZC3 (Sliding Window Chunk Spec)\n- **알고리즘**: LZ77 + Huffman (정적 허프만 코딩)\n- **동작**: 32KB 크기 슬라이딩 윈도우 룩어헤드 내에서 이전 데이터와의 중복 영역을 감지하여 거리(Distance)와 길이(Length) 정보의 백레퍼런스로 코딩. 압축 효율 향상을 위해 정적 허프만 부호화를 2차 결합.\n\n### 1.4 MZC4 (Dynamic Huffman Spec)\n- **알고리즘**: Canonical Dynamic Huffman Tree\n- **동작**: 1KB 크기 이상의 정적 트리 헤더 오버헤드를 타파하기 위해, 실제 청크 파일에서 출현한 기호 빈도를 기준하여 Canonical Tree를 동적 생성. 트리의 코드길이 정보 자체를 Tree RLE 압축으로 묶어 단 20~40바이트의 초슬림 헤더를 실현.\n\n### 1.5 MZC5 (Bit-Packed Spec \u0026 Preprocessors)\n- **알고리즘**: 🪙 비트 레벨 플래그 패킹 + ⚡ 지연 매칭 + 🎹 BCJ / Delta 전처리 필터\n- **동작**:\n  - **Bit-level Stream Packing**: 블록마다 붙던 1바이트 접두사 타입 바이트를 전면 폐기하고, 압축 요소 8개씩 묶어 2바이트(16비트, 2비트 x 8) 플래그 스트림으로 직렬화하여 오버헤드 15~25% 감소.\n  - **Lazy Matching**: 그리디(Greedy) 방식 LZ77 탐색을 우회하여, 한 바이트 진행한 오프셋에서 더 긴 일치 항목이 출현할 시 현재 바이트는 리터럴로 보내고 더 긴 일치 정보를 인코딩.\n  - **Delta Preprocessor**: Wav, Bmp 등 인접 파형/바이트 간 차분값 계산으로 정보 엔트로피를 물리적으로 축소.\n  - **BCJ Preprocessor**: x86 바이너리의 Jump/Call 명령 상대 주소를 절대 주소로 대치 대칭시켜 데이터 반복률 유도.\n  - **Decompression Safety Verification**: 데이터 복원 시 유해한 깨진 데이터 오염이 발생하더라도 디코더에서 임의 크기 벡터 할당 및 인덱스 월경을 즉시 감지하여 차단하는 안전망 내장.\n\n### 1.6 MZC6 (Asymmetric Numeral Systems \u0026 Shared Dictionaries Spec)\n- **알고리즘**: Asymmetric Numeral Systems (tANS) + LZ77 Hash Chains + Global Shared Dictionary\n- **헤더 규격**: 56바이트 고정 헤더 (사전 크기 필드 재활용)\n- **동작**:\n  - **LZ77 Hash Chains**: 선형 탐색 대신 65,536개 크기의 해시 테이블을 도입하여 3바이트 접두사의 매칭 체인을 뒤쫓는 방식으로 $O(limit)$ 매칭 스캔 달성.\n  - **tANS (Table-based Asymmetric Numeral Systems)**: Huffman 코딩의 1비트 한계를 돌파하여 분수 비트 단위의 엔트로피 압축을 수행하는 최첨단 ANS 압축 엔진 내장 (`src/ans.rs`).\n  - **Global Shared Dictionary**: 개별 청크 내 사전을 중복 직렬화하지 않고, 파일 헤더 직후에 1회만 내장하여 공유하도록 개선.\n  - **Dictionary Training**: 여러 샘플 데이터셋으로부터 공통 바이트 시퀀스를 빌드하여 `.dict` 형태의 공유 사전을 사전 학습(Training)할 수 있는 CLI 기능 추가.\n\n### 1.7 MZC7 (Context Mixing \u0026 Media Filters Spec - 최신 사양)\n- **알고리즘**: 🧠 컨텍스트 믹싱 레인지 코더 (CM) + 🖼️ PNG Paeth 필터 + 🎧 LPC 오디오 필터 + ⚡ GZIP/DEFLATE 디코더\n- **헤더 규격**: 56바이트 고정 헤더 (MZC7 전용 비트 패킹 플래그 적용)\n- **동작**:\n  - **Context Mixing Range Coder**: 직전 비트 문맥을 0차, 1차, 2차(해시 직접 매핑)로 분할 분석하여 가중치 평균(1:2:5)으로 섞어 확률을 예측하고, 실수 하위 구간을 쪼개는 산술 레인지 코더를 결합하여 압축합니다 (`src/cm.rs`).\n  - **PNG Paeth Filter**: 이미지 픽셀 간의 2차원 공간적 중복성을 줄이기 위한 Paeth 그라디언트 예측 필터를 전처리로 적용합니다.\n  - **LPC Audio Filter**: 16비트 PCM 오디오 신호의 인접 시퀀스 흐름을 2차 선형 예측(Order-2 LPC)하여 그 잔차(Residual) 차분만 압축하도록 변환합니다.\n  - **RFC 1951/1952 DEFLATE \u0026 GZIP 디코더**: 표준 GZIP 형식 파일의 압축을 해제하여 원본 데이터를 복원해주는 디코더 모듈을 순수 Rust로 구현했습니다 (`src/deflate.rs`).\n\n---\n\n## 2. 압축 알고리즘 성능 벤치마크 (Benchmark)\n\nMZC7(컨텍스트 믹싱 및 미디어 필터) 사양을 기준으로 업계 표준 압축기(Gzip 및 Zstandard)와 비교한 무손실 압축률 벤치마크 결과입니다. (각 데이터셋 크기: 약 200KB)\n\n| 데이터셋 분류 | MZC1 (RLE) | MZC3 (LZ77) | MZC7 (Context Mixing) | Gzip (flate2 Default) | Zstd (Level 3) |\n| :--- | :---: | :---: | :---: | :---: | :---: |\n| 📝 **일반 텍스트 (Text)** | 100.04% | 6.84% | **9.37%** | 3.35% | 3.49% |\n| 🎧 **오디오 파일 (Audio)** | 100.04% | 83.72% | **35.20%** 🏆 | 75.73% | 70.06% |\n| 🖼️ **이미지 파일 (Image)** | 100.04% | 5.85% | **8.20%** | 3.86% | 5.02% |\n| 💻 **실행 파일 (Executable)** | 100.04% | 94.46% | **84.48%** | 82.90% | 75.41% |\n\n\u003e [!TIP]\n\u003e **오디오 데이터셋의 독보적인 압축률**: 오디오 파일(16-bit PCM WAV)의 경우, MZC7에 탑재된 **LPC(선형 예측) 필터**와 **산술 레인지 코더**의 결합을 통해 업계 표준인 Gzip(75.73%) 및 Zstd(70.06%) 대비 **35.20%**라는 압축 효율을 달성하여 압도적인 성능적 우위를 보여줍니다. 전체 포맷별 상세 벤치마크 비교 데이터는 [벤치마크 결과 명세서](docs/benchmark_results.md)를 참고하시기 바랍니다.\n\n### 2.1 내부 Criterion 벤치마크 (v0.11.1 SIMD 최적화)\n\nv0.11.1에서 적용된 **AVX2/NEON SIMD 가속** 및 **Radix Suffix Array** 최적화 후 `cargo bench` 결과입니다.\n\n| 벤치마크 | 소요 시간 | 이전 대비 변화 | 상태 |\n| :--- | :---: | :---: | :---: |\n| `compress_text/MZC2_LZ77` | 28.2 ms | **-36.1%** | ✅ 향상 |\n| `compress_repeats/MZC2_LZ77` | 6.76 ms | **-59.7%** | ✅ 향상 |\n| `compress_text/MZC4_Deflate` | 12.84 ms | **-63.7%** | ✅ 향상 |\n| `compress_repeats/MZC4_Deflate` | 6.39 ms | **-67.3%** | ✅ 향상 |\n| `compress_text/MZC5_tANS` | 12.99 ms | **-64.2%** | ✅ 향상 |\n| `compress_repeats/MZC5_tANS` | 21.78 ms | **-52.7%** | ✅ 향상 |\n| `compress_text/MZC7_CM` | 22.66 ms | **-48.5%** | ✅ 향상 |\n| `compress_repeats/MZC7_CM` | 10.67 ms | **-51.8%** | ✅ 향상 |\n| `micro/bwt_apply` | 1.37 ms | **-67.8%** | ✅ 향상 |\n| `micro/cm_compress` | 3.24 ms | **-61.5%** | ✅ 향상 |\n\n\u003e [!NOTE]\n\u003e **전 알고리즘 36~68% 속도 향상**: CM 레인지 코더의 가중치 혼합 루프에 AVX2 `_mm256_mullo_epi32` / NEON `vmulq_s32` SIMD 명령어를 적용하고, BWT 접미사 배열을 $O(N \\log N)$ Radix Sort 방식으로 교체한 결과입니다.\n\n\n---\n\n## 3. GUI 다중 탭 대시보드 탑재\n\n`egui` 및 `egui_plot`을 이용한 화려한 시각적 GUI 성능 진단 화면을 제공하며, 상단 탭을 통해 모드를 전환할 수 있습니다.\n- **Dashboard 탭**: \n  - **Rayon Thread Occupancy Gauge**: 압축 연산 시 내부 스레드 코어의 점유율 상태를 백분율 프로그레스바로 시각화.\n  - **실시간 Throughput/Ratio Curves**: 1MB 청크가 처리될 때마다 실시간 압축 속도(MB/s) 및 압축률(%) 곡선을 렌더링.\n  - **물리적 이진 그리드 맵**: 복원된 RLE, 토큰, 백레퍼런스, 리터럴 블록의 기하학적 분포를 캔버스상에 색상 그리드로 매핑.\n- **Trainer 탭**: 다수의 텍스트나 데이터를 로드하여 다용도 공유 사전(`.dict`)을 클릭 몇 번으로 쉽게 자동 학습하고 내보낼 수 있는 시각적 트레이너 위저드.\n- **tANS Plot 탭**: tANS 알고리즘 동작 중 입력 기호에 따른 상태 전이(State Transition) 과정을 애니메이션 기하학적 좌표 노드 플롯으로 렌더링 시뮬레이션.\n\n---\n\n## 4. 설치 및 빌드 방법\n\n### 4.1 사전 요구사항\n- [Rust 및 Cargo 도구 체인 설치](https://www.rust-lang.org/tools/install) (Edition 2021 지원)\n\n### 4.2 최신 릴리스 다운로드\n- 최신 버전: **v0.12.1**\n- Windows 설치 파일: [mzc-setup.exe](https://github.com/jeiel85/minimal-zip-concept/releases/download/v0.12.1/mzc-setup.exe)\n- 전체 릴리스 자산: [GitHub Releases](https://github.com/jeiel85/minimal-zip-concept/releases/tag/v0.12.1)\n\n### 4.3 빌드\n```bash\n# 릴리즈 실행 파일 컴파일 (target/release/mzc 생성)\ncargo build --release\n```\n\n---\n\n## 5. 실제 명령어 가이드\n\nMZC 엔진은 서브커맨드 기반 CLI 명령과 GUI 단독 실행 모드를 지원합니다.\n\n### 5.1 CLI 압축 (`compress`)\n```bash\n# MZC5 최상위 레벨 압축 실행 (레벨 9, Delta 전처리 활성화, BCJ 전처리 활성화)\n./target/release/mzc compress input_file.bin output_file.mzc -m lz77 -e dynamic -l 9 --delta --bcj\n\n# MZC6 tANS 및 사전 파일을 사용한 압축 실행\n./target/release/mzc compress input_file.bin output_file.mzc -m lz77 -e ans -l 6 --dict-file trained.dict\n\n# MZC7 컨텍스트 믹싱 및 PNG 필터를 사용한 압축 실행\n./target/release/mzc compress input_image.png output_file.mzc -m hybrid -e cm --png\n```\n\n### 5.2 CLI 압축 해제 (`decompress`)\n```bash\n# SHA-256 검증 및 자동 버전/필터 식별 디코딩 복원 (내장 전역 사전 자동 추출)\n./target/release/mzc decompress output_file.mzc restored_file.bin\n\n# 외부 사전을 지정하여 해제하는 경우 (옵션)\n./target/release/mzc decompress output_file.mzc restored_file.bin --dict-file trained.dict\n```\n\n### 5.3 CLI GZIP 압축 해제 (`inflate`)\n```bash\n# 표준 GZIP 포맷(.gz) 파일의 압축을 해제하여 복원\n./target/release/mzc inflate archive.gz restored_file.txt\n```\n\n### 5.4 CLI 사전 학습 (`train`)\n```bash\n# 다수의 샘플 파일들로부터 공통 패턴을 수집하여 trained.dict 파일로 학습 저장\n./target/release/mzc train samples/*.txt -o trained.dict\n```\n\n### 5.5 CLI 파일 검사 및 상세 정보 진단 (`inspect`)\n```bash\n./target/release/mzc inspect output_file.mzc\n```\n\n### 5.6 데스크톱 GUI 진단 대시보드 기동 (`gui`)\n```bash\n./target/release/mzc gui\n# 또는 cargo run -- gui\n```\n\n---\n\n## 6. 실행 예제 (Examples)\n\nMZC 라이브러리를 API 형태로 사용할 때 도움을 주는 실행 예제 코드가 `examples/` 디렉터리에 제공됩니다.\n\n* **기본 인메모리 압축 예제**: MZC API를 활용해 메모리 상에서 텍스트를 인코딩/디코딩합니다.\n  ```bash\n  cargo run --release --example simple_compression\n  ```\n* **공유 사전 학습 및 압축 예제**: 샘플 말뭉치로부터 패턴 사전을 학습 및 추출하여 사전 기반으로 텍스트를 압축합니다.\n  ```bash\n  cargo run --release --example shared_dictionary\n  ```\n* **점진적 압축 벤치마크 측정 예제**: 텍스트, 이미지, 사운드 파형, 실행 파일에 대해 MZC1부터 MZC7까지의 성능을 벤치마킹합니다.\n  ```bash\n  cargo run --release --example benchmark\n  ```\n\n---\n\n## 7. 공식 기술 규격서 및 성능 측정 보고서\n\n* **[MZC 파일 포맷 상세 기술 규격서 (docs/spec.md)](docs/spec.md)**: MZC1~MZC7의 이진 헤더 명세, RLE/LZ77/tANS/Context Mixing의 비트스트림 구조 및 전처리 필터 수학 공식을 수록했습니다.\n* **[MZC 압축 알고리즘 벤치마크 성능 보고서 (docs/benchmark_results.md)](docs/benchmark_results.md)**: 다양한 파일 도메인(Text, Audio, Image, Executable)에서의 압축률 및 소요 시간을 벤치마크 프로그램 구동 결과와 함께 기록했습니다.\n\n---\n\n## 8. 학습용 설계 아키텍처\n\nMZC는 모듈 간의 의존성이 명확하여 Rust의 에러 핸들링, 비트 스트림 다루기, GUI 및 멀티스레딩 학습에 훌륭한 길잡이가 됩니다.\n\n```mermaid\ngraph TD\n    CLI[src/cli.rs: clap 인수 파싱] --\u003e Main[src/main.rs: 진입점]\n    Main --\u003e Lib[src/lib.rs: 통합 라이브러리 인터페이스]\n    Lib --\u003e GUI[src/gui.rs: egui 렌더러 \u0026 비동기 태스크]\n    Lib --\u003e Format[src/format.rs: 파일 헤더 분기 파서]\n    Lib --\u003e Rle[src/rle.rs: 패킹, 지연매치, RLE, LZ77, 필터 코어]\n    Lib --\u003e Huffman[src/huffman.rs: Dynamic/Static 허프만 트리]\n    Lib --\u003e Ans[src/ans.rs: tANS 부호화 엔진]\n    Lib --\u003e CM[\"src/cm.rs: CM 산술 코더 (AVX2/NEON SIMD)\"]\n    Lib --\u003e Filters[src/filters.rs: PNG/LPC 미디어 예측 필터]\n    Lib --\u003e Deflate[src/deflate.rs: GZIP/DEFLATE 디코더]\n    Lib --\u003e Checksum[src/checksum.rs: SHA-256 체크섬 계산]\n    Lib --\u003e Inspect[src/inspect.rs: 인스펙터 분석 엔진]\n    Lib --\u003e WASM[src/wasm.rs: WebAssembly 바인딩]\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeiel85%2Fminimal-zip-concept","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeiel85%2Fminimal-zip-concept","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeiel85%2Fminimal-zip-concept/lists"}