Magnum::Trade::StanfordImporter class
#include <MagnumPlugins/StanfordImporter/StanfordImporter.h>

Stanford PLY importer plugin.

Imports PLY (*.ply) files. You can use StanfordSceneConverter to encode meshes into this format.

Usage

This plugin depends on the Trade library and is built if MAGNUM_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(MAGNUM_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.

ASCII files

The plugin implements parsing of binary files only. If an ASCII file is detected, it's forwarded to the AssimpImporter plugin, if available. Calls to meshCount(), meshLevelCount(), meshAttributeName(), meshAttributeForName() and mesh() are then proxied to AssimpImporter. The close() function closes and discards the internally instantiated plugin; isOpened() works as usual.

Note that AssimpImporter implements only a subset of features provided by this plugin. In particular, ASCII files with custom mesh attributes or per-face attributes will be imported as if they didn't have them, and both index and vertex data will be always in the full 32-bit type.

Plugin-specific configuration

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

See Editing plugin-specific configuration for more information and an example showing how to edit the configuration values.

Base classes

class AbstractImporter
Base for importer plugins.

Constructors, destructors, conversion operators

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