MakeHuman: A manual

Marc Flerackers March 16, 2011

Contents
Preface iv

I
1

General usage
The view 1.1 Mouse movement . . 1.2 Keyboard movement 1.3 View options . . . . 1.3.1 Background . 1.3.2 Anaglyphs . 1.3.3 Wireframe . 1.3.4 Smooth . . . 1.4 Cameras . . . . . . . 1.5 Undo, redo and reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1
2 2 2 2 2 3 3 3 3 3 4 4 5 5 5 5 5 5 6 6 7 7 7 7 7 7 7

Modeling 2.1 Macro modeling . . . . . . . . . . . . 2.2 Detail modeling . . . . . . . . . . . . 2.2.1 Face . . . . . . . . . . . . . . 2.2.2 Breasts . . . . . . . . . . . . 2.2.3 Stomach, pelvis and buttocks . 2.2.4 Genitals . . . . . . . . . . . . 2.3 Micro modeling . . . . . . . . . . . . Files 3.1 Save and Load . . . . . . . . 3.2 Export . . . . . . . . . . . . 3.2.1 Wavefront (obj) . . . 3.2.1.1 Eyebrows 3.2.1.2 Diamonds 3.2.1.3 Skeleton . 3.2.1.4 Groups . . 3.2.1.5 Subdivide

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

CONTENTS 3.2.1.6 Hair . . . . . Blender exchange (mhx) 3.2.2.1 Version . . . . 3.2.2.2 Expressions . 3.2.2.3 Rig . . . . . . 3.2.3 Collada (dae) . . . . . . 3.2.4 Quake (md5) . . . . . . 3.2.5 Stereolithography (stl) . 3.2.5.1 Format . . . . 3.2.5.2 Subdivide . . Ethnics . . . . . . . . . . . . . 3.2.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

ii 7 7 8 8 8 8 8 8 8 8 8 9 9 9 10 10 10 11 11 11 11 11 11 11 11 11 11 11 11 11 11 12 12 12 12 13 13 13 14 14 14

3.3 4

Posing 4.1 Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2 Poses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Rendering 5.1 General . . . . . . . . . . . . . . . . 5.2 Aqsis . . . . . . . . . . . . . . . . . 5.2.1 Shading rate . . . . . . . . . 5.2.2 Samples . . . . . . . . . . . . 5.2.3 Skin oil . . . . . . . . . . . . 5.3 Povray . . . . . . . . . . . . . . . . . 5.3.1 Format . . . . . . . . . . . . 5.3.2 Action . . . . . . . . . . . . . 5.4 LuxRender . . . . . . . . . . . . . . 5.5 Settings . . . . . . . . . . . . . . . . 5.5.1 Dimensions . . . . . . . . . . 5.5.2 Hair . . . . . . . . . . . . . . 5.5.2.1 Clump radius . . . 5.5.2.2 Clump children . . 5.5.2.3 Multistrand children 5.5.2.4 Randomness . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

Advanced Modeling 6.1 Measure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2 Asymmetry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3 Randomize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Settings 7.1 Shader . . . . . 7.2 Slider behavior 7.3 Mouse behavior 7.4 Units . . . . . . 7.5 Shortcuts . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

CONTENTS

iii

II
8

Development
Writing plugins 8.1 Plugins . . . . . . . . . . . . . . 8.2 GUI . . . . . . . . . . . . . . . . 8.3 Morph targets . . . . . . . . . . . 8.4 Undo-redo . . . . . . . . . . . . . 8.5 Meshes . . . . . . . . . . . . . . 8.6 The camera . . . . . . . . . . . . 8.7 GUI controls . . . . . . . . . . . 8.8 Layout guidelines . . . . . . . . . 8.9 Asynchronous calls and animation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

15
16 16 16 17 18 19 19 20 21 22

Preface
This manual, like the MakeHuman software, is under constant construction and will change with the software. The latest edition can always be found on the makehuman website. MakeHuman is a 3d modeling tool which is build for one single purpose: creating a professional 3d human model. The base mesh has gone through many iterations to perfect the topology and all the modications which are available to the user are morphs which are modeled by hand by skilled artists. While the software is build with usability and simplicity in mind, there will always be questions, thats what Part I of this manual is for. It is modeled on the application and follows the menu system and options closely. Part II focuses on developing with MakeHuman, to create your own plugin and add functionality to the main application. This manual is provided under an Attribution-NonCommercial-NoDerivs 3.0 Unported (CC BY-NC-ND 3.0) license.

iv

Part I

General usage

Chapter 1

The view
1.1 Mouse movement

The model can be freely moved and rotated using the mouse. Keep the left button pressed to rotate the model. Keep the right button pressed to translate the model. Zooming can be done by using the scroll wheel, or by keeping both the left and right button pressed. If the manipulation speed is too slow, hold shift to speed up movement.

1.2

Keyboard movement

The following keyboard navigation is the standard navigation. It can be customized in settings, shortcuts. Use the arrow keys to move the model around. Use the 2, 4, 6 and 8 keys to rotate the model. Use the + and - keys to zoom. There are 3 standard views which have shortcut keys. For a side view press 7, for a front view press 1 and for a top view press 3. The . key resets both position and zoom.

1.3

View options

There are 4 view options which might help during modeling: background, anaglyphs, wireframe and smooth.

1.3.1

Background

The background mode shows an image le on top of the model. This is useful when the model should resemble an existing sketch, photograph or render. The rst time it is activated, it shows a list of les from the ~/makehuman/backgrounds folder to choose from. Afterward the background button toggles the background on and off. To choose another image go to library, background.

CHAPTER 1. THE VIEW

1.3.2

Anaglyphs

Anaglyphs mode renders the view from two viewpoints in red and cyan. When viewing this using red-cyan 3d glasses you can see the model in real 3d. There are two anaglyphs modes which use a slightly different method to render both views, so it takes two presses of the button to turn it back off.

1.3.3

Wireframe

Wireframe mode is good to see the topology and how vertices and faces are changed by certain modications.

1.3.4

Smooth

Smooth view might be too slow to work with on some systems. It subdivides the mesh with Catmull-Clark subdivision and keeps this subdivided mesh updated when modifying the model.

1.4

Cameras

There are two camera viewpoints between which can be quickly toggled, global camera and face camera.

1.5

Undo, redo and reset

These are not view options, but they appear throughout the application. Undo and redo are quite straightforward, they undo the last modication or redo the last undone modication. Reset removes all modications, be careful as it is impossible to undo this action.

Chapter 2

Modeling

2.1

Macro modeling

Macro modeling is the roughest step in modeling a human, but it also has the biggest impact on the resulting mesh. Macro modeling has 5 sliders. The rst 4 sliders modify the 4 main dimensions of the human: gender, age, muscle and weight. The last slider, height, modies the proportions. The functionality of the gender and age sliders are straightforward. Gender goes from female to male, initially it is at 50% of each, which gives a neutral gender. Age goes from 12 years old to 70 years old, initially it is at 25 years old. The muscle and weight sliders inuence each other. Only increasing muscle you doesnt create a bodybuilder, that also requires weight. Similarly only increasing weight doesnt create a really fat model, that also requires less muscle. Finally as said before the height slider doesnt just scale the model vertically, but it changes the 4

CHAPTER 2. MODELING proportions too. It goes from dwarf to giant.

2.2

Detail modeling

Detail modeling lets you move and scale large body parts. The moving and scaling is not just geometrical, but preserves body shapes. Manipulation is done on the mesh itself. Click and drag to transform the bodypart which lights up. Besides these transformations, detail modeling also lets you change some other details of the model.

2.2.1

Face

Many facial features like eyes, nose, ears, mouth, jaw, head shape can be modied using the sliders in the corresponding categories. Face age varies from young to old and face angle from slanted up to slated down.

2.2.2

Breasts

Breasts have two sliders, size and rmness. Since this is only sufcient for a subset of shapes, more sliders are planned.

2.2.3

Stomach, pelvis and buttocks

The stomach goes from bulging to rm. For female models this can be used to simulate mid to late pregnancy. The pelvis goes from wide to thin and the buttocks from round to rm.

2.2.4

Genitals

The genital slider goes from female to male genitals, initially it is in the center, which means no genitals.

2.3

Micro modeling

Micro modeling, like detail modeling lets you move and scale body parts, but on a much ner level.

Chapter 3

Files

3.1

Save and Load

Saving and loading happens in a custom and optimized format for MakeHuman with the mhm extension. It is advised to always save in this format also when you export models, since you cant load any other format back into MakeHuman. This is important when you want to make changes at a later stage of production.

CHAPTER 3. FILES

3.2
3.2.1

Export
Wavefront (obj)

Wavefront obj is a good format when you need a simple mesh for an external renderer. It comes with an mtl le dening the material. 3.2.1.1 Eyebrows

For some uses, like raytracing, the eyebrow geometry causes problems. If this is the case, uncheck it to avoid it from being exported. 3.2.1.2 Diamonds

The diamond geometry is used to keep track of the skeleton. However in most cases this is not needed. In case the diamond geometry is desired, check it to export it. 3.2.1.3 Skeleton

This option exports the skeleton in Biovision hierarchical data (bvh) format which is generally used for motion capture. Note however that the model is not rigged to this skeleton. 3.2.1.4 Groups

Whether groups are useful depends on the software used. Many importers also give the option to import the groups or not. Groups can be used to select specic body parts for modication or deletion. If groups are not desired, uncheck it. 3.2.1.5 Subdivide

If a high poly mesh is needed, and the modeler or renderer used does not have a good subdivision algorithm, you can check the subdivide option to export a mesh with 4 times the amount of faces, generated with Catmull-Clark subdivision. 3.2.1.6 Hair

If hair is present, it can be exported as a polygon mesh or as curves. Again it depends on the software which is going to import the le whether mesh or curves is the best option.

3.2.2

Blender exchange (mhx)

The Blender exchange format is a custom format designed to bring a rigged model into Blender. It comes with a skeleton, forward and inverse kinematics with limits, render materials, lip-sync and more.

CHAPTER 3. FILES 3.2.2.1 Version

Currently it is still possible to export for Blender 2.4, however this may change once Blender 2.5 is stable. 3.2.2.2 Expressions

If checked, all expressions available within MakeHuman are exported to the mhx, this makes the export considerably bigger in size. 3.2.2.3 Rig

Two rigs are available, mhx rig or game rig. For posing and animating the mhx rig is preferred.

3.2.3 3.2.4

Collada (dae) Quake (md5)

The md5 exporter is not yet fully functional, the skin is not correctly attached to the skeleton.

3.2.5

Stereolithography (stl)

Stereolithography is a format used for 3d printing. 3.2.5.1 Format

The binary format is a lot more compact than the ASCII format. However the latter is provided for compatibility reasons. 3.2.5.2 Subdivide

If a high poly mesh is needed, and the exernal modeler or renderer does not have a good subdivision algorithm, you can check the subdivide option to export a mesh with 4 times the amount of faces, generated with Catmull-Clark subdivision.

3.3

Ethnics

Ethnics are models which try to closely resemble people from a specic region in the world. They are model les with a special nishing morph for features which cannot be created with the tools in MakeHuman. To load an ethnic, the main ethnic is selected, then one of the sub ethnics of that ethnic. The gender and age are also chosen before loading. While the these can, theoretically, be modied afterward, it is advised to choose the gender and age as close as to what you need.

Chapter 4

Posing
4.1 Expressions

To make an expression on the models face, choose the expression category on the right, then drag the slider from the desired expression on the left as much to the right as needed.

4.2

Poses

Chapter 5

Rendering

5.1

General

For rendering, MakeHuman uses one of the installed external renderers. You only need to install the renderer of your choice.

5.2

Aqsis

Aqsis, a renderman compliant renderer, can be downloaded from http://www.aqsis.org/.

10

CHAPTER 5. RENDERING

11

5.2.1 5.2.2 5.2.3

Shading rate Samples Skin oil

5.3

Povray

Povray, or the Persistence of Vision Raytracer, can be downloaded from http://www.povray.org/.

5.3.1

Format

There is both support for the older array format and the newer mesh2 format.

5.3.2

Action

Determines whether only the pov les are written or whether Povray is also launched to render the le.

5.4

LuxRender

LuxRender, a physically based and unbiased rendering engine, can be downloaded from http://www.luxrender.net.

5.5

Settings

Some of the rendering settings are valid for all renderers. These include the dimensions of the rendered image and the hair settings.

5.5.1

Dimensions

The width and height of the rendered image

5.5.2
5.5.2.1 5.5.2.2 5.5.2.3 5.5.2.4

Hair
Clump radius Clump children Multistrand children Randomness

Chapter 6

Advanced Modeling
6.1 Measure

Measure has sliders which modify the length and/or circumference of specic body parts and shows the length and/or circumference of many body parts in centimeters. You can change the units to inches in Settings. Note that modifying one parameter might have impact on other measurements too.

6.2

Asymmetry

Sometimes a perfect symmetric model is not what is desired. Asymmetry can make some features of the models face or body asymmetric.

6.3

Randomize

When a lot of different models are needed, or some inspiration is needed, it is sometimes better to let the pseudorandom generator decide how the macro modeling is done. An existing model can also be modied by randomization of its macro features.

12

Chapter 7

Settings

7.1

Shader

MakeHuman can make use of GLSL shaders to give a better preview of how the model will look when rendered.

7.2

Slider behavior

MakeHuman does not require a very fast computer, though some operations might be too heavy for some systems. Turning off normal recalculation or turning off real-time updates completely might help in making MakeHuman usable on low-end systems.

13

CHAPTER 7. SETTINGS

14

7.3

Mouse behavior

This allows you to ne-tune the speed of moving the model using the mouse. Both the normal speed and the speed when holding down shift can be modied.

7.4

Units

Metric or imperial units can be chosen. Note that imperial units will use inches throughout the program, also for longer lengths.

7.5

Shortcuts

All shortcuts can be customized.

Part II

Development

15

Chapter 8

Writing plugins
8.1 Plugins

Makehuman has a simple plugin framework which makes it easy to add and remove features. At startup, MakeHuman now looks for .py les in the plugins folder which are not starting with an underscore (which makes it easier to disable unwanted plugins). It loads them one by one and calls the load entry point passing a reference to the application. The plugin can use this reference to add the necessary GUI widgets or code to the application. The rules for plugins are very simple: A plugin is a .py le in the plugins folder with a load entry point. A plugin only imports core les. The reason a plugin cannot import other plugins is that it would make it difcult to know which les belong to which plugin. We still need to dene a convention for shared les beyond the core MakeHuman les. To get started look at example.py or any of the other plugins to see how you can create your own feature in MakeHuman.

8.2

GUI

The GUI in MakeHuman is still far from nished. Since the rst alpha there have been many changes already and many other will come. This is because when features are added or modied, we can run out of space, or start to see things differently. Sometimes we experiment to see how a modier can be manipulated in a different way. For example in the details and microdetails we chose to have tools manipulating the model directly instead of using sliders. Another idea for the macrodetails was a multidimensional slider, like a radar chart which would replace all ve sliders. It is impossible to pour the GUI into into its nal form while we are still adding functionality and getting new ideas. However dont let the lack of guidelines stop you from adding a GUI to your own plugins. The current GUI API is very usable, and gets more mature every 16

CHAPTER 8. WRITING PLUGINS

17

day. The layout at the moment is a two level tab control. The tabs at the top represent categories, like modeling, les, rendering. The ones at the bottom are the tasks in the current category and rene the more broad category in macrodetail, detail and microdetail modeling, or saving, loading and exporting. So when creating your plugin, the rst thought should be "In which category does it belong?". From experience we know that it can be a though question to answer. Sometimes the only answer is adding a new category. This is what we initially did for measurement for example.
1 2 def load(app): category = gui3d.Category(app, "Measurement")

Next you probably want your own task to implement your feature. While its possible to attach functionality to an instance of gui3d.Task, its often easier to derive your own class. When you create an instance of your class, you pass the parent of your task, which can either be an existing category
1 2 def load(app): taskview = HairPropertiesTaskView(app.categories["Modelling"])

or the new one which you added.

1 2 3 def load(app): category = gui3d.Category(app, "Measurement") taskview = MeasurementTaskView(category)

In your derived task you will then add the necessary controls to let the user interact. A good place to see how to use the different controls is the example plugin. You will see that even if you dont add any controls, the model is already visible. This is because the model is attached to the root of the GUI tree. In the onShow event of your task you might want to reset the camera position, like we do in the save task, or hide the model, like we do in the load task. Just dont forget to reset the state when your task gets hidden in onHide.

8.3

Morph targets

Whatever your plugin does, theres a big chance that it will modify the model. As many of you probably know, MakeHuman doesnt work mathematically or procedural, but artistically. This means that you dont just drag vertices when moving a part of the body, but you actually apply a morph made by an artist. There are different kind of morphs targets which are applied in different ways. Macro targets, which are the most complex internally, are ironically the easiest to use: human.setGender, human.setAge, human.setWeight and human.setMuscle can be used to change the corresponding macro features. Height was originally not there, so you had to make the modier yourself. We will look at that in a moment. Detail and micro detail targets both come in pairs. For example one target to move a body part to the left, and another target to move the same body part to the right. Therefore you should never apply both targets at the same time. This means that when you apply one, and later you want to apply the other, you need to remove the rst. While you could use human.setDetail to this, it is easier to use the Modier class which does all of the needed logic behind the the method modier.setValue, it has an accompanying modier.getValue which has the reverse logic. To use it, you create a modier passing the two opposite targets:

CHAPTER 8. WRITING PLUGINS

1 2 3 4 modifier = humanmodifier.Modifier( "data/targets/macrodetails/universal-stature-dwarf.target", "data/targets/macrodetails/universal-stature-giant.target") modifier.setValue(human, 0.0)

18

A value between -1.0 and 0.0 will use the dwarf target, while a value between 0.0 and 1.0 will use the giant target. Using 0.0 will remove both targets. While using a modier also applies the target, to keep changes interactive other targets are not reapplied and normals are not recalculated. Once you have made the necessary changes, you commit them using human.applyAllTargets. Which does exactly what it says. It applies all the targets one by one and additionally recalculates the normals. Reapplying all targets minimizes the size of mathematical error in the nal model.

8.4

Undo-redo

One of the rst features written was undo-redo. Having this from the start saves us a lot of time later as we add this functionality to each kind of model modication immediately. It is important that every modication is undo-able, since just one undoable modication would leave the user without the possibility to undo anything. So its crucial that if you write a plugin which modies the model, you also make undo work. The Application class has several methods to work with actions. An action is a class with two methods, do and undo. If the action itself does the modication you can use app.do to add it to the undo stack. If you did the modication yourself already during user interaction, you can add the action using app.did. The application wont call the do method of the action in that case. If you want to make your own undo-redo buttons, you can use app.undo and app.redo. To illustrate, here is the action we use to change the hair color:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 class Action: def __init__(self, human, before, after, postAction = None): self.name = "Change hair color" self.human = human self.before = before self.after = after self.postAction = postAction def do(self): self.human.hairColor = self.after if self.postAction: self.postAction() return True def undo(self): self.human.hairColor = self.before if self.postAction: self.postAction() return True

The postAction is a handy way to specify a method to keep your GUI in sync with the changes. In this case we update the color control to show the correct color when the user chooses to undo or redo the hair color change.

CHAPTER 8. WRITING PLUGINS

19

8.5

Meshes

When writing exporters, subdivision or polygon reducing algorithms it can be useful to know how the mesh is stored in Python (the C side has a different compact but less convenient representation). An Object3D has three important lists: object.verts, object.faces and object.faceGroups. The rst two lists contain instances of Vertex and Face. The facesGroups contain FaceGroup objects. A FaceGroup species the name of the group and the faces that make up the group. A Face references 3 vertices in face.verts. A Vert or vertex holds its coordinates in vert.co and normal in vert.no. If we put all this together, we can write a simple Wavefront object exporter now:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 f = open(filename, w) for v in obj.verts: f.write("v %f %f %f\n" %tuple(v.co)) for uv in obj.uvValues: f.write("vt %f %f\n" %tuple(uv)) for v in obj.verts: f.write("vn %f %f %f\n" %tuple(v.no)) for g in obj.faceGroups: f.write("g %s\n" %(g.name)) for fc in g.faces: f.write("f") for v in fc.verts: f.write(" %i/%i/%i " %(v.idx + 1, fc.uv[i] + 1, v.idx + 1)) f.close()

As you can see, we take the uv values from obj.uvValues. The uv values are referenced in two places, obj.uvValues holds all the uv values of each vertex by index. Face.uv is a list with the uv values of each vertex of the face. The reason is that while normals are per vertex, uv values are per face-vertex, because a vertex can have a different uv depending on which face is drawn.

8.6

The camera

When your plugin allows editing a certain part of the model, its often good to focus the camera on that region. There are two cameras used in MakeHuman, accessible from the application class as modelCamera and guiCamera. The camera which we are interested in is the modelCamera. The application class itself is accessible in every GUI control as app. A camera has the following properties: fovAngle: The eld of view angle. nearPlane: The near clipping plane. farPlane: The far clipping plane. projection: The projection type, 0 for orthogonal, 1 for perspective. stereoMode: The stereo mode, 0 for no stereo, 1 for toe-in, 2 for off-axis.

CHAPTER 8. WRITING PLUGINS eyeSeparation: The eye separation. eyeX, eyeY, eyeZ: The position of the eye. focusX, focusY, focusZ: The position of the focus. upX, upY, upZ: The up vector.

20

The properties youll use to position the camera are the eye and focus position. The Application class has a few methods for camera presets, like setFaceCamera to focus on the face. Well look at what this method does to better understand how to position the camera: First we get the currently selected human (yes, we do anticipate having more than one human in the scene).
1 human = self.scene3d.selectedHuman

Next we get the vertices which belong to the head by facegroup names.
2 3 headNames = [group.name for group in human.meshData.facesGroups if ("head" in group.name or "jaw" in group.name)] self.headVertices, self.headFaces = human.meshData.getVerticesAndFacesForGroups( headNames)

We calculate the center of these vertices as this will become our focus point at which we will look at.
4 center = centroid([v.co for v in self.headVertices])

Now we are ready to set the eye and focus positions. We set the focus to the center position, and the eye a bit to the back.
5 6 7 8 9 10 self.modelCamera.eyeX = self.modelCamera.eyeY = self.modelCamera.eyeZ = self.modelCamera.focusX self.modelCamera.focusY self.modelCamera.focusZ center[0] center[1] 10 = center[0] = center[1] = 0

Finally we reset the humans position and rotation so that our calculations are as simple as the ones above.
11 12 human.setPosition([0.0, 0.0, 0.0]) human.setRotation([0.0, 0.0, 0.0])

If we would allow the human to be translated and rotated, we would need to take this transformation into account, as above we calculated the center of the untransformed mesh.

8.7

GUI controls

Whether you are writing an exporter, modeling feature or mesh algorithm, sooner or later you will need to add some controls in order to interact with the user. MakeHuman has a lot of the usual controls which you nd in in other GUI toolkits: Button: A regular push button.

CHAPTER 8. WRITING PLUGINS

21

ToggleButton: A button which has two states, selected and deselected, clicking the button toggles between the states. Used for making an on/off choice. CheckBox: A togglebutton, but with a check box look. RadioButton: A button which is part of a group, clicking one of the buttons selects it and deselects the others. Used for a multiple choice. Slider: Used to select a value from a discrete or continous range. TextEdit: A one line text eld. TextView: A label. GroupBox: Used to group a few controls together under a title.

8.8

Layout guidelines

To have a consistent look, it is important that all tasks use the same layout practices. GroupBoxes on the left side have x=10. The rst GroupBox starts at y=80. Controls start 25 pixels lower, and after the last control there are 6 extra pixels (besides the 4 pixels spacing from the last control). So the total height of a GroupBox is 25+content+6. Sliders start at x=10 and are 128 pixels wide, so there is no border left or right. Buttons start at x=18 and are 112 wide, so there are 8 pixels of border on each side. Between controls there are 4 pixels. Sliders are 32 pixels high and Buttons are 20 pixels high. This means that the space to the next control for a Slider is 36, and for a Button 24. So the height of a GroupBox can be calculated as 25+36*sliders+24*buttons+6. Between GroupBoxes there are 10 pixels.

CHAPTER 8. WRITING PLUGINS

22

Figure 8.1: Padding in yellow, spacing in fuschia, size in green Labels only have the rst letter capitalized, unless there is an acronym that needs to be in uppercase.

8.9

Asynchronous calls and animation

When doing lengthy operations it is important not to block the GUI from redrawing. Since everything runs in one thread, it is easy to block the event loop in your plugin. There are 4 ways to avoid this, depending on the need. If no user interaction is needed, a progressbar can be used. A progressbar uses the redrawNow() method of the application. This redraws the screen outside the event loop. Instead of creating your own progressbar, it is advised to use the progress method, which uses the global progressbar. Calling progress with a value greater than zero shows the progressbar, a value of zero hides it.

CHAPTER 8. WRITING PLUGINS

1 2 3 4 5 6 7 8 9 inc = value for i # 1.0 / n = inc in xrange(n): Shows the progressbar the first time self.app.progress(value) .. value += inc # Hides the progressbar self.app.progress(0)

23

If user interaction is desired during the operation, either asynchronous calls, a timer or a thread can be used. Asynchronous calls are used when a lengthy operation can be split in several units. It is used for example in the startup procedure as well as for the plugin loading loop. The mh.callAsync(method) queues the calling of method in the event loop, so it will be called when the event gets processed. In case different methods need to be called after each other, as in the startup procedure, callAsync is used to call the next method.
1 2 3 def method1(self): .. mh.callAsync(self.method2)

In case of the plugin loading loop, it calls the same method until it is done.
1 2 3 4 def method(self): .. if continue: mh.callAsync(self.method)

This is not to be used for animations, as it takes very little time between calling callAsync and the event loop calling the method. Calling time.sleep(dt) to avoid this should not be done as it blocks the main thread. For animations use timers instead. An example of this can be found in the BvhPlayer plugin. The method mh.addTimer(interval, method) adds a timer which calls the given method every interval milliseconds. It returns a value to be used by removeTimer to stop the timer.
1 2 3 4 5 6 7 8 def play(self): self.timer = mh.addTimer(33, self.nextFrame) def pause(self): mh.removeTimer(self.timer) def nextframe(self): ..

If a lengthy operation includes blocking on sockets or pipes, it is advised to use a python thread. However this has been shown to be problematic on Linux. See the clock plugin example for example code on how to use threads.