class
StanfordImporterStanford 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::
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.
- Both Little- and Big-Endian binary files are supported, with bytes swapped to match platform endianness.
- Position coordinates (
x
/y
/z
) are expected to have the same type, be tightly packed in a XYZ order and be either 32-bit floats or (signed) bytes or shorts. Resulting position type is then VertexFormat::Vector3, VertexFormat:: Vector3ub, VertexFormat:: Vector3b, VertexFormat:: Vector3us or VertexFormat:: Vector3s. 32-bit integer and double positions are not supported. - Normal coordinates (
nx
/ny
/nz
) are expected to have the same type, be tightly packed in a XYZ order and be either 32-bit floats or signed bytes or shorts. Resulting normal type is then VertexFormat::Vector3, VertexFormat:: Vector3bNormalized or VertexFormat:: Vector3sNormalized. 32-bit integer, unsigned and double normals are not supported. - Texture coordinates (
u
/v
ors
/t
) are expected to have the same type, be tightly packed in a XY order and be either 32-bit floats or unsigned bytes or shorts. Resulting texture coordinate type is then VertexFormat::Vector2, VertexFormat:: Vector2ubNormalized or VertexFormat:: Vector2usNormalized. Double texture coordinates are not supported, signed and 32.bit integer coordinates don't have a well-defined mapping to the range and thus are not supported either. - Color channels (
red
/green
/blue
and optionalalpha
) are expected to have the same type, be tightly packed in a RGB or RGBA order and be either 32-bit floats or unsigned bytes/shorts. Tesulting color type is then VertexFormat::Vector3 / VertexFormat:: Vector4, VertexFormat:: Vector3ubNormalized / VertexFormat:: Vector4ubNormalized or VertexFormat:: Vector3usNormalized / VertexFormat:: Vector4usNormalized. Signed, 32-bit integer and double colors are not supported. - Per-vertex object ID attribute is imported as either VertexFormat::
UnsignedInt, VertexFormat:: UnsignedShort or VertexFormat:: UnsignedByte. By default object_id
is the recognized name, use theobjectIdAttribute
configuration option to change the identifier that's being looked for. Because there are real-world files with signed object IDs, signed types are allowed as well, but interpreted as unsigned. - Indices (
vertex_indices
orvertex_index
) are imported as either MeshIndexType::UnsignedByte, MeshIndexType:: UnsignedShort or MeshIndexType:: UnsignedInt. Quads are triangulated, but higher-order polygons are not supported. Because there are real-world files with signed indices, signed types are allowed for indices as well, but interpreted as unsigned (because negative values wouldn't make sense anyway).
The mesh is always indexed; positions are always present, other attributes are optional.
The importer recognizes ImporterFlag::
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::
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::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() deprecated in Git master explicit
- Default constructor.
-
StanfordImporter(PluginManager::
AbstractManager& manager, const Containers:: StringView& plugin) explicit - Plugin manager constructor.
Function documentation
Magnum:: Trade:: StanfordImporter:: StanfordImporter() explicit
Default constructor.