cvd-simulator 1.1.1__tar.gz

cvd_simulator-1.1.1/.zenodo.json

@@ -0,0 +1,60 @@
+{
+  "title": "CVD Simulator: A Scientifically-Validated Tool for Color Vision Deficiency Simulation",
+  "description": "A comprehensive Python package for simulating color vision deficiencies (CVD) including protanopia, deuteranopia, tritanopia, and achromatopsia. Unifies multiple peer-reviewed algorithms (Brettel 1997, Viénot 1999, Machado 2009) with configurable severity levels, batch processing, and production-ready features.",
+  "creators": [
+    {
+      "name": "Semoglou, Michail",
+      "orcid": "0009-0003-3268-5657",
+      "affiliation": "College of Design and Innovation, Tongji University"
+    }
+  ],
+  "version": "1.1.1",
+  "license": {
+    "id": "MIT"
+  },
+  "upload_type": "software",
+  "access_right": "open",
+  "keywords": [
+    "color vision deficiency",
+    "color blindness",
+    "accessibility",
+    "image processing",
+    "daltonization",
+    "protanopia",
+    "deuteranopia",
+    "tritanopia",
+    "achromatopsia",
+    "scientific computing",
+    "human-computer interaction",
+    "inclusive design",
+    "Python"
+  ],
+  "related_identifiers": [
+    {
+      "scheme": "url",
+      "identifier": "https://github.com/MichailSemoglou/types-of-cvd-simulator-app",
+      "relation": "isSupplementTo"
+    },
+    {
+      "scheme": "url",
+      "identifier": "https://pypi.org/project/cvd-simulator/",
+      "relation": "isIdenticalTo"
+    },
+    {
+      "scheme": "doi",
+      "identifier": "10.1364/JOSAA.14.002647",
+      "relation": "references"
+    },
+    {
+      "scheme": "doi",
+      "identifier": "10.1002/(SICI)1520-6378(199908)24:4<243::AID-COL5>3.0.CO;2-3",
+      "relation": "references"
+    },
+    {
+      "scheme": "doi",
+      "identifier": "10.1109/TVCG.2009.113",
+      "relation": "references"
+    }
+  ],
+  "notes": "Published via the Zenodo-GitHub integration. Each GitHub release automatically triggers a new Zenodo deposit."
+}

cvd_simulator-1.1.1/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to the **CVD Simulator** project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [1.1.1] — 2026-02-13
+
+### New Features
+
+- **Multiple Simulation Algorithms** — Support for Brettel (1997), Viénot (1999), Machado (2009), Vischeck, and an auto-select mode that picks the best algorithm for the requested CVD type.
+- **All CVD Types** — Simulate protanopia, deuteranopia, tritanopia, and achromatopsia (full grayscale) with adjustable severity from 0.0 to 1.0.
+- **Batch Processing** — Process multiple images in a single invocation with `tqdm` progress bars and `rich` console output.
+- **Configuration Presets** — Built-in presets for common workflows: Web Design, Print Media, Scientific Visualization, and more (`PresetType` enum / `apply_preset()`).
+- **Video Frame Extraction** — Basic video processing via FFmpeg integration (`VideoProcessor`).
+- **Metadata Export** — JSON sidecar files recording algorithm, severity, CVD type, and timing for full reproducibility (`SimulationMetadata`, `export_metadata()`).
+- **Performance Profiling** — Built-in `PerformanceProfiler` and `Timer` utilities for benchmarking simulation pipelines.
+- **Flexible Configuration** — Configure via Python API (`SimulationConfig`), environment variables, CLI arguments, or presets. Optional Pydantic model available (`SimulationConfigPydantic`).
+- **Async Support** — `AsyncCVDSimulator` for non-blocking batch processing in asynchronous applications.
+- **Security & Validation** — Input validation, path sanitization, and file-size limits to harden against malicious inputs (`validators` module).
+- **Type Safety** — Fully typed codebase with `mypy --strict` compliance; custom exception hierarchy (`CVDSimulatorError`, `ImageProcessingError`, `SecurityError`, `ValidationError`, `ConfigurationError`).
+- **CLI** — Feature-rich command-line interface (`cvd-simulator`) with support for `--list-algorithms`, `--list-cvd-types`, format selection, output directories, and more.
+- **Comprehensive Test Suite** — Unit, integration, property-based (Hypothesis), and benchmark (pytest-benchmark) tests with coverage reporting.
+- **Documentation** — Sphinx-based docs (RST) with autodoc, type hints, and Read the Docs–compatible configuration.
+- **Docker Support** — `Dockerfile` and `docker-compose.yml` for containerised usage.
+- **CI/CD** — GitHub Actions workflow for automated PyPI publishing on release.
+
+### Known Issues
+
+- Zenodo DOI: [10.5281/zenodo.18639546](https://doi.org/10.5281/zenodo.18639546)
+- Video processing requires a system-installed FFmpeg binary; it is not bundled with the package.
+
+---
+
+## [Unreleased]
+
+_No unreleased changes._
+
+---
+
+[1.1.1]: https://github.com/MichailSemoglou/types-of-cvd-simulator-app/releases/tag/v1.1.1
+[Unreleased]: https://github.com/MichailSemoglou/types-of-cvd-simulator-app/compare/v1.1.1...HEAD

cvd_simulator-1.1.1/CITATION.cff

@@ -0,0 +1,95 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it using the metadata from this file."
+type: software
+title: "CVD Simulator: A Scientifically-Validated Tool for Color Vision Deficiency Simulation"
+abstract: >-
+  A comprehensive Python package for simulating color vision deficiencies (CVD)
+  including protanopia, deuteranopia, tritanopia, and achromatopsia. CVD Simulator
+  unifies multiple peer-reviewed algorithms (Brettel 1997, Viénot 1999, Machado 2009)
+  with configurable severity levels, batch processing capabilities, and production-ready
+  features including security validation, comprehensive testing, and type safety.
+authors:
+  - family-names: "Semoglou"
+    given-names: "Michail"
+    orcid: "https://orcid.org/0009-0003-3268-5657"
+    affiliation: "College of Design and Innovation, Tongji University"
+repository-code: "https://github.com/MichailSemoglou/types-of-cvd-simulator-app"
+url: "https://github.com/MichailSemoglou/types-of-cvd-simulator-app"
+license: MIT
+version: "1.1.1"
+date-released: "2026-02-13"
+keywords:
+  - color vision deficiency
+  - color blindness
+  - accessibility
+  - image processing
+  - daltonization
+  - protanopia
+  - deuteranopia
+  - tritanopia
+  - achromatopsia
+  - scientific computing
+  - human-computer interaction
+  - inclusive design
+  - Python
+identifiers:
+  - type: doi
+    value: "10.5281/zenodo.18639546"
+    description: "The DOI for version 1.1.1"
+preferred-citation:
+  type: software
+  title: "CVD Simulator: A Scientifically-Validated Tool for Color Vision Deficiency Simulation"
+  authors:
+    - family-names: "Semoglou"
+      given-names: "Michail"
+      orcid: "https://orcid.org/0009-0003-3268-5657"
+      affiliation: "College of Design and Innovation, Tongji University"
+  year: 2026
+  url: "https://github.com/MichailSemoglou/types-of-cvd-simulator-app"
+  version: "1.1.1"
+references:
+  - type: article
+    authors:
+      - family-names: "Brettel"
+        given-names: "Hans"
+      - family-names: "Viénot"
+        given-names: "Françoise"
+      - family-names: "Mollon"
+        given-names: "John D."
+    title: "Computerized simulation of color appearance for dichromats"
+    year: 1997
+    journal: "Journal of the Optical Society of America A"
+    volume: 14
+    issue: 10
+    pages: "2647-2655"
+    doi: 10.1364/JOSAA.14.002647
+  - type: article
+    authors:
+      - family-names: "Viénot"
+        given-names: "Françoise"
+      - family-names: "Brettel"
+        given-names: "Hans"
+      - family-names: "Mollon"
+        given-names: "John D."
+    title: "Digital video colourmaps for checking the legibility of displays by dichromats"
+    year: 1999
+    journal: "Color Research & Application"
+    volume: 24
+    issue: 4
+    pages: "243-252"
+    doi: 10.1002/(SICI)1520-6378(199908)24:4<243::AID-COL5>3.0.CO;2-3
+  - type: article
+    authors:
+      - family-names: "Machado"
+        given-names: "Gustavo M."
+      - family-names: "Oliveira"
+        given-names: "Manuel M."
+      - family-names: "Fernandes"
+        given-names: "Leandro A. F."
+    title: "A physiologically-based model for simulation of color vision deficiency"
+    year: 2009
+    journal: "IEEE Transactions on Visualization and Computer Graphics"
+    volume: 15
+    issue: 6
+    pages: "1291-1298"
+    doi: 10.1109/TVCG.2009.113

cvd_simulator-1.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Michail Semoglou
+
+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.

cvd_simulator-1.1.1/MANIFEST.in

@@ -0,0 +1,17 @@
+# Root metadata files
+include LICENSE CITATION.cff CHANGELOG.md README.md
+include .zenodo.json
+include requirements.txt requirements-dev.txt
+
+# Documentation (Sphinx sources + assets)
+recursive-include docs *.rst *.py *.css
+include docs/Makefile
+
+# Examples
+recursive-include examples *.py
+
+# Tests (allows running tests from the sdist)
+recursive-include tests *.py
+
+# Prevent build artifacts from leaking into the sdist
+global-exclude *.pyc *.pyo *.pyd __pycache__ .DS_Store Thumbs.db

cvd_simulator-1.1.1/PKG-INFO

@@ -0,0 +1,348 @@
+Metadata-Version: 2.4
+Name: cvd-simulator
+Version: 1.1.1
+Summary: A comprehensive tool for simulating color vision deficiencies
+Author: Michail Semoglou
+License: MIT
+Project-URL: Homepage, https://github.com/MichailSemoglou/types-of-cvd-simulator-app
+Project-URL: Repository, https://github.com/MichailSemoglou/types-of-cvd-simulator-app.git
+Project-URL: Issues, https://github.com/MichailSemoglou/types-of-cvd-simulator-app/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: daltonlens==0.1.5
+Requires-Dist: Pillow==12.1.1
+Requires-Dist: numpy>=2.0.0
+Requires-Dist: tqdm>=4.66.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: hypothesis>=6.0.0; extra == "dev"
+Requires-Dist: black>=24.0.0; extra == "dev"
+Requires-Dist: flake8>=7.0.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+Requires-Dist: pydantic>=2.0.0; extra == "dev"
+Requires-Dist: psutil>=5.9.0; extra == "dev"
+Requires-Dist: sphinx>=7.0.0; extra == "dev"
+Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "dev"
+Requires-Dist: sphinx-autodoc-typehints>=1.25.0; extra == "dev"
+Requires-Dist: setuptools>=61.0; extra == "dev"
+Requires-Dist: wheel>=0.37.0; extra == "dev"
+Dynamic: license-file
+
+# CVD Simulator
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18639546.svg)](https://doi.org/10.5281/zenodo.18639546)
+
+A comprehensive Python package for simulating color vision deficiencies (CVD), including protanopia, deuteranopia, and tritanopia. This tool uses scientifically-validated algorithms to simulate how images appear to individuals with different types of color blindness.
+
+## Features
+
+- **Multiple Simulation Algorithms**: Support for Brettel (1997), Viénot (1999), Machado (2009), Vischeck, and Auto-select algorithms
+- **All CVD Types**: Simulate protanopia, deuteranopia, tritanopia, and grayscale (achromatopsia)
+- **Batch Processing**: Process multiple images efficiently with progress bars
+- **Configuration Presets**: Quick presets for Web Design, Print Media, Scientific Visualization, and more
+- **Video Frame Extraction**: Basic video processing with FFmpeg integration
+- **Metadata Export**: JSON sidecar files for reproducibility
+- **Performance Profiling**: Built-in timing and performance analysis
+- **Flexible Configuration**: Configure via code, environment variables, CLI arguments, or presets
+- **Security**: Built-in input validation and path sanitization
+- **Type Hints**: Fully typed codebase for better IDE support
+- **Comprehensive Testing**: Unit and integration test suite
+
+## Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install cvd-simulator
+```
+
+### From Source
+
+```bash
+git clone https://github.com/MichailSemoglou/types-of-cvd-simulator-app.git
+cd types-of-cvd-simulator-app
+pip install -e .
+```
+
+### Video Processing (Optional)
+
+For video frame extraction capabilities:
+
+```bash
+# macOS
+brew install ffmpeg
+
+# Ubuntu/Debian
+sudo apt-get install ffmpeg
+
+# Windows (via Chocolatey)
+choco install ffmpeg
+```
+
+### Development Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### Command Line Interface
+
+```bash
+# Process a single image
+cvd-simulator input.jpg
+
+# Process with specific algorithm and severity
+cvd-simulator input.jpg -a MACHADO_2009 -s 0.7
+
+# Process multiple images
+cvd-simulator img1.jpg img2.jpg img3.jpg
+
+# Output as PNG with custom directory
+cvd-simulator input.jpg -f PNG -o ./my_outputs
+
+# List available algorithms
+cvd-simulator --list-algorithms
+
+# List available CVD types
+cvd-simulator --list-types
+
+# Use a preset configuration (v1.1.1+)
+cvd-simulator input.jpg --preset web_design
+
+# Show progress bar during batch processing (v1.1.1+)
+cvd-simulator img1.jpg img2.jpg img3.jpg --progress
+
+# Export metadata for reproducibility (v1.1.1+)
+cvd-simulator input.jpg --export-metadata
+
+# Enable performance profiling (v1.1.1+)
+cvd-simulator input.jpg --profile
+
+# List available presets (v1.1.1+)
+cvd-simulator --list-presets
+```
+
+### Python API
+
+```python
+from pathlib import Path
+from cvd_simulator import CVDSimulator, SimulationConfig
+from cvd_simulator.enums import Algorithm, CVDType, OutputFormat
+
+# Create configuration
+config = SimulationConfig(
+    algorithm=Algorithm.MACHADO_2009,
+    severity=0.8,
+    output_format=OutputFormat.PNG,
+    output_directory=Path("./outputs"),
+)
+
+# Initialize simulator
+simulator = CVDSimulator(config)
+
+# Process a single image
+results = simulator.process_image(Path("input.jpg"))
+
+# Access specific CVD simulation
+protan_path = results[CVDType.PROTAN]
+deutan_path = results[CVDType.DEUTAN]
+tritan_path = results[CVDType.TRITAN]
+bw_path = results[CVDType.GRAYSCALE]
+
+# Process specific CVD type only
+image = simulator.loader.load(Path("input.jpg"))
+simulated = simulator.simulate(image, CVDType.PROTAN)
+
+# Batch processing
+image_paths = [Path("img1.jpg"), Path("img2.jpg")]
+batch_results = simulator.process_batch(image_paths)
+
+# Using configuration presets (v1.1.1+)
+from cvd_simulator.presets import apply_preset, PresetType
+
+config = apply_preset(PresetType.WEB_DESIGN)
+simulator = CVDSimulator(config)
+
+# Export metadata for reproducibility (v1.1.1+)
+from cvd_simulator.utils.metadata import create_metadata, export_metadata, generate_sidecar_path
+
+results = simulator.process_image(Path("input.jpg"))
+metadata = create_metadata(
+    Path("input.jpg"),
+    results,
+    config,
+    notes="Research batch 2026-02"
+)
+sidecar_path = generate_sidecar_path("input.jpg")
+export_metadata(metadata, sidecar_path)
+
+# Performance profiling (v1.1.1+)
+from cvd_simulator.utils.profiling import PerformanceProfiler
+
+profiler = PerformanceProfiler()
+with profiler.time_operation("batch_process"):
+    results = simulator.process_batch(image_paths)
+
+print(profiler.get_summary())
+```
+
+### Configuration via Environment Variables
+
+```bash
+export CVD_SIMULATOR_ALGORITHM=MACHADO_2009
+export CVD_SIMULATOR_SEVERITY=0.7
+export CVD_SIMULATOR_OUTPUT_FORMAT=PNG
+export CVD_SIMULATOR_OUTPUT_DIRECTORY=./my_outputs
+
+cvd-simulator input.jpg
+```
+
+## Project Structure
+
+```
+cvd-simulator/
+├── src/
+│   ├── cvd_simulator/
+│   │   ├── __init__.py
+│   │   ├── exceptions.py      # Custom exceptions
+│   │   ├── enums.py           # Enumerations (CVDType, Algorithm, etc.)
+│   │   ├── config.py          # Configuration management
+│   │   ├── core/
+│   │   │   ├── __init__.py
+│   │   │   ├── simulator.py   # Main CVDSimulator class
+│   │   │   ├── image_loader.py
+│   │   │   └── output_writer.py
+│   │   ├── interfaces/
+│   │   │   ├── __init__.py
+│   │   │   └── cli.py         # Command-line interface
+│   │   └── utils/
+│   │       ├── __init__.py
+│   │       ├── validators.py  # Security validation
+│   │       └── logging_config.py
+│   └── main.py
+├── tests/
+│   ├── unit/
+│   ├── integration/
+│   └── conftest.py
+├── docs/
+├── examples/
+├── outputs/                   # Default output directory
+├── requirements.txt
+├── setup.py
+├── pyproject.toml
+└── README.md
+```
+
+## Algorithms
+
+The simulator supports multiple scientifically-validated algorithms:
+
+| Algorithm          | Description                                               |
+| ------------------ | --------------------------------------------------------- |
+| **Brettel (1997)** | Classic algorithm, widely used, computationally efficient |
+| **Viénot (1999)**  | Improved accuracy for severe deficiencies                 |
+| **Machado (2009)** | Modern approach, handles severity levels well             |
+| **Vischeck**       | Based on the popular Vischeck tool                        |
+| **Auto-select**    | Automatically chooses the best algorithm                  |
+
+## CVD Types
+
+| Type          | Description                                         |
+| ------------- | --------------------------------------------------- |
+| **Protan**    | Protanopia - missing or defective L-cones (red)     |
+| **Deutan**    | Deuteranopia - missing or defective M-cones (green) |
+| **Tritan**    | Tritanopia - missing or defective S-cones (blue)    |
+| **Grayscale** | Achromatopsia - complete color blindness            |
+
+## Testing
+
+Run the test suite:
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=cvd_simulator
+
+# Run only unit tests
+pytest tests/unit
+
+# Run only integration tests
+pytest tests/integration
+
+# Run with verbose output
+pytest -v
+```
+
+## Development
+
+### Code Formatting
+
+```bash
+# Format with black
+black src tests
+
+# Type checking
+mypy src
+
+# Linting
+flake8 src tests
+```
+
+### Building Documentation
+
+```bash
+cd docs
+make html
+```
+
+## References
+
+- Brettel, H., Viénot, F., & Mollon, J. D. (1997). Computerized simulation of color appearance for dichromats. _Journal of the Optical Society of America A_, _14_(10), 2647–2655. https://doi.org/10.1364/JOSAA.14.002647
+- Viénot, F., Brettel, H., & Mollon, J. D. (1999). Digital video colourmaps for checking the legibility of displays by dichromats. _Color Research & Application_, _24_(4), 243–252. https://doi.org/10.1002/(SICI)1520-6378(199908)24:4<243::AID-COL5>3.0.CO;2-3
+- Machado, G. M., Oliveira, M. M., & Fernandes, L. A. F. (2009). A physiologically-based model for simulation of color vision deficiency. _IEEE Transactions on Visualization and Computer Graphics_, _15_(6), 1291–1298. https://doi.org/10.1109/TVCG.2009.113
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Citation
+
+If you use CVD Simulator in your research, please cite:
+
+```bibtex
+@software{semoglou2026cvd,
+  author = {Semoglou, Michail},
+  title = {CVD Simulator: A Scientifically-Validated Tool for Color Vision Deficiency Simulation},
+  year = {2026},
+  version = {1.1.1},
+  url = {https://github.com/MichailSemoglou/types-of-cvd-simulator-app},
+  doi = {10.5281/zenodo.18639546}
+}
+```
+
+See [CITATION.cff](CITATION.cff) for additional citation formats.
+
+## Acknowledgments
+
+- [DaltonLens](https://github.com/DaltonLens) library for the core simulation algorithms
+- [Pillow](https://python-pillow.org/) for image processing
+- [NumPy](https://numpy.org/) for numerical operations