Complete tutorial and doc

sunset1995 · Jan 23, 2019 · 5314a16 · 5314a16 · zc1018x · Jul 29, 2022
1 parent b85e724
commit 5314a16
Show file tree

Hide file tree

Showing 25 changed files with 63 additions and 60 deletions.
diff --git a/README.md b/README.md
@@ -1,7 +1,5 @@
 # py360convert
 
-**This README is still under construction**
-
 Features of this project:
 - Convertion between cubemap and equirectangular  
     ![](assert/teaser_convertion.png)
@@ -19,13 +17,56 @@ Features of this project:
 ## Run with command line
 You can run command line to use the functionality. Please See `python convert360.py -h` for detailed. The python script is also an example code to see how to use this as a package in your code.
 
-## Doc
-All of the below examples assume the packages are loaded as:
 ```
-import numpy as np
-from PIL import Image
-import py360convert
+python convert360.py --convert e2c --i assert/example_input.png --o assert/example_e2c.png --w 200
+```
+| Input Equirectangular | Output Cubemap |
+| :---: | :----: |
+| ![](assert/example_input.png) | ![](assert/example_e2c.png) |
+
+-----
+
+```
+python convert360.py --convert c2e --i assert/example_e2c.png --o assert/example_c2e.png --w 800 --h 400
+```
+| Input Cubemap | Output Equirectangular |
+| :---: | :----: |
+| ![](assert/example_e2c.png) | ![](assert/example_c2e.png) |
+
+You can see the blurring artifacts in the polar region because the equirectangular in above figure are resampled twice (`e2c` then `c2e`).
+
+----
+
+```
+python convert360.py --convert e2p --i assert/example_input.png --o assert/example_e2p.png --w 300 --h 300 --u_deg 120 --v_deg 23
 ```
+| Input Equirectangular | Output Perspective |
+| :---: | :----: |
+| ![](assert/example_input.png) | ![](assert/example_e2p.png) |
+
+
+## Doc
+
+#### `e2c(e_img, face_w=256, mode='bilinear', cube_format='dice')`
+Convert the given equirectangular to cubemap.  
+**Parameters**:
+- `e_img`: Numpy array with shape [H, W, C].
+- `face_w`: The width of each cube face.
+- `mode`: `bilinear` or `nearest`.
+- `cube_format`: See `c2e` explaination.
+
+
+#### `e2p(e_img, fov_deg, u_deg, v_deg, out_hw, in_rot_deg=0, mode='bilinear')`
+Take perspective image from given equirectangular.
+**Parameters**:
+- `e_img`: Numpy array with shape [H, W, C].
+- `fov_deg`: Field of view given in int or tuple `(h_fov_deg, v_fov_deg)`.
+- `u_deg`: Horizontal viewing angle in range [-pi, pi]. (- Left / + Right).
+- `v_deg`: Vertical viewing angle in range [-pi/2, pi/2]. (- Down/ + Up).
+- `out_hw`: Output image `(height, width)` in tuple.
+- `in_rot_deg`: Inplane rotation.
+- `mode`: `bilinear` or `nearest`.
+
 
 #### `c2e(cubemap, h, w, cube_format='dice')`
 Convert the given cubemap to equirectangular.  
@@ -37,6 +78,10 @@ Convert the given cubemap to equirectangular.
 
 **Example**:
 ```
+import numpy as np
+from PIL import Image
+import py360convert
+
 cube_dice = np.array(Image.open('assert/demo_cube.png'))
 
 # You can make convertion between supported cubemap format

diff --git a/assert/demo_cube.png b/assert/demo_cube.png
diff --git a/assert/demo_equirec.png b/assert/demo_equirec.png
diff --git a/assert/demo_pers.png b/assert/demo_pers.png
diff --git a/assert/example_c2e.png b/assert/example_c2e.png
diff --git a/assert/example_e2c.png b/assert/example_e2c.png
diff --git a/assert/example_e2p.png b/assert/example_e2p.png
diff --git a/assert/example_input.jpg b/assert/example_input.jpg
diff --git a/assert/example_input.png b/assert/example_input.png
diff --git a/assert/example_results/c2e.jpg b/assert/example_results/c2e.jpg
diff --git a/assert/example_results/diff.jpg b/assert/example_results/diff.jpg
diff --git a/assert/example_results/e2c_B.jpg b/assert/example_results/e2c_B.jpg
diff --git a/assert/example_results/e2c_D.jpg b/assert/example_results/e2c_D.jpg
diff --git a/assert/example_results/e2c_F.jpg b/assert/example_results/e2c_F.jpg
diff --git a/assert/example_results/e2c_L.jpg b/assert/example_results/e2c_L.jpg
diff --git a/assert/example_results/e2c_R.jpg b/assert/example_results/e2c_R.jpg
diff --git a/assert/example_results/e2c_U.jpg b/assert/example_results/e2c_U.jpg
diff --git a/assert/example_results/e2c_cube_dice.jpg b/assert/example_results/e2c_cube_dice.jpg
diff --git a/assert/example_results/e2c_cube_h.jpg b/assert/example_results/e2c_cube_h.jpg
diff --git a/assert/example_results/e2p.jpg b/assert/example_results/e2p.jpg
diff --git a/assert/teaser_2planar.png b/assert/teaser_2planar.png
diff --git a/assert/teaser_convertion.png b/assert/teaser_convertion.png
diff --git a/example.py b/example.py
diff --git a/py360convert/c2e.py b/py360convert/c2e.py
@@ -3,7 +3,14 @@
 from . import utils
 
 
-def c2e(cubemap, h, w, cube_format='dice'):
+def c2e(cubemap, h, w, mode='bilinear', cube_format='dice'):
+    if mode == 'bilinear':
+        order = 1
+    elif mode == 'nearest':
+        order = 0
+    else:
+        raise NotImplementedError('unknown mode')
+
     if cube_format == 'horizon':
         pass
     elif cube_format == 'list':
@@ -50,7 +57,7 @@ def c2e(cubemap, h, w, cube_format='dice'):
     coor_y = (np.clip(coor_y, -0.5, 0.5) + 0.5) * face_w
 
     equirec = np.stack([
-        utils.sample_cubefaces(cube_faces[..., i], tp, coor_y, coor_x, order=1)
+        utils.sample_cubefaces(cube_faces[..., i], tp, coor_y, coor_x, order=order)
         for i in range(cube_faces.shape[3])
     ], axis=-1)
 

diff --git a/py360convert/e2p.py b/py360convert/e2p.py
@@ -14,8 +14,7 @@ def e2p(e_img, fov_deg, u_deg, v_deg, out_hw, in_rot_deg=0, mode='bilinear'):
     h, w = e_img.shape[:2]
 
     try:
-        fov = fov_deg * np.pi / 180
-        h_fov, v_fov = fov
+        h_fov, v_fov = fov_deg[0] * np.pi / 180, fov_deg[1] * np.pi / 180
     except:
         h_fov, v_fov = fov, fov
     in_rot = in_rot_deg * np.pi / 180
@@ -27,7 +26,7 @@ def e2p(e_img, fov_deg, u_deg, v_deg, out_hw, in_rot_deg=0, mode='bilinear'):
     else:
         raise NotImplementedError('unknown mode')
 
-    u = u_deg * np.pi / 180
+    u = -u_deg * np.pi / 180
     v = v_deg * np.pi / 180
     xyz = utils.xyzpers(h_fov, v_fov, u, v, out_hw, in_rot)
     uv = utils.xyz2uv(xyz)