The MakeHuman API Project (MHAPI)

From experience, we know that it is hard for new potential developers to get a grip of the MakeHuman internals. Much of the inner working is, by necessity, rather complex. To address this, and to make it easier to further extend MakeHuman, we are now starting The MakeHuman API Project (MHAPI).

Motivation

Code is usually tech oriented. When you build things, you focus on getting things done. This usually means you build a structure around the technical implementation, and add calls and subroutines addressing this technical implementation. The upside of this is you get raw, "bare metal" access to the core functionality, which means you're free to do what you want without limitations. The downside is that you first have to know how the technological details are structured and implemented before you can start to figure out how to implement a change or extension. This also holds true for a tech oriented API: if you don't know what call to use, you have to first figure out which technical detail it applies to, then look at available calls for that detail. Needless to say, if you don't understand how the technical implementation is structured, finding the correct call to use will be very difficult.

The alternative way of structure an API is to make it task oriented and focusing on concepts rather than technical implementation. Here you first know what you want to do, and then go look for a call which claims to be able to do this. The calls are organized along concept lines rather than conforming to how the code is structured in the background. The upsides of this are that a new developer will quickly be able to produce code, code written against the API will make a lot more sense, and the API can remain stable even if the background implementation changes. The downsides are that there is a distance between how you write code and how things actually work, and that there is a maintenance cost in keeping the API up to date with the technical implementation.

Vision

Our goal with the MHAPI project is to implement something approaching being a DSL (Domain Specific Language), ie a python-based scripting language with calls that makes sense and which is very easy to use. Primarily we intend for the API to be used for writing extensions via plugins, but in the long run it is not strictly necessary to limit new code to this. 

The vision is that someone with basic programming knowledge should be able to start writing code for MakeHuman within minutes from having skimmed through the API description and making a copy of the example plugin.

Structure

As said the calls will be task oriented and sorted along concept lines. A subset of the API could (we're still at concept stage, discussing layout) look like this:

  api
    camera
      zoom()
      move()
      rotate()
      ...
    human
      applyTarget()
      setAge()
      ...
    clothes
      equipClothing()
      setClothingColor()
      ...
    interface
      addButton()
      addTab()
      ...
    messages
      showMessageBox()
      writeMessageToLog()
      ...

With this kind of API, you'd need one simple call to equip a hat to the human, for example api.clothes.equipClothing("fedora"). The goal is that it will be similarly easy to add a new tab with buttons and functionality.

Note that all of the above is just an example. The API structure is by no means finished (or mostly even started)

Timeline

The following is a basic outline of the steps we plan to take:

  • Make a list of top level namespaces (camera, human, clothes...) which conform to the concepts we think are relevant and important
    • Collect ideas from the community
    • Debate different approaches for dividing the namespaces into concepts
  • Add some minor example calls here and there in the namespaces
    • Collect wish list of calls from community, as well as suggestions
    • Write and debate different ways of naming and sorting calls
  • Make a rough draft of the code necessary to represent the API, as well as an example plugin using the API
  • Start a code repository for the API (it will be developed outside the MakeHuman source tree to start with)
  • Add and implement calls (this will be a long process that might never finish. We'll probably keep thinking up new calls to add for the foreseeable future.). 
    • Keep a tight and involved discussion with community
    • Decide when the set of available calls is good enough for releasing an alpha
  • Release an alpha implementation for evaluation
  • Make a re-iteration where the API is restructured and moved around to make more sense if something wasn't logical to start with
  • Freeze existing calls in the API (adding new calls will always be allowed, but existing calls shouldn't change. This in order to guarrantee a stable API to program against)
  • Release a beta version with at least the most important calls implemented
  • Fix reported bugs
  • Release a first frozen API version.
  • Merge with MakeHuman source tree
  • Re-implement some plugins that were useful once but which hasn't been kept up to date with the internals (might as well use those as case examples)
  • Start adding cool stuff.

How you can help

We want lots and lots of suggestions. The goal is to have a very open process where we integrate wishes about calls and concepts to represent. 

The easiest thing you can do is to go to the forums and make a suggestion for a call or concept you would want to be present. The slightly more advanced (but preferred) option is to go make a comment in issue #534 in the bugtracker. (yes, we're aware that people with a space in their forum user name can't log in on the bug tracker currently)

Resources

At this stage we're mainly discussing how the new API should look, so there isn't much to see. However, 

  • There is a repository with experimental stuff at https://bitbucket.org/joepal1976/makehuman-api-project/overview. Don't believe anything you see here, it's chaos programming at best currently. However, eventually there will be examples and implementations here.
  • The main feature request is issue #534. This is still the central place for discussions, although this might change if the project gets momentum.
  • There is a wiki page with random notes about the potential API. Same thing here, don't take anything written here for final or even serious. As of yet it's mainly wild ideas. However, we'll probably stage the API structure here before making a more structured reference.

 

MakeHuman for forensic face reconstruction and crime investigation.

Last week, from September 4th to 6th, the 12th Brazilian Congress of Forensic Dentistry took place in Florianópolis. The biennial event featured conferences and workshops by forensic professionals from Brazil, Uruguay, Peru and USA.

The attendees could also submit poster and short oral presentations to compete for the best academic works awards. The oral presentation "Protocol for Forensic Facial Reconstruction with open software: method simplification using MakeHuman" was one of the winners.

 

 

 

In this work, authors Cicero Moraes and Dr. Paulo Miamoto explained how the application of MakeHuman to forensic facial reconstruction can aid this technique by simplifying and individualizing the anatomic modeling process, as well as allowing the operator to adjust the 3D humanoid template to soft tissue pegs and other objective parameters using the Blender export mode.

The method was also presented at one of the official conferences of the event by Dr. Miamoto. Moraes, a 3D Designer, and Miamoto, a Forensic Dentist, are members of the NGO "Brazilian Team of Forensic Anthropology and Dentistry - Ebrafol", a non-profit organization that aims the promotion of Human Rights by applying knowledges of the aforesaid sciences. One of Ebrafol's expectations is provide official forensic units with training on 3D technology using open software.

 

 

 

 

 

 

 

 

MHX2 - MakeHuman eXchange format 2

Update 18/09/14: Most of the features that I wanted have now been implemented, although some tweaking remains. There is some initial documentation at http://thomasmakehuman.wordpress.com/mhx2-documentation/.

 

The MHX format that has been bundled with MakeHuman for the past five years has a number of problems. It will therefore be replaced by a completely new format, MHX2. The first MHX was essentially an interpreter for a Blender script that builds a character, and as such it was completely Blender-specific by design. In contrast, MHX2 is not tied to a specific application. Instead it exports all relevant information about the MakeHuman meshes and materials, which allows importers to add their own data, such as application-specific rigs, morph targets, etc. What makes me particular happy is that the lipsync tool that existed 2009-2011 but was removed after alpha 6 has finally been possible to reimplement.

Currently there is only an importer for Blender, but mhx2 importers for other applications could be written and optimized for other applications as well. Support for the old MHX format will eventually be terminated.

IMPORTANT: MHX2 is not part of the official MakeHuman distribution.

To download the repository as a zip file, go to https://bitbucket.org/ThomasMakeHuman/mhx2-makehuman-exchange/downloads.

Instructions.

  1. Copy or link the folder 9_export_mhx2 to the MakeHuman plugins folder.

  2. Copy or link the folder import_runtime_mhx2 to the addons destination directory where Blender will look for user-defined add-ons. Depending on the OS, this may be:

    Windows 7: C:\Users\%username%\AppData\Roaming\Blender Foundation\Blender\2.6x\scripts\addons

    Windows XP: C:\Documents and Settings\%username%\Application Data\Blender Foundation\Blender\2.6x\scripts\addons

    Vista: C:\Program Files\Blender Foundation\Blender\%blenderversion%\scripts\addons (this is valid at least for blender 2.69)

    Linux: /home/$user/.blender/$version/scripts/addons

  3. Open MakeHuman and design you character. In the Files > Export tab, select MakeHuman Exchange (mhx2), select the export path, and press export.

  4. Open Blender and enable the MHX2 importer. Select File > User Preferences. In the window that opens, select the Addons tab and then the MakeHuman category. Enable MakeHuman: Import-Runtime: MakeHuman eXchange 2 (.mhx2), and Save User Settings.

  5. In the File tab, enable Auto Run Python Scripts and Save User Settings.

  6. Select File > Import > MakeHuman (.mhx2), and navigate to the mhx2 file exported from MakeHuman.

  7. By default, the exported character is imported into Blender as it appears in MakeHuman. However, if Override Export Data is selected, the character will be rebuilt according to the options that appear.

MHX2 is very much work in progress, so it is too early for extensive documentation or bug report, but I think it might already be quite useful as it is.

Pages

Subscribe to