{"id":13644214,"url":"https://github.com/ultralytics/xview-yolov3","last_synced_at":"2025-05-16T14:04:50.886Z","repository":{"id":39616002,"uuid":"137117503","full_name":"ultralytics/xview-yolov3","owner":"ultralytics","description":"xView 2018 Object Detection Challenge: YOLOv3 Training and Inference.","archived":false,"fork":false,"pushed_at":"2025-05-11T00:06:48.000Z","size":62978,"stargazers_count":270,"open_issues_count":3,"forks_count":56,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-05-11T00:26:41.322Z","etag":null,"topics":["challenge","deep-learning","machine-learning","ultralytics","xview","xview-2018","yolov3","yolov3-training"],"latest_commit_sha":null,"homepage":"https://docs.ultralytics.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ultralytics.png","metadata":{"funding":{"github":"glenn-jocher","patreon":"ultralytics","open_collective":"ultralytics"},"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-06-12T19:21:21.000Z","updated_at":"2025-05-11T00:06:50.000Z","dependencies_parsed_at":"2023-11-20T01:43:46.486Z","dependency_job_id":"9307b684-609f-40f7-a969-23e9e80b830f","html_url":"https://github.com/ultralytics/xview-yolov3","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ultralytics%2Fxview-yolov3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ultralytics%2Fxview-yolov3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ultralytics%2Fxview-yolov3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ultralytics%2Fxview-yolov3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ultralytics","download_url":"https://codeload.github.com/ultralytics/xview-yolov3/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254544146,"owners_count":22088807,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["challenge","deep-learning","machine-learning","ultralytics","xview","xview-2018","yolov3","yolov3-training"],"created_at":"2024-08-02T01:01:59.234Z","updated_at":"2025-05-16T14:04:50.867Z","avatar_url":"https://github.com/ultralytics.png","language":"Python","funding_links":["https://github.com/sponsors/glenn-jocher","https://patreon.com/ultralytics","https://opencollective.com/ultralytics"],"categories":["Object Detection Applications","Python"],"sub_categories":[],"readme":"\u003ca href=\"https://www.ultralytics.com/\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/ultralytics/assets/main/logo/Ultralytics_Logotype_Original.svg\" width=\"320\" alt=\"Ultralytics logo\"\u003e\u003c/a\u003e\n\n# 🚀 Introduction\n\nWelcome to the Ultralytics `xview-yolov3` repository! This project provides the necessary code and instructions to train the powerful [Ultralytics YOLOv3](https://docs.ultralytics.com/models/yolov3/) object detection model on the challenging [xView dataset](https://challenge.xviewdataset.org/). The primary goal is to support participants in the [xView Challenge](https://challenge.xviewdataset.org/), which focuses on advancing the state-of-the-art in detecting objects within [satellite imagery](https://www.ultralytics.com/blog/using-computer-vision-to-analyse-satellite-imagery), a critical application of [computer vision](https://www.ultralytics.com/glossary/computer-vision-cv) in remote sensing.\n\n[![Ultralytics Actions](https://github.com/ultralytics/xview-yolov3/actions/workflows/format.yml/badge.svg)](https://github.com/ultralytics/xview-yolov3/actions/workflows/format.yml)\n[![Ultralytics Discord](https://img.shields.io/discord/1089800235347353640?logo=discord\u0026logoColor=white\u0026label=Discord\u0026color=blue)](https://discord.com/invite/ultralytics)\n[![Ultralytics Forums](https://img.shields.io/discourse/users?server=https%3A%2F%2Fcommunity.ultralytics.com\u0026logo=discourse\u0026label=Forums\u0026color=blue)](https://community.ultralytics.com/)\n[![Ultralytics Reddit](https://img.shields.io/reddit/subreddit-subscribers/ultralytics?style=flat\u0026logo=reddit\u0026logoColor=white\u0026label=Reddit\u0026color=blue)](https://reddit.com/r/ultralytics)\n\n\u003cimg src=\"https://github-production-user-asset-6210df.s3.amazonaws.com/26833433/238799379-bb3b02f0-dee4-4e67-80ae-4b2378b813ad.jpg?raw=true\" width=\"100%\" alt=\"xView dataset example detections\"\u003e\n\n# 📦 Requirements\n\nTo successfully run this project, ensure your environment meets the following prerequisites:\n\n- **Python:** Version 3.6 or later. You can download Python from the [official Python website](https://www.python.org/downloads/).\n- **Dependencies:** Install the required packages using pip. It's recommended to use a virtual environment.\n\n```bash\npip3 install -U -r requirements.txt\n```\n\nKey dependencies include:\n\n- `numpy`: Essential for numerical operations in Python.\n- `scipy`: Provides algorithms for scientific and technical computing.\n- `torch`: The core [PyTorch](https://pytorch.org/) library for deep learning.\n- `opencv-python`: The [OpenCV](https://opencv.org/) library for computer vision tasks.\n- `h5py`: Enables interaction with data stored in HDF5 format.\n- `tqdm`: A utility for displaying progress bars in loops and command-line interfaces.\n\n# 📥 Download Data\n\nBegin by downloading the necessary xView dataset files. You can obtain the data directly from the [xView Challenge data download page](https://challenge.xviewdataset.org/data-download). Ensure you have sufficient storage space, as satellite imagery datasets can be quite large.\n\n# 🏋️‍♂️ Training\n\nTraining the YOLOv3 model on the xView dataset involves preprocessing the data and then running the training script.\n\n## Preprocessing Steps\n\nBefore initiating the training process, we perform several preprocessing steps on the target labels to enhance model performance:\n\n1.  **Outlier Removal:** Outliers in the dataset are identified and removed using sigma-rejection to clean the data.\n2.  **Anchor Generation:** A new set of 30 [k-means anchors](https://www.ultralytics.com/glossary/anchor-based-detectors) are generated specifically tailored for the `c60_a30symmetric.cfg` configuration file. This process utilizes the MATLAB script `utils/analysis.m`. The generated anchors help the model better predict bounding boxes of various sizes and aspect ratios present in the xView dataset.\n\n\u003cimg src=\"https://github.com/ultralytics/xview-yolov3/blob/main/cfg/c60_a30.png?raw=true\" width=\"500\" alt=\"k-means anchors plot\"\u003e\n\n## Starting the Training\n\nOnce the xView data is downloaded and placed in the expected directory, you can **start training** by executing the `train.py` script. You will need to configure the path to your xView data within the script:\n\n- Modify line 41 for local machine execution.\n- Modify line 43 if you are training in a cloud environment like [Google Colab](https://docs.ultralytics.com/integrations/google-colab/) or [Kaggle](https://docs.ultralytics.com/integrations/kaggle/).\n\n```bash\npython train.py\n```\n\n## Resuming Training\n\nIf your training session is interrupted, you can easily **resume training** from the last saved checkpoint. Use the `--resume` flag as shown below:\n\n```bash\npython train.py --resume 1\n```\n\nThe script will automatically load the weights from the `latest.pt` file located in the `checkpoints/` directory and continue the training process.\n\n## Training Details\n\nDuring each training epoch, the system processes 8 randomly sampled 608x608 pixel chips extracted from each full-resolution image in the dataset. On hardware like an Nvidia GTX 1080 Ti, you can typically complete around 100 epochs per day.\n\nBe mindful of [overfitting](https://www.ultralytics.com/glossary/overfitting), which can become a significant issue after approximately 200 epochs. Monitoring validation metrics is crucial. The best observed validation mean Average Precision ([mAP](https://www.ultralytics.com/glossary/mean-average-precision-map)) in experiments was 0.16 after 300 epochs (roughly 3 days of training), corresponding to a training mAP of 0.30.\n\nMonitor the training progress by observing the loss plots for bounding box regression, objectness, and class confidence. These plots should ideally show decreasing trends, similar to the example below:\n\n\u003cimg src=\"https://github.com/ultralytics/xview-yolov3/blob/main/data/xview_training_loss.png?raw=true\" width=\"100%\" alt=\"xView training loss plot\"\u003e\n\n### Image Augmentation 📸\n\nTo improve model robustness and generalization, the `datasets.py` script applies various [data augmentations](https://www.ultralytics.com/glossary/data-augmentation) to the full-resolution input images during training using OpenCV. The specific augmentations and their parameters are:\n\n| Augmentation   | Description                               |\n| -------------- | ----------------------------------------- |\n| Translation    | +/- 1% (vertical and horizontal)          |\n| Rotation       | +/- 20 degrees                            |\n| Shear          | +/- 3 degrees (vertical and horizontal)   |\n| Scale          | +/- 30%                                   |\n| Reflection     | 50% probability (vertical and horizontal) |\n| HSV Saturation | +/- 50%                                   |\n| HSV Intensity  | +/- 50%                                   |\n\n**Note:** Augmentation is applied **only** during the training phase. During inference or validation, the original, unaugmented images are used. The corresponding [bounding box](https://www.ultralytics.com/glossary/bounding-box) coordinates are automatically adjusted to match the transformations applied to the images. Explore more augmentation techniques with [Albumentations](https://docs.ultralytics.com/integrations/albumentations/).\n\n# 🔍 Inference\n\nAfter training completes, the model checkpoints (`.pt` files) containing the learned weights are saved in the `checkpoints/` directory. You can use the `detect.py` script to perform [inference](https://docs.ultralytics.com/modes/predict/) on new or existing xView images using your trained model.\n\nFor example, to run detection on the image `5.tif` from the training set using the best performing weights (`best.pt`), you would run:\n\n```bash\npython detect.py --weights checkpoints/best.pt --source path/to/5.tif\n```\n\nThe script will process the image, detect objects, draw bounding boxes, and save the output image. An example output might look like this:\n\n\u003cimg src=\"https://github.com/ultralytics/xview/blob/main/output_img/1047.jpg?raw=true\" width=\"100%\" alt=\"Example inference output on xView image\"\u003e\n\n# 📝 Citation\n\nIf you find this repository, the associated tools, or the xView dataset useful in your research or work, please consider citing the relevant sources:\n\n[![DOI](https://zenodo.org/badge/137117503.svg)](https://zenodo.org/badge/latestdoi/137117503)\n\nFor the xView dataset itself, please refer to the citation guidelines provided on the [xView Challenge website](https://challenge.xviewdataset.org/).\n\n# 👥 Contribute\n\n🤝 We thrive on community contributions! Open-source projects like this benefit greatly from your input. Whether it's fixing bugs, adding features, or improving documentation, your help is valuable. Please see our [Contributing Guide](https://docs.ultralytics.com/help/contributing/) for more details on how to get started.\n\nWe also invite you to share your feedback through our [Survey](https://www.ultralytics.com/survey?utm_source=github\u0026utm_medium=social\u0026utm_campaign=Survey). Your insights help shape the future of Ultralytics projects.\n\nA huge thank you 🙏 to all our contributors for making our community vibrant and innovative!\n\n[![Ultralytics open-source contributors](https://raw.githubusercontent.com/ultralytics/assets/main/im/image-contributors.png)](https://github.com/ultralytics/ultralytics/graphs/contributors)\n\n# 📜 License\n\nUltralytics offers two licensing options to accommodate different needs:\n\n- **AGPL-3.0 License:** Ideal for students, researchers, and enthusiasts, this [OSI-approved](https://opensource.org/license/agpl-v3) open-source license promotes open collaboration and knowledge sharing. See the [LICENSE](https://github.com/ultralytics/xview-yolov3/blob/main/LICENSE) file for full details.\n- **Enterprise License:** Designed for commercial use, this license allows integration of Ultralytics software and AI models into commercial products and services without the open-source requirements of AGPL-3.0. If your project requires an Enterprise License, please contact us via [Ultralytics Licensing](https://www.ultralytics.com/license).\n\n# 📬 Contact\n\nFor bug reports, feature requests, or suggestions, please use the [GitHub Issues](https://github.com/ultralytics/xview-yolov3/issues) page. For general questions, discussions, and community interaction, join our [Discord](https://discord.com/invite/ultralytics) server!\n\n\u003cbr\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/ultralytics\"\u003e\u003cimg src=\"https://github.com/ultralytics/assets/raw/main/social/logo-social-github.png\" width=\"3%\" alt=\"Ultralytics GitHub\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png\" width=\"3%\" alt=\"space\"\u003e\n  \u003ca href=\"https://www.linkedin.com/company/ultralytics/\"\u003e\u003cimg src=\"https://github.com/ultralytics/assets/raw/main/social/logo-social-linkedin.png\" width=\"3%\" alt=\"Ultralytics LinkedIn\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png\" width=\"3%\" alt=\"space\"\u003e\n  \u003ca href=\"https://twitter.com/ultralytics\"\u003e\u003cimg src=\"https://github.com/ultralytics/assets/raw/main/social/logo-social-twitter.png\" width=\"3%\" alt=\"Ultralytics Twitter\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png\" width=\"3%\" alt=\"space\"\u003e\n  \u003ca href=\"https://youtube.com/ultralytics?sub_confirmation=1\"\u003e\u003cimg src=\"https://github.com/ultralytics/assets/raw/main/social/logo-social-youtube.png\" width=\"3%\" alt=\"Ultralytics YouTube\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png\" width=\"3%\" alt=\"space\"\u003e\n  \u003ca href=\"https://www.tiktok.com/@ultralytics\"\u003e\u003cimg src=\"https://github.com/ultralytics/assets/raw/main/social/logo-social-tiktok.png\" width=\"3%\" alt=\"Ultralytics TikTok\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png\" width=\"3%\" alt=\"space\"\u003e\n  \u003ca href=\"https://ultralytics.com/bilibili\"\u003e\u003cimg src=\"https://github.com/ultralytics/assets/raw/main/social/logo-social-bilibili.png\" width=\"3%\" alt=\"Ultralytics BiliBili\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png\" width=\"3%\" alt=\"space\"\u003e\n  \u003ca href=\"https://discord.com/invite/ultralytics\"\u003e\u003cimg src=\"https://github.com/ultralytics/assets/raw/main/social/logo-social-discord.png\" width=\"3%\" alt=\"Ultralytics Discord\"\u003e\u003c/a\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fultralytics%2Fxview-yolov3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fultralytics%2Fxview-yolov3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fultralytics%2Fxview-yolov3/lists"}