From 840c177350b9bf37e1a877ab864429649f0b96e8 Mon Sep 17 00:00:00 2001
From: WEI CHEN <77597327+Wei-Chen-hub@users.noreply.github.com>
Date: Mon, 19 Jun 2023 15:20:14 +0800
Subject: [PATCH 1/9] Update human_data.md

---
 docs/human_data.md | 63 ++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 55 insertions(+), 8 deletions(-)

diff --git a/docs/human_data.md b/docs/human_data.md
index 7b11804f..faa650b7 100644
--- a/docs/human_data.md
+++ b/docs/human_data.md
@@ -6,19 +6,66 @@ HumanData is a subclass of python built-in class dict, containing single-view, i
 
 ### Key/Value definition
 
-#### The keys and values supported by HumanData are described as below.
+#### Paths:
 
+Image path is included, and optionally path of segmantation map and depth image can be included if provided by dataset.
 - image_path: (N, ), list of str, each element is a relative path from the root folder (exclusive) to the image.
+- segmantation_path (optional): (N, ), list of str, each element is a relative path from the root folder (exclusive) to the segmantation map.
+- depth_path (optional): (N, ), list of str, each element is a relative path from the root folder (exclusive) to the depth image.
+
+#### Keypoints：
+
+Following keys should be included in `HumanData` if applicable. For each dictionary key of keypoints，a corresponding dictionart key of mask should be included，stating which keypoint is valid. For example `keypoints3d_original` should correspond to `keypoints3d_original_mask`.
+- keypoints3d_smpl / keypoints3d_smplx: (N, 190, 4), numpy array, `smplx / smplx` 3d joints with confidence, joints from each datasets are mapped to HUMAN_DATA joints.
+- keypoints3d_original: (N, 190, 4), numpy array, 3d joints with confidence which provided by the dataset originally, joints from each datasets are mapped to HUMAN_DATA joints.
+- keypoints2d_smpl / keypoints2d_smplx: (N, 190, 3), numpy array, `smpl / smplx` 2d joints with confidence, joints from each datasets are mapped to HUMAN_DATA joints.
+- keypoints2d_original: (N, 190, 3), numpy array, 2d joints with confidence which provided by the dataset originally, joints from each datasets are mapped to HUMAN_DATA joints.
+- (mask sample) keypoints2d_smpl_mask: (190, ), numpy array, mask for which keypoint is valid in `keypoints2d_smpl`. 0 means that the joint in this position cannot be found in original dataset.
+
+#### Bounding Box：
+
+Bounding box of body (smpl), face and hand (smplx), which data type is `[x_min, y_min, width, height, confidence]`，and should not exceed the image boundary. 
 - bbox_xywh: (N, 5), numpy array, bounding box with confidence, coordinates of bottom-left point x, y, width w and height h of bbox, score at last.
+- face_bbox_xywh, lhand_bbox_xywh, rhand_bbox_xywh (optional): (N, 5), numpy array, should be included if `smplx` data is provided, and is derived from smplx2d keypoints. Have the same srtucture as above.
+
+#### Human Pose and Shape Parameters：
+
+Normally saved as smpl/smplx.
+- smpl: (1, ), dict, keys are `['body_pose': numpy array, (N, 23, 3), 'global_orient': numpy array, (N, 3), 'betas': numpy array, (N, 10), 'transl': numpy array, (N, 3)]`.
+- smplx: (1, ), dict, keys are `['body_pose': numpy array, (N, 21, 3),'global_orient': numpy array, (N, 3), 'betas': numpy array, (N, 10), 'transl': numpy array, (N, 3), 'left_hand_pose': numpy array, (N, 15, 3), 'right_hand_pose': numpy array, (N, 15, 3), 'expression': numpy array (N, 10), 'leye_pose': numpy array (N, 3), 'reye_pose': (N, 3), 'jaw_pose': numpy array (N, 3)]`.
+
+
+#### Other keys
+
 - config: (), str, the flag name of config for individual dataset.
-- keypoints2d: (N, 190, 3), numpy array, 2d joints of smplx model with confidence, joints from each datasets are mapped to HUMAN_DATA joints.
-- keypoints3d: (N, 190, 4), numpy array, 3d joints of smplx model with confidence. Same as above.
-- smpl: (1, ), dict, keys are ['body_pose': numpy array, (N, 23, 3), 'global_orient': numpy array, (N, 3), 'betas': numpy array, (N, 10), 'transl': numpy array, (N, 3)].
-- smplx: (1, ), dict, keys are ['body_pose': numpy array, (N, 21, 3),'global_orient': numpy array, (N, 3), 'betas': numpy array, (N, 10), 'transl': numpy array, (N, 3), 'left_hand_pose': numpy array, (N, 15, 3), 'right_hand_pose': numpy array, (N, 15, 3), 'expression': numpy array (N, 10), 'leye_pose': numpy array (N, 3), 'reye_pose': (N, 3), 'jaw_pose': numpy array (N, 3)].
 - meta: (1, ), dict, its keys are meta data from dataset like 'gender'.
-- keypoints2d_mask: (190, ), numpy array, mask for which keypoint is valid in keypoints2d. 0 means that the joint in this position cannot be found in original dataset.
-- keypoints3d_mask: (190, ), numpy array, mask for which keypoint is valid in keypoints3d. 0 means that the joint in this position cannot be found in original dataset.
-- misc: (1, ), dict, keys and values are defined by user. The space misc takes(sys.getsizeof(misc)) shall be no more than 6MB.
+- misc: (1, ), dict, keys and values are designed to describe the different settings for each dataset. Can also be defined by user. The space misc takes(sys.getsizeof(misc)) shall be no more than 6MB.
+
+#### Suggestion for WHAT to include in `HumanData['misc']`:
+
+Miscellaneous contains the info of different settings for each dataset, including camaera type, source of keypoints annotation, bounding box etc. Aims to faclitate different usage of data.
+`HumanData['misc']` is a dictionary and its keys are discribed as following:
+- kps3d_root_aligned： Bool, stating that if keypoints3d is root-aligned，root_alignment is not preferred for HumanData. If this key does not exist, root_aligenment is by default to be `False`.
+- flat_hand_mean：Bool, applicable for smplx data，for most datasets `flat_hand_mean=False`.
+- bbox_source：source of bounding box，`bbox_soruce='keypoints2d_smpl' or 'keypoints2d_smplx' or 'keypoints2d_original'`，describing which type of keypoints are used to derive the bounding box，OR `bbox_source='provide_by_dataset'` shows that bounding box if provided by dataset. (For example, from some detection module rather than keypoints)
+- bbox_body_scale: applicable if bounding box is derived by keypoints，stating the zoom-in scale of bounding scale from smpl/smplx/2d_gt keypoints，we suggest `bbox_body_scale=1.2`.
+- bbox_hand_scale, bbox_face_scale: applicable if bounding box is derived by smplx keypoints，stating the zoom-in scale of bounding scale from smplx/2d_gt keypoints，we suggest `bbox_hand_scale=1.0, bbox_face_scale=1.0`
+- smpl_source / smplx_source: describing the source of smpl/smplx annotations，`'original', 'nerual_annot', 'eft', 'osx_annot', 'cliff_annot'`.
+- cam_param_type: describing the type of camera parameters，`cam_param_type='prespective' or 'predicted_camera' or 'eft_camera'`
+- principal_point, focal_length: (1, 2), numpy array，applicable if camera parameters are same across the whole dataset, which is the case for some synthetic datasets.
+- image_shape: (1, 2), numpy array，applicable if image shape are same across the whole dataset.
+
+#### Suggestion for WHAT to include in `HumanData['meta']`:
+
+- gender: (N, ), list of str, each element represents the gender for an smpl/smplx instance. (key not required if dataset use gender-neutral model)
+- height， width：(N, )， list of str, each element represents the width of height of image. (keys should be in `HumanData['misc']` if image shape are same across the dataset）
+- other keys，applicable if the key value is different，and have some imapct on keypoints or smpl/smplx (2d and 3d)，For example, `focal_length` and `principal_point`, focal_length = (N, 2), principal_point = (N, 2)
+
+#### Some other info of HumanData
+
+- All annotations are transfromed from world space to opencv camera space, for space transformation we use:
+
+    ```from mmhuman3d.models.body_models.utils import transform_to_camera_frame, batch_transform_to_camera_frame```
 
 #### Key check in HumanData.
 

From 3eb71c1d1e388dd6295f81acf68d83b55b655c57 Mon Sep 17 00:00:00 2001
From: WEI CHEN <77597327+Wei-Chen-hub@users.noreply.github.com>
Date: Mon, 19 Jun 2023 15:20:55 +0800
Subject: [PATCH 2/9] Update human_data.md

---
 docs_zh-CN/human_data.md | 62 ++++++++++++++++++++++++++++++++++------
 1 file changed, 53 insertions(+), 9 deletions(-)

diff --git a/docs_zh-CN/human_data.md b/docs_zh-CN/human_data.md
index f8855669..2fc887bd 100644
--- a/docs_zh-CN/human_data.md
+++ b/docs_zh-CN/human_data.md
@@ -5,21 +5,65 @@
 `HumanData`是Python内置字典的子类，主要用于存放包含人体的单视角图像的信息。它具有通用的基础结构，也兼容具有新特性的客制化数据。
 原生的`HumanData`包含`numpy.ndarray`或其他的Python内置的数据结构，但不包含`torch.Tensor`的数据。可以使用`human_data.to()`将其转换为`torch.Tensor`(支持CPU和GPU)。
 
-### `Key/Value`的定义
+### `Key/Value`的定义：如下是对`HumanData`支持的`Key`和`Value`的描述.
 
-#### 如下是对`HumanData`支持的`Key`和`Value`的描述.
+#### 路径:
 
+通常包含图片路径，如果数据集有提供额外的深度或者分割图，也可以记录下来。
 - image_path: (N, ), 字符串组成的列表, 每一个元素是图像相对于根目录的路径。
+- segmantation_path (可选): (N, ), 字符串组成的列表, 每一个元素是图像分割图相对于根目录的路径。
+- depth_path (可选): (N, ), 字符串组成的列表, 每一个元素是图像深度图相对于根目录的路径。
+
+#### 关键点：
+
+以下关键点keys如果适用，则应包含在HumanData中。任何一个关键点的key，应存在一个mask，表示其中哪些关键点有效。如`keypoints3d_original`应对应`keypoints3d_original_mask`
+- keypoints3d_smpl / keypoints3d_smplx: (N, 190, 4), numpy array, `smplx / smplx`模型的3d关节点与置信度, 每一个数据集的关节点映射到了`HUMAN_DATA`的关节点。
+- keypoints3d_original: (N, 190, 4), numpy array, 由数据集本身提供的3d关节点与置信度, 每一个数据集的关节点映射到了`HUMAN_DATA`的关节点。
+- keypoints2d_smpl / keypoints2d_smplx: (N, 190, 3), numpy array, `smpl / smplx`模型的2d关节点与置信度, 每一个数据集的关节点映射到了`HUMAN_DATA`的关节点。
+- keypoints2d_original: (N, 190, 3), numpy array, 由数据集本身提供的2d关节点与置信度, 每一个数据集的关节点映射到了`HUMAN_DATA`的关节点。
+- （mask示例） keypoints2d_smpl_mask: (190, ), numpy array, 表示`keypoints2d_smpl`中关键点是否有效的掩膜。 0表示该位置的关键点在原始数据集中无法找到。
+
+#### 检测框：
+
+身体（smpl），手脸（smplx）的检测框，标注为`[x_min, y_min, width, height, confidence]`，且不应超出图片。
 - bbox_xywh: (N, 5), numpy array, 边界框的置信度, 边界框左下角点的坐标x和y, 边界框的宽w和高h, 置信度得分放置在最后。
-- config: (), 字符串, 单个数据集的配置的标志。
-- keypoints2d: (N, 190, 3), numpy array, `smplx`模型的2d关节点与置信度, 每一个数据集的关节点映射到了`HUMAN_DATA`的关节点。
-- keypoints3d: (N, 190, 4), numpy array, `smplx`模型的3d关节点与置信度, 每一个数据集的关节点映射到了`HUMAN_DATA`的关节点。
+- face_bbox_xywh, lhand_bbox_xywh, rhand_bbox_xywh（可选）： (N, 5), numpy array, 如果数据标注中含有`smplx`, 则应包括这三个key，由smplx2d关键点得出，格式同上。
+
+#### 人体模型参数：
+
+通常以smpl/smplx格式存储。
 - smpl: (1, ), 字典, `keys` 分别为 ['body_pose': numpy array, (N, 23, 3), 'global_orient': numpy array, (N, 3), 'betas': numpy array, (N, 10), 'transl': numpy array, (N, 3)].
 - smplx: (1, ), 字典, `keys` 分别为 ['body_pose': numpy array, (N, 21, 3),'global_orient': numpy array, (N, 3), 'betas': numpy array, (N, 10), 'transl': numpy array, (N, 3), 'left_hand_pose': numpy array, (N, 15, 3), 'right_hand_pose': numpy array, (N, 15, 3), 'expression': numpy array (N, 10), 'leye_pose': numpy array (N, 3), 'reye_pose': (N, 3), 'jaw_pose': numpy array (N, 3)].
-- meta: (1, ), 字典, `keys` 为数据集中类似性别的元数据。
-- keypoints2d_mask: (190, ), numpy array, 表示`keypoints2d`中关键点是否有效的掩膜。 0表示该位置的关键点在原始数据集中无法找到。
-- keypoints3d_mask: (190, ), numpy array, 表示`keypoints3d`中关键点是否有效的掩膜。 0表示该位置的关键点在原始数据集中无法找到。
-- misc: (1, ), 字典, `keys`和`values`由用户定义。`misc`占用的空间(可以通过`sys.getsizeof(misc)`获取)不能超过6MB。
+
+#### 其它keys
+
+- config: (), 字符串, 单个数据集的配置的标志。
+- meta: (1, ), 字典, `keys`为数据集中的各种元数据。
+- misc: (1, ), 字典, `keys`为数据集中各种独特设定，也可以由用户自定义。`misc`占用的空间(可以通过`sys.getsizeof(misc)`获取)不能超过6MB。
+
+#### `HumanData['misc']`中建议（可能）包含的内容:
+Miscellaneous部分中包含了每个数据集的独特设定，包括相机种类，关键点标注来源，检测框来源，是否包含smpl/smplx标注等等，用于便利数据读取。
+`HumanData['misc']`中包含一个dictionary，建议包含的key如下所示：
+- kps3d_root_aligned： Bool 描述keypoints3d是否经过root align，建议不进行root_alignment，如果不包含这个key，则默认没有进行过root_aligenment
+- flat_hand_mean：Bool 对于smplx标注的数据，应该存在此项，大多数数据集中`flat_hand_mean=False`
+- bbox_source：描述检测框的来源，`bbox_soruce='keypoints2d_smpl' or 'keypoints2d_smplx' or 'keypoints2d_original'`，描述检测框是由哪种关键点得出的，或者`bbox_source='provide_by_dataset'`表示检测框由数据集直接给出（比如用其自带检测器生成而不是由关键点推导得出）
+- bbox_body_scale: 如果检测框由关键点推导得出，则应包含此项，描述由smpl/smplx/2d_gt关键点推导出的身体检测框的放大比例，建议`bbox_body_scale=1.2`
+- bbox_hand_scale, bbox_face_scale: 如果检测框由关键点推导得出，则应包含这两项，描述由smpl/smplx/2d_gt关键点推导出的身体检测框的放大比例，建议`bbox_hand_scale=1.0, bbox_face_scale=1.0`
+- smpl_source / smplx_source: 描述smpl/smplx的来源，`'original', 'nerual_annot', 'eft', 'osx_annot', 'cliff_annot'`, 来描述smpl/smnplx是来源于数据集提供，或者其它标注来源
+- cam_param_type: 描述相机参数的种类，`cam_param_type='prespective' or 'predicted_camera' or 'eft_camera'`
+- principal_point, focal_length: (1, 2), numpy array，如果数据集中相机参数恒定，则应包含这两项，通常适用于生成数据集。
+- image_shape: (1, 2), numpy array，如果数据集中图片大小恒定，则应包含此项。
+
+#### `HumanData['meta']`中建议（可能）包含的内容:
+- gender: (N, )， 字符串组成的列表, 每一个元素是smplx模型的性别（中性则不必标注）
+- height， width：(N, )， 字符串组成的列表, 每一个元素是图片的长或宽（数据集图片分辨率一致则应标注在`HumanData['misc']`中）
+- 其它有标识性的key，若数据集中该key不一致，且会影响keypoints or smpl/smplx，则建议标注，如focal_length与principal_point, focal_length = (N, 2), principal_point = (N, 2)
+
+#### 关于HumanData的一些说明
+
+- 所有数据标注均已从世界坐标转移到opencv相机空间，进行smpl/smplx的相机空间转换可以用
+
+```from mmhuman3d.models.body_models.utils import transform_to_camera_frame, batch_transform_to_camera_frame```
 
 #### 检查`HumanData`中的`key`.
 

From a34adcfffae5900c5c75cec2cac8ec638f203669 Mon Sep 17 00:00:00 2001
From: WEI CHEN <77597327+Wei-Chen-hub@users.noreply.github.com>
Date: Tue, 27 Jun 2023 15:11:05 +0800
Subject: [PATCH 3/9] Update human_data.md

---
 docs/human_data.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/human_data.md b/docs/human_data.md
index faa650b7..34124f13 100644
--- a/docs/human_data.md
+++ b/docs/human_data.md
@@ -8,9 +8,9 @@ HumanData is a subclass of python built-in class dict, containing single-view, i
 
 #### Paths:
 
-Image path is included, and optionally path of segmantation map and depth image can be included if provided by dataset.
+Image path is included, and optionally path of segmentation map and depth image can be included if provided by dataset.
 - image_path: (N, ), list of str, each element is a relative path from the root folder (exclusive) to the image.
-- segmantation_path (optional): (N, ), list of str, each element is a relative path from the root folder (exclusive) to the segmantation map.
+- segmentation (optional): (N, ), list of str, each element is a relative path from the root folder (exclusive) to the segmentation map.
 - depth_path (optional): (N, ), list of str, each element is a relative path from the root folder (exclusive) to the depth image.
 
 #### Keypoints：
@@ -24,7 +24,7 @@ Following keys should be included in `HumanData` if applicable. For each diction
 
 #### Bounding Box：
 
-Bounding box of body (smpl), face and hand (smplx), which data type is `[x_min, y_min, width, height, confidence]`，and should not exceed the image boundary. 
+Bounding box of body (smpl), face and hand (smplx), which data type is `[x_min, y_min, width, height, confidence]`，and should not exceed the image boundary.
 - bbox_xywh: (N, 5), numpy array, bounding box with confidence, coordinates of bottom-left point x, y, width w and height h of bbox, score at last.
 - face_bbox_xywh, lhand_bbox_xywh, rhand_bbox_xywh (optional): (N, 5), numpy array, should be included if `smplx` data is provided, and is derived from smplx2d keypoints. Have the same srtucture as above.
 
@@ -44,7 +44,7 @@ Normally saved as smpl/smplx.
 #### Suggestion for WHAT to include in `HumanData['misc']`:
 
 Miscellaneous contains the info of different settings for each dataset, including camaera type, source of keypoints annotation, bounding box etc. Aims to faclitate different usage of data.
-`HumanData['misc']` is a dictionary and its keys are discribed as following:
+`HumanData['misc']` is a dictionary and its keys are described as following:
 - kps3d_root_aligned： Bool, stating that if keypoints3d is root-aligned，root_alignment is not preferred for HumanData. If this key does not exist, root_aligenment is by default to be `False`.
 - flat_hand_mean：Bool, applicable for smplx data，for most datasets `flat_hand_mean=False`.
 - bbox_source：source of bounding box，`bbox_soruce='keypoints2d_smpl' or 'keypoints2d_smplx' or 'keypoints2d_original'`，describing which type of keypoints are used to derive the bounding box，OR `bbox_source='provide_by_dataset'` shows that bounding box if provided by dataset. (For example, from some detection module rather than keypoints)
@@ -59,11 +59,11 @@ Miscellaneous contains the info of different settings for each dataset, includin
 
 - gender: (N, ), list of str, each element represents the gender for an smpl/smplx instance. (key not required if dataset use gender-neutral model)
 - height， width：(N, )， list of str, each element represents the width of height of image. (keys should be in `HumanData['misc']` if image shape are same across the dataset）
-- other keys，applicable if the key value is different，and have some imapct on keypoints or smpl/smplx (2d and 3d)，For example, `focal_length` and `principal_point`, focal_length = (N, 2), principal_point = (N, 2)
+- other keys，applicable if the key value is different，and have some impact on keypoints or smpl/smplx (2d and 3d)，For example, `focal_length` and `principal_point`, focal_length = (N, 2), principal_point = (N, 2)
 
 #### Some other info of HumanData
 
-- All annotations are transfromed from world space to opencv camera space, for space transformation we use:
+- All annotations are transformed from world space to opencv camera space, for space transformation we use:
 
     ```from mmhuman3d.models.body_models.utils import transform_to_camera_frame, batch_transform_to_camera_frame```
 

From 71e32725fbd6d3a2283cfb8d3997b693a5a453a6 Mon Sep 17 00:00:00 2001
From: wei-chen-hub <weichen@WeiChen-officeSG.localdomain>
Date: Tue, 27 Jun 2023 16:34:30 +0800
Subject: [PATCH 4/9] fix

---
 configs/gta_human/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/configs/gta_human/README.md b/configs/gta_human/README.md
index 0a04d172..f2b5e733 100644
--- a/configs/gta_human/README.md
+++ b/configs/gta_human/README.md
@@ -66,7 +66,7 @@ Please refer to [getting_started.md](../../docs/getting_started.md) for training
 
 ## Visualization
 
-We prepared a script with a sample sequence that should help you with the SMPL overlay. 
+We prepared a script with a sample sequence that should help you with the SMPL overlay.
 You may download it from [here](https://drive.google.com/file/d/11osPM67KiQN6NbdJo3plcgNoPNxfJ_j7/view?usp=share_link).
 
 ## Notes

From 8a36f931d027238f545035df9dceda4f5387a602 Mon Sep 17 00:00:00 2001
From: wei-chen-hub <weichen@WeiChen-officeSG.localdomain>
Date: Mon, 3 Jul 2023 16:10:07 +0800
Subject: [PATCH 5/9] minor docs update English & Chinese

---
 docs/human_data.md       | 7 +++++--
 docs_zh-CN/human_data.md | 7 ++++---
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/docs/human_data.md b/docs/human_data.md
index 34124f13..4956e93a 100644
--- a/docs/human_data.md
+++ b/docs/human_data.md
@@ -16,6 +16,9 @@ Image path is included, and optionally path of segmentation map and depth image
 #### Keypoints：
 
 Following keys should be included in `HumanData` if applicable. For each dictionary key of keypoints，a corresponding dictionart key of mask should be included，stating which keypoint is valid. For example `keypoints3d_original` should correspond to `keypoints3d_original_mask`.
+
+In `HumanData`, keypoints are stored as `HUMAN_DATA` format, which includes 190 joints. We provide keypoints format (for both 2d and 3d keypoints) convention for many datasets, please see [keypoints_convention](../docs/keypoints_convention.md).
+
 - keypoints3d_smpl / keypoints3d_smplx: (N, 190, 4), numpy array, `smplx / smplx` 3d joints with confidence, joints from each datasets are mapped to HUMAN_DATA joints.
 - keypoints3d_original: (N, 190, 4), numpy array, 3d joints with confidence which provided by the dataset originally, joints from each datasets are mapped to HUMAN_DATA joints.
 - keypoints2d_smpl / keypoints2d_smplx: (N, 190, 3), numpy array, `smpl / smplx` 2d joints with confidence, joints from each datasets are mapped to HUMAN_DATA joints.
@@ -39,7 +42,7 @@ Normally saved as smpl/smplx.
 
 - config: (), str, the flag name of config for individual dataset.
 - meta: (1, ), dict, its keys are meta data from dataset like 'gender'.
-- misc: (1, ), dict, keys and values are designed to describe the different settings for each dataset. Can also be defined by user. The space misc takes(sys.getsizeof(misc)) shall be no more than 6MB.
+- misc: (1, ), dict, keys and values are designed to describe the different settings for each dataset. Can also be defined by user. The space misc takes (sys.getsizeof(misc)) shall be no more than 6MB.
 
 #### Suggestion for WHAT to include in `HumanData['misc']`:
 
@@ -58,7 +61,7 @@ Miscellaneous contains the info of different settings for each dataset, includin
 #### Suggestion for WHAT to include in `HumanData['meta']`:
 
 - gender: (N, ), list of str, each element represents the gender for an smpl/smplx instance. (key not required if dataset use gender-neutral model)
-- height， width：(N, )， list of str, each element represents the width of height of image. (keys should be in `HumanData['misc']` if image shape are same across the dataset）
+- height (width)：(N, )， list of str, each element represents the height (width) of an image, `image_shape=(width, height): (N, 2)` is not suggested as width and height might need to be referenced in different orders. (keys should be in `HumanData['misc']` if image shape are same across the dataset)
 - other keys，applicable if the key value is different，and have some impact on keypoints or smpl/smplx (2d and 3d)，For example, `focal_length` and `principal_point`, focal_length = (N, 2), principal_point = (N, 2)
 
 #### Some other info of HumanData
diff --git a/docs_zh-CN/human_data.md b/docs_zh-CN/human_data.md
index 2fc887bd..f4f5e3a6 100644
--- a/docs_zh-CN/human_data.md
+++ b/docs_zh-CN/human_data.md
@@ -16,7 +16,8 @@
 
 #### 关键点：
 
-以下关键点keys如果适用，则应包含在HumanData中。任何一个关键点的key，应存在一个mask，表示其中哪些关键点有效。如`keypoints3d_original`应对应`keypoints3d_original_mask`
+以下关键点keys如果适用，则应包含在HumanData中。任何一个关键点的key，应存在一个mask，表示其中哪些关键点有效。如`keypoints3d_original`应对应`keypoints3d_original_mask`。
+`HumanData` 中的关键点存储格式为`HUMAN_DATA`, 包含190个关键点. MMHuman3d中提供了很多常用关键点格式的转换（2d及3d均支持）, 详见 [keypoints_convention](../docs_zh-CN/keypoints_convention.md).
 - keypoints3d_smpl / keypoints3d_smplx: (N, 190, 4), numpy array, `smplx / smplx`模型的3d关节点与置信度, 每一个数据集的关节点映射到了`HUMAN_DATA`的关节点。
 - keypoints3d_original: (N, 190, 4), numpy array, 由数据集本身提供的3d关节点与置信度, 每一个数据集的关节点映射到了`HUMAN_DATA`的关节点。
 - keypoints2d_smpl / keypoints2d_smplx: (N, 190, 3), numpy array, `smpl / smplx`模型的2d关节点与置信度, 每一个数据集的关节点映射到了`HUMAN_DATA`的关节点。
@@ -39,7 +40,7 @@
 
 - config: (), 字符串, 单个数据集的配置的标志。
 - meta: (1, ), 字典, `keys`为数据集中的各种元数据。
-- misc: (1, ), 字典, `keys`为数据集中各种独特设定，也可以由用户自定义。`misc`占用的空间(可以通过`sys.getsizeof(misc)`获取)不能超过6MB。
+- misc: (1, ), 字典, `keys`为数据集中各种独特设定，也可以由用户自定义。`misc`占用的空间（可以通过`sys.getsizeof(misc)`获取）不能超过6MB。
 
 #### `HumanData['misc']`中建议（可能）包含的内容:
 Miscellaneous部分中包含了每个数据集的独特设定，包括相机种类，关键点标注来源，检测框来源，是否包含smpl/smplx标注等等，用于便利数据读取。
@@ -56,7 +57,7 @@ Miscellaneous部分中包含了每个数据集的独特设定，包括相机种
 
 #### `HumanData['meta']`中建议（可能）包含的内容:
 - gender: (N, )， 字符串组成的列表, 每一个元素是smplx模型的性别（中性则不必标注）
-- height， width：(N, )， 字符串组成的列表, 每一个元素是图片的长或宽（数据集图片分辨率一致则应标注在`HumanData['misc']`中）
+- height（width）：(N, )， 字符串组成的列表, 每一个元素是图片的高（或宽），这里不推荐使用`image_shape=(width, height): (N, 2)`，因为有时需要按反顺序读取图片格式。（数据集图片分辨率一致则应标注在`HumanData['misc']`中）
 - 其它有标识性的key，若数据集中该key不一致，且会影响keypoints or smpl/smplx，则建议标注，如focal_length与principal_point, focal_length = (N, 2), principal_point = (N, 2)
 
 #### 关于HumanData的一些说明

From e2f42ca549bcd67acf4a92464d155d9a1d27cf75 Mon Sep 17 00:00:00 2001
From: wei-chen-hub <weichen@WeiChen-officeSG.localdomain>
Date: Mon, 3 Jul 2023 16:13:03 +0800
Subject: [PATCH 6/9] minor docs update English & Chinese

---
 docs_zh-CN/human_data.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs_zh-CN/human_data.md b/docs_zh-CN/human_data.md
index f4f5e3a6..a866f453 100644
--- a/docs_zh-CN/human_data.md
+++ b/docs_zh-CN/human_data.md
@@ -17,7 +17,7 @@
 #### 关键点：
 
 以下关键点keys如果适用，则应包含在HumanData中。任何一个关键点的key，应存在一个mask，表示其中哪些关键点有效。如`keypoints3d_original`应对应`keypoints3d_original_mask`。
-`HumanData` 中的关键点存储格式为`HUMAN_DATA`, 包含190个关键点. MMHuman3d中提供了很多常用关键点格式的转换（2d及3d均支持）, 详见 [keypoints_convention](../docs_zh-CN/keypoints_convention.md).
+`HumanData` 中的关键点存储格式为`HUMAN_DATA`, 包含190个关键点。MMHuman3d中提供了很多常用关键点格式的转换（2d及3d均支持）, 详见 [keypoints_convention](../docs_zh-CN/keypoints_convention.md).
 - keypoints3d_smpl / keypoints3d_smplx: (N, 190, 4), numpy array, `smplx / smplx`模型的3d关节点与置信度, 每一个数据集的关节点映射到了`HUMAN_DATA`的关节点。
 - keypoints3d_original: (N, 190, 4), numpy array, 由数据集本身提供的3d关节点与置信度, 每一个数据集的关节点映射到了`HUMAN_DATA`的关节点。
 - keypoints2d_smpl / keypoints2d_smplx: (N, 190, 3), numpy array, `smpl / smplx`模型的2d关节点与置信度, 每一个数据集的关节点映射到了`HUMAN_DATA`的关节点。

From 290f0f7b7c0b469ff976287e4c2458f6a4949bb1 Mon Sep 17 00:00:00 2001
From: wei-chen-hub <weichen@WeiChen-officeSG.localdomain>
Date: Tue, 25 Jul 2023 13:28:43 +0800
Subject: [PATCH 7/9] Remove pickle5

---
 mmhuman3d/data/data_converters/agora.py | 2 +-
 setup.cfg                               | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/mmhuman3d/data/data_converters/agora.py b/mmhuman3d/data/data_converters/agora.py
index 619e4e7a..961d250a 100644
--- a/mmhuman3d/data/data_converters/agora.py
+++ b/mmhuman3d/data/data_converters/agora.py
@@ -1,9 +1,9 @@
 import os
+import pickle
 from typing import List, Tuple
 
 import cv2
 import numpy as np
-import pickle5 as pickle
 from tqdm import tqdm
 
 from mmhuman3d.core.conventions.keypoints_mapping import convert_kps
diff --git a/setup.cfg b/setup.cfg
index a5899aa2..5ac7f557 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -15,6 +15,6 @@ multi_line_output = 3
 include_trailing_comma = true
 known_standard_library = pkg_resources,setuptools
 known_first_party = mmhuman3d
-known_third_party = PIL,cdflib,colormap,cv2,einops,h5py,matplotlib,mmcv,mpl_toolkits,numpy,openpifpaf,pickle5,plyfile,pytest,pytorch3d,pytorch_sphinx_theme,scipy,skimage,smplx,surrogate,torch,tqdm,trimesh,vedo
+known_third_party = PIL,cdflib,colormap,cv2,einops,h5py,matplotlib,mmcv,mpl_toolkits,numpy,openpifpaf,plyfile,pytest,pytorch3d,pytorch_sphinx_theme,scipy,skimage,smplx,surrogate,torch,tqdm,trimesh,vedo
 no_lines_before = STDLIB,LOCALFOLDER
 default_section = THIRDPARTY

From e9ee8956682e56dc7d6353071239f8820e4dab28 Mon Sep 17 00:00:00 2001
From: Wei-Chen-hub <1259566226@qq.com>
Date: Tue, 25 Jul 2023 14:08:33 +0800
Subject: [PATCH 8/9] Update MMCV max version to 2.0.0

---
 mmhuman3d/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/mmhuman3d/__init__.py b/mmhuman3d/__init__.py
index ddc69792..503457b0 100644
--- a/mmhuman3d/__init__.py
+++ b/mmhuman3d/__init__.py
@@ -16,7 +16,7 @@ def digit_version(version_str):
 
 
 mmcv_minimum_version = '1.3.17'
-mmcv_maximum_version = '1.8.0'
+mmcv_maximum_version = '2.0.0'
 mmcv_version = digit_version(mmcv.__version__)
 
 

From ae8646b1535843e0a676a982e4a1798591dcc1e9 Mon Sep 17 00:00:00 2001
From: Wei-Chen-hub <1259566226@qq.com>
Date: Tue, 25 Jul 2023 14:31:33 +0800
Subject: [PATCH 9/9] remove pickle5

---
 requirements/runtime.txt | 1 -
 1 file changed, 1 deletion(-)

diff --git a/requirements/runtime.txt b/requirements/runtime.txt
index 813f02a9..04d690ea 100644
--- a/requirements/runtime.txt
+++ b/requirements/runtime.txt
@@ -9,7 +9,6 @@ matplotlib
 numpy<1.24
 opencv-python
 pandas<2.0.0
-pickle5
 plyfile
 rtree
 scikit-image