M = polymesh.read (FILE) reads the mesh in FILE and returns it as a polymesh.Mesh, with the colours of its vertices or faces where the file has them. The extension of FILE names the format, .stl, .obj, .ply or .3mf, in any case.

• An STL file is binary or ASCII. It is binary when it is exactly as long as the number of triangles it declares makes it, and anything else is read as ASCII, the three numbers after each vertex, whatever the case and spacing. It has no colours.
• An OBJ file is text. Its v lines give the vertices, by their first three numbers, and their colours by the next three where they have them; its f lines give the faces, by the index of each corner’s vertex, counted from 1, or back from the last vertex so far when it is below 0. A face takes the colour Kd of the material its usemtl names, from the libraries its mtllib lines name, read from the folder of FILE. Texture and normal indices after a slash are ignored, as is every other line, and so are textures.
• A PLY file is ASCII or binary, in either byte order. The vertices are the properties x, y and z of the element vertex, and the faces the list vertex_indices, or vertex_index, of the element face, counted from 0. The properties red, green and blue of either element are its colours: an integer type from 0 to its largest value, as the common uchar from 0 to 255, a float from 0 to 1. Every other element and property is read past, alpha among them.
• A 3MF file is the archive slicers write, its parts stored or deflated. The mesh is every item of its build, each object placed where its transform puts it, the objects it is made of placed in turn, those in other model parts of the archive included, in millimetres whatever unit the file declares. A triangle takes the colour its property names, or else its object’s, from base materials or a colour group; textures and the other kinds of property are passed over.

A face of more than three corners, which OBJ and PLY allow, is cut into triangles turned the way the face is, each taking the colour of the face. It is cut in the plane it lies nearest, so a concave face is cut inside its outline; a face that crosses itself is cut as a fan from one corner.

Points that are equal are welded into one vertex, shared by every triangle that meets there, and a triangle two of whose corners become one is dropped. That is what joins the triangles of an STL file, which repeats every corner for every triangle that has it. A vertex welded from several of the file’s vertices takes the mean of their colours. The vertices come in the order the triangles first use them, and a vertex that no face uses is left out. The coordinates are taken as they are written; none of the three formats has units, and most files are in millimetres. A file with vertices but no faces, such as a point cloud, is an error.

A file that colours only some of its vertices, or only some of its faces, gives the rest the grey [0.72, 0.74, 0.78] that an uncoloured mesh is shown in. An OBJ file whose material library is missing is read without face colours, and a material missing from its library leaves the faces that use it grey; each is a warning. A colour outside 0 to 1 is an error.

M = polymesh.read (FILE, 'Tolerance', T) welds points that lie within T of one another, not only those that are equal, which closes the hairline gaps some programs leave in a mesh. The default T is 0.

See also: polymesh.Mesh, polymesh.Mesh.write, solid.polyhedron

Source Code: polymesh.read