{"id":31653149,"url":"https://github.com/boschresearch/hyp-ow","last_synced_at":"2025-10-07T10:41:34.065Z","repository":{"id":222409045,"uuid":"757197237","full_name":"boschresearch/Hyp-OW","owner":"boschresearch","description":"[AAAI 2024] Official code for                    \"Hyp-OW: Exploiting Hierarchical Structure Learning with Hyperbolic Distance Enhances Open World Object Detection\"","archived":false,"fork":false,"pushed_at":"2024-02-14T18:12:59.000Z","size":14081,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-02-15T03:23:31.978Z","etag":null,"topics":["deformable-detr","hierarchical-structure-learning","hyperbolic-distance","ms-coco","open-world-object-detection","pascal-voc"],"latest_commit_sha":null,"homepage":"","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/boschresearch.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}},"created_at":"2024-02-14T01:38:16.000Z","updated_at":"2024-02-14T02:16:58.000Z","dependencies_parsed_at":"2024-02-14T03:33:40.227Z","dependency_job_id":null,"html_url":"https://github.com/boschresearch/Hyp-OW","commit_stats":null,"previous_names":["boschresearch/hyp-ow"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/boschresearch/Hyp-OW","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boschresearch%2FHyp-OW","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boschresearch%2FHyp-OW/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boschresearch%2FHyp-OW/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boschresearch%2FHyp-OW/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/boschresearch","download_url":"https://codeload.github.com/boschresearch/Hyp-OW/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boschresearch%2FHyp-OW/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278762925,"owners_count":26041444,"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","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["deformable-detr","hierarchical-structure-learning","hyperbolic-distance","ms-coco","open-world-object-detection","pascal-voc"],"created_at":"2025-10-07T10:41:32.645Z","updated_at":"2025-10-07T10:41:34.059Z","avatar_url":"https://github.com/boschresearch.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hyp-OW: Exploiting Hierarchical Structure Learning with Hyperbolic Distance Enhances Open World Object Detection (AAAI 2024)\n\n:fire:  Official Implementation \n\n[![arXiv](https://img.shields.io/badge/📜arXiv-2306.14291-red)](https://arxiv.org/abs/2306.14291) [![Static Badge](https://img.shields.io/badge/🖼️pdf-Poster-blue)](https://github.com/boschresearch/Hyp-OW/blob/main/img/Poster_Hyp_AAAI.pdf)  [![Static Badge](https://img.shields.io/badge/%F0%9F%A4%97%20HuggingFace-Model-Green)](https://huggingface.co/tldoan/Hyp-OW/tree/main) [![Static Badge](https://img.shields.io/badge/🎥Youtube-Video-orange)](https://youtu.be/dXaF0WpNFlA)\n\n\n#### [Thang Doan](https://tldoan.github.io/), Xin Li, Sima Behpour, [Wenbin He](https://hewenbin.github.io/), Liang Gou, [Liu Ren](https://sites.google.com/site/liurenshomepage/) ####\n\n\n### Abstract\n\nOpen World Object Detection (OWOD) is a challenging and realistic task that extends beyond the scope of standard Object Detection task. It involves detecting both known and unknown objects while integrating learned knowledge for future tasks. However, the level of \"unknownness\" varies significantly depending on the context. For example, a tree is typically considered part of the background in a self-driving scene, but it may be significant in a household context. We argue that this contextual information should already be embedded within the known classes. In other words, there should be a semantic or latent structure relationship between the known and unknown items to be discovered. Motivated by this observation, we propose Hyp-OW, a method that learns and models hierarchical representation of known items through a SuperClass Regularizer. Leveraging this representation allows us to effectively detect unknown objects using a similarity distance-based relabeling module. Extensive experiments on benchmark datasets demonstrate the effectiveness of Hyp-OW, achieving improvement in both known and unknown detection (up to 6 percent). These findings are particularly pronounced in our newly designed benchmark, where a strong hierarchical structure exists between known and unknown objects.\n\n### Overview\n\n\u003cimg src=\"./img/github_cartoon.png\" alt=\"hypow\" width=\"100%\" height=\"100%\"\u003e\n\n### Datasets\nIn addition to OWOD and OWDETR Split benchmarks, we introduce a third `Hierarchical Split` ([download here](https://github.com/tldoan/Hyp-OW/tree/master/data/OWOD/ImageSets/HIERARCHICAL)) with a strong semantic correlation between knowns and unknowns to be discovered. This allows us to assess baselines across `Low` (OWDETR), `Medium` (OWOD), and `High` (Hierarchical) data structure levels (`regime`).\n\n\n\n### Results\n\n\u003cimg src=\"./img/full_results_table.png\" alt=\"hypow\" width=\"100%\" height=\"100%\"\u003e\n\n\u003cimg src=\"./img/qualitative_results.png\" alt=\"hypow\" width=\"100%\" height=\"100%\"\u003e\n\n# Installation\n\n### Requirements\n\nWe have trained and tested our models on `Ubuntu 16.04`, `CUDA 11.1/11.3`, `GCC 5.4.0`, `Python 3.10.4`\n\n \n```bash\nconda create --name hypow python==3.10.4\nconda activate hypow\npip install -r requirements.txt\npip install torch==1.12.0+cu113 torchvision==0.13.0+cu113 torchaudio==0.12.0 --extra-index-url https://download.pytorch.org/whl/cu113\n```\n\n\n\n```\napt-get install build-essential  -y   ffmpeg  libsm6  libxext6   zip   htop  vim ;\napt-get -y install zipinstall ffmpeg libsm6 libxext6htop vim  ; \napt-get -y install ffmpeg libsm6 libxext6  -y ;\napt-get install htop vim  -y;\n```\n\n### Backbone features\n\nDownload the self-supervised backbone from [here](https://dl.fbaipublicfiles.com/dino/dino_resnet50_pretrain/dino_resnet50_pretrain.pth) and add in `models` folder.\n\n```\ncd /workspace/Hyp-OW/models/;\ngdown https://dl.fbaipublicfiles.com/dino/dino_resnet50_pretrain/dino_resnet50_pretrain.pth;\n```\n\n### Compiling CUDA operators\n```bash\ncd ./models/ops\nsh ./make.sh\n# unit test (should see all checking is True)\n```\n\n\n\n\n## Data Structure\n\n```\nHyp-OW/\n└── data/\n    └── OWOD/\n        ├── JPEGImages\n        ├── Annotations\n        └── ImageSets\n            ├── OWDETR\n            ├── TOWOD\n            └── HIERARCHICAL\n            \n```\n\n### Dataset Structure\n\nThe splits are present inside `data/OWOD/ImageSets/` folder.\n1. Download the COCO Images and Annotations from [coco dataset](https://cocodataset.org/#download) into the `data/` directory.\n2. Unzip train2017 and val2017 folder. The current directory structure should look like:\n```\nHyp-OW/\n└── data/\n    └── coco/\n        ├── annotations/\n        ├── train2017/\n        └── val2017/\n```\n4. Move all images from `train2017/` and `val2017/` to `JPEGImages` folder.\n5. Use the code `coco2voc.py` for converting json annotations to xml files.\n6. Download the PASCAL VOC 2007 \u0026 2012 Images and Annotations from [pascal dataset](http://host.robots.ox.ac.uk/pascal/VOC/) into the `data/` directory.\n7. untar the trainval 2007 and 2012 and test 2007 folders.\n8. Move all the images to `JPEGImages` folder and annotations to `Annotations` folder. \n\nCurrently, we follow the VOC format for data loading and evaluation\n\n### Dataset Download (Code)\n\n```\ncd /workspace/Hyp-OW/data/OWOD;\nwget -O JPEGImages.zip https://www.dropbox.com/s/dzy9ngucde94wga/JPEGImages.zip?dl=0;\nunzip JPEGImages.zip;\n\ngdown https://drive.google.com/uc?id=1paoJRaHTnptPaEJd3D6XiUkNetLgti6R;\nunzip Annotations.zip;\n\nmkdir /workspace/Hyp-OW/data/coco;\ncd /workspace/Hyp-OW/data/coco;\n\ngdown http://images.cocodataset.org/annotations/annotations_trainval2017.zip;\nunzip annotations_trainval2017.zip;\n\n\n```\n\n\n```\ngit clone https://github.com/bot66/coco2voc.git;\ncd /workspace/coco2voc;\n\npython coco2voc.py --json_path /workspace/Hyp-OW/data/coco/annotations/instances_train2017.json   --output /workspace/Hyp-OW/data/OWOD/Annotations;\npython coco2voc.py --json_path /workspace/Hyp-OW/data/coco/annotations/instances_val2017.json   --output /workspace/Hyp-OW/data/OWOD/Annotations;\n\n\n```\n# Training\n\n#### Training on single node\n\nTo train Hyp-OW on a single node with 4 GPUS on HIERARCHICAL SPLIT\n```bash\nsh run.sh\n```\n**note: you may need to give permissions to the .sh files under the 'configs' and 'tools' directories by running `chmod +x *.sh` in each directory.\n\nBy editing the run.sh file, you can decide to run each one of the configurations defined in ``\\configs``:\n\n# Evaluation\n\nDownload our [weights](https://huggingface.co/tldoan/Hyp-OW/tree/main) and place them in the 'exps' directory.\nIt contains weights of Hyp-OW for each split (OWOD, OWDETR and Hierarchical) and each task (1 to 4)\n\n**note: you may need to give permissions to the .sh files by running `chmod +x *.sh` in each directory.\n\n```\nmkdir exps/;\ncd exps/;\ngdown https://drive.google.com/uc?id=13bMwaGa1YFmK34o_lDDVpxNkruxedMvV;\nunzip -j Hyp-OW_weights.zip;\n\nsh /workspace/Hyp-OW/run_eval.sh\n## make sure the path for the weights you are loading is correct for each *.sh file\n```\n\n# Citation\n\nIf you found this repo useful, please consider citing Hyp-OW:\n\n```bibtex\n@inproceedings{doan_2024_HypOW,\n  title={Hyp-OW: Exploiting Hierarchical Structure Learning with Hyperbolic Distance Enhances Open World Object Detection},\n  author={Doan, Thang and Li, Xin and Behpour, Sima and He, Wenbin and Gou, Liang and Ren, Liu},\n  booktitle={Proceedings of the AAAI Conference on Artificial Intelligence},\n  volume={38},\n  year={2024}\n}\n```\n\n## License\n\nThis project is open-sourced under the AGPL-3.0 license. See the\n[LICENSE](LICENSE) file for details.\n\nFor a list of other open source components included in this project, see the\nfile [3rd-party-licenses.txt](3rd-party-licenses.txt).\n\n\n## Acknowledgments:\n\nBuilt from [PROB](https://github.com/orrzohar/PROB.git), [OWDETR](https://github.com/akshitac8/OW-DETR), [PROB](https://orrzohar.github.io/)\n\n\n## Purpose of the project\n\nThis software is a research prototype, solely developed for and published as\npart of the publication cited above. \n\n## Contact     \n\nPlease feel free to open an issue or contact personally if you have questions, need help, or need explanations. Don't hesitate to write an email to the following email address:\ndoantl89@gmail.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboschresearch%2Fhyp-ow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fboschresearch%2Fhyp-ow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboschresearch%2Fhyp-ow/lists"}