<div align="center" id="paramtunercv">
# ParamTunerCV
[](https://python.org)
[](https://opencv.org)
[](https://opensource.org/licenses/MIT)
[](https://github.com/harsh194/ParamTunerCV/graphs/commit-activity)
*Professional interactive image viewer and processing application for computer vision research and real-time parameter tuning.*
</div>
---
## 📋 Table of Contents
- [Quick Start](#quick-start)
- [Features](#features)
- [Examples](#examples)
- [Controls](#controls)
- [Interface Gallery](#interface-gallery)
- [Architecture](#architecture)
- [API Reference](#api-reference)
- [Contributing](#contributing)
- [License](#license)
<a id="quick-start"></a>
## 🚀 Quick Start
```bash
# Option 1: Install from PyPI (recommended for users)
pip install ParamTunerCV
# Option 2: Install with uv (fastest)
uv add ParamTunerCV
# Option 3: Development setup with uv (recommended for contributors)
git clone https://github.com/harsh194/ParamTunerCV.git
cd ParamTunerCV
uv sync
# Option 4: Development setup with pip
git clone https://github.com/harsh194/ParamTunerCV.git
cd ParamTunerCV
pip install -e .
# Test the installation
python examples/01_basic_usage.py
```
**Requirements:** Python 3.8+, OpenCV 4.10.0, NumPy 2.2.6, Matplotlib 3.10.3
<a id="features"></a>
## ✨ Features
- **50+ Pre-configured Trackbars** - Real-time parameter tuning for morphology, edge detection, filtering, thresholding
- **15+ Specialized Factory Viewers** - Ready-to-use viewers for Canny, Hough transforms, corner detection
- **Interactive ROI System** - Rectangle, polygon, and line drawing with visual feedback
- **Multi-Space Thresholding** - Support for 7 color spaces (BGR, HSV, Lab, etc.) with binary, adaptive, Otsu methods
- **Professional Analysis Suite** - Multi-channel histograms, pixel intensity profiles, JSON/CSV export
- **Dual Operation Modes** - Full GUI for development, headless for production automation
<a id="examples"></a>
## 📖 Examples
Start with these progressive examples in the `examples/` folder:
| Example | Description |
|---------|-------------|
| `01_basic_usage.py` | Core workflow and main loop pattern |
| `02_window_control.py` | Window management and UI controls |
| `03_trackbar_definitions.py` | Custom trackbars and parameter control |
| `04_app_debug_mode.py` | GUI vs headless operation modes |
| `05_viewer_factory_usage.py` | Pre-built viewers for common CV tasks |
### Quick Integration
```python
from ParamTunerCV import ImageViewer, ViewerConfig
import numpy as np
import cv2
config = ViewerConfig()
trackbar_definitions = [
{"name": "Show Image", "param_name": "show", "max_value": "num_images-1", "initial_value": 0},
{"name": "Count", "param_name": "count", "max_value": 50, "initial_value": 10},
{"name": "Gauss Size", "param_name": "GaussianSize", "max_value": 31, "callback": "odd", "initial_value": 5},
{"name": "Thresh Val", "param_name": "thresh_val", "max_value": 255, "initial_value": 128},
]
IMG_HEIGHT, IMG_WIDTH = 600, 800
viewer = ImageViewer(config, trackbar_definitions)
while viewer.should_loop_continue():
params = viewer.trackbar.parameters
current_thresh = params.get("thresh_val")
current_gaussian_size = params.get("GaussianSize", 5)
block_count = params.get("count", 10)
base_color_image = np.full((IMG_HEIGHT, IMG_WIDTH, 3), (block_count * 5, 0, 0), dtype=np.uint8)
cv2.rectangle(base_color_image, (50, 50), (IMG_WIDTH - 50, IMG_HEIGHT - 50), (0, 255, 0), 3)
gray_image = cv2.cvtColor(base_color_image, cv2.COLOR_BGR2GRAY)
gauss_image = cv2.GaussianBlur(gray_image, (current_gaussian_size, current_gaussian_size), 0)
_, thresh_image = cv2.threshold(gauss_image, current_thresh, 255, cv2.THRESH_BINARY)
viewer.display_images = [
(base_color_image, "Color"),
(gray_image, "Grayscale Image"),
(gauss_image, "Gaussian Blur)"),
(thresh_image, "Threshold image")
]
viewer.cleanup_viewer()
```
<a id="controls"></a>
## 🖱️ Controls
**Mouse:** Left drag (ROI), wheel (zoom), middle drag (pan), right click (remove selection)
**Keys:** R (rectangle), L (line), P (polygon), H (histogram), Q/ESC (quit)
<a id="interface-gallery"></a>
## 📸 Interface Gallery
### 🎛️ Real-Time Parameter Control
<div align="center">
<img src="assets/trackbar.png" alt="Trackbar Interface" width="700">
</div>
*50+ preconfigured trackbars for real-time OpenCV parameter tuning - adjust Gaussian blur, edge detection, morphological operations, and thresholding with immediate visual feedback*
### 📊 Professional Analysis Suite
<div align="center">
<img src="assets/analysis_controls.png" alt="Analysis Controls" width="600">
</div>
*Comprehensive analysis control panel with ROI management, drawing tools, histogram generation, pixel intensity profiling, and integrated data export functionality*
### 🎨 Advanced Multi-Space Thresholding
<div align="center">
<img src="assets/thresholding_control_window.png" alt="Thresholding Controls" width="650">
</div>
*Sophisticated thresholding interface supporting 7 color spaces (BGR, HSV, Lab, etc.) with binary, adaptive, Otsu, and range-based methods for precise image segmentation*
### 💾 Multi-Format Data Export
<div align="center">
<img src="assets/export_window.png" alt="Export Interface" width="500">
</div>
*Professional export system for analysis results - save histograms, pixel profiles, and geometric data in JSON/CSV formats with configurable options*
<a id="architecture"></a>
## 🏗️ Architecture
```
src/ParamTunerCV/
├── core/ # ImageViewer main orchestrator
├── config/ # ViewerConfig management
├── controls/ # TrackbarManager for real-time controls
├── events/ # MouseHandler for interactions
├── gui/ # WindowManager and UI components
├── analysis/ # Analysis modules (plotting, export, threshold)
└── utils/ # Factory methods and utilities
```
**Design:** Factory pattern for viewers, Observer pattern for callbacks, Fluent interface for configuration
<a id="api-reference"></a>
## 📚 API Reference
### Testing
```bash
python examples/01_basic_usage.py # Primary test
```
<a id="contributing"></a>
## 🤝 Contributing
1. Fork the repository
2. Create feature branch: `git checkout -b feature/amazing-feature`
3. Test changes: `python examples/01_basic_usage.py`
4. Submit pull request
**Coding Standards:** PEP 8, docstrings, type hints
<a id="license"></a>
## 📄 License
MIT License © 2025 Harsh Ranjan
**Contact:** harshranjan194@gmail.com
---
<div align="center">
[⬆️ Back to Top](#paramtunercv)
</div>
Raw data
{
"_id": null,
"home_page": null,
"name": "ParamTunerCV",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "computer-vision, opencv, parameter-tuning, image-processing",
"author": null,
"author_email": "Harsh Ranjan <harshranjan194@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/94/ba/482a58b2adbb1fc7a8677463e8c09385fcdd81f9057a89fe4b78d989f936/paramtunercv-0.1.2.tar.gz",
"platform": null,
"description": "<div align=\"center\" id=\"paramtunercv\">\r\n\r\n# ParamTunerCV\r\n\r\n[](https://python.org)\r\n[](https://opencv.org)\r\n[](https://opensource.org/licenses/MIT)\r\n[](https://github.com/harsh194/ParamTunerCV/graphs/commit-activity)\r\n\r\n*Professional interactive image viewer and processing application for computer vision research and real-time parameter tuning.*\r\n\r\n</div>\r\n\r\n---\r\n\r\n## \ud83d\udccb Table of Contents\r\n\r\n- [Quick Start](#quick-start)\r\n- [Features](#features)\r\n- [Examples](#examples)\r\n- [Controls](#controls)\r\n- [Interface Gallery](#interface-gallery)\r\n- [Architecture](#architecture)\r\n- [API Reference](#api-reference)\r\n- [Contributing](#contributing)\r\n- [License](#license)\r\n\r\n<a id=\"quick-start\"></a>\r\n## \ud83d\ude80 Quick Start\r\n\r\n```bash\r\n # Option 1: Install from PyPI (recommended for users)\r\n pip install ParamTunerCV\r\n\r\n # Option 2: Install with uv (fastest)\r\n uv add ParamTunerCV\r\n\r\n # Option 3: Development setup with uv (recommended for contributors)\r\n git clone https://github.com/harsh194/ParamTunerCV.git\r\n cd ParamTunerCV\r\n uv sync\r\n\r\n # Option 4: Development setup with pip\r\n git clone https://github.com/harsh194/ParamTunerCV.git\r\n cd ParamTunerCV\r\n pip install -e .\r\n\r\n # Test the installation\r\n python examples/01_basic_usage.py\r\n```\r\n\r\n**Requirements:** Python 3.8+, OpenCV 4.10.0, NumPy 2.2.6, Matplotlib 3.10.3\r\n\r\n<a id=\"features\"></a>\r\n## \u2728 Features\r\n\r\n- **50+ Pre-configured Trackbars** - Real-time parameter tuning for morphology, edge detection, filtering, thresholding\r\n- **15+ Specialized Factory Viewers** - Ready-to-use viewers for Canny, Hough transforms, corner detection\r\n- **Interactive ROI System** - Rectangle, polygon, and line drawing with visual feedback\r\n- **Multi-Space Thresholding** - Support for 7 color spaces (BGR, HSV, Lab, etc.) with binary, adaptive, Otsu methods\r\n- **Professional Analysis Suite** - Multi-channel histograms, pixel intensity profiles, JSON/CSV export\r\n- **Dual Operation Modes** - Full GUI for development, headless for production automation\r\n\r\n<a id=\"examples\"></a>\r\n## \ud83d\udcd6 Examples\r\n\r\nStart with these progressive examples in the `examples/` folder:\r\n\r\n| Example | Description |\r\n|---------|-------------|\r\n| `01_basic_usage.py` | Core workflow and main loop pattern |\r\n| `02_window_control.py` | Window management and UI controls |\r\n| `03_trackbar_definitions.py` | Custom trackbars and parameter control |\r\n| `04_app_debug_mode.py` | GUI vs headless operation modes |\r\n| `05_viewer_factory_usage.py` | Pre-built viewers for common CV tasks |\r\n\r\n### Quick Integration\r\n\r\n```python\r\nfrom ParamTunerCV import ImageViewer, ViewerConfig\r\nimport numpy as np\r\nimport cv2\r\n\r\nconfig = ViewerConfig()\r\n\r\ntrackbar_definitions = [\r\n {\"name\": \"Show Image\", \"param_name\": \"show\", \"max_value\": \"num_images-1\", \"initial_value\": 0},\r\n {\"name\": \"Count\", \"param_name\": \"count\", \"max_value\": 50, \"initial_value\": 10}, \r\n {\"name\": \"Gauss Size\", \"param_name\": \"GaussianSize\", \"max_value\": 31, \"callback\": \"odd\", \"initial_value\": 5}, \r\n {\"name\": \"Thresh Val\", \"param_name\": \"thresh_val\", \"max_value\": 255, \"initial_value\": 128}, \r\n]\r\n\r\nIMG_HEIGHT, IMG_WIDTH = 600, 800\r\nviewer = ImageViewer(config, trackbar_definitions)\r\n\r\nwhile viewer.should_loop_continue():\r\n params = viewer.trackbar.parameters\r\n \r\n current_thresh = params.get(\"thresh_val\") \r\n current_gaussian_size = params.get(\"GaussianSize\", 5)\r\n block_count = params.get(\"count\", 10)\r\n\r\n base_color_image = np.full((IMG_HEIGHT, IMG_WIDTH, 3), (block_count * 5, 0, 0), dtype=np.uint8)\r\n cv2.rectangle(base_color_image, (50, 50), (IMG_WIDTH - 50, IMG_HEIGHT - 50), (0, 255, 0), 3)\r\n\r\n gray_image = cv2.cvtColor(base_color_image, cv2.COLOR_BGR2GRAY)\r\n\r\n gauss_image = cv2.GaussianBlur(gray_image, (current_gaussian_size, current_gaussian_size), 0)\r\n\r\n _, thresh_image = cv2.threshold(gauss_image, current_thresh, 255, cv2.THRESH_BINARY)\r\n \r\n viewer.display_images = [\r\n (base_color_image, \"Color\"),\r\n (gray_image, \"Grayscale Image\"),\r\n (gauss_image, \"Gaussian Blur)\"),\r\n (thresh_image, \"Threshold image\")\r\n ]\r\n\r\nviewer.cleanup_viewer()\r\n```\r\n<a id=\"controls\"></a>\r\n## \ud83d\uddb1\ufe0f Controls\r\n\r\n**Mouse:** Left drag (ROI), wheel (zoom), middle drag (pan), right click (remove selection)\r\n\r\n**Keys:** R (rectangle), L (line), P (polygon), H (histogram), Q/ESC (quit)\r\n\r\n<a id=\"interface-gallery\"></a>\r\n## \ud83d\udcf8 Interface Gallery\r\n\r\n### \ud83c\udf9b\ufe0f Real-Time Parameter Control\r\n<div align=\"center\">\r\n<img src=\"assets/trackbar.png\" alt=\"Trackbar Interface\" width=\"700\">\r\n</div>\r\n\r\n*50+ preconfigured trackbars for real-time OpenCV parameter tuning - adjust Gaussian blur, edge detection, morphological operations, and thresholding with immediate visual feedback*\r\n\r\n### \ud83d\udcca Professional Analysis Suite\r\n<div align=\"center\">\r\n<img src=\"assets/analysis_controls.png\" alt=\"Analysis Controls\" width=\"600\">\r\n</div>\r\n\r\n*Comprehensive analysis control panel with ROI management, drawing tools, histogram generation, pixel intensity profiling, and integrated data export functionality*\r\n\r\n### \ud83c\udfa8 Advanced Multi-Space Thresholding\r\n<div align=\"center\">\r\n<img src=\"assets/thresholding_control_window.png\" alt=\"Thresholding Controls\" width=\"650\">\r\n</div>\r\n\r\n*Sophisticated thresholding interface supporting 7 color spaces (BGR, HSV, Lab, etc.) with binary, adaptive, Otsu, and range-based methods for precise image segmentation*\r\n\r\n### \ud83d\udcbe Multi-Format Data Export\r\n<div align=\"center\">\r\n<img src=\"assets/export_window.png\" alt=\"Export Interface\" width=\"500\">\r\n</div>\r\n\r\n*Professional export system for analysis results - save histograms, pixel profiles, and geometric data in JSON/CSV formats with configurable options*\r\n\r\n<a id=\"architecture\"></a>\r\n## \ud83c\udfd7\ufe0f Architecture\r\n\r\n```\r\nsrc/ParamTunerCV/ \r\n\u251c\u2500\u2500 core/ # ImageViewer main orchestrator\r\n\u251c\u2500\u2500 config/ # ViewerConfig management \r\n\u251c\u2500\u2500 controls/ # TrackbarManager for real-time controls\r\n\u251c\u2500\u2500 events/ # MouseHandler for interactions\r\n\u251c\u2500\u2500 gui/ # WindowManager and UI components\r\n\u251c\u2500\u2500 analysis/ # Analysis modules (plotting, export, threshold)\r\n\u2514\u2500\u2500 utils/ # Factory methods and utilities\r\n```\r\n\r\n**Design:** Factory pattern for viewers, Observer pattern for callbacks, Fluent interface for configuration\r\n\r\n<a id=\"api-reference\"></a>\r\n## \ud83d\udcda API Reference\r\n### Testing\r\n\r\n```bash\r\npython examples/01_basic_usage.py # Primary test\r\n```\r\n\r\n<a id=\"contributing\"></a>\r\n## \ud83e\udd1d Contributing\r\n\r\n1. Fork the repository\r\n2. Create feature branch: `git checkout -b feature/amazing-feature`\r\n3. Test changes: `python examples/01_basic_usage.py`\r\n4. Submit pull request\r\n\r\n**Coding Standards:** PEP 8, docstrings, type hints\r\n\r\n<a id=\"license\"></a>\r\n## \ud83d\udcc4 License\r\n\r\nMIT License \u00a9 2025 Harsh Ranjan \r\n**Contact:** harshranjan194@gmail.com\r\n\r\n---\r\n\r\n<div align=\"center\">\r\n\r\n[\u2b06\ufe0f Back to Top](#paramtunercv)\r\n\r\n</div>\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Parameter tuning tool for computer vision",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/harsh194/ParamTunerCV",
"Issues": "https://github.com/harsh194/ParamTunerCV/issues",
"Repository": "https://github.com/harsh194/ParamTunerCV"
},
"split_keywords": [
"computer-vision",
" opencv",
" parameter-tuning",
" image-processing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "416d21e4e54f09459362f38a80d1b11921b54a2fabf570ba9b3544178c074da5",
"md5": "9eda50cda5b1780486d480415865c0dd",
"sha256": "adda1876f9314ed177cdfa075b6688b8e2fa16fc1998899038b0d2cd1e968627"
},
"downloads": -1,
"filename": "paramtunercv-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9eda50cda5b1780486d480415865c0dd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 162166,
"upload_time": "2025-08-16T16:07:01",
"upload_time_iso_8601": "2025-08-16T16:07:01.921165Z",
"url": "https://files.pythonhosted.org/packages/41/6d/21e4e54f09459362f38a80d1b11921b54a2fabf570ba9b3544178c074da5/paramtunercv-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "94ba482a58b2adbb1fc7a8677463e8c09385fcdd81f9057a89fe4b78d989f936",
"md5": "732c4423ed5548a9955f8ccb7e56aff3",
"sha256": "c6163a96485958bc37f216b6ed3b706613929876d97ddc9badc92f5f1cf657e4"
},
"downloads": -1,
"filename": "paramtunercv-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "732c4423ed5548a9955f8ccb7e56aff3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 283248,
"upload_time": "2025-08-16T16:07:04",
"upload_time_iso_8601": "2025-08-16T16:07:04.560649Z",
"url": "https://files.pythonhosted.org/packages/94/ba/482a58b2adbb1fc7a8677463e8c09385fcdd81f9057a89fe4b78d989f936/paramtunercv-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-16 16:07:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "harsh194",
"github_project": "ParamTunerCV",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "opencv-contrib-python",
"specs": [
[
">=",
"4.5.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.21.0"
]
]
},
{
"name": "matplotlib",
"specs": [
[
">=",
"3.5.0"
]
]
}
],
"lcname": "paramtunercv"
}
JSON
