# Latent Watermark
A robust latent watermark system for tracking image distribution. This package provides tools for embedding and extracting invisible watermarks in images to track buyer information and prevent unauthorized distribution.
## Installation
Install via pip:
```bash
pip install latent-watermark
```
Or install from source:
```bash
git clone https://github.com/yourusername/latent-watermark.git
cd latent-watermark
pip install -e .
```
## Quick Start
### Embed Watermark
Embed a watermark with buyer information:
```bash
# Basic usage
latent_watermark --embed --buyer 'john snow' example/
# With custom output directory
latent_watermark --embed --buyer 'john snow' example/ -o output_example/
# Single file
latent_watermark --embed --buyer 'john snow' image.jpg -o watermarked.jpg
```
### Extract Watermark
Extract watermark information from watermarked files:
```bash
# From directory
latent_watermark --extract example/
# From single file
latent_watermark --extract watermarked.jpg
```
### View Configuration
Show current watermark configuration:
```bash
latent_watermark --config
```
## Usage Examples
### Directory Processing
Process entire directories:
```bash
# Embed watermarks in all images in a directory
latent_watermark --embed --buyer 'alice@company.com' photos/
# Extract watermarks from all files in a directory
latent_watermark --extract watermarked_photos/
```
### Complex Buyer Names
Handle special characters and Unicode:
```bash
# Unicode names
latent_watermark --embed --buyer '测试用户' images/
# Names with spaces and special characters
latent_watermark --embed --buyer "O'Brien & Co." assets/
# Email addresses
latent_watermark --embed --buyer 'user@example.com' documents/
```
## Command Line Interface
### Options
- `--embed`: Embed watermark into files
- `--extract`: Extract watermark from files
- `--config`: Show current configuration
- `--buyer`: Buyer name for watermark embedding (required with --embed)
- `-o, --output`: Output directory/file path
- `input`: Input file or directory path
### Examples
```bash
# Help
latent_watermark --help
# Embed with output specification
latent_watermark --embed --buyer 'john snow' input.jpg -o watermarked.jpg
# Batch processing
latent_watermark --embed --buyer 'batch_user' images/ -o watermarked_images/
# Extraction
latent_watermark --extract watermarked_images/
```
## Development
### Setup Development Environment
```bash
git clone https://github.com/yourusername/latent-watermark.git
cd latent-watermark
pip install -e ".[dev]"
```
### Running Tests
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=latent_watermark
# Run specific test files
pytest tests/test_config_formatter.py -v
```
### Code Formatting
```bash
# Format code
black .
isort .
# Type checking
mypy latent_watermark/
```
## Architecture
### Core Components
- **WatermarkEmbedder**: Handles watermark embedding with fixed-length encoding
- **WatermarkExtractor**: Extracts watermarks using optimized bit length calculation
- **Configuration**: YAML-based configuration system with fixed-length settings
- **CLI**: Command-line interface for embedding and extraction
- **Validation**: Robust input validation and error handling
### Simplified Watermark Format
The system uses a **streamlined watermark format** optimized for essential information:
- **Format**: `author:buyer:date:hash` (4 fields)
- **Date**: 8-digit format `yyMMddHH` (e.g., `25082000` = Aug 20, 2025, 00:00)
- **Hash**: Last 4 digits of MD5 hash for compact verification
- **Author**: Optional, falls back to config default
- **Buyer**: Mandatory parameter for each watermark
- **Fixed Length**: All watermarks padded to consistent length for reliable extraction
### Configuration
Configure author and length via YAML:
```yaml
watermark:
author: "your_author_name" # Default author when not specified
encoding:
fixed_length: 32 # Fixed length for all watermarks
max_total_length: 128 # Increased from 32 for better flexibility
quality:
d1: 36 # d1/d2 越大鲁棒性越强,但输出图片的失真越大
d2: 20 # d1/d2 越大鲁棒性越强,但输出图片的失真越大
```
## Quality Configuration
Adjust watermark robustness vs image quality trade-offs:
```yaml
watermark:
quality:
d1: 36 # Higher values increase robustness but may increase image distortion
d2: 20 # Higher values increase robustness but may increase image distortion
```
- **d1/d2**: Control watermark embedding strength
- **Higher values**: More robust against attacks, but may cause visible artifacts
- **Lower values**: Less visible artifacts, but potentially less robust
- **Default**: d1=36, d2=20 provides good balance
## Watermark Format Details
### Field Structure
- **Author**: 1-16 characters (configurable default)
- **Buyer**: 1-16 characters (mandatory parameter)
- **Date**: 8 digits exactly (yyMMddHH format)
- **Hash**: 4 hex digits exactly (last 4 of MD5)
### Example Watermarks
- `john_doe:alice_smith:25082000:7a3f`
- `default_author:bob_jones:25082000:e4d2`
### Usage Examples
```bash
# Basic usage
latent_watermark --embed --buyer "alice_smith" images/
# With custom author
latent_watermark --embed --buyer "alice_smith" --author "john_doe" images/
# Extract watermark
latent_watermark --extract watermarked/
```
## Error Handling
The system provides comprehensive error handling:
- **Invalid buyer names**: Rejected with clear error messages
- **Malformed watermarks**: Detected during extraction
- **Missing files**: Handled gracefully with helpful messages
- **Configuration errors**: Validated on startup
## Security Features
- **Unique buyer tracking**: Each watermark contains buyer-specific information
- **Tamper detection**: Watermark integrity validation
- **Format validation**: Strict format checking prevents injection attacks
- **Unicode support**: Handles international buyer names safely
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run the test suite
6. Submit a pull request
## Support
For issues and questions:
- GitHub Issues: https://github.com/yourusername/latent-watermark/issues
- Documentation: https://latent-watermark.readthedocs.io
Raw data
{
"_id": null,
"home_page": null,
"name": "latent-watermark",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "watermark, image, security, tracking, latent",
"author": null,
"author_email": "Cheng Yanru <yanru@cyanru.com>",
"download_url": "https://files.pythonhosted.org/packages/eb/12/7450f9882c928e793553a4589feb34457cfa3d684a1598b4218a3a5cd1e4/latent_watermark-0.1.0.tar.gz",
"platform": null,
"description": "# Latent Watermark\n\nA robust latent watermark system for tracking image distribution. This package provides tools for embedding and extracting invisible watermarks in images to track buyer information and prevent unauthorized distribution.\n\n## Installation\n\nInstall via pip:\n\n```bash\npip install latent-watermark\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/yourusername/latent-watermark.git\ncd latent-watermark\npip install -e .\n```\n\n## Quick Start\n\n### Embed Watermark\n\nEmbed a watermark with buyer information:\n\n```bash\n# Basic usage\nlatent_watermark --embed --buyer 'john snow' example/\n\n# With custom output directory\nlatent_watermark --embed --buyer 'john snow' example/ -o output_example/\n\n# Single file\nlatent_watermark --embed --buyer 'john snow' image.jpg -o watermarked.jpg\n```\n\n### Extract Watermark\n\nExtract watermark information from watermarked files:\n\n```bash\n# From directory\nlatent_watermark --extract example/\n\n# From single file\nlatent_watermark --extract watermarked.jpg\n```\n\n### View Configuration\n\nShow current watermark configuration:\n\n```bash\nlatent_watermark --config\n```\n\n## Usage Examples\n\n### Directory Processing\n\nProcess entire directories:\n\n```bash\n# Embed watermarks in all images in a directory\nlatent_watermark --embed --buyer 'alice@company.com' photos/\n\n# Extract watermarks from all files in a directory\nlatent_watermark --extract watermarked_photos/\n```\n\n### Complex Buyer Names\n\nHandle special characters and Unicode:\n\n```bash\n# Unicode names\nlatent_watermark --embed --buyer '\u6d4b\u8bd5\u7528\u6237' images/\n\n# Names with spaces and special characters\nlatent_watermark --embed --buyer \"O'Brien & Co.\" assets/\n\n# Email addresses\nlatent_watermark --embed --buyer 'user@example.com' documents/\n```\n\n## Command Line Interface\n\n### Options\n\n- `--embed`: Embed watermark into files\n- `--extract`: Extract watermark from files\n- `--config`: Show current configuration\n- `--buyer`: Buyer name for watermark embedding (required with --embed)\n- `-o, --output`: Output directory/file path\n- `input`: Input file or directory path\n\n### Examples\n\n```bash\n# Help\nlatent_watermark --help\n\n# Embed with output specification\nlatent_watermark --embed --buyer 'john snow' input.jpg -o watermarked.jpg\n\n# Batch processing\nlatent_watermark --embed --buyer 'batch_user' images/ -o watermarked_images/\n\n# Extraction\nlatent_watermark --extract watermarked_images/\n```\n\n## Development\n\n### Setup Development Environment\n\n```bash\ngit clone https://github.com/yourusername/latent-watermark.git\ncd latent-watermark\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=latent_watermark\n\n# Run specific test files\npytest tests/test_config_formatter.py -v\n```\n\n### Code Formatting\n\n```bash\n# Format code\nblack .\nisort .\n\n# Type checking\nmypy latent_watermark/\n```\n\n## Architecture\n\n### Core Components\n\n- **WatermarkEmbedder**: Handles watermark embedding with fixed-length encoding\n- **WatermarkExtractor**: Extracts watermarks using optimized bit length calculation\n- **Configuration**: YAML-based configuration system with fixed-length settings\n- **CLI**: Command-line interface for embedding and extraction\n- **Validation**: Robust input validation and error handling\n\n### Simplified Watermark Format\n\nThe system uses a **streamlined watermark format** optimized for essential information:\n\n- **Format**: `author:buyer:date:hash` (4 fields)\n- **Date**: 8-digit format `yyMMddHH` (e.g., `25082000` = Aug 20, 2025, 00:00)\n- **Hash**: Last 4 digits of MD5 hash for compact verification\n- **Author**: Optional, falls back to config default\n- **Buyer**: Mandatory parameter for each watermark\n- **Fixed Length**: All watermarks padded to consistent length for reliable extraction\n\n### Configuration\n\nConfigure author and length via YAML:\n\n```yaml\nwatermark:\n author: \"your_author_name\" # Default author when not specified\n encoding:\n fixed_length: 32 # Fixed length for all watermarks\n max_total_length: 128 # Increased from 32 for better flexibility\n quality:\n d1: 36 # d1/d2 \u8d8a\u5927\u9c81\u68d2\u6027\u8d8a\u5f3a,\u4f46\u8f93\u51fa\u56fe\u7247\u7684\u5931\u771f\u8d8a\u5927\n d2: 20 # d1/d2 \u8d8a\u5927\u9c81\u68d2\u6027\u8d8a\u5f3a,\u4f46\u8f93\u51fa\u56fe\u7247\u7684\u5931\u771f\u8d8a\u5927\n```\n\n## Quality Configuration\n\nAdjust watermark robustness vs image quality trade-offs:\n\n```yaml\nwatermark:\n quality:\n d1: 36 # Higher values increase robustness but may increase image distortion\n d2: 20 # Higher values increase robustness but may increase image distortion\n```\n\n- **d1/d2**: Control watermark embedding strength\n- **Higher values**: More robust against attacks, but may cause visible artifacts\n- **Lower values**: Less visible artifacts, but potentially less robust\n- **Default**: d1=36, d2=20 provides good balance\n\n## Watermark Format Details\n\n### Field Structure\n- **Author**: 1-16 characters (configurable default)\n- **Buyer**: 1-16 characters (mandatory parameter)\n- **Date**: 8 digits exactly (yyMMddHH format)\n- **Hash**: 4 hex digits exactly (last 4 of MD5)\n\n### Example Watermarks\n- `john_doe:alice_smith:25082000:7a3f`\n- `default_author:bob_jones:25082000:e4d2`\n\n### Usage Examples\n```bash\n# Basic usage\nlatent_watermark --embed --buyer \"alice_smith\" images/\n\n# With custom author\nlatent_watermark --embed --buyer \"alice_smith\" --author \"john_doe\" images/\n\n# Extract watermark\nlatent_watermark --extract watermarked/\n```\n\n## Error Handling\n\nThe system provides comprehensive error handling:\n\n- **Invalid buyer names**: Rejected with clear error messages\n- **Malformed watermarks**: Detected during extraction\n- **Missing files**: Handled gracefully with helpful messages\n- **Configuration errors**: Validated on startup\n\n## Security Features\n\n- **Unique buyer tracking**: Each watermark contains buyer-specific information\n- **Tamper detection**: Watermark integrity validation\n- **Format validation**: Strict format checking prevents injection attacks\n- **Unicode support**: Handles international buyer names safely\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Run the test suite\n6. Submit a pull request\n\n## Support\n\nFor issues and questions:\n- GitHub Issues: https://github.com/yourusername/latent-watermark/issues\n- Documentation: https://latent-watermark.readthedocs.io\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A robust latent watermark system for tracking image distribution",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/cyanru/latent-watermark#readme",
"Homepage": "https://github.com/cyanru/latent-watermark",
"Repository": "https://github.com/cyanru/latent-watermark"
},
"split_keywords": [
"watermark",
" image",
" security",
" tracking",
" latent"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "65a6dd0a3429ca4c7dd0076f9a82e930159689a118f6024efc2851317d34b905",
"md5": "d8ae1bf8353de10b425f575ac05dd344",
"sha256": "fe56e9af07a0a4f9ea505828daf6dad06810719f938a6ebd9db5c6520a7a13a3"
},
"downloads": -1,
"filename": "latent_watermark-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d8ae1bf8353de10b425f575ac05dd344",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 23618,
"upload_time": "2025-08-23T06:41:03",
"upload_time_iso_8601": "2025-08-23T06:41:03.521435Z",
"url": "https://files.pythonhosted.org/packages/65/a6/dd0a3429ca4c7dd0076f9a82e930159689a118f6024efc2851317d34b905/latent_watermark-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "eb127450f9882c928e793553a4589feb34457cfa3d684a1598b4218a3a5cd1e4",
"md5": "d5c6d8cd28643a75607e9e74ca47214c",
"sha256": "2d545b3b2dec8dc544ac9fc9b04ffebe4994098ed1fc7f4b5e924323de745a16"
},
"downloads": -1,
"filename": "latent_watermark-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "d5c6d8cd28643a75607e9e74ca47214c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 31333,
"upload_time": "2025-08-23T06:41:05",
"upload_time_iso_8601": "2025-08-23T06:41:05.466988Z",
"url": "https://files.pythonhosted.org/packages/eb/12/7450f9882c928e793553a4589feb34457cfa3d684a1598b4218a3a5cd1e4/latent_watermark-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-23 06:41:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cyanru",
"github_project": "latent-watermark#readme",
"github_not_found": true,
"lcname": "latent-watermark"
}
JSON
