The Algos3D Module

MakeHuman 3D Transformation functions.

Project Name: MakeHuman

Product Home Page: http://www.makehuman.org/

Code Home Page: https://bitbucket.org/MakeHuman/makehuman/

Authors: Manuel Bastioni, Marc Flerackers, Jonas Hauquier

Copyright(c): MakeHuman Team 2001-2015

Licensing: AGPL3 (http://www.makehuman.org/doc/node/the_makehuman_application.html)

This file is part of MakeHuman (www.makehuman.org).

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

Coding Standards: See http://www.makehuman.org/node/165

Abstract

This module contains algorithms used to perform high-level 3D transformations on the 3D mesh that is used to represent the human figure in the MakeHuman application.

These currently include:

• morphing for anatomical variations
• pose deformations
• mesh coherency tests (for use during the development cycle)
• visualisation functions (for use during the development cycle)

This will also be where any future mesh transformation algorithms will be coded. For example:

• collision deformations
• etc..

class algos3d.Target(obj, name)

This class is used to store morph targets.

algos3d.defaultTargetLicense()

Default license for targets, shared for all targets that do not specify their own custom license, which is useful for saving storage space as this license is globally referenced by and applies to the majority of targets.

algos3d.getTarget(obj, targetPath)

This function retrieves a set of translation vectors from a morphing target file and stores them in a buffer. It is usually only called if the translation vectors from this file have not yet been buffered during the current session.

The translation target files contain lists of vertex indices and corresponding 3D translation vectors. The buffer is structured as a list of lists (a dictionary of dictionaries) indexed using the morph target file name, so: “targetBuffer[targetPath] = targetData” and targetData is a list of vectors keyed on their vertex indices.

For example, a translation direction vector of [0,5.67,2.34] for vertex 345 would be stored using “targetData[345] = [0,5.67,2.34]”. If this is taken from target file “foo.target”, then this targetData could be assigned to the buffer with ‘targetBuffer[“c:/MH/foo.target”] = targetData’.

obj:

3d object. The target object to which the translations are to be applied. This object is read by this function to define a list of the vertices affected by this morph target file.

targetPath:

string. The file system path to the file containing the morphing targets. The precise format of this string will be operating system dependant.

algos3d.loadTranslationTarget(obj, targetPath, morphFactor, faceGroupToUpdateName=None, update=1, calcNorm=1, scale=[1.0, 1.0, 1.0], animatedMesh=None)

This function retrieves a set of translation vectors and applies those translations to the specified vertices of the mesh object. This set of translations corresponds to a particular morph target file. If the file has already been loaded into memory then the translation vectors are read from the target data buffer, otherwise a function is first called to load the target data from disk into a buffer for future use.

The translation target files contain lists of vertex indices and corresponding 3D translation vectors. The translation vector for each vertex is multiplied by a common factor (morphFactor) before being applied to the specified vertex.

obj:

3d object. The target object to which the translations are to be applied. This object is read and updated by this function.

targetPath:

string. The file system path to the file containing the morphing targets. The precise format of this string will be operating system dependant.

morphFactor:

float. A factor between 0 and 1 controlling the proportion of the translations to be applied. If 0 then the object remains unmodified. If 1 the ‘full’ translations are applied. This parameter would normally be in the range 0-1 but can be greater than 1 or less than 0 when used to produce extreme deformations (deformations that extend beyond those modelled by the original artist).

faceGroupToUpdateName:

string. Optional: The name of a single facegroup to be affected by the target. If specified, then only transformations to faces contained by the specified facegroup are applied. If not specified, all transformations contained within the morph target file are applied. This permits a single morph target file to contain transformations that affect multiple facegroups, but to only be selectively applied to individual facegroups.

update:

int flag. A flag to indicate whether the update method on the object should be called.

calcNorm:

int flag. A flag to indicate whether the normals are to be recalculated (1/true) or not (0/false).

scale:

float. Scale the target offsets with this vector. Defaults to unit vector.

animatedMesh:

AnimatedMesh. Posed state of the basemesh with which the target should be transformed before being applied.

algos3d.refreshCachedTarget(targetPath)

Invalidate the cache for the specified target, so that it will be reloaded next time it is requested. Generally this only has effect if the target was loaded from an ascii file, not from npz archive.

algos3d.resetObj(obj, update=None, calcNorm=None)

This function resets the positions of the vertices of an object to their original base positions.

obj:

3D object. The object whose vertices are to be reset.

update:

int. An indicator to control whether to call the vectors update method.

calcNorm:

int. An indicator to control whether or not the normals should be recalculated

algos3d.saveTranslationTarget(obj, targetPath, groupToSave=None, epsilon=0.001)

This function analyses an object to determine the differences between the current set of vertices and the vertices contained in the originalVerts list, writing the differences out to disk as a morphing target file.

obj:

3d object. The object from which the current set of vertices is to be determined.

targetPath:

string. The file system path to the output file into which the morphing targets will be written.

groupToSave:

faceGroup. It’s possible to save only the changes made to a specific part of the mesh object by indicating the face group to save.

epsilon:

float. The distance that a vertex has to have been moved for it to be considered ‘moved’ by this function. The difference between the original vertex position and the current vertex position is compared to this value. If that difference is greater than the value of epsilon, the vertex is considered to have been modified and will be saved in the output file as a morph target.