Metadata-Version: 2.4
Name: anivis
Version: 0.1.0
Summary: A modular, reliable, and developer-friendly Python computer vision library
Author: Anirudh Ghanshyam Sarve
License: MIT
Project-URL: Homepage, https://github.com/anisarve2006/anivis
Project-URL: Repository, https://github.com/anisarve2006/anivis.git
Project-URL: Issues, https://github.com/anisarve2006/anivis/issues
Project-URL: Changelog, https://github.com/anisarve2006/anivis/blob/main/CHANGELOG.md
Keywords: computer-vision,image-processing,vision,perception,opencv,numpy,anivis,visionkit
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22.0
Requires-Dist: opencv-python-headless>=4.5.0; sys_platform != "win32"
Requires-Dist: opencv-python>=4.5.0; sys_platform == "win32"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=6.0.0; extra == "docs"
Requires-Dist: furo>=2023.0.0; extra == "docs"
Requires-Dist: myst-parser>=1.0.0; extra == "docs"
Provides-Extra: all
Requires-Dist: anivis[dev,docs]; extra == "all"
Dynamic: license-file

<div align="center">

# 📷 AniVis (VisionKit)

**A modular, reliable, and developer-friendly Python computer vision library.**

[![PyPI version](https://img.shields.io/pypi/v/anivis.svg?color=blue)](https://pypi.org/project/anivis/)
[![GitHub](https://img.shields.io/badge/GitHub-anisarve2006%2Fanivis-181717?logo=github)](https://github.com/anisarve2006/anivis)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
[![Code Style: Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)]()

</div>

---

## 🎯 Mission

Make reusable computer vision and visual perception tools accessible through a clean, consistent Python API.

### 📐 Design Principles

- **Modular:** Install and use only the functionality you need.
- **Reliable:** Validated inputs, predictable outputs, automated tests.
- **RGB by Default:** Native NumPy arrays in RGB format—no more unexpected BGR color inversion headaches.
- **Efficient:** Measure performance before optimizing (SIMD-accelerated quality metrics).
- **Extensible:** Support established backends (OpenCV / NumPy / SciPy) instead of reinventing every algorithm.
- **Developer-Friendly:** Typed signatures, helpful validation errors, and practical documentation.

---

## ⚡ Quickstart

### Installation from PyPI

```bash
pip install anivis
```

### Installation from Source (Development)

```bash
# Clone the repository
git clone https://github.com/anisarve2006/anivis.git
cd anivis

# Install in development mode
pip install -e ".[dev]"
```

### 5-Line Example

You can import as either `anivis` or `visionkit`:

```python
import anivis as vk  # or: import visionkit as vk

image = vk.read("input.jpg")
gray = vk.grayscale(image)
resized = vk.resize(gray, width=640)
edges = vk.detect_edges(resized)
vk.save(edges, "output.png")

print("Image processing completed.")
```

Run the built-in example script:

```bash
python example.py
```

---

## 📦 Core Capabilities

### 1. Image I/O
- `vk.read(path, mode="rgb")`: Read image files into standard RGB or grayscale NumPy arrays with informative error reporting on missing or corrupt files.
- `vk.save(image, path, mode="rgb")`: Save NumPy arrays to disk with automatic parent directory creation.

### 2. Color Conversion
- `vk.grayscale(image, keep_dims=False)`: Convert RGB, BGR, or RGBA images to 2D or 3D grayscale arrays.
- `vk.to_rgb(image)`: Normalize any single-channel, grayscale, or RGBA image to 3-channel RGB.
- `vk.rgb_to_hsv(image)` / `vk.hsv_to_rgb(image)`: Fast HSV color space transformations.

### 3. Geometric Transformations
- `vk.resize(image, width=None, height=None, fx=None, fy=None, interpolation="linear")`: Resizing with automatic aspect ratio calculation when only one dimension is supplied.
- `vk.flip(image, direction="horizontal")`: Flip along horizontal, vertical, or both axes.
- `vk.crop(image, x, y, width, height)`: Safe bounding box cropping with bounds validation.

### 4. Smoothing and Filtering
- `vk.gaussian_blur(image, kernel_size=(5, 5), sigma=1.0)`: Gaussian smoothing with validated odd kernel dimensions.
- `vk.median_blur(image, kernel_size=5)`: Salt-and-pepper noise removal.
- `vk.box_blur(image, kernel_size=(5, 5))`: Normalized average box blur.
- `vk.bilateral_filter(image, diameter=9, sigma_color=75.0, sigma_space=75.0)`: Edge-preserving smoothing.

### 5. Edge and Gradient Detection
- `vk.detect_edges(image, method="canny", low_threshold=50, high_threshold=150)`: Clean edge masks (supports `canny`, `sobel`, `laplacian`, `scharr`).
- `vk.sobel_gradients(image)`: Returns directional gradients `(grad_x, grad_y)`, gradient magnitude, and angle in radians.

### 6. Thresholding & Binarization
- `vk.threshold(image, thresh=127, maxval=255, method="binary")`: Global thresholding, Otsu's thresholding, and Triangle method.
- `vk.adaptive_threshold(image, method="gaussian", block_size=11, c=2.0)`: Local adaptive thresholding for uneven lighting conditions.

### 7. Morphology
- `vk.erode`, `vk.dilate`: Fundamental morphological operators.
- `vk.morphology_open`, `vk.morphology_close`: Noise filtering and hole closure.
- `vk.morphology_gradient`, `vk.top_hat`, `vk.black_hat`: Advanced structural feature extraction.

### 8. Image Comparison Metrics
- `vk.mean_squared_error(im1, im2)` (or `vk.mse`): SIMD-accelerated pixel error.
- `vk.psnr(im1, im2)`: Peak Signal-to-Noise Ratio in dB.
- `vk.ssim(im1, im2)`: Structural Similarity Index.

---

## 🧪 Testing

Run the automated test suite using `pytest`:

```bash
pytest -v
```

Run test suite with code coverage:

```bash
pytest --cov=anivis --cov-report=term-missing
```

---

## 🗺️ Development Roadmap

- [x] **01 Core Image Processing**
  - [x] Robust I/O (RGB default)
  - [x] Input validation & custom exception hierarchy
  - [x] Color space utilities & Grayscale
  - [x] Geometric transformations & Aspect-ratio resizing
  - [x] Filtering & Smoothing
  - [x] Edge detection (Canny, Sobel, Laplacian, Scharr)
  - [x] Thresholding (Binary, Otsu, Adaptive)
  - [x] Morphological operations
  - [x] Image quality metrics (MSE, PSNR, SSIM)
- [ ] **02 Feature Extraction**
  - Corner detection (Harris, Shi-Tomasi, FAST)
  - Keypoint descriptors & Feature matching (ORB, SIFT)
  - Hough transforms (lines and circles)
- [ ] **03 Visual Perception**
  - Optical flow (Lucas-Kanade, Farneback)
  - Visual object tracking (CSRT, KCF, ByteTrack wrapper)
  - Camera calibration & lens distortion correction
- [ ] **04 Quality and Performance**
  - Automated CI matrix (Python 3.9 - 3.13, Linux, macOS, Windows)
  - Benchmarks & performance regression tracking
- [ ] **05 Public Release**
  - Sphinx documentation site on ReadTheDocs
  - PyPI release configuration & GitHub Actions deployment

---

## 👤 Author

Developed and maintained by **[Anirudh Sarve](https://github.com/anisarve2006)**.

---

## 📄 License

AniVis is open-source software licensed under the [MIT License](LICENSE).
