Functionality to represent a Morphable Model, its PCA models, and functions to load models and blendshapes. More...

Classes
struct	Blendshape
	A class representing a 3D blendshape. More...

struct	EdgeTopology
	A struct containing a 3D shape model's edge topology. More...

class	MorphableModel
	A class representing a 3D Morphable Model, consisting of a shape- and colour (albedo) PCA model. More...

class	PcaModel
	This class represents a PCA-model that consists of: More...

Typedefs
using	Blendshapes = std::vector< Blendshape >

using	ExpressionModel = cpp17::variant< PcaModel, Blendshapes >
	Type alias to represent an expression model, which can either consist of blendshapes or a PCA model.

Functions
std::vector< Blendshape >	load_blendshapes (std::string filename)

void	save_blendshapes (const std::vector< Blendshape > &blendshapes, std::string filename)

Eigen::MatrixXf	to_matrix (const std::vector< Blendshape > &blendshapes)
	Copies the blendshapes into a matrix, with each column being a blendshape.

Eigen::Map< const Eigen::VectorXf >	to_vector (const std::vector< float > &coefficients)
	Maps an std::vector of coefficients with Eigen::Map, so it can be multiplied with a blendshapes matrix.

void	save_coefficients (std::vector< float > coefficients, std::string filename)

std::vector< float >	load_coefficients (std::string filename)

void	save_edge_topology (EdgeTopology edge_topology, std::string filename)

EdgeTopology	load_edge_topology (std::string filename)

Eigen::VectorXf	draw_sample (const ExpressionModel &expression_model, std::vector< float > expression_coefficients)

std::vector< std::array< double, 2 > >	load_isomap (std::string isomap_file)

MorphableModel	load_scm_model (std::string model_filename, cpp17::optional< std::string > isomap_file=cpp17::nullopt)

core::Mesh	sample_to_mesh (const Eigen::VectorXf &shape_instance, const Eigen::VectorXf &color_instance, const std::vector< std::array< int, 3 > > &tvi, const std::vector< std::array< int, 3 > > &tci, const std::vector< std::array< double, 2 > > &texture_coordinates=std::vector< std::array< double, 2 > >(), const std::vector< std::array< int, 3 > > &texture_triangle_indices=std::vector< std::array< int, 3 > >())

MorphableModel	load_model (std::string filename)

void	save_model (MorphableModel model, std::string filename)

Eigen::MatrixXf	rescale_pca_basis (const Eigen::MatrixXf &orthonormal_basis, const Eigen::VectorXf &eigenvalues)

Eigen::MatrixXf	normalise_pca_basis (const Eigen::MatrixXf &rescaled_basis, const Eigen::VectorXf &eigenvalues)

PcaModel	load_pca_model (std::string filename)

void	save_pca_model (PcaModel model, std::string filename)

Detailed Description

Functionality to represent a Morphable Model, its PCA models, and functions to load models and blendshapes.

Typedef Documentation

◆ Blendshapes

using eos::morphablemodel::Blendshapes = typedef std::vector<Blendshape>

Shorthand notation for an std::vector<Blendshape>.

◆ ExpressionModel

using eos::morphablemodel::ExpressionModel = typedef cpp17::variant<PcaModel, Blendshapes>

Type alias to represent an expression model, which can either consist of blendshapes or a PCA model.

Defining a type alias so that we don't have to spell out the type everywhere.

Function Documentation

◆ draw_sample()

Eigen::VectorXf eos::morphablemodel::draw_sample	(	const ExpressionModel &	expression_model,
		std::vector< float >	expression_coefficients
	)

inline

Returns a sample from an expression model with the given expression coefficients.

The underlying expression model can be both a PcaModel as well as a Blendshapes model. If a partial coefficient vector is given, it is filled with zeros up to the end.

Parameters

[in]	expression_model	The expression model to draw a sample from.
[in]	expression_coefficients	The coefficients used to generate the expression sample.

Returns: A model instance with given coefficients.

◆ load_blendshapes()

std::vector< Blendshape > eos::morphablemodel::load_blendshapes ( std::string filename )

inline

Helper method to load a file with blendshapes from a cereal::BinaryInputArchive from the harddisk.

Parameters

[in] filename Filename to a blendshapes-file.

Returns: The loaded blendshapes.

Exceptions

std::runtime_error When the file given in filename fails to be opened (most likely because the file doesn't exist).

◆ load_coefficients()

std::vector< float > eos::morphablemodel::load_coefficients ( std::string filename )

inline

Loads coefficients (for example PCA shape coefficients) from a json file.

Parameters

[in] filename The file to read.

Returns: Returns vector of floats.

Exceptions

std::runtime_error if unable to open the given file for reading.

◆ load_edge_topology()

EdgeTopology eos::morphablemodel::load_edge_topology ( std::string filename )

inline

Load a 3DMM edge topology file from a json file.

Parameters

[in] filename The file to load the edge topology from.

Returns: A struct containing the edge topology.

Exceptions

std::runtime_error if unable to open the given file for writing.

◆ load_isomap()

std::vector< std::array< double, 2 > > eos::morphablemodel::load_isomap ( std::string isomap_file )

inline

Load a set of 2D texture coordinates pre-generated by the isomap algorithm. After loading, we rescale the coordinates to [0, 1] x [0, 1].

Parameters

[in] isomap_file Path to an isomap file containing texture coordinates.

Returns: The 2D texture coordinates for every vertex.

Exceptions

...

◆ load_model()

MorphableModel eos::morphablemodel::load_model ( std::string filename )

inline

Helper method to load a Morphable Model from a cereal::BinaryInputArchive from the harddisk.

Parameters

[in] filename Filename to a model.

Returns: The loaded Morphable Model.

Exceptions

std::runtime_error When the file given in filename fails to be opened (most likely because the file doesn't exist).

◆ load_pca_model()

PcaModel eos::morphablemodel::load_pca_model ( std::string filename )

inline

Helper method to load a PCA model from a cereal::BinaryInputArchive from the harddisk.

Usually, morphablemodel::load_model(std::string) should be used to directly load a MorphableModel. This function can be useful when it is necessary to just load a PCA model.

Parameters

[in] filename Filename to a model.

Returns: The loaded PCA model.

Exceptions

std::runtime_error When the file given in filename fails to be opened (most likely because the file doesn't exist).

◆ load_scm_model()

MorphableModel eos::morphablemodel::load_scm_model	(	std::string	model_filename,
		cpp17::optional< std::string >	isomap_file = `cpp17::nullopt`
	)

inline

Load a shape and color model from a .scm file containing a Morphable Model in the Surrey format. CVSSP's software internally trains and stores the model in this custom binary format and this class provides means to load them.

Note on multi-resolution models: The landmarks to vertex-id mapping is always the same. The lowest resolution model has all the landmarks defined and for the higher resolutions, the mesh is divided from that on. Note: For new landmarks we add, this might not be the case if we add them in the highest resolution model, so take care!

For the optional isomap_file, a text file along the lines of 'IsoMnF_Ar2.txt' or 'isomap.txt' from CVSSP can be given.

The PCA basis matrix stored in the file and loaded is the orthogonal PCA basis, i.e. it is not normalised by the eigenvalues.

Parameters

[in]	model_filename	A binary .scm-file containing the model.
[in]	isomap_file	An optional path to a text file containing texture coordinates.

Returns: The Morphable Model loaded from the file.

Exceptions

std::runtime_error when reading either of the files fails.

◆ normalise_pca_basis()

Eigen::MatrixXf eos::morphablemodel::normalise_pca_basis	(	const Eigen::MatrixXf &	rescaled_basis,
		const Eigen::VectorXf &	eigenvalues
	)

inline

Takes a rescaled PCA basis matrix and scales it back to an orthonormal basis matrix by multiplying each eigenvector by 1 over the square root of its corresponding eigenvalue.

Parameters

[in]	rescaled_basis	A rescaled PCA basis matrix.
[in]	eigenvalues	A row or column vector of eigenvalues.

Returns: The orthonormal PCA basis matrix.

◆ rescale_pca_basis()

Eigen::MatrixXf eos::morphablemodel::rescale_pca_basis	(	const Eigen::MatrixXf &	orthonormal_basis,
		const Eigen::VectorXf &	eigenvalues
	)

inline

Takes an orthonormal PCA basis matrix (a matrix consisting of the eigenvectors) and rescales it, i.e. multiplies each eigenvector by the square root of its corresponding eigenvalue.

Parameters

[in]	orthonormal_basis	An orthonormal_basis PCA basis matrix.
[in]	eigenvalues	A row or column vector of eigenvalues.

Returns: The rescaled PCA basis matrix.

◆ sample_to_mesh()

core::Mesh eos::morphablemodel::sample_to_mesh	(	const Eigen::VectorXf &	shape_instance,
		const Eigen::VectorXf &	color_instance,
		const std::vector< std::array< int, 3 > > &	tvi,
		const std::vector< std::array< int, 3 > > &	tci,
		const std::vector< std::array< double, 2 > > &	texture_coordinates,
		const std::vector< std::array< int, 3 > > &	texture_triangle_indices
	)

inline

Helper function that creates a Mesh from given shape and colour PCA instances. Needs the vertex index lists as well to assemble the mesh - and optional texture coordinates.

If color_instance is empty, it will create a mesh without vertex colouring. Colour values are assumed to be in the range [0, 1] and will be clamped to [0, 1].

Parameters

[in]	shape_instance	PCA shape model instance.
[in]	color_instance	PCA colour model instance.
[in]	tvi	Triangle vertex indices.
[in]	tci	Triangle colour indices (usually identical to the vertex indices).
[in]	texture_coordinates	Optional texture coordinates for each vertex.
[in]	texture_triangle_indices	Optional triangulation for the texture coordinates.

Returns: A mesh created from given parameters.

◆ save_blendshapes()

void eos::morphablemodel::save_blendshapes	(	const std::vector< Blendshape > &	blendshapes,
		std::string	filename
	)

inline

Helper method to save a set of blendshapes to the harddisk as a cereal::BinaryOutputArchive.

Parameters

[in]	blendshapes	The blendshapes to be saved.
[in]	filename	Filename for the blendshapes.

◆ save_coefficients()

void eos::morphablemodel::save_coefficients	(	std::vector< float >	coefficients,
		std::string	filename
	)

inline

Saves coefficients (for example PCA shape coefficients) to a json file.

Parameters

[in]	coefficients	A vector of coefficients.
[in]	filename	The file to write.

Exceptions

std::runtime_error if unable to open the given file for writing.

◆ save_edge_topology()

void eos::morphablemodel::save_edge_topology	(	EdgeTopology	edge_topology,
		std::string	filename
	)

inline

Saves a 3DMM edge topology file to a json file.

Parameters

[in]	edge_topology	A model's edge topology.
[in]	filename	The file to write.

Exceptions

std::runtime_error if unable to open the given file for writing.

◆ save_model()

void eos::morphablemodel::save_model	(	MorphableModel	model,
		std::string	filename
	)

inline

Helper method to save a Morphable Model to the harddrive as cereal::BinaryOutputArchive.

Parameters

[in]	model	The model to be saved.
[in]	filename	Filename for the model.

◆ save_pca_model()

void eos::morphablemodel::save_pca_model	(	PcaModel	model,
		std::string	filename
	)

inline

Helper method to save a PCA model to the harddrive as cereal::BinaryOutputArchive.

Parameters

[in]	model	The model to be saved.
[in]	filename	Filename for the model.

◆ to_matrix()

Eigen::MatrixXf eos::morphablemodel::to_matrix ( const std::vector< Blendshape > & blendshapes )

inline

Copies the blendshapes into a matrix, with each column being a blendshape.

Parameters

[in] blendshapes Vector of blendshapes.

Returns: The resulting matrix.

◆ to_vector()

Eigen::Map< const Eigen::VectorXf > eos::morphablemodel::to_vector ( const std::vector< float > & coefficients )

inline

Maps an std::vector of coefficients with Eigen::Map, so it can be multiplied with a blendshapes matrix.

Note that the resulting Eigen::Map only lives as long as the data given lives and is in scope.

Parameters

[in] coefficients Vector of blendshape coefficients.

Returns: An Eigen::Map pointing to the given coefficients data.

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ Blendshapes

◆ ExpressionModel

Function Documentation

◆ draw_sample()

◆ load_blendshapes()

◆ load_coefficients()

◆ load_edge_topology()

◆ load_isomap()

◆ load_model()

◆ load_pca_model()

◆ load_scm_model()

◆ normalise_pca_basis()

◆ rescale_pca_basis()

◆ sample_to_mesh()

◆ save_blendshapes()

◆ save_coefficients()

◆ save_edge_topology()

◆ save_model()

◆ save_pca_model()

◆ to_matrix()

◆ to_vector()