Cliff (#93)

* Create README.MD

* code and data link

* Update README.MD

Update README.MD

Author: zhihaolee

CLIFF/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (C) 2022. Huawei Technologies Co., Ltd. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

CLIFF/README.MD

@@ -1,22 +1,28 @@
 # CLIFF [ECCV 2022 Oral]
 
+<img src="assets/teaser.gif" width="100%">
 
+*(This testing video is from the 3DPW testset, and processed frame by frame without temporal smoothing.)*
 
-This repo contains the CLIFF demo code, 
+## Introduction
+This repo contains the demo code, 
 and the pseudo-GT SMPL parameters used in the training for the paper:
 
-**CLIFF: Carrying Location Information in Full Frames into Human Pose and Shape Estimation**
+**CLIFF: Carrying Location Information in Full Frames into Human Pose and Shape Estimation**.
 
 ## Installation
 ```bash
 conda create -n cliff python=3.10
 pip install -r requirements.txt
 ```
 
-1. Download [the SMPL models](https://smpl.is.tue.mpg.de/) for rendering the reconstructed meshes
-2. Download [pytorch-yolo-v3](https://github.com/ayooshkathuria/pytorch-yolo-v3), unzip it under the `lib` directory, and change the folder name to **"pytorch_yolo_v3_master"**
-2. Download the pretrained checkpoints and some testing samples to run the demo [[Google Drive]()]
-3. Download the CLIFF pseudo-GT for the in-the-wild datasets [[Google Drive]()]
+1. Download [the SMPL models](https://smpl.is.tue.mpg.de) for rendering the reconstructed meshes
+2. Download [pytorch-yolo-v3](https://github.com/ayooshkathuria/pytorch-yolo-v3), 
+   unzip it under the `lib` directory, and change the folder name to **"pytorch_yolo_v3_master"**
+3. Download the pretrained checkpoints and some testing samples to run the demo [[Google Drive](
+    https://drive.google.com/drive/folders/1EmSZwaDULhT9m1VvH7YOpCXwBWgYrgwP?usp=sharing)]
+4. Download the CLIFF pseudo-GT for the in-the-wild datasets [[Google Drive](
+    https://drive.google.com/drive/folders/1EmSZwaDULhT9m1VvH7YOpCXwBWgYrgwP?usp=sharing)]
 
 Finally put these data following the directory structure as below:
 ```
@@ -26,38 +32,81 @@ ${ROOT}
     |-- mpii_cliffGT.npz
 |-- data
     |-- ckpt
-        |-- hr48-PA43.0_MJE69.0_MVE81.2_3dpw-PA32.6_MJE47.6_MVE60.1_h36m-p2.pt
-        |-- res50-PA45.7_MJE72.0_MVE85.3_3dpw-PA35.7_MJE52.8_MVE63.2_h36m-p2.pt
+        |-- hr48-PA43.0_MJE69.0_MVE81.2_3dpw.pt
+        |-- res50-PA45.7_MJE72.0_MVE85.3_3dpw.pt
+        |-- yolov3.weights
     |-- smpl
         |-- SMPL_FEMALE.pkl
         |-- SMPL_MALE.pkl
         |-- SMPL_NEUTRAL.pkl
 |-- lib
     |-- pytorch_yolo_v3_master
-    |-- yolov3.weights
 ```
 
-
 ## Demo
 ```shell
 sh scripts/run_demo.sh
 ```
-Change the options in the scripts. 
-See the option description in the bottom lines of `demo.py`
+
+<p float="left">
+   <img src="assets/im08036/im08036.png" width="24%">
+   <img src="assets/im08036/im08036_bbox.jpg" width="24%">
+   <img src="assets/im08036/im08036_front_view_cliff_hr48.jpg" width="24%">
+   <img src="assets/im08036/im08036_side_view_cliff_hr48.jpg" width="24%">
+</p>
+
+<p float="left">
+   <img src="assets/im00492/im00492.png" width="24%">
+   <img src="assets/im00492/im00492_bbox.jpg" width="24%">
+   <img src="assets/im00492/im00492_front_view_cliff_hr48.jpg" width="24%">
+   <img src="assets/im00492/im00492_side_view_cliff_hr48.jpg" width="24%">
+</p>
+
+The results will be saved in the same directory as the input, including the detected bbox, 
+the front-view and side-view rendering of the reconstructed meshes, 
+and the npz file containing all the estimation information. 
+
+One can change the demo options in the script. 
+Please see the option description in the bottom lines of `demo.py`.
 
 ## Pseudo-GT
+
+Run the script to visualize the pseudoGT, press the `<-` and `->` button to the next sample, and `esc` to exit.
+
 ```shell
 sh scripts/run_cliffGT_visualization.sh
 ```
 
+<p float="left">
+   <img src="assets/visualized_cliffGT/viz_cliffGT_perImg-COCO_sample.jpg" width="49%">
+   <img src="assets/visualized_cliffGT/viz_cliffGT_perSubject-MPII_sample.jpg" width="49%">
+</p>
 
+Data format: 
+```
+'imgname':     # image name, e.g., images/015601864.jpg, train2014/COCO_train2014_000000044474.jpg 
+'center':      # bbox center, [x, y]
+'scale':       # bbox scale, bbox_size_in_pixel / 200.
+'part':        # 2D keypoint annotation, shape (24, 3), [x, y, conf], see common/skeleton_drawer.py for the order
+'annot_id':    # annotation ID, only available for the COCO dataset
+'pose':        # SMPL pose parameters in axis-angle, shape (72,)
+'shape':       # SMPL shape parameters, shape (10,)
+'has_smpl':    # whether the smpl parameters are available (true for all samples)
+'global_t':    # Pelvis translation in the camera coordinate system w.r.t the original full-frame image
+'focal_l':     # estimated focal length for the original image, np.sqrt(img_w ** 2 + img_h ** 2)
+'S':           # 3D joints with Pelvis aligned at (0, 0, 0), shape (24, 4), [x, y, z, conf], same order as 'part'
+```
+
+## Issues
+When submitting an issue, please add **"[CLIFF]"** before the title, e.g., `[CLIFF] your issue title`.
+This is for clarifying which subproject the issue points to.
 
 ## Citing
 ```
-@Inproceedings{li_2022_eccv_cliff,
+@Inproceedings{li2022cliff,
   Title     = {CLIFF: Carrying Location Information in Full Frames into Human Pose and Shape Estimation},
   Author    = {Li, Zhihao and Liu, Jianzhuang and Zhang, Zhensong and Xu, Songcen and Yan, Youliang},
   Booktitle = {ECCV},
   Year      = {2022}
 }
-```
+```

CLIFF/THIRD PARTY OPEN SOURCE SOFTWARE NOTICE.txt

@@ -0,0 +1,65 @@
+Please note we provide an open source software notice for the third party open source software along with this software and/or this software component contributed by Huawei (in the following just “this SOFTWARE”). The open source software licenses are granted by the respective right holders.
+
+Warranty Disclaimer
+THE OPEN SOURCE SOFTWARE IN THIS SOFTWARE IS DISTRIBUTED IN THE HOPE THAT IT WILL BE USEFUL, BUT WITHOUT ANY WARRANTY, WITHOUT EVEN THE IMPLIED WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. SEE THE APPLICABLE LICENSES FOR MORE DETAILS.
+
+Copyright Notice and License Texts
+Software: SPIN (https://github.com/nkolot/SPIN)
+Copyright notice: 
+Copyright (c) 2019, 
+University of Pennsylvania, 
+Max Planck Institute for Intelligent Systems
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above
+   copyright notice, this list of conditions and the following
+   disclaimer in the documentation and/or other materials provided
+   with the distribution.
+
+3. The names of the contributors may not be used to endorse or
+   promote products derived from this software without specific
+   prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Copyright Notice and License Texts
+Software: HRNet-Image-Classification (https://github.com/HRNet/HRNet-Image-Classification)
+Copyright notice: 
+MIT License
+
+Copyright (c) 2019 Microsoft Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.