# DistinaNet: Combining Object Detection with Distance Estimation
[](https://www.python.org/downloads/)
[](https://pytorch.org/)
[](https://github.com/jonher16/distinanet/blob/main/LICENSE)
DistinaNet extends RetinaNet with an additional **distance estimation head** that predicts the distance to detected objects. This enables simultaneous object detection and distance estimation in a single forward pass.
## 🚀 Key Features
- **Multi-task learning**: Object detection + distance estimation
- **Multiple distance head architectures**: Base, Deep, Bottleneck, CBAM, Dynamic Branching
- **Flexible loss functions**: Huber, L1, L2, Smooth L1, LogCosh
- **Research-oriented**: Easy to modify and extend
- **KITTI dataset support**: Built-in tools for KITTI dataset preparation
- **Unified CLI interface**: Single entry point for all operations
## 📋 Table of Contents
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Project Structure](#project-structure)
- [Dataset Preparation](#dataset-preparation)
- [Training](#training)
- [Evaluation](#evaluation)
- [Inference](#inference)
- [Video Processing](#video-processing)
- [Model Architecture](#model-architecture)
- [Development](#development)
- [Citation](#citation)
## 💻 Installation
### 🔥 Quick Start (Recommended)
**Step 1: Install PyTorch with CUDA support**
```bash
# Visit https://pytorch.org/get-started/locally/ and select your configuration
# Example for CUDA 11.7:
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu117
# Example for CUDA 12.1:
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
# For CPU-only:
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
```
**Step 2: Install DistinaNet**
```bash
pip install distinanet
```
### 📦 Installation Options
#### Option 1: PyPI Installation (Stable)
```bash
# Install PyTorch first (see Step 1 above)
pip install distinanet
#### Option 2: Development Installation
```bash
# Clone and install in development mode
git clone https://github.com/jonher16/distinanet.git
cd distinanet
# Install PyTorch first (see Step 1 above)
# Then install DistinaNet
pip install -e .
```
#### Option 3: Conda Environment (Recommended for Research)
```bash
# Create environment with CUDA support
conda create -n distinanet python=3.9
conda activate distinanet
# Install PyTorch with CUDA (example for CUDA 11.7)
conda install pytorch torchvision torchaudio pytorch-cuda=11.7 -c pytorch -c nvidia
# Install DistinaNet
pip install distinanet
```
### ✅ Tested With
**Environment**
- Python **3.9.23**
- CUDA **11.7**
- GPU: **NVIDIA GeForce RTX 3050 OEM (8GB VRAM)**
- Driver Version: **575.64.03**
**Core Dependencies**
- `torch==1.13.1+cu117`
- `torchvision==0.14.1+cu117`
- `torchaudio==0.13.1+cu117`
- `numpy==1.26.4`
- `opencv-python==4.9.0.80`
**Additional Dependencies**
- `scikit-image==0.24.0`
- `matplotlib==3.9.4`
- `pandas==2.3.2`
- `tensorboard==2.20.0`
- `tqdm==4.67.1`
- `six==1.17.0`
- `openpyxl==3.1.5`
**Package Managers**
- `conda 24.9.2`
- `pip 25.2`
> 💡 **Note:** The project is compatible with newer versions, but the above were the exact versions used for testing and development.
### Verify Installation
```bash
# Check if DistinaNet is installed correctly
distinanet --help
# Check PyTorch and CUDA
python -c "import torch; print(f'PyTorch: {torch.__version__}'); print(f'CUDA available: {torch.cuda.is_available()}')"
# Test DistinaNet import
python -c "import distinanet; print('✅ DistinaNet installed successfully!')"
```
### Troubleshooting
**🚨 CUDA Installation Issues:**
If you encounter CUDA-related problems:
1. **Install PyTorch with CUDA first:**
```bash
# Check your CUDA version
nvidia-smi
# Install matching PyTorch version from https://pytorch.org/
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu117
# Then install DistinaNet
pip install distinanet
```
2. **Verify CUDA compatibility:**
```bash
python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}'); print(f'CUDA version: {torch.version.cuda}')"
```
**🔧 Dependency Conflicts:**
For development setups with specific requirements:
```bash
# Use flexible requirements (recommended for development)
pip install -r requirements.txt
pip install -e .
```
**📦 NumPy Compatibility Issues:**
If you see "Numpy is not available" errors:
```bash
# Use NumPy 1.x (stable with PyTorch)
pip install "numpy>=1.20.0,<2.0.0"
pip install "opencv-python>=4.5.0,<4.10.0"
```
**🐍 Environment Isolation:**
For clean installations:
```bash
# Create isolated environment
conda create -n distinanet python=3.9
conda activate distinanet
# Install PyTorch first, then DistinaNet
conda install pytorch torchvision pytorch-cuda=11.7 -c pytorch -c nvidia
pip install distinanet
```
**💡 Pro Tips:**
- Always install PyTorch **before** DistinaNet for proper CUDA detection
- Use `conda` for CUDA environments when possible
- Check [PyTorch compatibility matrix](https://pytorch.org/get-started/locally/) for your system
- For headless servers, consider `opencv-python-headless` instead of `opencv-python`
## 🚀 Quick Start
DistinaNet provides a unified command-line interface for all operations through the `distinanet` command:
```bash
# Train a model
distinanet train --csv_train data/train.csv --csv_classes data/classes.csv --csv_val data/val.csv
# Evaluate a model
distinanet evaluate --model_path checkpoints/model.pt --csv_annotations_path data/val.csv --csv_classes data/classes.csv
# Run inference on an image
distinanet inference --model checkpoints/model.pt --csv_classes data/classes.csv --csv_val data/val.csv
# Process a video
distinanet video --model_path checkpoints/model.pt --video_path input.mp4 --output_path output/
```
### Help and Usage
```bash
# General help
distinanet --help
# Mode-specific help
distinanet train --help
distinanet evaluate --help
distinanet inference --help
distinanet video --help
```
### Alternative: Create Your Own Shell Scripts
For convenience, you can create shell scripts with your preferred parameters. Create these files and make them executable with `chmod +x scriptname.sh`:
**Create `train.sh`:**
```bash
#!/bin/bash
export CUDA_VISIBLE_DEVICES=0
distinanet train \
--optimizer adam \
--epochs 10 \
--batch_size 16 \
--distance_loss_type huber \
--distance_head_type base \
--csv_train kitti_dataset/annotations/train_objects.csv \
--csv_classes kitti_dataset/classes.csv \
--csv_val kitti_dataset/annotations/validation_objects.csv \
--depth 18 \
--num_gpus 1
```
**Create `test.sh`:**
```bash
#!/bin/bash
export CUDA_VISIBLE_DEVICES=0
distinanet evaluate \
--csv_annotations_path kitti_dataset/annotations/test_objects.csv \
--model_path runs/2025-09-17_15-05-20/checkpoints/epoch_0.pt \
--images_path kitti_dataset/testing/image_2 \
--class_list_path kitti_dataset/classes.csv \
--save_path runs/2025-09-17_15-05-20/validation_results
```
**Create `inference.sh`:**
```bash
#!/bin/bash
export CUDA_VISIBLE_DEVICES=0
distinanet inference \
--csv_classes kitti_dataset/classes.csv \
--csv_val kitti_dataset/annotations/test_objects.csv \
--model runs/2025-09-17_15-05-20/checkpoints/epoch_0.pt
```
**Create `video.sh`:**
```bash
#!/bin/bash
export CUDA_VISIBLE_DEVICES=0
distinanet video \
--model_path runs/2025-09-17_15-05-20/checkpoints/epoch_0.pt \
--video_path kitti_dataset/test.mp4 \
--output_path runs/2025-09-17_15-05-20/video
```
**Make scripts executable:**
```bash
chmod +x train.sh test.sh inference.sh video.sh
```
## 📁 Project Structure
```
distinanet/
├── pyproject.toml # 📦 Modern Python packaging configuration
├── requirements.txt # 📋 Dependencies (for legacy installs)
├── README.md
├── LICENSE
├── distinanet/ # 📦 Core package
│ ├── __init__.py
│ ├── cli.py # 🚀 Main CLI entry point
│ └── config.py # ⚙️ Configuration management
│
│ ├── scripts/ # 📜 Executable scripts
│ │ ├── __init__.py
│ │ ├── train.py # Training script
│ │ ├── test.py # Evaluation script
│ │ ├── inference.py # Inference script
│ │ └── video.py # Video processing script
│ ├── model/ # 🧠 Model definitions
│ │ ├── model.py # Main DistinaNet model
│ │ └── ...
│ ├── data/ # 📊 Data handling
│ │ ├── datasets.py # Dataset classes
│ │ ├── dataloader.py # Data loading utilities
│ │ ├── transforms.py # Data transformations
│ │ └── ...
│ ├── engine/ # 🔧 Training engine
│ │ ├── trainer.py # Training logic
│ │ └── ...
│ ├── utils/ # 🛠️ Utilities
│ │ ├── logging_utils.py # Logging configuration
│ │ └── ...
│ └── evaluation/ # 📈 Evaluation metrics
├── kitti_dataset/ # 📊 KITTI dataset tools
│ ├── download_kitti.sh
│ ├── generate_annotations.sh
│ └── ...
└── runs/ # 📁 Training outputs and logs
```
### Installation Commands
After installing the package with `pip install .` or `pip install distinanet`, you can use:
```bash
# Direct CLI commands (recommended)
distinanet train --help
distinanet evaluate --help
distinanet inference --help
distinanet video --help
# Create your own shell scripts (optional)
# See "Alternative: Create Your Own Shell Scripts" section above
```
## 📊 Dataset Preparation
### KITTI Dataset
1. **Download KITTI dataset**
```bash
cd kitti_dataset
chmod +x download_kitti.sh
./download_kitti.sh
```
2. **Generate annotations**
```bash
chmod +x generate_annotations.sh
./generate_annotations.sh
```
This creates `train_objects.csv`, `validation_objects.csv`, and `test_objects.csv` files (used for training the model).
### Custom Dataset Format
#### Annotations CSV Format
```
path/to/image.jpg,x1,y1,x2,y2,class_name,distance
```
**Example:**
```
/data/imgs/img_001.jpg,837,346,981,456,cow,12.5
/data/imgs/img_002.jpg,215,312,279,391,cat,6.8
/data/imgs/img_002.jpg,22,5,89,84,bird,23.1
/data/imgs/img_003.jpg,,,,,, # Negative example (no objects)
```
#### Classes CSV Format
```
class_name,id
```
**Example:**
```
cow,0
cat,1
bird,2
```
## 🏃♂️ Training
### Using CLI
```bash
distinanet train \\
--csv_train kitti_dataset/annotations/train_objects.csv \\
--csv_classes kitti_dataset/classes.csv \\
--csv_val kitti_dataset/annotations/validation_objects.csv \\
--epochs 100 \\
--batch_size 16 \\
--depth 18 \\
--distance_head_type base \\
--distance_loss_type huber \\
--optimizer adam
```
### Using Your Shell Script
```bash
# Create and use your train.sh script (see "Create Your Own Shell Scripts" section)
chmod +x train.sh
./train.sh
```
### Training Parameters
| Parameter | Options | Default | Description |
|-----------|---------|---------|-------------|
| `--depth` | 18, 34, 50, 101, 152 | 50 | ResNet backbone depth |
| `--distance_head_type` | base, deep, bottleneck, cbam, dynamicbranching | base | Distance head architecture |
| `--distance_loss_type` | huber, l1, l2, smoothl1, logcosh | huber | Distance loss function |
| `--optimizer` | adam, sgd, rmsprop, adagrad, nadam | adam | Optimization algorithm |
| `--batch_size` | int | 1 | Training batch size |
| `--epochs` | int | 100 | Number of training epochs |
| `--lr` | float | 1e-5 | Learning rate |
## 📈 Evaluation
### Using CLI
```bash
distinanet evaluate \\
--model_path runs/latest/checkpoints/model.pt \\
--csv_annotations_path kitti_dataset/annotations/test_objects.csv \\
--class_list_path kitti_dataset/classes.csv \\
--images_path kitti_dataset/testing/image_2
```
### Using Your Shell Script
```bash
# Create and use your test.sh script (see "Create Your Own Shell Scripts" section)
chmod +x test.sh
./test.sh
```
**Metrics:**
- **mAP**: Mean Average Precision for object detection
- **MAE**: Mean Absolute Error for distance estimation
- **IoU**: Intersection over Union thresholds
## 🔍 Inference
### Single Image Inference
```bash
distinanet inference \\
--model runs/latest/checkpoints/model.pt \\
--csv_classes kitti_dataset/classes.csv \\
--csv_val kitti_dataset/annotations/test_objects.csv
```
### Using Your Shell Script
```bash
# Create and use your inference.sh script (see "Create Your Own Shell Scripts" section)
chmod +x inference.sh
./inference.sh
```
The inference script will:
- Load the trained model
- Process images from the validation set
- Display results with bounding boxes and distance predictions
- Save annotated images (optional)
## 🎥 Video Processing
### Process Video Files
```bash
distinanet video \\
--model_path runs/latest/checkpoints/model.pt \\
--video_path input_video.mp4 \\
--output_path output_directory/
```
### Using Your Shell Script
```bash
# Create and use your video.sh script (see "Create Your Own Shell Scripts" section)
chmod +x video.sh
./video.sh
```
Features:
- Real-time object detection and distance estimation
- Annotated output video generation
- Support for various video formats
- Configurable confidence thresholds
## 🏗️ Model Architecture
DistinaNet consists of:
1. **ResNet Backbone**: Feature extraction (ResNet-18/34/50/101/152)
2. **Feature Pyramid Network (FPN)**: Multi-scale feature fusion
3. **Classification Head**: Object class prediction
4. **Regression Head**: Bounding box regression
5. **Distance Head**: Distance estimation (5 different architectures available)
### Distance Head Architectures
- **Base**: Simple convolutional layers
- **Deep**: Deeper convolutional network
- **Bottleneck**: Efficient bottleneck design
- **CBAM**: Convolutional Block Attention Module
- **Dynamic Branching**: Adaptive feature selection
## 🔧 Development
### Adding New Distance Heads
1. Implement your distance head in `distinanet/model/model.py`
2. Add it to the model factory in `distinanet/model/model_factory.py`
3. Update configuration options in `config.py`
### Running Tests
```bash
# Test the installation
python -c \"import distinanet; print('DistinaNet imported successfully')\"
# Test training (1 epoch)
python cli.py train --epochs 1 --csv_train small_dataset.csv --csv_classes classes.csv
```
### Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes in the appropriate module
4. Test your changes
5. Commit (`git commit -m 'Add amazing feature'`)
6. Push (`git push origin feature/amazing-feature`)
7. Create a Pull Request
## 📝 Citation
If you use DistinaNet in your research, please cite:
```bibtex
@inproceedings{distinanet2025,
author = {Jon Hernandez Aranda and Patrick Dominique Vibild and Daeyoung Kim},
title = {Distance-Aware Single-Stage Detectors: Combining Detection with Object-Specific Distance Estimation},
booktitle = {Proceedings of the 2025 16th International Conference on Information and Communication Technology Convergence (ICTC)},
year = {2025}
}
```
## 🙏 Acknowledgements
- Base implementation from [pytorch-retinanet](https://github.com/yhenon/pytorch-retinanet)
- Significant code borrowed from [keras-retinanet](https://github.com/fizyr/keras-retinanet)
- NMS module from [pytorch-faster-rcnn](https://github.com/ruotianluo/pytorch-faster-rcnn)
- Original RetinaNet paper: [Focal Loss for Dense Object Detection](https://arxiv.org/abs/1708.02002)
## 📄 License
This project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## 📞 Support
If you encounter any issues or have questions:
1. Check the [Issues](https://github.com/jonher16/distinanet/issues) page
2. Create a new issue with detailed information
3. Provide code examples and error messages when applicable
Raw data
{
"_id": null,
"home_page": null,
"name": "distinanet",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "computer vision, deep learning, distance estimation, object detection, pytorch, retinanet",
"author": null,
"author_email": "Jon Hernandez Aranda <jonher16@kaist.ac.kr>",
"download_url": "https://files.pythonhosted.org/packages/fe/cd/cc2aef906cd57fb230d09bb759848cb96f3cf7c0566b9febacb5f0854e81/distinanet-1.0.1.tar.gz",
"platform": null,
"description": "# DistinaNet: Combining Object Detection with Distance Estimation\n\n[](https://www.python.org/downloads/)\n[](https://pytorch.org/)\n[](https://github.com/jonher16/distinanet/blob/main/LICENSE)\n\n\n\nDistinaNet extends RetinaNet with an additional **distance estimation head** that predicts the distance to detected objects. This enables simultaneous object detection and distance estimation in a single forward pass.\n\n## \ud83d\ude80 Key Features\n\n- **Multi-task learning**: Object detection + distance estimation\n- **Multiple distance head architectures**: Base, Deep, Bottleneck, CBAM, Dynamic Branching\n- **Flexible loss functions**: Huber, L1, L2, Smooth L1, LogCosh\n- **Research-oriented**: Easy to modify and extend\n- **KITTI dataset support**: Built-in tools for KITTI dataset preparation\n- **Unified CLI interface**: Single entry point for all operations\n\n## \ud83d\udccb Table of Contents\n\n- [Installation](#installation)\n- [Quick Start](#quick-start) \n- [Project Structure](#project-structure)\n- [Dataset Preparation](#dataset-preparation)\n- [Training](#training)\n- [Evaluation](#evaluation)\n- [Inference](#inference)\n- [Video Processing](#video-processing)\n- [Model Architecture](#model-architecture)\n- [Development](#development)\n- [Citation](#citation)\n\n## \ud83d\udcbb Installation\n\n### \ud83d\udd25 Quick Start (Recommended)\n\n**Step 1: Install PyTorch with CUDA support**\n```bash\n# Visit https://pytorch.org/get-started/locally/ and select your configuration\n# Example for CUDA 11.7:\npip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu117\n\n# Example for CUDA 12.1:\npip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121\n\n# For CPU-only:\npip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu\n```\n\n**Step 2: Install DistinaNet**\n```bash\npip install distinanet\n```\n\n### \ud83d\udce6 Installation Options\n\n#### Option 1: PyPI Installation (Stable)\n```bash\n# Install PyTorch first (see Step 1 above)\npip install distinanet\n\n#### Option 2: Development Installation\n```bash\n# Clone and install in development mode\ngit clone https://github.com/jonher16/distinanet.git\ncd distinanet\n\n# Install PyTorch first (see Step 1 above)\n# Then install DistinaNet\npip install -e .\n```\n\n#### Option 3: Conda Environment (Recommended for Research)\n```bash\n# Create environment with CUDA support\nconda create -n distinanet python=3.9\nconda activate distinanet\n\n# Install PyTorch with CUDA (example for CUDA 11.7)\nconda install pytorch torchvision torchaudio pytorch-cuda=11.7 -c pytorch -c nvidia\n\n# Install DistinaNet\npip install distinanet\n```\n\n### \u2705 Tested With\n\n**Environment**\n- Python **3.9.23**\n- CUDA **11.7**\n- GPU: **NVIDIA GeForce RTX 3050 OEM (8GB VRAM)**\n- Driver Version: **575.64.03**\n\n**Core Dependencies**\n- `torch==1.13.1+cu117`\n- `torchvision==0.14.1+cu117`\n- `torchaudio==0.13.1+cu117`\n- `numpy==1.26.4`\n- `opencv-python==4.9.0.80`\n\n**Additional Dependencies**\n- `scikit-image==0.24.0`\n- `matplotlib==3.9.4`\n- `pandas==2.3.2`\n- `tensorboard==2.20.0`\n- `tqdm==4.67.1`\n- `six==1.17.0`\n- `openpyxl==3.1.5`\n\n**Package Managers**\n- `conda 24.9.2`\n- `pip 25.2`\n\n> \ud83d\udca1 **Note:** The project is compatible with newer versions, but the above were the exact versions used for testing and development.\n\n### Verify Installation\n\n```bash\n# Check if DistinaNet is installed correctly\ndistinanet --help\n\n# Check PyTorch and CUDA\npython -c \"import torch; print(f'PyTorch: {torch.__version__}'); print(f'CUDA available: {torch.cuda.is_available()}')\"\n\n# Test DistinaNet import\npython -c \"import distinanet; print('\u2705 DistinaNet installed successfully!')\"\n```\n\n### Troubleshooting\n\n**\ud83d\udea8 CUDA Installation Issues:**\n\nIf you encounter CUDA-related problems:\n\n1. **Install PyTorch with CUDA first:**\n ```bash\n # Check your CUDA version\n nvidia-smi\n \n # Install matching PyTorch version from https://pytorch.org/\n pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu117\n \n # Then install DistinaNet\n pip install distinanet\n ```\n\n2. **Verify CUDA compatibility:**\n ```bash\n python -c \"import torch; print(f'CUDA available: {torch.cuda.is_available()}'); print(f'CUDA version: {torch.version.cuda}')\"\n ```\n\n**\ud83d\udd27 Dependency Conflicts:**\n\nFor development setups with specific requirements:\n```bash\n# Use flexible requirements (recommended for development)\npip install -r requirements.txt\npip install -e .\n```\n\n**\ud83d\udce6 NumPy Compatibility Issues:**\n\nIf you see \"Numpy is not available\" errors:\n```bash\n# Use NumPy 1.x (stable with PyTorch)\npip install \"numpy>=1.20.0,<2.0.0\"\npip install \"opencv-python>=4.5.0,<4.10.0\"\n```\n\n**\ud83d\udc0d Environment Isolation:**\n\nFor clean installations:\n```bash\n# Create isolated environment\nconda create -n distinanet python=3.9\nconda activate distinanet\n\n# Install PyTorch first, then DistinaNet\nconda install pytorch torchvision pytorch-cuda=11.7 -c pytorch -c nvidia\npip install distinanet\n```\n\n**\ud83d\udca1 Pro Tips:**\n- Always install PyTorch **before** DistinaNet for proper CUDA detection\n- Use `conda` for CUDA environments when possible \n- Check [PyTorch compatibility matrix](https://pytorch.org/get-started/locally/) for your system\n- For headless servers, consider `opencv-python-headless` instead of `opencv-python`\n\n## \ud83d\ude80 Quick Start\n\nDistinaNet provides a unified command-line interface for all operations through the `distinanet` command:\n\n```bash\n# Train a model\ndistinanet train --csv_train data/train.csv --csv_classes data/classes.csv --csv_val data/val.csv\n\n# Evaluate a model\ndistinanet evaluate --model_path checkpoints/model.pt --csv_annotations_path data/val.csv --csv_classes data/classes.csv\n\n# Run inference on an image\ndistinanet inference --model checkpoints/model.pt --csv_classes data/classes.csv --csv_val data/val.csv\n\n# Process a video\ndistinanet video --model_path checkpoints/model.pt --video_path input.mp4 --output_path output/\n```\n\n### Help and Usage\n```bash\n# General help\ndistinanet --help\n\n# Mode-specific help\ndistinanet train --help\ndistinanet evaluate --help\ndistinanet inference --help\ndistinanet video --help\n```\n\n### Alternative: Create Your Own Shell Scripts\n\nFor convenience, you can create shell scripts with your preferred parameters. Create these files and make them executable with `chmod +x scriptname.sh`:\n\n**Create `train.sh`:**\n```bash\n#!/bin/bash\nexport CUDA_VISIBLE_DEVICES=0\ndistinanet train \\\n --optimizer adam \\\n --epochs 10 \\\n --batch_size 16 \\\n --distance_loss_type huber \\\n --distance_head_type base \\\n --csv_train kitti_dataset/annotations/train_objects.csv \\\n --csv_classes kitti_dataset/classes.csv \\\n --csv_val kitti_dataset/annotations/validation_objects.csv \\\n --depth 18 \\\n --num_gpus 1\n```\n\n**Create `test.sh`:**\n```bash\n#!/bin/bash\nexport CUDA_VISIBLE_DEVICES=0\ndistinanet evaluate \\\n --csv_annotations_path kitti_dataset/annotations/test_objects.csv \\\n --model_path runs/2025-09-17_15-05-20/checkpoints/epoch_0.pt \\\n --images_path kitti_dataset/testing/image_2 \\\n --class_list_path kitti_dataset/classes.csv \\\n --save_path runs/2025-09-17_15-05-20/validation_results\n```\n\n**Create `inference.sh`:**\n```bash\n#!/bin/bash\nexport CUDA_VISIBLE_DEVICES=0\ndistinanet inference \\\n --csv_classes kitti_dataset/classes.csv \\\n --csv_val kitti_dataset/annotations/test_objects.csv \\\n --model runs/2025-09-17_15-05-20/checkpoints/epoch_0.pt\n```\n\n**Create `video.sh`:**\n```bash\n#!/bin/bash\nexport CUDA_VISIBLE_DEVICES=0\ndistinanet video \\\n --model_path runs/2025-09-17_15-05-20/checkpoints/epoch_0.pt \\\n --video_path kitti_dataset/test.mp4 \\\n --output_path runs/2025-09-17_15-05-20/video\n```\n\n**Make scripts executable:**\n```bash\nchmod +x train.sh test.sh inference.sh video.sh\n```\n\n## \ud83d\udcc1 Project Structure\n\n```\ndistinanet/\n\u251c\u2500\u2500 pyproject.toml # \ud83d\udce6 Modern Python packaging configuration\n\u251c\u2500\u2500 requirements.txt # \ud83d\udccb Dependencies (for legacy installs)\n\u251c\u2500\u2500 README.md \n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 distinanet/ # \ud83d\udce6 Core package\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 cli.py # \ud83d\ude80 Main CLI entry point\n\u2502 \u2514\u2500\u2500 config.py # \u2699\ufe0f Configuration management\n\u2502\n\u2502 \u251c\u2500\u2500 scripts/ # \ud83d\udcdc Executable scripts\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 train.py # Training script\n\u2502 \u2502 \u251c\u2500\u2500 test.py # Evaluation script\n\u2502 \u2502 \u251c\u2500\u2500 inference.py # Inference script\n\u2502 \u2502 \u2514\u2500\u2500 video.py # Video processing script\n\u2502 \u251c\u2500\u2500 model/ # \ud83e\udde0 Model definitions\n\u2502 \u2502 \u251c\u2500\u2500 model.py # Main DistinaNet model\n\u2502 \u2502 \u2514\u2500\u2500 ...\n\u2502 \u251c\u2500\u2500 data/ # \ud83d\udcca Data handling\n\u2502 \u2502 \u251c\u2500\u2500 datasets.py # Dataset classes\n\u2502 \u2502 \u251c\u2500\u2500 dataloader.py # Data loading utilities\n\u2502 \u2502 \u251c\u2500\u2500 transforms.py # Data transformations\n\u2502 \u2502 \u2514\u2500\u2500 ...\n\u2502 \u251c\u2500\u2500 engine/ # \ud83d\udd27 Training engine\n\u2502 \u2502 \u251c\u2500\u2500 trainer.py # Training logic\n\u2502 \u2502 \u2514\u2500\u2500 ...\n\u2502 \u251c\u2500\u2500 utils/ # \ud83d\udee0\ufe0f Utilities\n\u2502 \u2502 \u251c\u2500\u2500 logging_utils.py # Logging configuration\n\u2502 \u2502 \u2514\u2500\u2500 ...\n\u2502 \u2514\u2500\u2500 evaluation/ # \ud83d\udcc8 Evaluation metrics\n\u251c\u2500\u2500 kitti_dataset/ # \ud83d\udcca KITTI dataset tools\n\u2502 \u251c\u2500\u2500 download_kitti.sh\n\u2502 \u251c\u2500\u2500 generate_annotations.sh\n\u2502 \u2514\u2500\u2500 ...\n\u2514\u2500\u2500 runs/ # \ud83d\udcc1 Training outputs and logs\n```\n\n### Installation Commands\n\nAfter installing the package with `pip install .` or `pip install distinanet`, you can use:\n\n```bash\n# Direct CLI commands (recommended)\ndistinanet train --help\ndistinanet evaluate --help\ndistinanet inference --help\ndistinanet video --help\n\n# Create your own shell scripts (optional)\n# See \"Alternative: Create Your Own Shell Scripts\" section above\n```\n\n## \ud83d\udcca Dataset Preparation\n\n### KITTI Dataset\n\n1. **Download KITTI dataset**\n```bash\ncd kitti_dataset\nchmod +x download_kitti.sh\n./download_kitti.sh\n```\n\n2. **Generate annotations**\n```bash\nchmod +x generate_annotations.sh\n./generate_annotations.sh\n```\n\nThis creates `train_objects.csv`, `validation_objects.csv`, and `test_objects.csv` files (used for training the model).\n\n### Custom Dataset Format\n\n#### Annotations CSV Format\n```\npath/to/image.jpg,x1,y1,x2,y2,class_name,distance\n```\n\n**Example:**\n```\n/data/imgs/img_001.jpg,837,346,981,456,cow,12.5\n/data/imgs/img_002.jpg,215,312,279,391,cat,6.8\n/data/imgs/img_002.jpg,22,5,89,84,bird,23.1\n/data/imgs/img_003.jpg,,,,,, # Negative example (no objects)\n```\n\n#### Classes CSV Format\n```\nclass_name,id\n```\n\n**Example:**\n```\ncow,0\ncat,1\nbird,2\n```\n\n## \ud83c\udfc3\u200d\u2642\ufe0f Training\n\n### Using CLI\n\n```bash\ndistinanet train \\\\\n --csv_train kitti_dataset/annotations/train_objects.csv \\\\\n --csv_classes kitti_dataset/classes.csv \\\\\n --csv_val kitti_dataset/annotations/validation_objects.csv \\\\\n --epochs 100 \\\\\n --batch_size 16 \\\\\n --depth 18 \\\\\n --distance_head_type base \\\\\n --distance_loss_type huber \\\\\n --optimizer adam\n```\n\n### Using Your Shell Script\n\n```bash\n# Create and use your train.sh script (see \"Create Your Own Shell Scripts\" section)\nchmod +x train.sh\n./train.sh\n```\n\n### Training Parameters\n\n| Parameter | Options | Default | Description |\n|-----------|---------|---------|-------------|\n| `--depth` | 18, 34, 50, 101, 152 | 50 | ResNet backbone depth |\n| `--distance_head_type` | base, deep, bottleneck, cbam, dynamicbranching | base | Distance head architecture |\n| `--distance_loss_type` | huber, l1, l2, smoothl1, logcosh | huber | Distance loss function |\n| `--optimizer` | adam, sgd, rmsprop, adagrad, nadam | adam | Optimization algorithm |\n| `--batch_size` | int | 1 | Training batch size |\n| `--epochs` | int | 100 | Number of training epochs |\n| `--lr` | float | 1e-5 | Learning rate |\n\n## \ud83d\udcc8 Evaluation\n\n### Using CLI\n\n```bash\ndistinanet evaluate \\\\\n --model_path runs/latest/checkpoints/model.pt \\\\\n --csv_annotations_path kitti_dataset/annotations/test_objects.csv \\\\\n --class_list_path kitti_dataset/classes.csv \\\\\n --images_path kitti_dataset/testing/image_2\n```\n\n### Using Your Shell Script\n\n```bash\n# Create and use your test.sh script (see \"Create Your Own Shell Scripts\" section)\nchmod +x test.sh\n./test.sh\n```\n\n**Metrics:**\n- **mAP**: Mean Average Precision for object detection\n- **MAE**: Mean Absolute Error for distance estimation\n- **IoU**: Intersection over Union thresholds\n\n## \ud83d\udd0d Inference\n\n### Single Image Inference\n\n```bash\ndistinanet inference \\\\\n --model runs/latest/checkpoints/model.pt \\\\\n --csv_classes kitti_dataset/classes.csv \\\\\n --csv_val kitti_dataset/annotations/test_objects.csv\n```\n\n### Using Your Shell Script\n\n```bash\n# Create and use your inference.sh script (see \"Create Your Own Shell Scripts\" section)\nchmod +x inference.sh\n./inference.sh\n```\n\nThe inference script will:\n- Load the trained model\n- Process images from the validation set\n- Display results with bounding boxes and distance predictions\n- Save annotated images (optional)\n\n## \ud83c\udfa5 Video Processing\n\n### Process Video Files\n\n```bash\ndistinanet video \\\\\n --model_path runs/latest/checkpoints/model.pt \\\\\n --video_path input_video.mp4 \\\\\n --output_path output_directory/\n```\n\n### Using Your Shell Script\n\n```bash\n# Create and use your video.sh script (see \"Create Your Own Shell Scripts\" section)\nchmod +x video.sh\n./video.sh\n```\n\nFeatures:\n- Real-time object detection and distance estimation\n- Annotated output video generation\n- Support for various video formats\n- Configurable confidence thresholds\n\n## \ud83c\udfd7\ufe0f Model Architecture\n\nDistinaNet consists of:\n\n1. **ResNet Backbone**: Feature extraction (ResNet-18/34/50/101/152)\n2. **Feature Pyramid Network (FPN)**: Multi-scale feature fusion\n3. **Classification Head**: Object class prediction\n4. **Regression Head**: Bounding box regression \n5. **Distance Head**: Distance estimation (5 different architectures available)\n\n### Distance Head Architectures\n\n- **Base**: Simple convolutional layers\n- **Deep**: Deeper convolutional network\n- **Bottleneck**: Efficient bottleneck design\n- **CBAM**: Convolutional Block Attention Module\n- **Dynamic Branching**: Adaptive feature selection\n\n## \ud83d\udd27 Development\n\n### Adding New Distance Heads\n\n1. Implement your distance head in `distinanet/model/model.py`\n2. Add it to the model factory in `distinanet/model/model_factory.py`\n3. Update configuration options in `config.py`\n\n### Running Tests\n\n```bash\n# Test the installation\npython -c \\\"import distinanet; print('DistinaNet imported successfully')\\\"\n\n# Test training (1 epoch)\npython cli.py train --epochs 1 --csv_train small_dataset.csv --csv_classes classes.csv\n```\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes in the appropriate module\n4. Test your changes\n5. Commit (`git commit -m 'Add amazing feature'`)\n6. Push (`git push origin feature/amazing-feature`)\n7. Create a Pull Request\n\n## \ud83d\udcdd Citation\n\nIf you use DistinaNet in your research, please cite:\n\n```bibtex\n@inproceedings{distinanet2025,\n author = {Jon Hernandez Aranda and Patrick Dominique Vibild and Daeyoung Kim},\n title = {Distance-Aware Single-Stage Detectors: Combining Detection with Object-Specific Distance Estimation},\n booktitle = {Proceedings of the 2025 16th International Conference on Information and Communication Technology Convergence (ICTC)},\n year = {2025}\n}\n```\n\n## \ud83d\ude4f Acknowledgements\n\n- Base implementation from [pytorch-retinanet](https://github.com/yhenon/pytorch-retinanet)\n- Significant code borrowed from [keras-retinanet](https://github.com/fizyr/keras-retinanet)\n- NMS module from [pytorch-faster-rcnn](https://github.com/ruotianluo/pytorch-faster-rcnn)\n- Original RetinaNet paper: [Focal Loss for Dense Object Detection](https://arxiv.org/abs/1708.02002)\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## \ud83d\udcde Support\n\nIf you encounter any issues or have questions:\n\n1. Check the [Issues](https://github.com/jonher16/distinanet/issues) page\n2. Create a new issue with detailed information\n3. Provide code examples and error messages when applicable\n",
"bugtrack_url": null,
"license": null,
"summary": "DistinaNet: RetinaNet with Distance Estimation for simultaneous object detection and distance estimation",
"version": "1.0.1",
"project_urls": {
"Bug Reports": "https://github.com/jonher16/distinanet/issues",
"Documentation": "https://distinanet.readthedocs.io",
"Homepage": "https://github.com/jonher16/distinanet",
"Repository": "https://github.com/jonher16/distinanet"
},
"split_keywords": [
"computer vision",
" deep learning",
" distance estimation",
" object detection",
" pytorch",
" retinanet"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1039fcc229e3d2debe6831295c25d74fb9ffcda314936e6203627c1558878d30",
"md5": "561725af3eebc0a7aac1a35d4b10775d",
"sha256": "5382210a0ceb546799ac7bfad8ceea46fb1154d022544b3c8abcdf49149d2393"
},
"downloads": -1,
"filename": "distinanet-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "561725af3eebc0a7aac1a35d4b10775d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 62517,
"upload_time": "2025-09-17T11:34:59",
"upload_time_iso_8601": "2025-09-17T11:34:59.693170Z",
"url": "https://files.pythonhosted.org/packages/10/39/fcc229e3d2debe6831295c25d74fb9ffcda314936e6203627c1558878d30/distinanet-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fecdcc2aef906cd57fb230d09bb759848cb96f3cf7c0566b9febacb5f0854e81",
"md5": "e5a6568105edd6ea2dd072c5d29a1e82",
"sha256": "70f8c45b31a234ad7c776e9a74898e9e5311dd9d686f91c35df04b23f98f6bfa"
},
"downloads": -1,
"filename": "distinanet-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "e5a6568105edd6ea2dd072c5d29a1e82",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 765820,
"upload_time": "2025-09-17T11:35:02",
"upload_time_iso_8601": "2025-09-17T11:35:02.797923Z",
"url": "https://files.pythonhosted.org/packages/fe/cd/cc2aef906cd57fb230d09bb759848cb96f3cf7c0566b9febacb5f0854e81/distinanet-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-17 11:35:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jonher16",
"github_project": "distinanet",
"github_not_found": true,
"lcname": "distinanet"
}
JSON
