Skip to main content

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

pip install hed-tensor

Usage (3 lines!)

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

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

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

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

# 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

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:

@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

Metadata

Release files for hed-tensor 2.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hed-tensor 2.0.0
File Size Uploaded Provenance Actions
hed_tensor-2.0.0.tar.gz 54.8 MB Without provenance Details for hed_tensor-2.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hed-tensor 2.0.0
File Interpreter ABI Platform Actions
hed_tensor-2.0.0-py3-none-any.whl Python 3 none any Details for hed_tensor-2.0.0-py3-none-any.whl

Total release size: 109.5 MB

Release files / hed_tensor-2.0.0.tar.gz

Download URL hed_tensor-2.0.0.tar.gz
Size 54.8 MB
Tags Source
SHA-256 checksum
How to use checksums
d71bf1e0806f9091eba0d4f194a9e81ba7168d19ed057e1a8718ca382ecf2e62
BLAKE2b-256 checksum
How to use checksums
d4a1e2fdf44d210fca3039b3405f9862bf9818d5e5826127b5d1cd0c9138ca41
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.11

Release files / hed_tensor-2.0.0-py3-none-any.whl

Download URL hed_tensor-2.0.0-py3-none-any.whl
Size 54.8 MB
Tags Python 3
SHA-256 checksum
How to use checksums
8f22d716110ec4f440af6c1a99aa6706b49d30139a5fbb6dbafdec13a7f50c86
BLAKE2b-256 checksum
How to use checksums
8478e68e6bc020344b0db4d0d95f250871a32a75d8d7f3f8ec80029bd40877b5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.11

Security for hed-tensor 2.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page