Merge pull request #1 from PurdueDigitalTwin/dev/github-page

GitHub Page

.github/pull_request_template.md

@@ -0,0 +1,14 @@
+<!-- markdownlint-disable -->
+
+# Description
+
+<!--
+Please include a summary of the change and which issue is fixed.
+Please also include relevant motivation and context.
+List any dependencies that are required for this change.
+List all the breaking changes introduced by this pull request.
+-->
+
+Fixes #\<issue_number>
+
+**Signed-off-by**: Your-name-here <example@domain>

.github/workflows/build_static.yaml

@@ -0,0 +1,43 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["master"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          # Upload entire repository
+          path: "./docs"
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

README.md

@@ -1 +1,103 @@
-# MACP
+# MACP: Efficient Model Adaptation for Cooperative Perception
+
+[![python](https://img.shields.io/badge/-Python_3.8-306998?logo=python&logoColor=white)](https://www.python.org/downloads/release/python-3817/)
+[![BSD 3-Clause License](https://img.shields.io/badge/license-MIT-750014.svg)](https://github.com/PurdueDigitalTwin/MACP/blob/master/LICENSE)
+
+---
+
+The official repository for the WACV 2024
+paper [MACP: Efficient Model Adaptation for Cooperative Perception](https://openaccess.thecvf.com/content/WACV2024/html/Ma_MACP_Efficient_Model_Adaptation_for_Cooperative_Perception_WACV_2024_paper.html).
+This work proposes a novel method to adapt a single-agent pretrained model to a V2V cooperative perception setting. It
+achieves state-of-the-art performance on both the [V2V4Real](https://mobility-lab.seas.ucla.edu/v2v4real/) and
+the [OPV2V](https://mobility-lab.seas.ucla.edu/opv2v/) datasets.
+
+## Setup
+
+Our project is based on [MMDetection3D v1.1.0](https://github.com/open-mmlab/mmdetection3d/releases/tag/v1.1.0). Please
+refer to the [official documentation](https://mmdetection3d.readthedocs.io/en/v1.1.0/get_started.html) to set up the
+environment.
+
+### Data Preparation
+
+Download the [V2V4Real](https://mobility-lab.seas.ucla.edu/v2v4real/)
+and [OPV2V](https://drive.google.com/drive/folders/1dkDeHlwOVbmgXcDazZvO6TFEZ6V_7WUu) datasets.
+
+Once the data is downloaded, it's necessary organize the data in the following structure:
+
+```plain
+├── $REPO_ROOT
+│   ├── data
+│   │   ├── v2v4real
+│   │   │   ├── train
+│   │   │   │   ├── testoutput_CAV_data_2022-03-15-09-54-40_0 # data folder
+│   │   │   ├── test
+|   |   ├── openv2v
+│   │   │   ├── train
+│   │   │   │   ├── 2021_08_16_22_26_54 # data folder
+│   │   │   ├── test
+|   |   |   ├── validate
+|   |   |   ├── test_culver_city
+```
+
+Then, run the script files `scripts/create_v2v4real.sh` and `scripts/create_openv2v.sh` to prepare the cached data.
+
+### Notes
+
+- The core code of our project is in the `projects/Coperception` folder.
+- The voxelization OP in the original implementation of `BEVFusion` is different from the implementation in MMCV. Please
+  refer [here](https://github.com/open-mmlab/mmdetection3d/tree/main/projects/BEVFusion#compiling-operations-on-cuda) to
+  compile the OP on CUDA.
+
+## MACP Weights
+
+If you are interested in including any other pretrained weights or details, please open an issue or
+contact [us](mailto:yunsheng@purdue.edu).
+
+|     Model     |    Backbone     |                                              Checkpoint                                               |                                                Config                                                 | AP@50 | AP@70 |                                                  Log                                                  |
+|:-------------:|:---------------:|:-----------------------------------------------------------------------------------------------------:|:-----------------------------------------------------------------------------------------------------:|:-----:|:-----:|:-----------------------------------------------------------------------------------------------------:|
+| MACP-V2V4Real | BEVFusion-LiDAR | [Google Drive](https://drive.google.com/file/d/1SVaMekq_hpnZ_dUb0dvD7tVYXNbTiSfj/view?usp=drive_link) | [Google Drive](https://drive.google.com/file/d/1K2IGPhxr2JWH20MbNlbi3hNiOdHk_LGw/view?usp=drive_link) | 67.6  | 47.9  | [Google Drive](https://drive.google.com/file/d/1SVaMekq_hpnZ_dUb0dvD7tVYXNbTiSfj/view?usp=drive_link) |
+|  MACP-OPV2V   | BEVFusion-LiDAR | [Google Drive](https://drive.google.com/file/d/1fWULVO-3vGQlQ_Hmqq9dcZ5SUSwYicD1/view?usp=drive_link) | [Google Drive](https://drive.google.com/file/d/1_dtbrYahK1zf_-fp4IYocIuMVbx01fNc/view?usp=drive_link) | 93.7  | 90.3  | [Google Drive](https://drive.google.com/file/d/1fzHDJdsNzmsZQ59zt0_FRzoUhC0i1Ufu/view?usp=drive_link) |
+
+## Training
+
+We train our model on one NVIDIA RTX 4090 GPU with 24GB memory. The training command is as follows:
+
+```bash
+cd /path/to/repo
+export PYTHONPATH=$PWD:$PYTHONPATH
+python tools/train.py path/to/config
+```
+
+## Evaluation
+
+The evaluation command is as follows:
+
+```bash
+cd /path/to/repo
+export PYTHONPATH=$PWD:$PYTHONPATH
+python tools/test.py path/to/config path/to/checkpoint
+```
+
+## Citation
+
+If you find our work useful in your research, please consider citing:
+
+```bibtex
+@inproceedings{ma2024macp,
+  title={MACP: Efficient Model Adaptation for Cooperative Perception},
+  author={Ma, Yunsheng and Lu, Juanwu and Cui, Can and Zhao, Sicheng and Cao, Xu and Ye, Wenqian and Wang, Ziran},
+  booktitle={Proceedings of the IEEE/CVF Winter Conference on Applications of Computer Vision},
+  pages={3373--3382},
+  year={2024}
+}
+```
+
+## Acknowledgement
+
+This project is based on code from several open-source projects. We would like to thank the authors for their great
+work:
+
+- [MMDetection3D](https://github.com/open-mmlab/mmdetection3d)
+- [BEVFusion](https://github.com/mit-han-lab/bevfusion)
+- [V2V4Real](https://github.com/ucla-mobility/V2V4Real)
+- [OpenCOOD](https://github.com/DerrickXuNu/OpenCOOD)

docs/CHANGELOG.md

@@ -0,0 +1,209 @@
+## Changelog
+
+### v1.1.0 (24/2/2020)
+
+**Highlights**
+- Dataset evaluation is rewritten with a unified api, which is used by both evaluation hooks and test scripts.
+- Support new methods: [CARAFE](https://arxiv.org/abs/1905.02188).
+
+**Breaking Changes**
+- The new MMDDP inherits from the official DDP, thus the `__init__` api is changed to be the same as official DDP.
+- The `mask_head` field in HTC config files is modified.
+- The evaluation and testing script is updated.
+- In all transforms, instance masks are stored as a numpy array shaped (n, h, w) instead of a list of (h, w) arrays, where n is the number of instances.
+
+**Bug Fixes**
+- Fix IOU assigners when ignore_iof_thr > 0 and there is no pred boxes. (#2135)
+- Fix mAP evaluation when there are no ignored boxes. (#2116)
+- Fix the empty RoI input for Deformable RoI Pooling. (#2099)
+- Fix the dataset settings for multiple workflows. (#2103)
+- Fix the warning related to `torch.uint8` in PyTorch 1.4. (#2105)
+- Fix the inference demo on devices other than gpu:0. (#2098)
+- Fix Dockerfile. (#2097)
+- Fix the bug that `pad_val` is unused in Pad transform. (#2093)
+- Fix the albumentation transform when there is no ground truth bbox. (#2032)
+
+**Improvements**
+- Use torch instead of numpy for random sampling. (#2094)
+- Migrate to the new MMDDP implementation in MMCV v0.3. (#2090)
+- Add meta information in logs. (#2086)
+- Rewrite Soft NMS with pytorch extension and remove cython as a dependency. (#2056)
+- Rewrite dataset evaluation. (#2042, #2087, #2114, #2128)
+- Use numpy array for masks in transforms. (#2030)
+
+**New Features**
+- Implement "CARAFE: Content-Aware ReAssembly of FEatures". (#1583)
+- Add `worker_init_fn()` in data_loader when seed is set. (#2066, #2111)
+- Add logging utils. (#2035)
+
+### v1.0.0 (30/1/2020)
+
+This release mainly improves the code quality and add more docstrings.
+
+**Highlights**
+- Documentation is online now: https://mmdetection.readthedocs.io.
+- Support new models: [ATSS](https://arxiv.org/abs/1912.02424).
+- DCN is now available with the api `build_conv_layer` and `ConvModule` like the normal conv layer.
+- A tool to collect environment information is available for trouble shooting.
+
+**Bug Fixes**
+- Fix the incompatibility of the latest numpy and pycocotools. (#2024)
+- Fix the case when distributed package is unavailable, e.g., on Windows. (#1985)
+- Fix the dimension issue for `refine_bboxes()`. (#1962)
+- Fix the typo when `seg_prefix` is a list. (#1906)
+- Add segmentation map cropping to RandomCrop. (#1880)
+- Fix the return value of `ga_shape_target_single()`. (#1853)
+- Fix the loaded shape of empty proposals. (#1819)
+- Fix the mask data type when using albumentation. (#1818)
+
+**Improvements**
+- Enhance AssignResult and SamplingResult. (#1995)
+- Add ability to overwrite existing module in Registry. (#1982)
+- Reorganize requirements and make albumentations and imagecorruptions optional. (#1969)
+- Check NaN in `SSDHead`. (#1935)
+- Encapsulate the DCN in ResNe(X)t into a ConvModule & Conv_layers. (#1894)
+- Refactoring for mAP evaluation and support multiprocessing and logging. (#1889)
+- Init the root logger before constructing Runner to log more information. (#1865)
+- Split `SegResizeFlipPadRescale` into different existing transforms. (#1852)
+- Move `init_dist()` to MMCV. (#1851)
+- Documentation and docstring improvements. (#1971, #1938, #1869, #1838)
+- Fix the color of the same class for mask visualization. (#1834)
+- Remove the option `keep_all_stages` in HTC and Cascade R-CNN. (#1806)
+
+**New Features**
+- Add two test-time options `crop_mask` and `rle_mask_encode` for mask heads. (#2013)
+- Support loading grayscale images as single channel. (#1975)
+- Implement "Bridging the Gap Between Anchor-based and Anchor-free Detection via Adaptive Training Sample Selection". (#1872)
+- Add sphinx generated docs. (#1859, #1864)
+- Add GN support for flops computation. (#1850)
+- Collect env info for trouble shooting. (#1812)
+
+
+### v1.0rc1 (13/12/2019)
+
+The RC1 release mainly focuses on improving the user experience, and fixing bugs.
+
+**Highlights**
+- Support new models: [FoveaBox](https://arxiv.org/abs/1904.03797), [RepPoints](https://arxiv.org/abs/1904.11490) and [FreeAnchor](https://arxiv.org/abs/1909.02466).
+- Add a Dockerfile.
+- Add a jupyter notebook demo and a webcam demo.
+- Setup the code style and CI.
+- Add lots of docstrings and unit tests.
+- Fix lots of bugs.
+
+**Breaking Changes**
+- There was a bug for computing COCO-style mAP w.r.t different scales (AP_s, AP_m, AP_l), introduced by #621. (#1679)
+
+**Bug Fixes**
+- Fix a sampling interval bug in Libra R-CNN. (#1800)
+- Fix the learning rate in SSD300 WIDER FACE. (#1781)
+- Fix the scaling issue when `keep_ratio=False`. (#1730)
+- Fix typos. (#1721, #1492, #1242, #1108, #1107)
+- Fix the shuffle argument in `build_dataloader`. (#1693)
+- Clip the proposal when computing mask targets. (#1688)
+- Fix the "index out of range" bug for samplers in some corner cases. (#1610, #1404)
+- Fix the NMS issue on devices other than GPU:0. (#1603)
+- Fix SSD Head and GHM Loss on CPU. (#1578)
+- Fix the OOM error when there are too many gt bboxes. (#1575)
+- Fix the wrong keyword argument `nms_cfg` in HTC. (#1573)
+- Process masks and semantic segmentation in Expand and MinIoUCrop transforms. (#1550, #1361)
+- Fix a scale bug in the Non Local op. (#1528)
+- Fix a bug in transforms when `gt_bboxes_ignore` is None. (#1498)
+- Fix a bug when `img_prefix` is None. (#1497)
+- Pass the device argument to `grid_anchors` and `valid_flags`. (#1478)
+- Fix the data pipeline for test_robustness. (#1476)
+- Fix the argument type of deformable pooling. (#1390)
+- Fix the coco_eval when there are only two classes. (#1376)
+- Fix a bug in Modulated DeformableConv when deformable_group>1. (#1359)
+- Fix the mask cropping in RandomCrop. (#1333)
+- Fix zero outputs in DeformConv when not running on cuda:0. (#1326)
+- Fix the type issue in Expand. (#1288)
+- Fix the inference API. (#1255)
+- Fix the inplace operation in Expand. (#1249)
+- Fix the from-scratch training config. (#1196)
+- Fix inplace add in RoIExtractor which cause an error in PyTorch 1.2. (#1160)
+- Fix FCOS when input images has no positive sample. (#1136)
+- Fix recursive imports. (#1099)
+
+**Improvements**
+- Print the config file and mmdet version in the log. (#1721)
+- Lint the code before compiling in travis CI. (#1715)
+- Add a probability argument for the `Expand` transform. (#1651)
+- Update the PyTorch and CUDA version in the docker file. (#1615)
+- Raise a warning when specifying `--validate` in non-distributed training. (#1624, #1651)
+- Beautify the mAP printing. (#1614)
+- Add pre-commit hook. (#1536)
+- Add the argument `in_channels` to backbones. (#1475)
+- Add lots of docstrings and unit tests, thanks to [@Erotemic](https://github.com/Erotemic). (#1603, #1517, #1506, #1505, #1491, #1479, #1477, #1475, #1474)
+- Add support for multi-node distributed test when there is no shared storage. (#1399)
+- Optimize Dockerfile to reduce the image size. (#1306)
+- Update new results of HRNet. (#1284, #1182)
+- Add an argument `no_norm_on_lateral` in FPN. (#1240)
+- Test the compiling in CI. (#1235)
+- Move docs to a separate folder. (#1233)
+- Add a jupyter notebook demo. (#1158)
+- Support different type of dataset for training. (#1133)
+- Use int64_t instead of long in cuda kernels. (#1131)
+- Support unsquare RoIs for bbox and mask heads. (#1128)
+- Manually add type promotion to make compatible to PyTorch 1.2. (#1114)
+- Allowing validation dataset for computing validation loss. (#1093)
+- Use `.scalar_type()` instead of `.type()` to suppress some warnings. (#1070)
+
+**New Features**
+- Add an option `--with_ap` to compute the AP for each class. (#1549)
+- Implement "FreeAnchor: Learning to Match Anchors for Visual Object Detection". (#1391)
+- Support [Albumentations](https://github.com/albumentations-team/albumentations) for augmentations in the data pipeline. (#1354)
+- Implement "FoveaBox: Beyond Anchor-based Object Detector". (#1339)
+- Support horizontal and vertical flipping. (#1273, #1115)
+- Implement "RepPoints: Point Set Representation for Object Detection". (#1265)
+- Add test-time augmentation to HTC and Cascade R-CNN. (#1251)
+- Add a COCO result analysis tool. (#1228)
+- Add Dockerfile. (#1168)
+- Add a webcam demo. (#1155, #1150)
+- Add FLOPs counter. (#1127)
+- Allow arbitrary layer order for ConvModule. (#1078)
+
+
+### v1.0rc0 (27/07/2019)
+- Implement lots of new methods and components (Mixed Precision Training, HTC, Libra R-CNN, Guided Anchoring, Empirical Attention, Mask Scoring R-CNN, Grid R-CNN (Plus), GHM, GCNet, FCOS, HRNet, Weight Standardization, etc.). Thank all collaborators!
+- Support two additional datasets: WIDER FACE and Cityscapes.
+- Refactoring for loss APIs and make it more flexible to adopt different losses and related hyper-parameters.
+- Speed up multi-gpu testing.
+- Integrate all compiling and installing in a single script.
+
+### v0.6.0 (14/04/2019)
+- Up to 30% speedup compared to the model zoo.
+- Support both PyTorch stable and nightly version.
+- Replace NMS and SigmoidFocalLoss with Pytorch CUDA extensions.
+
+### v0.6rc0(06/02/2019)
+- Migrate to PyTorch 1.0.
+
+### v0.5.7 (06/02/2019)
+- Add support for Deformable ConvNet v2. (Many thanks to the authors and [@chengdazhi](https://github.com/chengdazhi))
+- This is the last release based on PyTorch 0.4.1.
+
+### v0.5.6 (17/01/2019)
+- Add support for Group Normalization.
+- Unify RPNHead and single stage heads (RetinaHead, SSDHead) with AnchorHead.
+
+### v0.5.5 (22/12/2018)
+- Add SSD for COCO and PASCAL VOC.
+- Add ResNeXt backbones and detection models.
+- Refactoring for Samplers/Assigners and add OHEM.
+- Add VOC dataset and evaluation scripts.
+
+### v0.5.4 (27/11/2018)
+- Add SingleStageDetector and RetinaNet.
+
+### v0.5.3 (26/11/2018)
+- Add Cascade R-CNN and Cascade Mask R-CNN.
+- Add support for Soft-NMS in config files.
+
+### v0.5.2 (21/10/2018)
+- Add support for custom datasets.
+- Add a script to convert PASCAL VOC annotations to the expected format.
+
+### v0.5.1 (20/10/2018)
+- Add BBoxAssigner and BBoxSampler, the `train_cfg` field in config files are restructured.
+- `ConvFCRoIHead` / `SharedFCRoIHead` are renamed to `ConvFCBBoxHead` / `SharedFCBBoxHead` for consistency.