{"id":15912939,"url":"https://github.com/x-tabdeveloping/burial-mounds-object-recognition","last_synced_at":"2025-06-19T11:36:08.612Z","repository":{"id":235105899,"uuid":"790066848","full_name":"x-tabdeveloping/burial-mounds-object-recognition","owner":"x-tabdeveloping","description":"Finetuning Object recognition models to recognize burial mounds.","archived":false,"fork":false,"pushed_at":"2024-05-28T12:27:37.000Z","size":3610,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-05-29T03:46:46.087Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/x-tabdeveloping.png","metadata":{"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}},"created_at":"2024-04-22T07:49:12.000Z","updated_at":"2024-05-31T10:29:46.760Z","dependencies_parsed_at":"2024-05-28T15:12:03.015Z","dependency_job_id":null,"html_url":"https://github.com/x-tabdeveloping/burial-mounds-object-recognition","commit_stats":null,"previous_names":["x-tabdeveloping/burial-mounds-object-recognition"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/x-tabdeveloping/burial-mounds-object-recognition","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/x-tabdeveloping%2Fburial-mounds-object-recognition","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/x-tabdeveloping%2Fburial-mounds-object-recognition/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/x-tabdeveloping%2Fburial-mounds-object-recognition/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/x-tabdeveloping%2Fburial-mounds-object-recognition/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/x-tabdeveloping","download_url":"https://codeload.github.com/x-tabdeveloping/burial-mounds-object-recognition/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/x-tabdeveloping%2Fburial-mounds-object-recognition/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260743289,"owners_count":23055934,"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":[],"created_at":"2024-10-06T16:21:53.885Z","updated_at":"2025-06-19T11:36:03.597Z","avatar_url":"https://github.com/x-tabdeveloping.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Only Looking Once - Burial Mound Recognition with YOLO\nFinetuning Object recognition models to recognize burial mounds.\n\nThis repo was built around using YOLOv8 for detecting burial mounds in satellite images and contains utilities for using pretrained models for burial mound detection and for training mound detctor models from scratch.\n\n\u003e This repository is the product for my exam project in Spatial Analytics at Aarhus University in the Cultural Data Science programme.\n\u003e I would by no means consider this a production-ready solution, and, due to the models' low performance, I would interpret their predictions with caution.\n\n## Installation\n\nYou can install the software package from PyPI.\n\n```bash\npip install burial_mounds\n```\n\nMake sure to also install OpenCV on your computer. Here's how you would do that for Debian-based systems (which I have used):\n\n```bash\nsudo apt update \u0026\u0026 sudo apt install python3-opencv\n```\n\n## Using Pretrained Models\n\nYou can load one of the pretrained models from our HuggingFace repository:\n\n```python\nfrom burial_mounds.model import MoundDetector\n\nmodel = MoundDetector.load_from_hub(\"kardosdrur/burial-mounds-yolov8m-obb\")\n```\n\nThe package includes utilities for finding bounding polygons (`shapely.Polygon`) of burial mounds in true color satellite images.\n\n```python\nbounding_polygons = model.detect_mounds(\"some_satellite_image.png\")\nfor polygon in bounding_polygons:\n    print(polygon)\n```\nAs well as for annotating images with bounding boxes.\n\n```python\nannotated_image = model.annotate_image(\"some_satellite_image.png\")\nannotated_image.show()\n```\n\n\u003cimg src=\"assets/detections.png\" alt=\"Detected mounds\" width=\"600\"\u003e\n\nFor a more detailed guide consult the [YOLOv8 documentation](https://docs.ultralytics.com/modes/predict/#key-features-of-predict-mode).\n\n\n\nMultiple models have been made available for mound detection as part of the project, these are:\n\n| **Model Name**               | **# Parameters** | **Pretraining**  | **Size (pixels)** | **Task** |\n|------------------------------|------------------|------------------|-------------------|----------|\n| burial-mounds-yolov8m        | 26.2 M           | Open Images V7   | 640               | Detect   |\n| burial-mounds-yolov8m-xview  | 26.2 M           | xView            | 640               | Detect   |\n| burial-mounds-yolov8m-obb    | 26.4 M           | DOTA             | 1024              | OBB      |\n\n\u003e Beware that none of the models perform particularly well, see the technical report for details.\n\n## Training Models from Scratch\n\nThe Python package contains a CLI for training all the above mentioned mound detector models from scratch along with code for preprocessing the datasets the models were trained on.\n\n### Preprocessing\n\n#### xView\n\nThe CLI has code for preprocessing the data in the [xView](http://xviewdataset.org/) dataset, which contains high quality annotated satellite imagery formulated as an object detection task.\n\nDownload the dataset, and arrange it in the following folder structure:\n\n```\n- data/\n    - xView/\n        - train_images/\n            - 10.tiff\n            ...\n        xView_train.geojson\n```\n\nThen run the command:\n\n```bash\npython3 -m burial_mounds preprocess_xview --data_dir data/xView\n```\n\nThis will convert all labels in the geoJSON file to YOLO format and output a config file for YOLO training under `configs/xview.yaml`\n\n#### Burial Mounds\n\nTo preprocess the burial mounds dataset, you can also utilise the CLI.\n\nThe preprocessing pipeline will split the large geoTIFF files into smaller images with annotations.\nThe script can either prepare data for simple object detection or for [OBB](https://docs.ultralytics.com/datasets/obb/) training.\n\nThe preprocessing consists of the following steps:\n1. Splitting the large raster files into smaller windows. (`--image_size` parameter controls the size of the windows)\n2. Minmax color normalization.\n3. Producing bounding box labels (either oriented or non-oriented formats, `--format` parameter)\n\nTo prepare the dataset for OBB:\n\n```bash\npython3 -m burial_mounds preprocess_mounds --data_dir data/TRAP_Data --out_dir data/mounds --image_size 1024 --format obb\n```\n\nFor simple object detection:\n\n```bash\npython3 -m burial_mounds preprocess_mounds --data_dir data/TRAP_Data --out_dir data/mounds --image_size 640 --format detect\n```\n\n### Finetuning\n\n\u003e You might need to set the `ultralytics` package's default dataset location to the current folder when training models. The package might not be able to find the training set otherwise.\n\nThere are two types of models you can choose from for finetuning.\nEither models that have been trained on OBB, or simple object detection.\n\n\u003e OBB models have been pretrained on the DOTA satellite object recognition dataset and are therefore more likely to perform better on satellite images without finetuning.\n\nFinetuning the models also comes with data augmentation built-in thereby increasing the robustness of trained models.\n\n#### Detection\n\nThese are the models that you can finetune on a detection task:\n\n| Model   | Size (pixels) | mAPval 50-95 | Speed CPU ONNX (ms) | Speed A100 TensorRT (ms) | Params (M) | FLOPs (B) |\n|---------|---------------|--------------|---------------------|--------------------------|------------|-----------|\n| YOLOv8n | 640           | 18.4         | 142.4               | 1.21                     | 3.5        | 10.5      |\n| YOLOv8s | 640           | 27.7         | 183.1               | 1.40                     | 11.4       | 29.7      |\n| YOLOv8m | 640           | 33.6         | 408.5               | 2.26                     | 26.2       | 80.6      |\n| YOLOv8l | 640           | 34.9         | 596.9               | 2.43                     | 44.1       | 167.4     |\n| YOLOv8x | 640           | 36.3         | 860.6               | 3.56                     | 68.7       | 260.6     |\n\nThese have been pretrained on the Open Images V7 dataset with all sorts of objects the models have to recognize.\n\nYou can finetune an already existing model on object detection with the `finetune` command.\nIf you want to go down this route I recommend that you finetune on xView first, so that the model will have seen satellite images before encountering the mound problem.\n\n```bash\npython3 -m burial_mounds finetune \"yolov8n.pt\" \"configs/xview.yaml\" --epochs 300 --image_size 640\n```\n\n#### OBB\n\nThese are the models that you can finetune on OBB detection:\n\n| Model       | Size (pixels) | mAPtest 50 | Speed CPU ONNX (ms) | Speed A100 TensorRT (ms) | Params (M) | FLOPs (B) |\n|-------------|---------------|------------|---------------------|--------------------------|------------|-----------|\n| YOLOv8n-obb | 1024          | 78.0       | 204.77              | 3.57                     | 3.1        | 23.3      |\n| YOLOv8s-obb | 1024          | 79.5       | 424.88              | 4.07                     | 11.4       | 76.3      |\n| YOLOv8m-obb | 1024          | 80.5       | 763.48              | 7.61                     | 26.4       | 208.6     |\n| YOLOv8l-obb | 1024          | 80.7       | 1278.42             | 11.83                    | 44.5       | 433.8     |\n| YOLOv8x-obb | 1024          | 81.36      | 1759.10             | 13.23                    | 69.5       | 676.7     |\n\nThese models have been pretrained on the DOTA dataset, which contains satellite imagery, and these models are therefore more likely to be better at mound recognition.\n\n```bash\npython3 -m burial_mounds finetune \"yolov8n.pt\" \"configs/mounds.yaml\" --epochs 300 --image_size 1024\n```\n\nTo run these finetuning scripts in the background (on Ucloud for instance), I recommend that you use `nohup` and store the logs.\n\n```bash\nnohup python3 -m burial_mounds finetune \"yolov8n.pt\" \"configs/mounds.yaml\" --epochs 300 --image_size 1024 \u0026\u003e \"nano_mounds_finetune.log\" \u0026\n```\n\n### Publishing\n\nIf you intend to publish a trained model to the HuggingFace Hub you can use the `push_to_hub` command.\n\n```bash\npython3 -m burial_mounds push_to_hub --model_path \"runs/detect/train8/weights/best.pt\" --repo_id \"chcaa/burial-mounds_yolov8n\"\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fx-tabdeveloping%2Fburial-mounds-object-recognition","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fx-tabdeveloping%2Fburial-mounds-object-recognition","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fx-tabdeveloping%2Fburial-mounds-object-recognition/lists"}