Reading and writing meshes

Note

PMeshIO uses IOUtilities to read and write compressed files (e.g., .obj.gz).

Note

The file format is only determined from file names, not from stream content (e.g., file headers).

Reading meshes

readmesh reads a mesh from an IO stream or from a file. The returned Mesh type is defined by providing a "template" mesh of same type, which remains unchanged: "Read a mesh that has the same type as the provided template."

readmesh sets only mesh attributes that are available for the template mesh type. At least vertex positions must be provided.

readmesh can enable mesh attributes that are read, see PMeshAttributes.

When reading from a stream, the format, an AbstractMeshFormat, must be given explicitly. When reading from a file, the format is determined from the file name.

The returned mesh is empty on error.

mesh = readmesh(io, format, template; options...) :: typeof(template)

mesh = readmesh(path, template;
                exceptions=false, options...) :: typeof(template)

Note

readmesh returns always a Mesh. An empty Mesh indicates failure. Use exceptions=true if you need the case that an empty mesh was read successfully.

Writing meshes

writemesh writes the contents of a mesh to an IO stream or to a file. Only attributes that are available and enabled are considered for writing. At least vertex positions must be provided.

When writing to a stream, the format, an AbstractMeshFormat, must be given explicitly. When writing to a file, the format is determined from the file name.

success = writemesh(io, format, template; options...) :: Bool

success = writemesh(path, template;
                    exceptions = false, options...) :: Bool

Error handling

When reading from or writing to a stream, exceptions are not handled but passed to the caller (with no diagnostic output). When assembling the mesh, PMesh may ignore errors like invalid faces silently or with a diagnostic message (and take an appropriate action like ignoring the face).

When reading from or writing to a file, exceptions are handled by default and the method returns an empty mesh or false. Only if the optional keyword argument exceptions=true exceptions are not handled but passed to the caller (with no diagnostic output).

Mesh attributes

readmesh and writemesh take keyword arguments, which specify the mesh attributes to be read or written. Attributes are references by their names as Symol or Val{S} where S::Symbol.

A value nothing indicates that the attribute should be ignore. The vertex position attribute cannot be ignored.

Note

For readmesh, availability and type of attributes is defined by given the template mesh.

The following keyword arguments are supported

keyword argument	default name / value	attribute
`positition`	`:x`	vertex position
`normal`	`:n` / `nothing`	vertex or face normal
`texcoord`	`:u`	texture coordinate
`color`	`:c`	vertex or face color

Note

File formats and methods readmesh and writemesh may support only a subset of attributes.

Type conversions

readmesh may use a intermediate representations such as OBJBuffer with parametric types, and writemesh typically writes text files.

The following keyword arguments control intermediate representations and text output

keyword argument	mode	default value	remark
`real_type`	read	`Float64`	all floating point data
`index_type`	read	`Int32`	use default
`color_type`	read	`RGBA`	32 bit RGBA type
`format`	write	`"%g"`	`sprintf` format string

Helper `createmesh`

You can use the createmesh method to create a mesh suitable for a specific file format (AbstractMeshFormat.

template = createmesh(OBJ())

createmesh uses the default naming scheme for attributes (see above). In addition if supports the ofllowing optional keyword arguments

real_type=Float64 (as described above)
dimx=Val(3) dimensions of vertex positions as Val(N)
dimu=Val(2) dimensions of texture coordinates as Val(N)

Note

It is important to specify the Mesh type such that Julia can always infer the concrete type (thus the template argument for readmesh)!

Otherwise there may be a significant performance penallty when working with PMesh!

API

PMesh.createmesh — Function

mesh = createmesh(format[; ...])

Create an empty "template mesh" suitable for reading meshes in AbstractMeshFormat format.

Optional keyword arguments

keyword argument	default name / value	attribute
`real_type`	`Float64`	all floating point data
`dimx`	`Val(3)`	dimension of vertex position
`dimu`	`Val(2)`	dimension of texture coordinate