Metadata-Version: 2.4
Name: hed-tensor
Version: 2.0.0
Summary: Holistic Edge Detection (HED) model for TensorFlow/Keras with bundled pretrained weights
Author: Mohammad Saad Nathani
Author-email: saadnathani2005@gmail.com
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
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 :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tensorflow>=2.16
Requires-Dist: numpy>=1.19.0
Requires-Dist: Pillow>=8.0.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.9.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# HED-Tensor: Holistic Edge Detection

A TensorFlow/Keras implementation of **Holistically-Nested Edge Detection (HED)** with **pretrained weights included**. Use it as easily as VGG16 or ResNet!

## 🚀 Quick Start

### Installation

```bash
pip install hed-tensor
```

### Usage (3 lines!)

```python
from hed_tensor import HED, detect_edges

model = HED()  # Weights automatically load!
edges = detect_edges('your_image.jpg', model=model)
```

That's it! No need to download weights separately. 🎉

## 🆕 What's new in 2.0.0

- **Retrained weights.** The bundled `hed_bsds500.weights.h5` was retrained from ImageNet VGG16 with the
  original authors' Caffe recipe: the full augmented HED-BSDS training set (28,800 images), 10 epochs
  (28,680 updates of 10 images), class-balanced loss summed over pixels, consensus labels, per-layer learning
  rates, SGD with momentum, learning rate 1e-6 divided by 10 every 10k updates. The 1.x weights came from a short
  run whose learning rate decayed to almost zero after 2 epochs, so their edge maps were mostly noise.
- **No unnecessary download.** `HED()` no longer downloads the ImageNet VGG16 weights (58 MB) when it loads HED
  weights; they are only used for `HED(weights=None)`, i.e. to start training.
- **Errors are raised.** A missing or incompatible weights file now raises an exception instead of printing a
  warning and silently returning an untrained model.
- **Loss = original HED loss.** `WeightedBCELoss` / `HEDLoss` now match the Caffe implementation the weights were
  trained with (summed over pixels per image, averaged over images; labels 0/1).
- `detect_edges` runs the model directly (faster, no re-tracing for each new image size);
  `batch_detect_edges` and `save_edge_map` are now exported, as the examples below always assumed.
- Requires TensorFlow ≥ 2.16 (Keras 3), which the weights file format needs.

## 📦 Features

✅ **Pretrained weights included** - No extra downloads needed  
✅ **Simple API** - Just like using VGG16 or ResNet  
✅ **Multiple input formats** - Works with file paths, PIL Images, or NumPy arrays  
✅ **Batch processing** - Process multiple images efficiently  
✅ **TensorFlow 2.16+ / Keras 3** - Modern and fast  

## 🎯 Examples

### Basic Usage

```python
from hed_tensor import HED, detect_edges
from PIL import Image

# Load model (weights auto-load)
model = HED()

# Detect edges
edges = detect_edges('image.jpg', model=model)

# Save result
Image.fromarray(edges).save('edges.png')
```

### Using NumPy arrays

```python
import numpy as np
from hed_tensor import HED, detect_edges

model = HED()
image_array = np.array(Image.open('image.jpg'))
edges = detect_edges(image_array, model=model)
```

### Batch Processing

```python
from hed_tensor import batch_detect_edges, HED

model = HED()
image_paths = ['img1.jpg', 'img2.jpg', 'img3.jpg']

edge_maps = batch_detect_edges(
    image_paths, 
    model=model, 
    output_dir='output_edges'
)
```

### Load Custom Weights

```python
# Use your own trained weights
model = HED(weights='path/to/your/model.weights.h5')

# Or skip loading weights (ImageNet VGG16 backbone, for training)
model = HED(weights=None)
```

### Side outputs

```python
import tensorflow as tf
from hed_tensor import HED, preprocess_image

model = HED()
logits = model(preprocess_image('image.jpg'), training=True)  # 5 side outputs + fused
side1, side2, side3, side4, side5, fused = [tf.sigmoid(l)[0, ..., 0].numpy() for l in logits]
```

## 📋 Requirements

- Python >= 3.9
- TensorFlow >= 2.16 (Keras 3)
- NumPy >= 1.19.0
- Pillow >= 8.0.0

## 🎓 Citation

If you use this package in your research, please cite the original HED paper:

```bibtex
@inproceedings{xie2015holistically,
  title={Holistically-nested edge detection},
  author={Xie, Saining and Tu, Zhuowen},
  booktitle={Proceedings of the IEEE International Conference on Computer Vision},
  pages={1395--1403},
  year={2015}
}
```

## 📄 License

MIT License

## 👨‍💻 Author

**Mohammad Saad Nathani**  
📧 saadnathani2005@gmail.com

## 🤝 Contributing

Contributions are welcome!

---

**Made with ❤️ for the Computer Vision community**
