Tools for a new model (from an existing one, or from scratch)

[TetoTheSquirrelFox]

I decided to open a "new thread" about tools I started to code, about creation of a new model from scratch, or from an existing model.

It's not a secret that, because of status Manuel Bastioni gave to his model (whatever for pictures/animation is OK, no way for use as model in a game), that MB-Lab needs at a new model (and needs also a cartoon model). But the model must be prepared, every part of it must be stored in a certain may, in order to the engine to be able to handle it, the way Manuel designed his addon anyway.

So I started by something easy (change/add/... morphs), that is the core of the engine before the finalization of a model, and now I started to try to figure out how a model is loaded in the engine, in order to be able to transform a model in data for the engine.

But in the same time, I want to be able to change a model by adding vertices (not remove, for the moment, but why not), to improve it, adding details that are lacking, and so on. In order to do that I'll have to know how the engine works and handles data because vertices are used for measures, joints, muscles, bboxes, groups, ... And if these elements are not properly done, the engine doesn't work.

But first, I have to deal with vertices, how to adapt new ones in an existing model, and how to add them in every file (morphs, groups, bboxes and so on) where they could be stored.

That's my goal for next weeks (months ?)

[TetoTheSquirrelFox]

So, the file where all begins, and which is important to explain, is characters_config.json.

Before all explanations, this file is for models made by MB, and won't be touched if there are new models, as new models/projects will have their own config.json, under another name, like myproject_config.json.

Characters_config.json

It's a json file, and when it's loaded, it's a dictionary with a bunch of keys/values that are interconnected .

1. "templates_list" : It has a list of base models. They are in fact keys themselves, that encapsulates all data to build the given base character. For example "human_female_base" is an item that is also a key for all items needed to build this model (see below).
2. "character_list" : All body types saved for the templates. Example "f_ca01". "f" means female, "ca" is for Caucasian here and 01 the number because you could have more than 1 Caucasian model. Things to understand here :

• A body type is for 1 model only, and the content for this type, aka all needed elements to define it are stored as values with body type name as the key. See n°4.
• You can have any models you want, but you can use only the files under the project subdirectories.
• Remember : base model (in a blend file) is morphed by "Body Type" to have a general morphology (like African) -> is morphed again to have preset (like fitness) and phenotype (like aboriginal). And after that, the user can morph again to "sculpt" it.

3. "human_female_base" (or "whatever_base") : The content for the template list (see n°1). You have the description, the model (which is stored in humanoid_library.blend for the base addon), the file for the body's vertices (not the eyes or teeth, just body), the number of vertices, and faces. Plus a label for GUI.
4. "f_ca01" : The content that defines each item stored in n°2. Here are all elements needed to load shaders (textures), skeleton, morphs, labels for GUI, BBoxes, Vertex groups, joints, proportions, measures file and the presets. The new version of MB-Lab will store the /data/ directory as well.

It would be tedious to explain all lines here, as they are self-explanatory. But they are all needed for the engine. However some of them can be empty, the engine won't crash, but features won't work either.

Important note : As a model (in the blend file) is the base for many characters, the engine cuts data like this :

• the shape of the model is in the blend file, to let know the relative position of vertices/faces/and so on. But that's all, the location of the vertices is not stored here. However, the tongue and eyes are stored here and used as is.
• The IDs of the vertices are stored in a whatever_polygs.json file, and store all ID for the body, and only for the body. Teeth, tongue and eyes are not used to define a body (Asian, Caucasian, ...)
• Each body type (African...) has its own json file, with the location of each vertex (x,y,z) but without the ID, because each ID in the polygs.json file matches the coordinates of each vertex.
• So you can have big differences between an African body and an Asian body, even if the base model is the same. That's why there are 2 families of morphs, the one which can be used for any body types, and the ones that can be used for one specific type. See dedicated documentation about morphs.

[TetoTheSquirrelFox]

Example of a minimal config file

{ "templates_list": [ "human_female_base" ], "character_list": [ "f_ca01" ], "human_female_base": { "description": "Generate the human female template", "template_model": "MBLab_human_female", "template_polygons": "human_female_polygs.json", "name": "human_female_base", "vertices": 18210, "faces": 17288, "label": "Human female" }, "f_ca01": { "description": "Generate a realistic Caucasian female character", "template_model": "MBLab_human_female", "name": "f_ca01", "label": "Caucasian female (F_CA01) (AGPL3)", "texture_albedo": "hum_f_cauc_albedo.png", "texture_bump": "human_female_bump.png", "texture_displacement": "human_female_displacement.png", "texture_eyes": "eyes_albedo.png", "texture_tongue_albedo": "human_female_albedo.png", "texture_teeth_albedo": "human_female_teeth.png", "texture_nails_albedo": "human_female_nails.png", "texture_eyelash_albedo": "human_female_eyelash.png", "texture_frecklemask": "human_female_frecklemask.png", "texture_blush": "human_female_blush.png", "texture_sebum": "human_female_sebum.png", "texture_lipmap": "human_female_lipmap.png", "texture_thickness": "human_female_thickness.png", "texture_iris_color" : "iris_color.png", "texture_iris_bump" : "iris_bump.png", "texture_sclera_color" : "sclera_color.png", "texture_translucent_mask" : "translucent_mask.png", "texture_sclera_mask" : "sclera_mask.png", "morphs_extra_file": "", "shared_morphs_file": "human_female_morphs.json", "shared_morphs_extra_file": "human_female_morphs_extra.json", "bounding_boxes_file": "human_female_bbox.json", "proportions_folder": "hu_f_anthropometry", "joints_base_file": "human_female_joints.json", "joints_offset_file": "human_female_joints_offset.json", "measures_file": "human_female_measures.json", "presets_folder": "human_female_base", "transformations_file": "human_female_base_transf.json", "vertexgroup_base_file": "human_female_vgroups_base.json", "vertexgroup_muscle_file": "human_female_vgroups_muscles.json" } }

[TetoTheSquirrelFox]

Introduction to integration tools :

By integration we mean here that after the creator has sculpted is model(s), UV-Mapped it and so on, he has to do several operations before be able to use his new model in MB-Lab as a "simple" user. The process is quite long, but necessary, and is done within several steps that can't be missed because the addon takes the creator by hand.

And an important file for this that creator must fill is the configuration file. Next steps explain how to create it.

Some reminder valid for any step from now :

• You don't have to create and fill your config at once. You always can save your work periodically.
• Most of the time you are taken by the hand, but in the same time,
• read the documentation, it's important, because it gives you information about the way MB-Lab works. And it's useful to know what's going on when you use tools.
• Most of the time, you can't choose the names you want, the place where the files are, and so on. Please don't try to change that. All buttons with a snowflake mean that the save/load/rename/... is automatic, you don't have to think about that.

Other important things to do before using the tools for next steps :

• The addon was first developed in an user point of view. It's not the case anymore, but that means that some things must be done outside the tool before trying to create a new model for it.
• The base models must be created, sculpted, UV-Mapped before integrate them in MB-Lab. This will be recalled when necessary anyway.

Step 1 :

So now, above tools for create a model from scratch, we have all related to the config file :

• 1st we can init the project and make a fresh start.
• 2nd the name of the project (in fact, the name of the /data/ directory where all files for the engine are). From there you can create most of subdirectories. Save the config file or load it (if the name is correct).
• Then you can use the tools. What is important to know here is :

1. You can have more than one model for a single project. Typically, both genders.
2. The sub-directories that are their name dependent to the model's name are created while using the tools, not when the project is initiated.
3. A special key is added to the config file and it's the /data/ directory..

On a side note, buttons here are exclusive :

• Create sub-directories can only be clicked if they don't exist (only first one is checked)
• Create configuration can't be clicked if the file already exists, so you can click on...
• Load configuration instead. The names for all these actions are automatic, user has nothing to do.

[TetoTheSquirrelFox]

Step 2 :

So, the configuration file is loaded. For the moment it's empty. The first thing to do is to load the model where all base models are stored.

• One blend file is permitted by cong file. It must have bodies, skeleton, lights eventually. For this example I took the base project file.
• Important : The blend file MUST be named projectName_library.blend, otherwise the button is inactive. And it must be placed in /data/ directory, not in project directory. So here for the example, the name is try_library.blend.

So if you click the button, all objects in the file show up, and you have access to the tools needed to construct config file. All objects are visible in the collection. And when you change the project, or use MB-Lab as a simple user, the collection and its content are deleted.

Important notes about the blend with model(s) :

• It can have all models you want. And other stuff if you want. But the lighter it is, better it is.
• However, the mesh you want to use must have the same name of its parent. Example : This is not good, because there's a typo, so the names are not the same. It's not allowed.
• All skin of the model must be linked, i.e seen by Blender as a single surface. Teeth, eyes, eyebrows are not linked, but all the rest must. This is not good : Head has 3 parts, it should have only one, as the rest of the body.

[TetoTheSquirrelFox]

Step 3 :

When models are loaded, the 1st thing to do when the config file is empty, is to name the templates :

1. The templates are the base models that MB-Lab uses to make the body types and gender as African male or Asian female. There's no template for the moment, so we create them.
2. You choose the name, the gender (undefined is possible). Again, the final name is automatic and has rules, so parts of it can't be changed.
3. One template for one base model, no more. You have 5 base models, you can create 5 templates at most.
4. Then it's done you can choose the template in the upper drop-down list. If you want to delete it, it's can be done in the next step. When you choose a template, a list of information to give appears, that defines completely the base model as a template for later models like African, Polynesian... (next step)

[TetoTheSquirrelFox]

Step 4 : The template

So now that the template is created, there are several information to give. The main concept to know here is when an information is known, it's displayed as a label with a checkmark icon. Here, for example, without having entered anything, the number of vertices and faces are already knwon because the drop-down list for base model shows 'MBLab_human_male". if we change it by "anime male", the values are changed. Note : The base model is in a drop-down list. When the content is saved, the list is changed by a simple label.

So the the creator has to give the information.

1. A button to delete the template. No undo !
2. Label : A short text to present the model. Be short !
3. Description : A longer description, that is shown as a tip.
4. The model to use that is stored in the blend file. IMPORTANT : One model for one template. If a model is used by a template, it can't be used for another template. NOTE : if your model disappears when you choose it (therefore you can't select it anymore), it's because the name of the mesh is not the same of its parent in collection. And it's case sensitive : "My_Model" is not identical to "my_model".
5. The directory where all (except config and blend files) is stored, as the morphs, the materials, shaders, and so on. It's the name of the "project". Here it's 'try'.
6. Tool that creates a list of indices that are always used by body types (as Asian, Caucasian). Here it's just the ID of vertices. The vertices for each body type are stored elsewhere and are without ID. The tool for body types is explained in next steps.
7. The number of vertices that the model has. The engine checks that later to be sure that it uses the right model. Automatic.
8. Same for the faces/polygons. Automatic. After that you have 3 buttons.
9. Delete content (but not the template).
10. Save the template. When saved, the UI changes. Example : Here, there's just the indice file that is not created yet.
11. Save configuration. The content is saved on file.

Note : When you check the content of all your templates, don't hesitate to click on "save template" for each template you're checking. Because by construction, data that are filled automatically, are not stored in the config automatically. You are sure of that by clicking the button. When the check is done, don't forget to save the file.

Next step, a tool for doing the same thing (basically) with body types. But be sure that all templates are done before going to the next step.

[TetoTheSquirrelFox]

Step 5 : The character

So now that we created all templates we wanted from the base models in the blend file, we have to create characters from them.

The creator has now to choose "Character creation tools". Then he basically has the same workflow to create his character :

• He starts by creating the name (see below for rules)
• Then he chooses the name he just created in the the dropdown list, then he has a bunch of files/folders to choose (next step).

Rules :

• For the name of character, it must be a 4 letters name; like as01, tt55 and so on. Shorter names are valid, but prefer 4 letters.
• By convention, the first 2 letters describe the body type : as for Asian, ca for Caucasian and so on. Then there are 2 numbers from 01 to 99 for obvious reason. These are not strict rules, but comply with it is better for clarity.

[TetoTheSquirrelFox]

Step 6 : Character content

Here is the most tedious part of the tool. As you have seen during the previous step, you have a bunch of items to fill in. Especially textures for shaders. Until the engine works another way, you have to fill up all dropdown with texture files stored in their dedicated directory.

So, before talking about the tool itself, few things to know :

• Morphs are their own directory (see documentation about making your own morphs for more details). Textures have their directory too, as joints, BBoxes and so on. Same thing about the 2 folders that have to be filled in. But some files have to be created outside MB-Lab, other don't. Here is the list :

1. Files that can be made with MB-Lab tools : Morphs, Measures, Transformations.
2. Files that have to be created outside MB-Lab : Textures.
3. Files that have to be created outside, but are transformed with internal tools before using them : BBoxes, Joints, VGroups.
4. The name of folder must be chosen during this step, and is stored in the config file, but the folder itself is physically created when files inside are created by MB-Lab's tools.

• The fill of this step can be long and tedious. But, as the other tools, it's not necessary to have all files created/known. But if you start a session, and then you decide to change some values, if you click on "delete character content", all values will be deleted and you'll have to fill in all values again.
• So, when you don't know a file, or you are sure to change it soon, let the dropdown list to "Unknown". This way, each time you start a new session for this character, you'll be able to choose a file.
• The exception for this is when you make changes during the session, for the same character. The dropdown lists keep in memory the last file shown. So if you validate the list, and decide to change it just after, no problem, you won't have to refill everything.

So, what's going on here :

1. Label + licence : gives a label shown when using the character. Here (F_AF01) is automatic, you don't have to write it.
2. Description : A long description of the character (as a tip for label).
3. Next, the base body to choose, as for the templates.
4. /data/ aka the project's directory, is automatic.
5. Next the files for the morphs. See documentation for the tools for creating morphs for more details. Here are the files for whole gender, aka files that can be used by all characters with the same base model. The files don't have to be created yet. Let "unknown" if necessary. Directory : /data/morphs/
6. All textures for skin, eyes, nails and so on. Depending of the shader used for rendering, sone of them may not be used. "Unknown" is good for these cases. See documentation about shaders for more details. Directory : /data/textures/
7. BBoxes : See documentation about the dedicated tool for more details. Directory : /data/bboxes/
8. Base joints and Joints offsets : See documentation about the dedicated tool for more details. Directory : /data/joints/
9. Measures : See documentation about the dedicated tool for more details. Directory : /data/measures/
10. Transformations : See documentation about the dedicated tool for more details. Directory : /data/transformations/
11. VGroups base and muscles : See documentation about the dedicated tool for more details. Directory : /data/vgroups/
12. Presets folder : Choose the folder where the presets will be stored. The name is the same as the template. Directory : /data/presets/named_folder/
13. Proportions folder : Naming is automatic. Directory : /data/anthropometry/named_folder/

Don't forget for each character to "save character" and 'save configuration" when you add/change/check things.

The configuration file is done.

The creator has to do more to be able to use his model in the engine. But it's a good start. Next we'll see tools that transform things done outside MB-Lab but done in Blender (BBoxes, skeleton, ...) and how to import them in the engine.

[TetoTheSquirrelFox]

This post is not a post for documentation, but explain the process the way I figured how bboxes files work. Maybe I'm wrong or I miss something, feel free to comment on the subject.

I didn't understand at first what's going on, so I did some reverse-engineering to try to understand.

What is the subject ? Every character (m_ca01 for example) has a bboxes file attached to it, under /data/bboxes. But when is it used ? If we open a file, it's a dictionary with integers as keys, and 6 others integers as values. Sometimes some values are in double. The key is obviously a key for a vertex, an edge or a face. As edges are never used or stored in MB-Lab, it can only be an index for a vertex or a face. I searched where/when/how is used the file, and I discovered that it's used only by morphs, and only when morphs are changed to shapekeys, when the character is finalized. And the function is to correct the shape of the morphs during the finalization process. And actually the only morphs that use this correction are the expressions, as they are the only ones which are changed in shapekeys.

So I didn't know what to think first. Let's take an index and see what we get (The file is human_female_bbox.json): In the file: "1333": [2173, 1643, 7570, 16412, 7533, 1319] But if we select the given indices we get : That does not make sense. The indices are not in place where we could guess (if you try with other vertices it's sometimes worse, you can have a vertex in the back of an eye), no symmetry, no obvious distribution or distance with the index, and so on, you name it. Other vertices give the same kind of thing, sometimes worse, and try to select edges or face is way worse (you can select a face in the right foot...)

The last thing to do is to compare with morphs themselves, as bboxes are used for them. So I searched where the index is used (here it's 1325):

• found in : ['Neck_Angle_max', 'Head_SizeZ_min', 'Pelvis_Length_max', 'Legs_LowerlegLength_min', 'Head_SizeX_min', 'Chest_SizeZ_max', 'Chest_SizeZ_min', 'Head_SizeY_min', 'Head_SizeZ_max', 'Neck_Length_min', 'Head_SizeX_max', 'Pelvis_Length_min', 'Head_SizeY_max', 'Torso_Length_max', 'Head_Size_min', 'Body_Size_max', 'Body_Size_min', 'Head_Size_max', 'Legs_UpperlegLength_max', 'Neck_Angle_min', 'Legs_UpperlegLength_min', 'Torso_Length_min', 'Legs_LowerlegLength_max', 'Neck_Length_max'] I don't explain what the names mean but it pretty straightforward to understand. Then I decided to do the same thing for the 6 indices attached to 1325 in the bboxes file.

And I got it (here the result with 1292):

• 1292 : ['Neck_Angle_max', 'Head_SizeZ_min', 'Pelvis_Length_max', 'Legs_LowerlegLength_min', 'Head_SizeX_min', 'Chest_SizeZ_max', 'Chest_SizeZ_min', 'Head_SizeY_min', 'Head_SizeZ_max', 'Neck_Length_min', 'Head_SizeX_max', 'Pelvis_Length_min', 'Head_SizeY_max', 'Torso_Length_max', 'Head_Size_min', 'Body_Size_max', 'Body_Size_min', 'Head_Size_max', 'Legs_UpperlegLength_max', 'Neck_Angle_min', 'Legs_UpperlegLength_min', 'Torso_Length_min', 'Legs_LowerlegLength_max', 'Neck_Length_max'] Exactly the same morphs (there's an exception with one index), and it's the same result for the 5 others. All indices attached to 1325 share the same morphs.

I tried few other indices and it worked perfectly (with few exceptions). Sometimes indices are doubled for a reason I didn't discovered yet. The only thing I have to figure now is that the 6 indices are not the only one that are in all shared morphs, so what is the rule here ? The indices/points are the most far from 1325, are the most close ? In the middle ? I have to check that.

But then I tried some vertices on hands, feet, and then nothing, they are not used in the file. So I decided to select all indices stored in bboxes file, and I got this : The bboxes file is only used for these parts of a body.

So what I understand so far :

• The bboxes is a concept developed by MB, but is used only for expressions (maybe I'm wrong). Was it the intention since the beginning ? I don't know.
• It's about the main morphs, the one used by all gender, not the ones dedicated to characters.
• That means that if user adds morphs for whole gender, it should recreate the bboxes files.
• That also means that for the tool I'll code, I need ask for vertices the creator want to use. By selecting directly the vertices ? By vertex painting ? Please tell me what you would use for this task.

[TetoTheSquirrelFox]

Step 7 : Measures files

Before explaining the tool, few explanations. Measures files, stored under /data/measures are used for many things :

• Measuring the body of a character, like its height, the girth of its neck and so on.
• Create general proportions of a model from measures given by the user.
• Create random models by randomizing these measures.

An important note :

• The file is a collection of keys/values (see below for details). The keys don't change, only their value.
• The keys are "hard-coded" i.e are used in other parts of the addon, like morphs. That means that for morphs, some of them must have a given name, whatever is the model.
• That means that for the moment, the addon can't be used "as is" for animals, and non humanoid creatures. Winged creatures would be OK, but without the need of measuring the wings for a reason.

How and when can creator use this tool ?

• After creating the config file, at least, because some elements must be known to use the tool.
• Its name is "Create measures template" and is available when the config file is created and base models / character template are entered :

Things to do to use it : The way Blender is working needs few things to do before using the tool.

1. The base models are shown (see doc about previous tools for details) but user need to be in edit mode to use some tools. It's the case here, so toggle on "Allow edit mode".
2. When the tool is chosen, you can choose the character template to work on. Even if it's already visible since the beginning, choose it again. That hides all bodies except the base model for this character.
3. The character is active and has a red silhouette (see below) : Click on it : the color becomes orange and now the model is selected. It's important because you can create measures only if the model is active AND selected.

Example : 1st image, the model is not selected. Topics "2points", "Girth", "Weights" are inactive and addon asks to click the model : Now the model is selected, creator can now use the topics :

When all that is done you can start using the tool. First, the creator must create the file. The file itself has strict rules, and is (in Python terminology) a dictionary with 4 keys :

• body_height_Z_parts : the parts concerned by measures. Don't change, and creator must not change the content.
• measures : content that can be changed with all points needed for measures.
• relations : relations between names given for measures and their counterpart as morph name. For example, measure "chest_depth_Y" corresponds to "Chest_SizeY_min/max" in morphs. This topic can't be changed.
• score_weights : The weight of body parts for the computation of measures.

The process to create the file is automatic and can be done after the creation of the config file. When filling the config file with the dedicated tool, let "measures file" on "unknown". So when you start the measures tool you have this : So, for the character f_af99 you can either choose a known file in a list, or create a new one ("other")

Here we'll choose an existing one : Since it's chosen (human_female_measures.json) you can :

• check inconsistencies. It's a really basic tool that reads the file and seeks if it's a valid one. Very basic. But useful when creator is not sure. The name and location of report is shown below the button.
• In the bottom the creator can also save the config file, needed if he created the file or has picked one in the list.

When it's done (if necessary), the creator must :

• Choose again "f_af99" on the top to hide all models but the one used by the character template.
• Click manually on it to set it active and selected.
• Then he can create points for measures ("2points" and "girth") or weights ('Weights").

(Next : see below)

[TetoTheSquirrelFox]

Now the model is active, selected and the measures file is known/created. From there, you have 3 topics to fill : 2 points, girth and weights.

• 2 points : a distance, between 2 points for a measure. The width of a foot, the height of the character and so on. Sometimes the points are symmetrical (shoulders width for example). Complete list : "upperleg_length", "buttock_depth_Y", "buttock_width_X", "lowerleg_length", "head_height_Z", "feet_length", "feet_heel_width", "torso_height_Z","shoulders_width", "feet_height_Z", "head_width_X", "chest_depth_Y", "forearm_length", "buttock_height_Z", "hands_width", "hands_length", "upperarm_length", "feet_width", "body_height_Z", "neck_height_Z", "head_length", "chest_width_X" No particular order. These names are automatic and created when you create the file. Always create the file from the tool.
• Girth : The girth of body parts like upper leg, the neck. No symmetry here, as a girth of the left arm will be the same for right arm. Complete list : "wrist_girth", "upperarm_axillary_girth", "neck_girth", "lowerleg_bottom_girth", "lowerleg_calf_girth", "upperleg_top_girth", "waist_girth", "elbow_girth", "upperleg_bottom_girth", "chest_girth", "buttock_girth". No particular order. These names are automatic and created when you create the file.
• Weights : Some parts are more important for internal computations, so they have more "weight" than others. For example the top of the upper leg is more important than the width of the foot. So the first will have a weight of 3 (the maximum) and the second will have 0.5 (the minimum). Write all parts would be tedious, and are created/filled with standard values automatically. These values are the ones used for original models. Except if the creator really knows what he does, I suggest to let the standard values.

So how to change the values ?

Important note : When you select points, only the last one can be saved and used by python. It's how Blender works. So if you want to select 5 points and save them, you have to select and save each point. Select, save, select the other, save it, and so on.

1. 2 points. (reminder, you must be allowed to go to edit mode, the model active and selected). The first line is a a label where you see the current measure in memory. Show points : Allows you to see the points on the body. Prev(ious), Curr(ent), Next : Put in memory and shows (if "shows points" is selected) previous, current or next '2 points'. Example : If no point is filled, nothing is shown. Now, if user wants to change them, he can use these buttons :

• Add : Add the last selected point by the user. If 2 points already exist, the first is deleted and replaced by the 2nd.
• Show sym : When you select/save a point, you can highlight its symmetry. Careful, even if it's highlighted (the point is orange), it's not selected. You have to select it manually (the point is white), then you can save it ('add').
• (X) Last, (X) Selected, (X) All : Delete last point, the one you selected manually, or all points.
• Recover all points : Recover the '2 points' from last save (in file). See documentation below about all '2 points' pictures for the original models.

2. Girth. More or less the same thing for adding/changing points for the girths. Here an example with the neck : You can see that you don't have to save all points around the neck. A girth doesn't have to be perfectly exact. Other thing important, a girth starts by a point, and finish by the same point. But you don't have to select it when you finish, it's automatically done when the file is saved. All buttons have the same function as '2 points' (no symmetry). But you have to select all points in the order. The girth is calculated by the order of selection. See documentation below about all 'girths' used in the original models.

3. Weights. At first you have this :

That means that you have to refresh the values first (again, it's because how Blender works). Click on "recover last save". This button can be used each time you want to recover last saved values (in memory). You can now change the values. The changes are saved (in memory) each time you click on "save all weights". Again, if you don't know exactly what you do, let the standard values. Those values are used for the original models, and always saved when you create a measures files with the tool.

Finally you can save your work on file : Save configuration ; If you have created/filled the measures file with this tool, and not when you created the config file, you can save the measures file name here. Save measures file : Save the measures file itself. For both saves, the location is automatic, user has nothing to do, the user has already filled the names.

Note : You can't change/add any name here, as they are "hard-coded" in the morph engine.

[TetoTheSquirrelFox]

Step 8 : Morphs template.

A quick tool for creating morphs template. Morphs are used to shape a character, but are also used for topics that need to know where vertices are, like measures. So some morphs are hard-coded, their name are used in many parts of the program, and can't be changed. There are all saved in the main morphs library used by all characters from a gender. For example, all female humans in the base addon use 2 morphs files, one for "core" morphs, one for "extras". Others morphs files are used too, but are specific to phenotypes (like Asian). The "core" morphs files contains many morphs, but also the ones needed for the engine to work properly.

So this tool make a template file with all needed morphs. It's very simple, as the morphs in fact do nothing, and user/creator will have to change their content with proper morphing. Example: "Elbows_Size_min": [[1, 0.0, 0.0, 0.0]] This is the morph for the size of elbows (at its minimum). There is just one vertex, index N°1, with zero displacement of the vertex. Creator has to sculpt this size later.

To create the file, user shows "Create morphs template" under "Model integration".

Then he must select manually the character he wants to work on. The base model for this character is showed, the others are hided. You have 3 things that can occur :

1. The name of the the morphs file is already known ; user has already filled the name when creating the config file, In this case, the file can be checked, and if some needed morphs are absent, a warning is shown.
2. The name is not in the config file, but user chooses an existing file in the list. Same as N°1 after that.
3. The file has to be created. The user can fill a name, and create the file (below). The main morphing name must be "unknown". The complete name of the file is shown. The user can create the file. It's saved automatically at the right place.

When the file is created or chosen, user can save the config file, but also check if the file has necessary morphs for working. If "Check Morphs File" is clicked, a .txt file will be created (the name here would be "human_female_morphs.json.txt") with the result.

The template is created. To change, add or delete morphs, 3 tools exist, for simple and combined morphs:

[TetoTheSquirrelFox]

Step 9 : Joints and offset templates

A tool that is directly related to skeleton and animation because this toll creates joints and offsets for them, in two separated files.

First, the basic skeleton available with MB-Lab in the base package, is a skeleton very outdated in many ways. Animation, type of skeletons, all that jazz are changing fast as the games engines, animation engines and so on, are improving constantly to give better technics to animate the characters. That said, MB-Lab was first developed in an user point of view, where users can develop only few things. Now user can also be a creator and able to create a whole character from scratch. Thereby, skeleton system should be able to change to fit new technics, needs (game, animation, ...) without need to change the program. For this purpose, MB-Lab provides this outdated skeleton system, that the creator must adhere, in order to let other skeleton systems to do their stuff without problem. Of course, since these two templates are created, the creator can add his own skeleton system ; but this way, his character is assured to work well in the engine and be easily adapted for other systems.

Le skeleton system in MB-Lab works works with 4 things :

• A base skeleton.
• A skeleton for muscles (see dedicated documentation).
• A joints file.
• An offset file.

These 2 files have to be created, as they manage the base skeleton.

1. The joints file. It's a file where the locations of the head and tails of for for skeletons, base and muscle, are stored. But the location is not stored itself ; instead vertices indices for a specific joint are stored, and the geometric center of those vertices (in red on the picture) is the location of the joint. As this point changes due to the morphing of the character, it's dynamic, so it's the vertices that control the position are stored.
2. The offset file. Sometimes the joint is used for inverted kinematics. This file allows to offset it in order to place the command. (the icosphere circled in green)

The tool for these 2 files drives the creator a lot, as the names can't be changed, as the number of bones. Again it makes adaptations for other skeleton systems easier.

So, how does it work ?

The beginning works exactly like the measures tools :

• You must allow to be in edit mode.
• You choose a character you want to work on (here f_af99).
• You choose it in the drop-down list, and click manually the model to active it.
• The tool already knows the file, or you have to fill the name or create the file.
• When it's done for joints base file, do the same for offsets :
• Now don't forget to save the config file if it's OK for you :
• Now the tool as 5 parts to work with : Note : When the 2 files are created, don't change anything manually ! Change with this tool.

1. Part in blue : Allows you to filter quickly the names in the data base. You can also use the string field to filter the part you want (like arm for example).
2. Part in red : As measures file tool, you can show all joints stored in file. Here the toll shows 2 things : the vertices, and the geometric center of the points. The center can't be selected manually, you don't have to anyway. See documentation for a list of all joints and the vertices selected in the base model.
3. Part in yellow : Like measures points, you can add, delete or recover vertices here.
4. Part in pink : Same tools to show offset point, except few things.

• Many joints don't need offset, so you don't have to create it if you don't have to.
• When you create it, an icosphere is created, and is located in the center on the center point (wich is an uvsphere). You can then go in object mode, place it where you want, then return in edit mode, then press 'Set point' to save the location in memory (not in file, there's a special button for that)
• If you delete the point you can recover it with the "Reco." button. But careful : Il you go to another joint, and come back later, you can't recover the offset from the file.

5. Part in green : You save your work in file. One for the joints base, one for the offset.

[TetoTheSquirrelFox]

Step 10 : VGroups

Now that the bones and joints are done, you have to apply weights on them, in order to have proper deformations in animation. This is done by vgroups, which keep the weight of each vertex in the group. There are two types of vgroups :

• For bones, named name_vgroups_base
• For muscles, named name_vgroups_muscles They are all available in /data/vgroups/ folder. Each type has its dedicated file.

As the previous tool, creator can't do what he wants, and there are guidelines to create vgroups. The main one are the names, that must fit the names given to the skeleton (and joints).

This tool has a slightly different approach, as the creator will actually use Blender to create the weights, then after the work is done, save the file with the MB-Lab tool.

What is the workflow ?

1. First, allow to use other modes, then choose "Vertices groups tools"
2. Then he has a drop-down to choose the character, and if it's for base or muscles.
3. The workflow to create or assign a file is the same as for previous tools. It's important to note here that creator must use this tool before create or change weight-paint of the character.
4. When the file is created and assigned, the creator can go to weight mode.
5. The name of vgroups is available under "Object data properties" Blender tab (along shapekeys) You can see that each name starts with base_ (or mscl_). That corresponds to the types of vgroups, one for base bones, one for muscles. It's because same names can be used for base and muscles. They are created automatically, and deleted when they are saved on file.
6. Now the creator can do his stuff, then when he has finished he can save his work. There's one button for each type.

[animate1978]

I have yet to fully test the new tools and to create the documentation for this so I don't know just how well they work.

[RegulusFen]

This is very exciting, I seem to have an issue with the load models file option, I have made sure to name the project blend library exact and placed in the data directory, I have tried several different names yet nothing is opening when I press the Load models file , I will post in discord with screen shots.

Edit: above is answered here - https://discordapp.com/channels/541724621398081546/555593306982187057/746980171357093918