jina-ai · hanxiao · Nov 2, 2021 · Nov 2, 2021 · Nov 2, 2021 · Nov 2, 2021
diff --git a/docs/datatype/mesh/3dmesh-man.gif b/docs/datatype/mesh/3dmesh-man.gif
diff --git a/docs/datatype/mesh/image45.gif b/docs/datatype/mesh/image45.gif
diff --git a/docs/datatype/mesh/img.png b/docs/datatype/mesh/img.png
diff --git a/docs/datatype/mesh/index.md b/docs/datatype/mesh/index.md
@@ -1,8 +1,69 @@
 # {octicon}`package` 3D Mesh
 
-A 3D mesh defines the properties such as shape, color and texture of an object in three dimensions. It is widely used in industries such as 3D printing and gaming. In addition to the traditional data types such text, audio and images, neural search can also be applied to less typical ones such as 3D meshes.
+````{tip}
 
- In this chapter, we will show you how simple it is to build a 3D mesh search pipeline and walk you through the process step by step.
+To enable the full feature of Document API on mesh data, you need to install `trimesh`.
+
+```shell
+pip install trimesh
+```
+````
+
+A 3D mesh is the structural build of a 3D model consisting of polygons. Most 3D meshes are created via professional software packages, such as commercial suites like Unity, or the free open source Blender 3D. Neural search on 3D mesh can be both fun and practically useful: consider a game developer places a zombie into a scene, one can leverage Jina to find looks-alike monsters and put them in the scene to bring the terror to the next level.
+
+```{figure} image45.gif
+:align: center
+:width: 50%
+```
+
+Before you start, let's recap some basic concepts of 3D mesh data and how Jina can help you process them.
+
+## Vertices, edges and faces
+
+A common misconception is that 3D model/mesh is just a set of points defined by (X, Y, Z) coordinates. That is not true, at least not the full story. 3D mesh is a collection of vertices, edges and faces that defines the shape of a polyhedral object. The faces usually consist of triangles since this simplifies rendering.  
+
+
+```{figure} img.png
+:align: center
+:width: 50%
+```
+
+When we talk about simple 3D mesh data, there are three concepts you need to be aware of:
+
+- **Vertex**: a (X, Y, Z) coordinate along with other meta information such as color, normal vector and texture.
+- **Edge**: a connection between two vertices.
+- **Face**: a closed set of edges, in which a triangle face has three edges.
+
+Our intuition on storing (X, Y, Z) coordinates only corresponds to the vertex-vertex representation, which describes a 3D object as a set of vertices connected to other vertices. Despite its simplicity, vertex-vertex representation is not widely used since the face and edge information is implicit. Thus, it is necessary to traverse the data in order to generate a list of faces for rendering. In addition, operations on edges and faces are not easily accomplished.
+
+## Common file formats
+
+Due to the variety of mesh representations, there are many 3D files in the market: `.glb`, `gltf`, `.fbx`, `.obj` etc. Some of them are proprietary and hence Jina does not provide a loader for all of them.
+
+## Point cloud
+
+Point cloud is another representation of a 3D mesh. It is made by repeated and uniformly sampling points within the 3D body. Comparing to the mesh representation, point cloud is a fixed size ndarray and hence easier for deep learning algorithms to handle. In Jina, you can simply load a 3D mesh and convert it into a point cloud via:
+
+```python
+from jina import Document
+doc = Document(uri='viking.glb').convert_uri_to_point_cloud_blob(1000)
+
+print(doc.blob)
+```
+
+```text
+(1000, 3)
+```
+
+The following pictures depict a 3D mesh and a point cloud with 1000 samples from that 3D mesh. 
+
+```{figure} 3dmesh-man.gif
+:width: 50%
+```
+
+```{figure} pointcloud-man.gif
+:width: 50%
+```
 
 ```{toctree}
 :hidden:

diff --git a/docs/datatype/mesh/pointcloud-man.gif b/docs/datatype/mesh/pointcloud-man.gif
@@ -77,4 +77,5 @@ kubernetes>=18.20.0:        perf, standard, devel
 pytest-kind==21.1.3:        test
 pytest-lazy-fixture:        test
 datasets:                   cicd
-av:                         cicd
+av:                         cicd
+trimesh:                    cicd
@@ -77,4 +77,5 @@ kubernetes>=18.20.0:        perf, standard, devel
 pytest-kind==21.1.3:        test
 pytest-lazy-fixture:        test
 datasets:                   cicd
-av:                         cicd
+av:                         cicd
+trimesh:                    cicd
diff --git a/jina/types/document/converters.py b/jina/types/document/converters.py
@@ -274,6 +274,35 @@ def convert_uri_to_audio_blob(self) -> 'Document':
             self.blob = audio_normalised
         return self
 
+    def convert_uri_to_point_cloud_blob(
+        self, samples: int, as_chunks: bool = False
+    ) -> 'Document':
+        """Convert a 3d mesh-like :attr:`.uri` into :attr:`.blob`
+
+        :param samples: number of points to sample from the mesh
+        :param as_chunks: when multiple geometry stored in one mesh file,
+            then store each geometry into different :attr:`.chunks`
+
+        :return: itself after processed
+        """
+        import trimesh
+
+        mesh = trimesh.load_mesh(self.uri).deduplicated()
+
+        pcs = []
+        for geo in mesh.geometry.values():
+            geo: trimesh.Trimesh
+            pcs.append(geo.sample(samples))
+
+        if as_chunks:
+            from . import Document
+
+            for p in pcs:
+                self.chunks.append(Document(blob=p))
+        else:
+            self.blob = np.stack(pcs).squeeze()
+        return self
+
     def convert_uri_to_image_blob(
         self,
         width: Optional[int] = None,

diff --git a/tests/unit/types/document/test.glb b/tests/unit/types/document/test.glb
diff --git a/tests/unit/types/document/test_converters.py b/tests/unit/types/document/test_converters.py
@@ -330,3 +330,9 @@ def test_deprecate_fn():
         doc.convert_uri_to_image_blob()
 
     assert len(record) == 0
+
+
+def test_glb_converters():
+    doc = Document(uri=os.path.join(cur_dir, 'test.glb'))
+    doc.convert_uri_to_point_cloud_blob(2000)
+    assert doc.blob.shape == (2000, 3)