Skip to content

Building 70 Projects ranging from beginner to advanced so anyone can β€” learn from, build upon, use as a reference, or even copy directly. Owned by my cybersecurity company πŸ‘‡

updated README

HERITAGE-XION5f5befab29ac
diff --git a/README.md b/README.md
index 21c4e265..0228194f 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,121 @@
-# Metadata Scrubber Tool
+# πŸ”’ Metadata Scrubber Tool
-A tool for scrubbing metadata from files.
+A privacy-focused CLI tool that removes sensitive metadata (EXIF, GPS, author info) from image files. Perfect for protecting your privacy before sharing photos online.
-## Installation
+## ✨ Features
+
+- **Multi-format support** - JPEG, PNG (with PDF/Office planned)
+- **Concurrent processing** - Process 1000+ files efficiently with ThreadPoolExecutor
+- **Dry-run mode** - Preview what would be scrubbed without making changes
+- **Smart format detection** - Uses Pillow's format detection, not just file extensions
+- **Beautiful CLI** - Rich progress bars and formatted output
+- **Privacy-first** - Removes GPS coordinates, camera info, timestamps, author data
+
+## πŸ“š Educational Value
+
+This project demonstrates:
+- **Factory pattern** for extensible file type handling
+- **Abstract base classes** for consistent handler interfaces
+- **Concurrent processing** with thread-safe operations
+- **CLI development** with Typer and Rich
+- **Image metadata handling** with Pillow and piexif
+
+## πŸ“‹ Prerequisites
+
+- Python 3.10+
+- [uv](https://github.com/astral-sh/uv) (recommended) or pip
+
+## πŸš€ Installation
```bash
+# Clone the repository
+git clone https://github.com/Heritage-XioN/metadata-scrubber-tool.git
+cd metadata-scrubber-tool
+
+# Create virtual environment and install dependencies
+uv venv
+.venv\Scripts\activate # Windows
+# source .venv/bin/activate # Linux/Mac
+
uv pip install -r requirements.txt
```
-## Usage
+## πŸ“– Usage
+
+### Read Metadata
+
+```bash
+# Single file
+python -m src.main read photo.jpg
+
+# Recursive directory scan
+python -m src.main read ./photos/ -r -ext jpg
+```
+
+### Scrub Metadata
```bash
-python -m src.main
+# Single file
+python -m src.main scrub photo.jpg --output ./cleaned
+
+# Batch process with 8 workers
+python -m src.main scrub ./photos/ -r -ext jpg --output ./cleaned --workers 8
+
+# Preview without changes
+python -m src.main scrub ./photos/ -r -ext jpg --dry-run
```
+
+### CLI Options
+
+| Command | Options |
+|---------|---------|
+| `read` | `-r` / `--recursive`, `-ext` / `--extension` |
+| `scrub` | `-r`, `-ext`, `-o` / `--output`, `-d` / `--dry-run`, `-w` / `--workers` |
+| Global | `-v` / `--verbose` |
+
+## πŸ—οΈ Architecture
+
+```
+src/
+β”œβ”€β”€ main.py # CLI entry point (Typer app)
+β”œβ”€β”€ commands/
+β”‚ β”œβ”€β”€ read.py # Read metadata command
+β”‚ └── scrub.py # Scrub metadata command (batch processing)
+β”œβ”€β”€ services/
+β”‚ β”œβ”€β”€ metadata_factory.py # Factory for creating handlers
+β”‚ β”œβ”€β”€ metadata_handler.py # Abstract base class
+β”‚ β”œβ”€β”€ image_handler.py # JPEG/PNG handler
+β”‚ └── batch_processor.py # Concurrent batch processing
+β”œβ”€β”€ core/
+β”‚ β”œβ”€β”€ jpeg_metadata.py # JPEG EXIF processor (piexif)
+β”‚ └── png_metadata.py # PNG metadata processor (PIL)
+└── utils/
+ β”œβ”€β”€ display.py # Rich output formatting
+ β”œβ”€β”€ formatter.py # Value formatting helpers
+ β”œβ”€β”€ exceptions.py # Custom exceptions
+ └── logger.py # Logging configuration
+```
+
+**Data Flow:**
+```
+CLI Command → MetadataFactory → Handler (read→wipe→save) → Output
+ ↓
+ Format Detection
+ ↓
+ JpegProcessor / PngProcessor
+```
+
+## ⚠️ Security Considerations
+
+- **Always backup files** before scrubbing in production
+- **Use `--dry-run`** to preview changes before committing
+- **GPS coordinates** are completely stripped for privacy
+- **Original files are not modified** - processed copies are created
+
+## πŸ“„ License
+
+MIT License - See [LICENSE](LICENSE) for details.
+
+---
+
+Made with ❀️ for privacy
diff --git a/examples/test_images/test_canon.jpg b/examples/test_images/test_canon.jpg
new file mode 100644
index 00000000..6eb33f12
Binary files /dev/null and b/examples/test_images/test_canon.jpg differ
diff --git a/examples/test_images/test_fuji.jpg b/examples/test_images/test_fuji.jpg
new file mode 100644
index 00000000..8cf1e5ca
Binary files /dev/null and b/examples/test_images/test_fuji.jpg differ
diff --git a/examples/test_images/test_metadata.png b/examples/test_images/test_metadata.png
new file mode 100644
index 00000000..55aa11f8
Binary files /dev/null and b/examples/test_images/test_metadata.png differ