update readme

README.md

@@ -2,24 +2,24 @@
 
 ## Introduction
 
- I organize this repo just for fun & my personal research use. 
-
-Hope this helps and you can enjoy it. : )
-
+ I organize this repo just for fun & my personal research. 
 
+Hope this helps and you'll enjoy it. : )
 
 ## Structure
 
 ```python
-# Since triangle mesh is the most popular representation of 3D face, the main part is mesh processing.
+# Since triangle mesh is the most popular representation of 3D face, 
+# the main part is mesh processing.
 mesh/             # written in python(numpy)
 |  io.py                 # read & write obj
 |  vis.py                # plot mesh
 |  transform.py          # transform mesh & estimate matrix
 |  light.py              # add light & estimate light(to do)
 |  render.py             # obj to image using rasterization render
 
-# When can not use vercorization to optimize, loop in python is too slow to use. So write core parts(loop) in c++, then use cython to compile it.
+# When can not use vercorization to optimize, loops in python are too slow to use. 
+# So write core parts(loop) in c++, then use cython to compile them.
 mesh_cython/      # written in c++(cython)
 |  render.py             # the same API as in mesh/render.py, with faster speed.
 |  light.py              # the same API as in mesh/light.py, with faster speed.
@@ -37,43 +37,70 @@ morphabel_model/  # witten in python(numpy)
 
 * **3dmm**.  `run examples/2_3dmm.py`
 
-  left: random examples generated by 3dmm
+  left:     random example generated by 3dmm
 
-  right: 3d face generated by fitted 3dmm&pose  parameters using 68 key points
+  right:  3d face generated by fitted 3dmm&pose  parameters using 68 key points
 
-![](examples/results/3dmm/generated.jpg)![](examples/results/3dmm/fitted.jpg)
+  ![](examples/results/3dmm/generated.jpg) ![](examples/results/3dmm/fitted.jpg)
 
 * **transform.**  `python examples/3_transform.py`
+  left:  
+
+  fix camera position & use orthographic projection.  (often used in reconstruction)
+
+  transform face object:
+
+  scale, change pitch angle, change yaw angle, change roll angle
+
+  right: 
+
+  fix obj position & use perspective projection(fovy=30).  (simulating real views)
+
+  move camera position and rotate camera:
 
-![](examples/results/transform/obj.gif)![](examples/results/transform/camera.gif)
+  from far to near,  down & up, left & right, rotate camera
+
+  ![](examples/results/transform/obj.gif) ![](examples/results/transform/camera.gif)
 
 * **light**.   `python examples/4_light.py`
 
-![](examples/results/light/position.gif)
+  single point light:
+
+  from left to right, from up to down, from near to far
+
+  ![](examples/results/light/position.gif)
 
 * **image map** `python examples/6_image_map.py`
 
-![](examples/results/image_map/depth.jpg) ![](examples/results/image_map/pncc.jpg) ![](examples/results/image_map/uv_coords.jpg)
+  render different attributes in image pixels.
+
+  : depth, pncc, uv coordinates
+
+  ![](examples/results/image_map/depth.jpg) ![](examples/results/image_map/pncc.jpg) ![](examples/results/image_map/uv_coords.jpg)
 
 * **uv map** `python examples/7_uv_map.py`
 
-![](examples/results/uv_map/uv_texture_map.jpg)![](examples/results/uv_map/uv_position_map.jpg)![](examples/results/uv_map/image.jpg)
+  render different attributes in uv coordinates.
+
+  : colors(texture map), position(2d facial image & corresponding position map)
+
+  ![](examples/results/uv_map/uv_texture_map.jpg) ![](examples/results/uv_map/image.jpg)![](examples/results/uv_map/uv_position_map.jpg) 
 
 
 
 ## Getting Started
 
 ### Prerequisite
 
-- Python 3+ (numpy, skimage, scipy)
+- Python 3 (python 2 should work, but I haven't tested)
 
 - Python packages:
   * numpy 
   * skimage (for reading&writing image)
   * scipy (for loading mat)
   * Cython (for compiling c++ files)
 
-- BFM Data
+- **BFM Data**
 
   see [Data/BFM/readme.md](Data/BFM/readme.md)
 

examples/Data/BFM/readme.md

@@ -0,0 +1,26 @@
+# Prepare BFM data
+
+1. Download raw BFM model 
+    website: https://faces.cs.unibas.ch/bfm/index.php?nav=1-0&id=basel_face_model.
+    copy 01_MorphabelModel.mat to raw/
+
+2. Download extra BFM information from 3DDFA(Face Alignment Across Large Poses: A 3D Solution).
+    website: http://www.cbsr.ia.ac.cn/users/xiangyuzhu/projects/3DDFA/main.htm
+    copy  *.mat to 3ddfa/
+
+3. Download UV coordinates fom STN
+    website: https://github.com/anilbas/3DMMasSTN/blob/master/util/BFM_UV.mat
+    copy BFM_UV.mat to stn/
+
+run generate.m in Matlab
+
+files will be saved in Out/
+
+
+
+Note: you need mkdir folders yourself, since I can not  upload empty folder in github.
+
+
+
+
+