ScreenshotScanner 0.1.0__tar.gz

screenshotscanner-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,42 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [ "main" ]
+  schedule:
+    - cron: '29 18 * * 3'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'python' ]
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v3
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v2
+      with:
+        languages: ${{ matrix.language }}
+
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v2
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v2
+      with:
+        category: "/language:${{ matrix.language }}"

screenshotscanner-0.1.0/.gitignore

@@ -0,0 +1,59 @@
+# Jupyter Notebook (DO NOT UPLOAD)
+Screenshot_detection_newst_combined.ipynb
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Jupyter Notebook checkpoints
+.ipynb_checkpoints
+
+# Virtual Environment
+venv/
+ENV/
+env/
+.venv
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Temporary files
+*.temp.jpg
+*.tmp
+.cache/
+
+# OS
+Thumbs.db
+.DS_Store

screenshotscanner-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,119 @@
+# Contributing to ScreenshotScanner
+
+Thank you for your interest in contributing to ScreenshotScanner! This document provides guidelines for contributing to the project.
+
+## Code of Conduct
+
+Be respectful and constructive in all interactions. We're all here to make this project better!
+
+## How to Contribute
+
+### Reporting Bugs
+
+If you find a bug, please create an issue on GitHub with:
+
+- A clear, descriptive title
+- Steps to reproduce the bug
+- Expected behavior vs. actual behavior
+- Screenshots or code samples if applicable
+- Your environment (OS, Python version, package version)
+
+### Suggesting Enhancements
+
+We welcome suggestions for new features or improvements! Please create an issue with:
+
+- A clear description of the enhancement
+- Use cases and benefits
+- Any implementation ideas you have
+
+### Pull Requests
+
+1. **Fork the repository** and create your branch from `main`
+2. **Make your changes** with clear, descriptive commits
+3. **Add tests** for new functionality
+4. **Update documentation** if needed
+5. **Ensure tests pass** before submitting
+6. **Submit a pull request** with a clear description
+
+## Development Setup
+
+```bash
+# Clone your fork
+git clone https://github.com/YOUR_USERNAME/ScreenshotScanner.git
+cd ScreenshotScanner
+
+# Create a virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install in development mode
+pip install -e .
+
+# Install development dependencies
+pip install pytest black flake8
+```
+
+## Code Style
+
+- Follow PEP 8 guidelines
+- Use meaningful variable and function names
+- Add docstrings to all functions and classes
+- Keep functions focused and modular
+
+### Running Code Formatters
+
+```bash
+# Format code with black
+black screenshot_scanner/
+
+# Check code style
+flake8 screenshot_scanner/
+```
+
+## Testing
+
+```bash
+# Run all tests
+python -m pytest tests/
+
+# Run with coverage
+python -m pytest --cov=screenshot_scanner tests/
+```
+
+### Writing Tests
+
+- Add tests for all new features
+- Ensure edge cases are covered
+- Use descriptive test names
+- Keep tests independent and isolated
+
+## Commit Messages
+
+- Use clear, descriptive commit messages
+- Start with a verb (Add, Fix, Update, Remove, etc.)
+- Keep the first line under 50 characters
+- Add detailed description if needed
+
+Example:
+```
+Add support for PNG alpha channel detection
+
+- Implement alpha channel check in detector
+- Add test cases for RGBA images
+- Update documentation
+```
+
+## Documentation
+
+- Update README.md for user-facing changes
+- Add docstrings for new functions/classes
+- Include usage examples for new features
+- Keep documentation clear and concise
+
+## Questions?
+
+Feel free to open an issue for any questions about contributing!
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

screenshotscanner-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AzwadFawadHasan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

screenshotscanner-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include LICENSE
+include requirements.txt
+include CONTRIBUTING.md
+recursive-include test_data *
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]

screenshotscanner-0.1.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: ScreenshotScanner
+Version: 0.1.0
+Summary: A heuristic-based tool to detect whether an image is a screenshot
+Home-page: https://github.com/AzwadFawadHasan/ScreenshotScanner
+Author: AzwadFawadHasan
+Author-email: AzwadFawadHasan <azwadfawadhasan@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/AzwadFawadHasan/ScreenshotScanner
+Project-URL: Documentation, https://github.com/AzwadFawadHasan/ScreenshotScanner#readme
+Project-URL: Repository, https://github.com/AzwadFawadHasan/ScreenshotScanner
+Project-URL: Bug Tracker, https://github.com/AzwadFawadHasan/ScreenshotScanner/issues
+Keywords: screenshot,detection,image-processing,document-verification,kyc
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: Pillow>=8.0.0
+Requires-Dist: scipy>=1.6.0
+Requires-Dist: opencv-python>=4.5.0
+Requires-Dist: pytesseract>=0.3.8
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+<p align="center">
+  <img src="ScreenshotScanner.png" alt="ScreenshotScanner Logo" width="250">
+</p>
+
+<h1 align="center">ScreenshotScanner</h1>
+
+<p align="center">
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.8+-blue.svg" alt="Python 3.8+"></a>
+  <a href="https://pypi.org/project/ScreenshotScanner/"><img src="https://img.shields.io/pypi/v/ScreenshotScanner.svg?logo=pypi&logoColor=959DA5&color=blue" alt="PyPI"></a>
+  <a href="https://pypistats.org/packages/screenshotscanner"><img src="https://static.pepy.tech/badge/ScreenshotScanner" alt="Downloads"></a>
+  <a href="https://github.com/AzwadFawadHasan/ScreenshotScanner/actions/workflows/codeql.yml"><img src="https://github.com/AzwadFawadHasan/ScreenshotScanner/actions/workflows/codeql.yml/badge.svg" alt="CodeQL"></a>
+</p>
+
+<p align="center">
+  A heuristic-based tool to detect whether an image is a screenshot or a photo of a physical document.
+  <br>
+  <b>Star this repo if it helped you!</b>
+</p>
+
+##  Features
+
+- **13 Heuristic Checks** - Multiple detection methods for high accuracy
+- **Simple API** - Easy to integrate into existing workflows
+- **Detailed Metrics** - Optional verbose mode for debugging
+- **No Training Required** - Rule-based system, no ML models needed
+- **Fast Processing** - Analyze images in milliseconds
+
+## Installation
+
+### Basic Installation
+
+```bash
+pip install ScreenshotScanner
+```
+
+
+## Quick Start
+
+```python
+from screenshot_scanner import ScreenshotScanner
+
+# Initialize scanner
+scanner = ScreenshotScanner()
+
+# Process an image (simple one-liner)
+result = scanner.process("path/to/image.jpg")
+
+print(result)
+```
+
+### Example Output
+
+```python
+{
+    'is_screenshot': True,
+    'score': 8,
+    'confidence': 80.0,
+    'reasons': ['Has alpha channel', 'Common aspect ratio: 1.78', 'Low ELA: 45.32', 'No EXIF data', 'High sharpness: 156.23']
+}
+```
+
+**That's it!** Just 3 lines of code to detect screenshots.
+
+<!-- 
+## 📖 Advanced Usage
+
+### Accessing Detailed Information
+
+```python
+result = scanner.process("image.jpg")
+
+# Access individual fields
+if result['is_screenshot']:
+    print(f"Screenshot detected with {result['confidence']:.1f}% confidence")
+    print(f"Detection score: {result['score']}/10")
+    print("Reasons:")
+    for reason in result['reasons']:
+        print(f"  - {reason}")
+```
+
+### Verbose Mode (All Metrics)
+
+For debugging or detailed analysis, use `is_screenshot()` with `verbose=True`:
+
+```python
+result = scanner.is_screenshot("image.jpg", verbose=True)
+
+# Access detailed metrics
+metrics = result['metrics']
+print(f"Alpha channel: {metrics['alpha']}")
+print(f"Aspect ratio: {metrics['aspect_ratio']}")
+print(f"ELA std: {metrics['ela_std']}")
+print(f"Sharpness: {metrics['sharpness']}")
+# ... and 9 more metrics
+```
+
+### Custom Threshold
+
+Adjust the detection sensitivity:
+
+```python
+# More strict (fewer false positives)
+strict_scanner = ScreenshotScanner(threshold=7)
+
+# More lenient (fewer false negatives)
+lenient_scanner = ScreenshotScanner(threshold=3)
+
+result = strict_scanner.process("image.jpg")
+```
+
+### Batch Processing
+
+Process multiple images:
+
+```python
+import os
+from screenshot_scanner import ScreenshotScanner
+
+scanner = ScreenshotScanner()
+image_folder = "path/to/images"
+
+for filename in os.listdir(image_folder):
+    if filename.endswith(('.jpg', '.png', '.jpeg')):
+        image_path = os.path.join(image_folder, filename)
+        result = scanner.process(image_path)
+        print(f"{filename}: {result['is_screenshot']} (score: {result['score']})")
+``` -->
+
+## How It Works
+
+ScreenshotScanner uses 13 different heuristic checks to determine if an image is a screenshot:
+
+1. **Alpha Channel** - Screenshots often have transparency
+2. **Aspect Ratio** - Common screen ratios (16:9, 4:3, etc.)
+3. **Border Variance** - Uniform borders indicate screenshots
+4. **ELA (Error Level Analysis)** - Lower compression artifacts in screenshots
+5. **EXIF Data** - Screenshots typically lack camera metadata
+6. **Horizontal Edges** - UI elements create horizontal patterns
+7. **Moiré Patterns** - Photos of screens show moiré, screenshots don't
+8. **Noise Analysis** - Screenshots have less sensor noise
+9. **Sharpness** - Screenshots are typically sharper
+10. **Solid Color Ratio** - UI elements have more solid colors
+11. **Status Bar Detection** - Mobile screenshots often have status bars
+12. **Text Confidence** - OCR works better on screenshot text
+13. **Vertical Symmetry** - UI layouts are often symmetric
+
+Each check contributes to a final score. A score ≥ 5 (default threshold) indicates a screenshot.
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+##  Motivation
+
+- There is no good tool without ML to detect screenshots. So i decided to come up with this.
+
+## Contact
+
+- **Author**: AzwadFawadHasan
+- **GitHub**: [@AzwadFawadHasan](https://github.com/AzwadFawadHasan)
+- **Issues**: [GitHub Issues](https://github.com/AzwadFawadHasan/ScreenshotScanner/issues)
+
+## Star
+
+If you find this project useful, please consider giving it a star on GitHub!
+
+---
+
+Made with ❤️ for better document verification by AzwadFawadHasan
+
+![Visitor Count](https://visitor-badge.laobi.icu/badge?page_id=AzwadFawadHasan.ScreenshotScanner)

screenshotscanner-0.1.0/README.md

@@ -0,0 +1,178 @@
+<p align="center">
+  <img src="ScreenshotScanner.png" alt="ScreenshotScanner Logo" width="250">
+</p>
+
+<h1 align="center">ScreenshotScanner</h1>
+
+<p align="center">
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.8+-blue.svg" alt="Python 3.8+"></a>
+  <a href="https://pypi.org/project/ScreenshotScanner/"><img src="https://img.shields.io/pypi/v/ScreenshotScanner.svg?logo=pypi&logoColor=959DA5&color=blue" alt="PyPI"></a>
+  <a href="https://pypistats.org/packages/screenshotscanner"><img src="https://static.pepy.tech/badge/ScreenshotScanner" alt="Downloads"></a>
+  <a href="https://github.com/AzwadFawadHasan/ScreenshotScanner/actions/workflows/codeql.yml"><img src="https://github.com/AzwadFawadHasan/ScreenshotScanner/actions/workflows/codeql.yml/badge.svg" alt="CodeQL"></a>
+</p>
+
+<p align="center">
+  A heuristic-based tool to detect whether an image is a screenshot or a photo of a physical document.
+  <br>
+  <b>Star this repo if it helped you!</b>
+</p>
+
+##  Features
+
+- **13 Heuristic Checks** - Multiple detection methods for high accuracy
+- **Simple API** - Easy to integrate into existing workflows
+- **Detailed Metrics** - Optional verbose mode for debugging
+- **No Training Required** - Rule-based system, no ML models needed
+- **Fast Processing** - Analyze images in milliseconds
+
+## Installation
+
+### Basic Installation
+
+```bash
+pip install ScreenshotScanner
+```
+
+
+## Quick Start
+
+```python
+from screenshot_scanner import ScreenshotScanner
+
+# Initialize scanner
+scanner = ScreenshotScanner()
+
+# Process an image (simple one-liner)
+result = scanner.process("path/to/image.jpg")
+
+print(result)
+```
+
+### Example Output
+
+```python
+{
+    'is_screenshot': True,
+    'score': 8,
+    'confidence': 80.0,
+    'reasons': ['Has alpha channel', 'Common aspect ratio: 1.78', 'Low ELA: 45.32', 'No EXIF data', 'High sharpness: 156.23']
+}
+```
+
+**That's it!** Just 3 lines of code to detect screenshots.
+
+<!-- 
+## 📖 Advanced Usage
+
+### Accessing Detailed Information
+
+```python
+result = scanner.process("image.jpg")
+
+# Access individual fields
+if result['is_screenshot']:
+    print(f"Screenshot detected with {result['confidence']:.1f}% confidence")
+    print(f"Detection score: {result['score']}/10")
+    print("Reasons:")
+    for reason in result['reasons']:
+        print(f"  - {reason}")
+```
+
+### Verbose Mode (All Metrics)
+
+For debugging or detailed analysis, use `is_screenshot()` with `verbose=True`:
+
+```python
+result = scanner.is_screenshot("image.jpg", verbose=True)
+
+# Access detailed metrics
+metrics = result['metrics']
+print(f"Alpha channel: {metrics['alpha']}")
+print(f"Aspect ratio: {metrics['aspect_ratio']}")
+print(f"ELA std: {metrics['ela_std']}")
+print(f"Sharpness: {metrics['sharpness']}")
+# ... and 9 more metrics
+```
+
+### Custom Threshold
+
+Adjust the detection sensitivity:
+
+```python
+# More strict (fewer false positives)
+strict_scanner = ScreenshotScanner(threshold=7)
+
+# More lenient (fewer false negatives)
+lenient_scanner = ScreenshotScanner(threshold=3)
+
+result = strict_scanner.process("image.jpg")
+```
+
+### Batch Processing
+
+Process multiple images:
+
+```python
+import os
+from screenshot_scanner import ScreenshotScanner
+
+scanner = ScreenshotScanner()
+image_folder = "path/to/images"
+
+for filename in os.listdir(image_folder):
+    if filename.endswith(('.jpg', '.png', '.jpeg')):
+        image_path = os.path.join(image_folder, filename)
+        result = scanner.process(image_path)
+        print(f"{filename}: {result['is_screenshot']} (score: {result['score']})")
+``` -->
+
+## How It Works
+
+ScreenshotScanner uses 13 different heuristic checks to determine if an image is a screenshot:
+
+1. **Alpha Channel** - Screenshots often have transparency
+2. **Aspect Ratio** - Common screen ratios (16:9, 4:3, etc.)
+3. **Border Variance** - Uniform borders indicate screenshots
+4. **ELA (Error Level Analysis)** - Lower compression artifacts in screenshots
+5. **EXIF Data** - Screenshots typically lack camera metadata
+6. **Horizontal Edges** - UI elements create horizontal patterns
+7. **Moiré Patterns** - Photos of screens show moiré, screenshots don't
+8. **Noise Analysis** - Screenshots have less sensor noise
+9. **Sharpness** - Screenshots are typically sharper
+10. **Solid Color Ratio** - UI elements have more solid colors
+11. **Status Bar Detection** - Mobile screenshots often have status bars
+12. **Text Confidence** - OCR works better on screenshot text
+13. **Vertical Symmetry** - UI layouts are often symmetric
+
+Each check contributes to a final score. A score ≥ 5 (default threshold) indicates a screenshot.
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+##  Motivation
+
+- There is no good tool without ML to detect screenshots. So i decided to come up with this.
+
+## Contact
+
+- **Author**: AzwadFawadHasan
+- **GitHub**: [@AzwadFawadHasan](https://github.com/AzwadFawadHasan)
+- **Issues**: [GitHub Issues](https://github.com/AzwadFawadHasan/ScreenshotScanner/issues)
+
+## Star
+
+If you find this project useful, please consider giving it a star on GitHub!
+
+---
+
+Made with ❤️ for better document verification by AzwadFawadHasan
+
+![Visitor Count](https://visitor-badge.laobi.icu/badge?page_id=AzwadFawadHasan.ScreenshotScanner)