Magnum::Trade::StanfordImporter class

Stanford PLY importer plugin.

Supports Little- and Big-Endian binary formats with triangle and quad meshes. Imports vertex positions, normals, 2D texture coordinates, vertex colors, custom attributes and per-face data as well.

Usage

This plugin depends on the Trade library and is built if WITH_STANFORDIMPORTER is enabled when building Magnum Plugins. To use as a dynamic plugin, load "StanfordImporter" via Corrade::PluginManager::Manager.

Additionally, if you're using Magnum as a CMake subproject, bundle the magnum-plugins repository and do the following:

set(WITH_STANFORDIMPORTER ON CACHE BOOL "" FORCE)
add_subdirectory(magnum-plugins EXCLUDE_FROM_ALL)

# So the dynamically loaded plugin gets built implicitly
add_dependencies(your-app MagnumPlugins::StanfordImporter)

To use as a static plugin or as a dependency of another plugin with CMake, put FindMagnumPlugins.cmake into your modules/ directory, request the StanfordImporter component of the MagnumPlugins package and link to the MagnumPlugins::StanfordImporter target:

find_package(MagnumPlugins REQUIRED StanfordImporter)

# ...
target_link_libraries(your-app PRIVATE MagnumPlugins::StanfordImporter)

See Downloading and building plugins, Plugin usage with CMake, Loading and using plugins and File format support for more information.

Behavior and limitations

In order to optimize for fast import, the importer supports a restricted subset of PLY features, which however shouldn't affect any real-world models.

The mesh is always indexed; positions are always present, other attributes are optional.

The importer recognizes ImporterFlag::Verbose, printing additional info when the flag is enabled.

Per-face attributes

By default, if the mesh contains per-face attributes apart from indices, these get converted to per-vertex during import. This is what the users usually want, however for large meshes this may have a performance impact due to calculating only unique per-vertex/per-face data combinations. If this conversion takes place, the resulting index type is always MeshIndexType::UnsignedInt, independent of what the file has.

Alternatively, if the perFaceToPerVertex configuration option is disabled, the importer provides access to per-face attributes in a second mesh level — i.e., meshLevelCount() returns 2 in that case, and calling mesh() with level set to 1 will return a MeshData instance with MeshPrimitive::Faces. The faces are triangulated, which means each item contains data for three vertices in the MeshPrimitive::Triangles mesh at level 0.

From the builtin attributes, colors, normals and object IDs can be either per-vertex or per-face, positions and texture coordinates are always per-vertex.

Custom attributes

Custom and unrecognized vertex and face attributes of known types are present in the imported meshes as well. Their mapping to/from a string can be queried using meshAttributeName() and meshAttributeForName(). Attributes with unknown types cause the import to fail, as the format relies on knowing the type size.

Plugin-specific config

It's possible to tune various import options through configuration(). See below for all options and their default values:

[configuration]

# Turn per-face attributes into per-vertex. If enabled, all attributes from the
# file (including custom ones) are present in the triangle mesh, with the
# additional cost of merging unique per-face attributes into vertices. If
# disabled, per-face attributes are available in a separate mesh level.
perFaceToPerVertex=true

# Use a fast index import path when the file looks like it has only triangle
# faces. This is significantly faster for large files but omits all face size
# checks and thus might cause broken files to not be detected correctly in rare
# cases.
triangleFastPath=true

# The non-standard MeshAttribute::ObjectId is by default recognized under this
# name. Change if your file uses a different identifier.
objectIdAttribute=object_id

Base classes

class AbstractImporter
Base for importer plugins.

Constructors, destructors, conversion operators

StanfordImporter() explicit
Default constructor.
StanfordImporter(PluginManager::AbstractManager& manager, const std::string& plugin) explicit
Plugin manager constructor.