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).
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.
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.
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)
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)
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.