eos 1.4.0
Loading...
Searching...
No Matches
Classes | Typedefs | Functions
eos::morphablemodel Namespace Reference

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< Blendshapeload_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_modelThe expression model to draw a sample from.
[in]expression_coefficientsThe 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]filenameFilename to a blendshapes-file.
Returns
The loaded blendshapes.
Exceptions
std::runtime_errorWhen 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]filenameThe file to read.
Returns
Returns vector of floats.
Exceptions
std::runtime_errorif 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]filenameThe file to load the edge topology from.
Returns
A struct containing the edge topology.
Exceptions
std::runtime_errorif 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_filePath 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]filenameFilename to a model.
Returns
The loaded Morphable Model.
Exceptions
std::runtime_errorWhen 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]filenameFilename to a model.
Returns
The loaded PCA model.
Exceptions
std::runtime_errorWhen 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_filenameA binary .scm-file containing the model.
[in]isomap_fileAn optional path to a text file containing texture coordinates.
Returns
The Morphable Model loaded from the file.
Exceptions
std::runtime_errorwhen 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_basisA rescaled PCA basis matrix.
[in]eigenvaluesA 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_basisAn orthonormal_basis PCA basis matrix.
[in]eigenvaluesA 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_instancePCA shape model instance.
[in]color_instancePCA colour model instance.
[in]tviTriangle vertex indices.
[in]tciTriangle colour indices (usually identical to the vertex indices).
[in]texture_coordinatesOptional texture coordinates for each vertex.
[in]texture_triangle_indicesOptional 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]blendshapesThe blendshapes to be saved.
[in]filenameFilename 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]coefficientsA vector of coefficients.
[in]filenameThe file to write.
Exceptions
std::runtime_errorif 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_topologyA model's edge topology.
[in]filenameThe file to write.
Exceptions
std::runtime_errorif 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]modelThe model to be saved.
[in]filenameFilename 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]modelThe model to be saved.
[in]filenameFilename 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]blendshapesVector 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]coefficientsVector of blendshape coefficients.
Returns
An Eigen::Map pointing to the given coefficients data.