Metadata-Version: 2.4
Name: CPVD
Version: 0.3.0
Summary: Complex Phase Vector Displacement (CPVD)
Author-email: Mohan Bhandari <mail2mohanbhandari@gmail.com>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: opencv-python-headless
Requires-Dist: matplotlib
Requires-Dist: scipy
Requires-Dist: scikit-image
Requires-Dist: scikit-learn

# CPVD (Complex Phase Vector Displacement)

**CPVD** is an image evaluation and computer vision library engineered for semantic segmentation assessment. While standard pixel-matching statistics (like Dice and Intersection over Union) capture raw overlap, they often fail to evaluate structural boundary alignments accurately. 

CPVD computes the structural fidelity of segmentation masks by transforming binary edges into directional gradient fields using complex numbers, tracking alignment coherence, and outputting an elegant, multi-stage analytical visual grid.## 🚀 Key Features

- **Boundary Structural Orientation:** Extracts Euclidean Distance Transforms (EDT) and maps them to a complex plane ($z = dx - i \cdot dy$) to capture boundary phase directions.
- **Automated Analytical Grid Plotting:** Generates complete debugging and visualization charts detailing distance maps, gradient fields, phase vectors, overlay errors, and directional coherence values ($C_{\text{norm}}$).
- **Comprehensive Metric Suite:** Combines CPVD with classic scoring frameworks like Hausdorff Distance, Dice-Sørensen Coefficient, Jaccard Index (IoU), Accuracy, Precision, Sensitivity, and Specificity.

- ## 📦 Installation

Install the package and all of its underlying scientific dependencies seamlessly via `pip`:

```bash
pip install CPVD
```

---

## 💻 Quickstart & Usage

The code adaptively resizes arrow vectors and scales analysis parameters based on whatever dimensions your user passes in.

### 1. CPVD Score

```python
import cpvd

# Load the user masks
gt_mask = cpvd.load_mask("my_user_gt.png")
pred_mask = cpvd.load_mask("my_user_pred.png")

# Generate the comprehensive evaluation matrix plots
pipeline_results = cpvd.plot_cpvd_intermediates(
    gt_mask=gt_mask,
    pred_mask=pred_mask,
    title="Plots"
)

# Extract specific structural alignment coefficients
print(f"CPVD Structural Similarity Index: {pipeline_results['cpvd']:.4f}")
```
---
## Print Complete Performance Summary
```python
import cpvd

# Load the user masks
gt_mask = cpvd.load_mask("my_user_gt.png")
pred_mask = cpvd.load_mask("my_user_pred.png")
# Calculate metrics and details
results = cpvd.compute_all_metrics(gt_mask, pred_mask)
cpvd_results = cpvd.complex_phase_vector_displacement_similarity_detailed(gt_mask, pred_mask)

print("\n" + "="*50)
print("              PERFORMANCE EVALUATION")
print("="*50)
print(f" CPVD Similarity Index : {cpvd_results['cpvd']:.4f}")
print(f" Dice Coefficient      : {results['dice']:.4f}")
print(f" Jaccard Index (IoU)   : {results['jaccard']:.4f}")
print(f" Accuracy              : {results['accuracy']:.4f}")
print(f" Precision             : {results['precision']:.4f}")
print(f" Sensitivity (Recall)  : {results['sensitivity']:.4f}")
print(f" Specificity           : {results['specificity']:.4f}")
print(f" Hausdorff Distance    : {results['hausdorff']:.2f} pixels")
print("="*50)
````



