Skip to content

read_mesh

read_mesh(file, fmt=None, return_UV=False, return_N=False, return_C=False, reader=None, merge_stl=True)

Reads a mesh from file.

If you have the approproate C++ extensions installed, this will use a fast C++-based reader. If you do not, this will use a slow python reader.

Currently only supports triangle meshes.

Parameters:

Name Type Description Default
file string

the path the mesh will be read from

 required
fmt string, optional (default

The file format of the mesh to open. If None, try to guess the format from the file extension. Supported formats: obj, stl

 None
return_UV bool, optional (default

Try reading texture coordinates, if they are present and the file format supports it. Only supported for OBJ files.

 False
return_N bool, optional (default

Try reading normal coordinates, if they are present and the file format supports it. Only supported for OBJ and PLY files.

 False
return_C bool, optional (default

Try reading color RGBA values, if they are present and the file format supports it. Only supported for PLY files.

 False
reader string, optional (default

Which reader engine to use. None, 'C++' or 'Python'. If None, will use C++ if available, and else Python.

 None
merge_stl bool, optional (default

If True, will merge the disconnected triangle STL file by removing duplicate vertices.

 True

Returns:

Name Type Description
V (n,3) numpy array

vertex list of a triangle mesh
F (m,3) numpy int array

face index list of a triangle mesh (into V)
UV (n_uv,2) numpy array, if requested

vertex list for texture coordinates
Ft (m,3) numpy int array, if requested

face index list for texture coordinates (into UV)
N (n_n,3) numpy array, if requested

vertex list for normal coordinates
Fn (m,3) numpy int array, if requested

face index list for normal coordinates (into N)
C (n,4) or (m,4) numpy int array, if requested

per-vertex or per-face colors

Examples:

# Read a mesh in OBJ format
v,f = gpytoolbox.read_mesh('mesh.obj')

# Read a mesh in STL format
v,f = gpytoolbox.read_mesh('mesh.stl',merge_stl=False)
# This mesh will just be a set of disconnected triangles, so functions like boundary_vertices will just return every vertex
assert len(gpytoolbox.boundary_vertices(f))==v.shape[0]
# Read a mesh in STL format, and merge the disconnected triangles
v,f = gpytoolbox.read_mesh('mesh.stl',merge_stl=True)
# Now the mesh is a single connected mesh, so boundary_vertices will return the correct result
assert len(gpytoolbox.boundary_vertices(f))<v.shape[0]
Source code in src/gpytoolbox/read_mesh.py 
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
def read_mesh(file,
    fmt=None,
    return_UV=False,
    return_N=False,
    return_C=False,
    reader=None,
    merge_stl=True):
    """Reads a mesh from file.

    If you have the approproate C++ extensions installed, this will use a fast
    C++-based reader. If you do not, this will use a slow python reader.

    Currently only supports triangle meshes.

    Parameters
    -------
    file : string
        the path the mesh will be read from
    fmt : string, optional (default: None)
        The file format of the mesh to open.
        If None, try to guess the format from the file extension.
        Supported formats: obj, stl
    return_UV : bool, optional (default: None)
        Try reading texture coordinates, if they are present and the file
        format supports it. Only supported for OBJ files.
    return_N : bool, optional (default: None)
        Try reading normal coordinates, if they are present and the file format
        supports it. Only supported for OBJ and PLY files.
    return_C : bool, optional (default: None)
        Try reading color RGBA values, if they are present and the file format
        supports it. Only supported for PLY files.
    reader : string, optional (default: None)
        Which reader engine to use. None, 'C++' or 'Python'.
        If None, will use C++ if available, and else Python.
    merge_stl : bool, optional (default: True)
        If True, will merge the disconnected triangle STL file by removing duplicate vertices.

    Returns
    ----------
    V : (n,3) numpy array
        vertex list of a triangle mesh
    F : (m,3) numpy int array
        face index list of a triangle mesh (into V)
    UV : (n_uv,2) numpy array, if requested
        vertex list for texture coordinates
    Ft : (m,3) numpy int array, if requested
        face index list for texture coordinates (into UV)
    N : (n_n,3) numpy array, if requested
        vertex list for normal coordinates
    Fn : (m,3) numpy int array, if requested
        face index list for normal coordinates (into N)
    C : (n,4) or (m,4) numpy int array, if requested
        per-vertex or per-face colors

    Examples
    --------
    ```python
    # Read a mesh in OBJ format
    v,f = gpytoolbox.read_mesh('mesh.obj')
    ```

    ```python
    # Read a mesh in STL format
    v,f = gpytoolbox.read_mesh('mesh.stl',merge_stl=False)
    # This mesh will just be a set of disconnected triangles, so functions like boundary_vertices will just return every vertex
    assert len(gpytoolbox.boundary_vertices(f))==v.shape[0]
    # Read a mesh in STL format, and merge the disconnected triangles
    v,f = gpytoolbox.read_mesh('mesh.stl',merge_stl=True)
    # Now the mesh is a single connected mesh, so boundary_vertices will return the correct result
    assert len(gpytoolbox.boundary_vertices(f))<v.shape[0]
    ```

    """

    # Detect format if it has not been specified
    if fmt is None:
        _, fmt = os.path.splitext(file)
    fmt = fmt[1:].lower()

    # Call appropriate helper function to read mesh
    if fmt=='obj':
        V,F,UV,Ft,N,Fn = _read_obj(file,return_UV,return_N,reader)
    elif fmt=='stl':
        V,F = _read_stl(file,merge_stl)
    elif fmt=='ply':
        V,F,N,C = _read_ply(file)
        if return_N:
            Fn = None
    else:
        assert False, "Mesh format not supported."

    # Arrange variables for output
    if return_UV and return_N:
        return V,F,UV,Ft,N,Fn
    if return_UV:
        return V,F,UV,Ft
    if (return_N and return_C):
        return V,F,N,Fn,C
    if return_N:
        return V,F,N,Fn
    if return_C:
        return V,F,C
    return V,F