The Property Maps API is provided by the Boost Property Map Library and by the MEPP2 Generic Property Map Concept.

The Boost Property Map Library and its Property Map Concepts defines an interface to store/retrieve data in a property map whose key is a mesh item (vertex descriptor, halfedge descriptor, face descriptor...).

The MEPP2 Generic Property Map Concept provides:

the pre-definition of standard property maps (vertex-color, face-normal...)
a way to define non-standard property maps
a container to store/retrieve all the property maps associated with a mesh

Generic Property Map Concept

Introduction

The original need for what MEPP2 refers to as "generic" property maps arises from contexts where one needs to have the warranty that storing/accessing a property map associated to some mesh will function even if such property map is not natively supported by the native mesh datastructure. For example when using the native readers, the properties read from the mesh file (like vertex color, vertex normal, face color, texture coordinates...) are stored inside the datastructure itself. But when using a generic reader, we don't have anymore access to the datastructure internal storage. "Generic" property maps provide such location for storing mesh properties outside from any native datastructure.

Note that the geometry of a mesh (the coordinates of the vertices) is always stored natively in the mesh datastructure (and thus is NOT a "generic" property map). The property map holding the geometry of a mesh can always be retrieved within

auto pm = get(boost::vertex_point, mesh);

Refer to the Generic property maps design notes for more concerning the motivation and the implementation design.

Definitions

The Property Maps Traits for standard property maps

The Property Maps Traits FEVV::PMap_traits<PropertyTag, MeshT> is the traits class that produces the right property map type for a standard property associated to a particular mesh type MeshT.

The most usual property tags are pre-defined in FEVV/Wrappings/properties.h e.g.:

Non-standard property maps

A mechanism is provided to extend the MEPP2 defined standard property maps (the property tags that are defined in FEVV/Wrappings/properties.h). It allows to create new "non-standard" property maps, to store user defined properties, in a generic way. For example, a property map may be needed inside a filter to temporary store some value attached to the vertices.

A container for property maps

It is handy to gather all property maps associated to one mesh in a unique container, to manipulate them as a whole.

FEVV::PMapsContainer is the type of the container dedicated to the storage of one mesh property maps.

FEVV/Wrappings/properties.h defines FEVV::PMapsContainer as:

typedef std::map<std::string, boost::any> PMapsContainer;

Property Map API

Notations

PM A type that is a model of FEVV::PMap_traits.
pm An object of type PM.
pmaps_bag An object of type FEVV::PMapsContainer.
pmap_tag A standard property map tag (e.g. FEVV::vertex_normal, FEVV::face_color...)
PMap A type that is a model of Boost Read/Write Property Map.
pmap An object of type PMap.
key An object of type boost::property_traits<PMap>::key_type.
val An object of type boost::property_traits<PMap>::value_type.
M A type that is a model of mesh (e.g. CGAL::Surface_mesh< >, CGAL::Polyhedron_3< , >, OpenMesh::PolyMesh_ArrayKernelT< >;).
m An object of type M.

Associated types

Type	Description
boost::property_traits<PMap>::key_type	The type of the property map key (e.g. vertex_descriptor, face_descriptor...)
boost::property_traits<PMap>::value_type	The type of the data stored in the property map.
FEVV::PMapsContainer	A container for property maps.

Valid expressions

Store/retrieve data in a property map (Boost Read/Write Property Map concept)

Expression	Returns	Description
get(pmap, key)	value_type	Get the value associated with the key.
put(pmap, key, val)	void	Assign val to the property associated with the key.

Create, store, retrieve standard property maps

Expression	Returns	Description
`make_property_map(pmap_tag, m)`	`PM`	Constructs and returns the `pmap_tag` standard property map associated to the `m` mesh instance.
`has_map(pmaps_bag, pmap_tag)`	`bool`	Returns `true` when the `pmaps_bag` property map bag holds the property map `pmap_tag`, `false` otherwise
`put_property_map(pmap_tag, m, pmaps_bag, pm)`	`void`	Stores the `pmap_tag` property map `pm` (associated to `m` mesh instance) within the `pmaps_bag` property map bag.
`get_property_map(pmap_tag, m, pmaps_bag)`	`PM`	Returns the property map `pmap_tag` associated to the `m` mesh instance from the `pmaps_bag` property maps bag.
`remove_property_map(pmap_tag, pmaps_bag)`	`PM`	Remove the property map `pmap_tag` from the `pmaps_bag` property maps bag.

Create, store, retrieve non-standard property maps

Expression	Returns	Description
FEVV::make_vertex_property_map<M, value_type>(m)	`PM`	Constructs and returns a custom property map storing `value_type` data associated with `m` mesh vertices.
FEVV::make_edge_property_map<M, value_type>(m)	`PM`	Constructs and returns a custom property map storing `value_type` data associated with `m` mesh edges.
FEVV::make_halfedge_property_map<M, value_type>(m)	`PM`	Constructs and returns a custom property map storing `value_type` data associated with `m` mesh halfedges.
FEVV::make_face_property_map<M, value_type>(m)	`PM`	Constructs and returns a custom property map storing `value_type` data associated with `m` mesh faces.

Note: at the moment there is no easy way to store/retrieve a non-standard property map in a property maps container. See example below.

Examples

Create, store and retrieve a standard generic property map

// example: create a standard property map to store a color per vertex
 
// defines vertex_color_map as the property map type designated to hold/store
// colors at (each) vertex of a mesh to type MeshT.
using vertex_color_map = typename FEVV::PMap_traits<FEVV::vertex_color_t, MeshT>::pmap_type;
 
vertex_color_map vertex_color_pm = make_property_map(FEVV::vertex_color, g);
 
// store the property map in an existing FEVV::PMapsContainer
FEVV::PMapsContainer pmaps_bag;     // property maps container
put_property_map(FEVV::vertex_color, g, pmaps_bag, vertex_color_pm);
 
// later retrieve the property map from the container
auto vertex_color_pm = get_property_map(FEVV::vertex_color, g, pmaps_bag);

Create, store and retrieve a non standard property map

// example: create a user defined property map to store a label per face
 
// defines face_label_pmap_type as the property map type designated to
// hold/store a label (string) at (each) face of a mesh to type MeshT.
typedef  std::string                                   value_type;
typedef  typename FEVV::Face_pmap<MeshT, value_type>   face_label_pmap_type;
 
face_label_pmap_type  face_label_pmap;
face_label_pmap = FEVV::make_face_property_map<MeshT, value_type>(Mesh);
 
// store the property map in an existing FEVV::PMapsContainer
FEVV::PMapsContainer pmaps_bag;     // property maps container
pmaps_bag["f:label"] = face_label_pmap;
 
// later retrieve the property map from the container
// explicit cast needed here
face_label_pmap_type pm = boost::any_cast<face_label_pmap_type>(pmaps_bag.at("f:label"));