Technical notes on MakeHuman - Revision history

Duststorm: /* Macro modifier dependencies */

2017-01-09T00:19:53Z

‎Macro modifier dependencies

Duststorm at 00:18, 9 January 2017

2017-01-09T00:18:45Z

Duststorm: /* Targets and modifiers */

2017-01-09T00:17:33Z

‎Targets and modifiers

Duststorm at 00:16, 9 January 2017

2017-01-09T00:16:23Z

Duststorm: /* Targets and modifiers */

2017-01-09T00:15:50Z

‎Targets and modifiers

Robbaer: /* Targets and modifiers */

2016-10-23T15:26:50Z

‎Targets and modifiers

Duststorm: /* Example */

2016-02-02T23:27:44Z

‎Example

Duststorm: /* Example */

2016-02-02T01:05:08Z

‎Example

Duststorm: /* Example */

2016-02-02T00:37:05Z

‎Example

Duststorm: /* Binary proxy */

2016-01-31T18:04:26Z

‎Binary proxy

@@ Line 87: / Line 87: @@
 Some more documentation about how macro modifiers resolve macro variables to actual variables can be found in this bug report: http://bugtracker.makehumancommunity.org/issues/1083
-Most of note here is probably how updateMacroTargets(), set<macrovariable>() and setDetail() interact.
+Most of note here is probably how updateMacroTargets(), set<macrovariable>() and setDetail() interact, to build the targetsDetailStack, which can then be applied to the human geometry using applyAllTargets().
 === Organization of modifiers ===

← Older revision		Revision as of 00:18, 9 January 2017
Line 87:		Line 87:

	Some more documentation about how macro modifiers resolve macro variables to actual variables can be found in this bug report: http://bugtracker.makehumancommunity.org/issues/1083		Some more documentation about how macro modifiers resolve macro variables to actual variables can be found in this bug report: http://bugtracker.makehumancommunity.org/issues/1083
		+	Most of note here is probably how updateMacroTargets(), set<macrovariable>() and setDetail() interact.

	=== Organization of modifiers ===		=== Organization of modifiers ===

@@ Line 85: / Line 85: @@
 As you might have understood, creating modifiers that depend on human variables is almost automatic. The only thing you need to do is create some targets that resolve to the same group name, add variations for all the macro variables you want and add the proper reserved tokens to the file or folder name (refer to the left column in the table above), and create a modifier with this group name. Once added to the human, the dependencies are tracked automatically.
 === Organization of modifiers ===
@@ Line 108: / Line 110: @@
 === Binary targets ===
 Because loading these ASCII target files, and iterating all target files and folders can be slow (especially on windows) in build versions, we compile all targets in the data/targets system folder into a single binary file, that furthermore acts exactly the same as multiple target files. The binary targets file is stored in the system data/ folder and is called targets.npz, it is created by running the compile_targets.py script, which is also automatically run in the build_prepare.py build routine. The file structure of the targets files is maintained in this binary file so that targets can be loaded from it in the same way as you would do with regular files. A change in the .target files, or newly added target files allow a recompilation of the targets npz file before the change is applied.
 == Proxy format ==

@@ Line 110: / Line 110: @@
 === Additional information ===
-Some more documentation can be found in this bug report: http://bugtracker.makehumancommunity.org/issues/1083
+Some more documentation about how macro modifiers resolve macro variables to actual variables can be found in this bug report: http://bugtracker.makehumancommunity.org/issues/1083
 == Proxy format ==

@@ Line 108: / Line 108: @@
 === Binary targets ===
 Because loading these ASCII target files, and iterating all target files and folders can be slow (especially on windows) in build versions, we compile all targets in the data/targets system folder into a single binary file, that furthermore acts exactly the same as multiple target files. The binary targets file is stored in the system data/ folder and is called targets.npz, it is created by running the compile_targets.py script, which is also automatically run in the build_prepare.py build routine. The file structure of the targets files is maintained in this binary file so that targets can be loaded from it in the same way as you would do with regular files. A change in the .target files, or newly added target files allow a recompilation of the targets npz file before the change is applied.
 == Proxy format ==

@@ Line 24: / Line 24: @@
 == Targets and modifiers ==
-MakeHuman applies targets on the human by means of modifiers. Such a modifier has a value (usually between [0, 1] or [-1, 1]) that determines the effect of it on the human mesh. A modifier can control one or more targets and in apply the mixed sum of them on the mesh. Some modifiers.
+MakeHuman applies targets on the human by means of modifiers. Such a modifier has a value (usually between [0, 1] or [-1, 1]) that determines the effect that it will have on the human mesh. A modifier can control one or more targets and it will apply the mixed sum of those targeys on the mesh. Some modifiers.
 === Organization of targets ===
-To make sure targets are linked to the right modifier, or to make managing targets easier, a certain discipline has to be observed in managing them. Targets are ASCII files in the data/targets or data/custom folder (in program or user folder) with a file extension of .target.
+To make sure targets are linked to the right modifier, or to make managing targets easier, a certain discipline has to be observed in managing them. Targets are ASCII files in the data/targets or data/custom folder (in either the program or user folder) and they haave file extension of .target.
-The file name and folder targets are in implicitly determines their group name. A group is identified by a sequence of tags or tokens, which are taken from the file and folder name of each target, and which can be delimited by “-” symbols, to include multiple tokens in a single file or folder name. The lib/targets.py module takes care of loading all the names of the available targets and assembles them into groups. All targets with the same tokens end up in the same group. This allows easy querying and requesting of targets. The creator is pretty much free to decide what groups to create for their targets. By passing the name of the target group to a modifier, they can make sure that modifier controls the targets belonging to this group. It does not matter whether you use folders or - delimited file names for creating groups.
+The file name and folder that targets are in implicitly determine their group name. A group is identified by a sequence of tags or tokens, which are taken from the file and folder name of each target. These tokens are delimited by “-” symbols, to include multiple tokens in a single file or folder name. The lib/targets.py module takes care of loading all the names of the available targets and assembles them into groups. All targets with the same tokens end up in the same group. This allows easy querying and requesting of targets. The creator is pretty much free to decide what groups to create for their targets. By passing the name of the target group to a modifier, they can make sure that modifier controls the targets belonging to this group. It does not matter whether you use folders or - delimited file names for creating groups.
 An example:
 data/targets/cartoon/eyes-large.target    is categorized in group (cartoon, eyes, large)
@@ Line 72: / Line 73: @@
 Note that it is not a good idea to use simply “max” or “min” as a reserved token name, because they need to be unique (otherwise it would not be possible to determine whether they are a minimum for, for example, weight or height). These reserved tokens are declared in the lib/targets.py module. The variable can be set and queried on the human object, for example human.getAge(), human.setMuscle(0.7), human.getProportion().
 The reserved tokens are NOT included in the group name, so you should at least include some other, non-reserved tokens in the file or folder names to assign your target to some meaningful group. The inclusion of these reserved tokens in your target names or paths makes it convenient to create macro modifiers.
@@ Line 78: / Line 80: @@
 === Macro modifier dependencies ===
 There are other macro modifiers that can also depend on the same variables age, gender, race that is controlled by the main macro modifiers, as discussed above. For example the macro modifiers that influence the weight and muscle mass of the human, controls the targets group “macrodetails-universal”, the universal token is added by prepending “universal-” to all the file names of related targets, which all reside in the folder “macrodetails” (thus macrodetails-universal ends up being the group name). They could have been included all in the “macrodetails” group, but are kept separate for performance reasons, so that the “macrodetails” group of targets (which already contains some 40 targets or so) can be applied in realtime while moving the slider.
-Of course a change in the variable that these age/race/gender modifiers control will have an effect on the macrodetails-universal modifiers (because they control targets that depend on age -- their targets include -young-  -old- etc. tokens in their filenames). This means there are inter-dependencies between macro modifiers, if one is updated, another one that depends on it should be refreshed. These dependencies can be descibed as follows: one macro modifier controls exactly one macro variable (such as age). It (or rather, the targets it controls) can however depend on multiple macro variables. The trivial case is where a macro modifier only depends on the macro variable that it controls itself. The tracking of these dependencies and deciding which modifiers must be updated when another is changed happens automatically. Dependencies are automatically tracked as soon as you add a modifier to the human (by calling modifier.setHuman(human)). To make this more performant in real-time, the propagation of updates to modifiers is limited while sliders are dragged (see realtimeDependencyUpdates in apps/humanmodifier.py).
 As you might have understood, creating modifiers that depend on human variables is almost automatic. The only thing you need to do is create some targets that resolve to the same group name, add variations for all the macro variables you want and add the proper reserved tokens to the file or folder name (refer to the left column in the table above), and create a modifier with this group name. Once added to the human, the dependencies are tracked automatically.
 === Organization of modifiers ===
 We already discussed how we organized targets in groups, to make it easier to connect them to a modifier. Now we will discuss how we can do a similar thing for modifiers.
-Modifiers provide an easy way to manage targets. They allow reducing many of hundreds of targets to a more manageable number of controllable properties. But even then, we still have about 100 modifiers, which is still quite a lot. Therefore we group them in groups of categories, much like we do in the GUI. This makes it easy to get a grouped overview of all modifiers when using an alternative interface, think of commandline or scripting. The way in which you declare the group and other properties of a modifier determines what target groups it gets its targets from.
-Modifiers are declared with a group name, some intermediary “target name” and a number of tail tokens (2 or 3 usually, eg min/max). The group of targets controlled by these modifiers is composed as: groupname-targets_name-tail.
+Modifiers provide an easy way to manage targets. They allow reducing many of hundreds of targets to a more manageable number of controllable properties. But even then, we still have about 100 modifiers, which is still quite a lot. Therefore we group them in groups of categories, much like we do in the GUI. This makes it easy to get a grouped overview of all modifiers when using an alternative interface, think of command line or scripting. The way in which you declare the group and other properties of a modifier determines what target groups it gets its targets from.
 Macro modifiers are declared with a group name,  and a controlled variable. The groupname must be the same groupname of the targets they control.
 === Declarative modifiers ===
 Instead of hard coding what modifiers you want to instantiate, MakeHuman offers a data-based format to declare what modifiers should be created, and how they should be shown in a user interface with sliders.
-A full declaration requires three files, all stored in data/modifiers. The first is the declaration of the modifiers (eg. modeling_modifiers.json). This format lists a modifier group name, and all the modifiers with their macro variable (if they are macro modifiers) or target name and 2 or 3 (if they are a modifier with a center point) tail tokens.
-The second file adds a description to the modifiers declared in the first file. It basically contains a key-value set, referencing the modifier name, and a textual description of what the modifier controls. A modifier name is constructed as follows: group/targets_name-all|the|tails and for a macro modifier: group/variable
+A full declaration requires '''three files''', all stored in data/modifiers. The '''first file''' is the declaration of the modifiers (e.g., modeling_modifiers.json). This format lists a modifier group name, and all the modifiers with their macro variable (if they are macro modifiers) or target name and 2 or 3 (if they are a modifier with a center point) tail tokens.
 The third file defines how these modifiers should be shown in the user interface as sliders. It lists a set of categories, and the sliders to show in them, and how their values have to be saved in a mhm file (mainly a feature for legacy compatibility).
 === Your own plugin with modifiers, sliders and targets ===

@@ Line 195: / Line 195: @@
      basemesh hm08
      tag Hats
-     version 1.2
+     version 120
      name fedora
@@ Line 205: / Line 205: @@
 It looks a lot like the v1.0 format, only the scale is no longer needed, and the vertex assignments have a new format.
 vIdxi references the vertices of a polygon of the basemesh

@@ Line 201: / Line 201: @@
      material materials/fedora.mhmat
      verts 0
-       polyIdx dx dy dz
+       vIdx1 vIdx2 vIdx3 vIdx4 dx dy dz
 It looks a lot like the v1.0 format, only the scale is no longer needed, and the vertex assignments have a new format.
-polyIdx references a polygon of the basemesh
+vIdxi references the vertices of a polygon of the basemesh
-dx dy dz is the distance vector between the polygon center and the proxy mesh vertex.
+dx dy dz is the distance (delta) vector between the polygon center and the proxy mesh vertex.
 === Binary proxy ===

@@ Line 208: / Line 208: @@
 dx dy dz is the distance vector between the polygon center and the proxy mesh vertex.
-==== Binary proxy ====
+=== Binary proxy ===
 Proxies, as well as their meshes, can be compiled into a more compact binary variant that is faster to load and smaller to distribute. MakeHuman will do this automatically for proxies in the home path. Files in the installation path will have to be compiled manually by running the compile_proxies.py and compile_meshes.py scripts. Usually these scripts are ran when a distribution is created, so need not to be repeated by the end user, unless MakeHuman is used from source.