Simplicage Documentation
Simplicage is a Blender addon to quickly generate physics-ready (through Blender cloth physics) cages for your models.
Main features
The main features are the following.
Generation of physics-ready cages from mesh and bone selection
Generation of collision boxes from mesh and bone selection
Presets system, with some available by default for most common applications
Tool to manage available cages, and quickly bake them
Requirements
Blender 3.2 or above (Blender 3.1.x or older versions are not supported)
Contents
Versions
There are 3 different versions of Simplicage. The features available in each version are summarized in the table.
Free Version
This version can be used to create fully working physics cages, as well as collision boxes. However, you are limited in creating cages only starting from single bones.
Lite Version
The Lite version provides all the Free version features, with the additional possibility to create cages from a multiple selection of bones. See the documentation part about Modes for more informations on this feature.
Pro Version
In the Pro version you can create a cage from any vertex group, even if an Armature is not available for the Object you want to create the cage from. See the documentation part about Modes for more informations on this feature.
Installation
In this section you will be guided in the process of installing/updating Simplicage as an add-on.
Install
The installation of the model should be done through the Blender preferences.
Note
Before proceeding with the installation, be sure to install the latest Blender version.
In particular, the addon is compatible with Blender 3.2.x or newest versions. We can not provide any support for installing Simplicage on earlier versions.
Note
Do not unpack the .zip file before installing the addon. Select directly the file you download.
The steps are the following.
Open Blender Settings.
Open the Add-on tab and click on the Install… button.
Select the file Simplicage.zip.
In the Setting window it should now appear the Simplicage addon. Enable it clicking on the check button.
Restart Blender.
You can now start using the addon. Go in Viewport and press N: you will enable the tabs on the right as in the image. Search for Simplicage and start using the addon!
Updating
If you are updating the add-on, please follow again the guide before. Be sure to restart Blender before using the new version of the add-on.
Note
While updating, the Setting window might not automatically select Simplicage. Simply search for Simplicage with the search field to quickly find the new version of the add-on, and check if it is enabled.
First cage
In this section we create the first cage with Simplicage!
The quick cage setup requires only a couple of very simple steps:
Open the Simplicage tab (see Installation if the tab is not available)
In the Simplicage tab, firstly select the Mesh Object from which the cage should be generated.
Select a bone of the armature whose Mesh Object is the one selected in the previous step.
Click on Create Cage.
More advanced options to customize your cage generation are available at Settings
Modes
Cage Modes
In this section we list the different cage modes available on Simplicage. Note that you might see less modes depending on the version you are using. Check the documentation part on Versions for more information.
Select one option to choose the method with with you want to select the region to generate the cage from.
Single Bone
The Single Bone mode creates a cage for each of the selected bones.
For instance, if we select one bone we obtain the single cage for the selected bone.
While selecting more bones, the addon will create a cage for each selected bone.
Chain (Lite Version and Pro Version)
This mode generates a unique cage for the selected bones, instead of one for each bone.
Note
If only one bone is selected, Chain mode will be automatically disabled when you generate the cage.
Vertex Group (Pro Version)
This mode generates a cage from the Vertex Group of the Mesh object selected. This mode works also on Objects that are not driven by an Armature.
Physics Modes
In this section we list the different Physics modes available on Simplicage. Select one option to choose which kind of physics to apply to the cage.
None
In this mode, a cage without physics is generated.
Cloth
In this mode, a cage with cloth physics is generated. It will also be bound to the Mesh from which it has been created.
Clicking on the generate cage, we can also change the cloth physics settings in the object Physics Options.
Collision Box
This mode will create a collision box instead of a cage for physics. This means that cages will collide with this collision box.
Note
When creating a collision cage, better results might be achieved disabling the Remesh option and the Close Cage Mesh option.
Clicking on the generated collision box, we can also change the collision settings in the object Physics Options.
Settings
Cage
Coverage
This option controls how much of the selected bone vertex group is considered when generating the cage.
In the example, the vertex group on the sphere of the selected bone is shown. It has non-null values on the whole spehere. Therefore a coverage of 1 will create a cage covering the whole sphere. When selecting 0.5 instead, we cover half the sphere.
Coverage = 1
Coverage = 0.5
Re-size Scale
Re-size Scale is the factor with which the final cage is rescaled using the cage Origin to Center of Mass (Surface) point as the origin.
Note
We advise to use a value slightly bigger than 1 for physics cages, and a value of 1 for Colllision cages.
Warning
If the mesh is complex, the rescaling might be not perfect due to the choice of the origin. While this is not an issue when using Surface Deform binding option (see below), it might be a problem when using Mehs Deform as the cage might fail to enclose the whole mesh. In this case, small manual tweaks of the mesh might be needed.
Re-size Scale = 1
Re-size Scale = 1.05
Close Cage Mesh
With this option you can choose to close the mesh, and the method to consider.
Note
When creating a collision cage, better results might be achieved disabling the Remesh option and the Close Cage Mesh option.
Note
We advise to change the method only if errors are generated during mesh creation.
Close Cage Mesh disabled
Close Cage Mesh enabled
Remesh
Remesh enables the possibility to remesh the generated cage. This in general will provide a nicer topology if you use Close Cage Mesh.
You can also use the Resolution setting to increase the number of vertices of the generated cages. Be aware that high resolutions can slow the simulation.
Finally, if some errors appears during the cage generation, you can also try to change the Remesh seed.
Note
When creating a collision cage, better results might be achieved disabling the Remesh option and the Close Cage Mesh option.
Remesh disabled
Remesh enabled with Resolution 900
Note
Even if the remeshed cage seems to have some problems at the boundary, it is perfectly fine and will not generate problems during the simulation. In fact, the remeshed mesh will behave better in general, due to the nicer topology, with respect to the non-remeshed one.
Clean Selection
This option improve the selection of the vertices used to generate the cage.
Clean Selection Threshold (Pro Version): in the Pro Version you can adjust the Clean Selection Threshold to try to fix some cage generation errors.
Note
If you are using the Free or Lite version, and the generated cage is not enclosing the whole mesh, disable this option. Otherwise, with the Pro version you can try to increase the Clean Selection Threshold.
Smooth Correction
With this option, a Smooth Correction modifier will be added to the cage to smooth the simulation. You can disable it after cage generation as usual, in the Modifier tab of the Cage object.
Pin Groups
Pin vettex groups define which parts of the cage will be affected by the cloth simulation, and therefore which parts will actually be moved. In the vertex groups, each vertex has a weight assigned. In the case of pin groups, when the weight is 1, the simulation will not act on that vertex; on the contrary, a null value means that the vertices will fully partecipate in the simulation. In between values can be useful to smooth out the transition between pinned part (weight = 1) and simulated parts (weight = 0).
In the images below, 0 values are depiced with blue color, and 1 values are depincted with red. Green/yellow color depicts in between values.
Use Proximity Data
With Use Proximity Data, the cage pin group will be generated setting weights to 0 for all vertices that are near the cage mesh. Higher values of the factor can be used to increase the distance.
In the following example, None normalization is used.
Use Proximity Data disabled
Use Proximity Data enabled with default factor 0.02
Use Proximity Data enabled with max factor 0.2
Normalization
The normalization options are used to normalize the pin group weights. Most of the time, tweaking this setting might be the key to achieve good pin groups and therefore nice results.
The normalization functions, and effects of different normalization functions on a simple example, are the following. All of the following examples weights are computed with Use Proximity Data enabled with default factor.
None normalization
\(Norm(w = \text{weights}) = 0\)
This function effectively set all weights to 0. If Use Proximity Data is disabled, the pin group would be all null. If enabled like in the figure, you still get a nice pinning on the part flat part of the half sphere.
It is useful to create simple weights, or without Use Proximity Data when we want to create a cage that is not pinned. In the latter case, the whole mesh will be simulated and it will interact with collision objects.
Linear normalization
\(Norm(w = \text{weights}) = w\)
Square normalization
\(Norm(w = \text{weights}) = w^2\)
Sigmoid normalization (default values)
\(Norm(w = \text{weights}) =\frac{1}{1 + \exp[-\text{f}*(w-\text{s})]}\)
Tanh normalization (gain 0.8 and min 0.2)
\(Norm(w = \text{weights}) =\tanh(\text{g}*w) + \text{m}\)
The gain g amplifies the vertex weights of the selected bone(s) and applies it to the newly generated cage, while min m is the minimum vertex weight that will be used.
Arcsch normalization (gain 1. and min 0.)
\(Norm(w = \text{weights}) = 1 - \tanh(w/\text{g}) + \text{m}\)
Note
Mathematically, we are normalizing the cage pin group generated from the inverted bone group of the parent mesh, using the selected normalization function. We do this using the normalization function as value of the weight instead of the value of the weight itself.
For those interested, you can plot these functions with Desmos.
Parenting
Deform Method
Different methods to deform the mesh with the cage are available.
Surface Deform
The default option, which in general provides better results and support parenting of the mesh with the armature. Therefore with this option the cage will firstly follow the armature bones, and then evaluate the physics simulation.
Mesh Deform
This option can be selected if the Surface Deform binding keeps failing. It only support single bone parenting methods (see below).
Parenting Method
If Deform Method is choosen to be Mesh Deform, this option is available to choose parenting.
Bone parenting
The cage will be parented to the bone with standard Blender parenting. Inverse transformation will be applied.
ChildOf
A Child Of modifier will be used for parenting.
Fix Influence
Fix Influence creates a better influence group (the group used to defined with parts of the mesh are influenced by the cage in the Surface/Mesh Deform modifier) for the mesh.
If not enabled, the bone group will be used instead.
Note
We advise to always keep it enabled, with default factor.
Fix Influence disabled
Fix Influence enabled with default setting
Smooth Correction
With this option, a Smooth Correction modifier will be added to the mesh to smooth the simulation. You can disable it after cage generation as usual, in the Modifier tab of the mesh object.
Cloth Physics Settings
In this section you can select the preset to use.
Some are available by default. To create new ones:
Change the cloth settings of the cage
Press on + button near the preset list
Choose a name and Create
Then you can call a preset just selecting it from the list. To delete a preset, click on the - button.
Note
You can also generate a cage without physics, disabling Apply Physics.
Manage Cages
In this window you can manage the cages/collision boxes that are on the scene.
Note
This window is available only if at least one cage/collision box is available on the scene.
Cages
This part lists all the cages available on the scene.
With the buttons you can show/hide in viewport (by default cages are always hidden in Render), and enable/disable physics simulation, each cage/collision box independently. Moreover, the X button deletes the cage from the scene and its mesh data.
Presets
In this section, you can change the preset for the selected cage. See Cloth Physics Settings for more informations about how to create or delete presets.
Global Cache
In this section you can bake the physics for all available cages. You can choose the initial and final frame, and with the double arrow button you can synchronise those values with the current initial and final animation frames values.
Note
All generated cages will consider these values as initial and final frames for physics computation. Changing these values will change the value of all Simplicage cages, but not other physics objects you have in the scene.
Warning
Before chaging intial/final frame values or baking, it is advised to Delete All Bake. This will prevent issues related to already baked cages.
Examples
General tutorial (advanced)
In this tutorial we show how to use the add-on, in particular showing some advanced functions and some manual tweaks that might help improve your animation physics results.
Hair physics (with bones)
In this tutorial we show an example on how to generate quick hair physics on a mesh with bones. We use Bone Dynamics for the bone physics, and Simplicage to generate the collision cages.
More tutorials will arrive soon!
Troubleshooting
Errors
Error: An error occurred while remeshing. Try to re-restart Blender and re-try.
This error appears because of Blender remesher. We are working on a solution, for the moment the workaround if this happens is to save the file, close Blender and re-try.
Error: An error occurred while binding the mesh. Try with different Coverage and Resolution settings, or change Close Cage Method.
This error occurs because Blender can not bind the generated cage with the mesh. Try the following: * Decrease Coverage by steps of 0.05 * Increase/decrease Remesh Resolution by steps of around 100/300 * Change Close Cage method * Change Deform method to Mesh Deform. Use this only as last resource, as this method has some limitations, see Deform Method.
Physics Simulation
Cages are not simulating physics correctly.
Sometime Blender caches the physics and does not flush them when a new simulation is started. To solve most of the issues, you should go in the Physics Cloth settings of the cage and manually change the final frame value on the Cache tab. This will force Blender to consider the current cache obsolete.
Cage generation
The Create Cage button can not be clicked (it’s grey) when I select a bone.
The only bones accepted are the ones with Deform activated. This prevents generation of cages with 0 vertices.
Sometime advanced rigs use proxy bones. You might need to search for bones in other layers, to find the actual deforming ones.
Generated cages are not enclosing the whole mesh.
Try to disable Clean Selection.
Debug
If you enable the console (on Windows, press F3 and search for Toggle System Console), some debug infos will be written when the cage is generated. If an un-documented error happens, please send use the content of your console to help us fix the error.
Limitations
In this section we list the current limitations and the known bugs.
Known Bugs
No known bug is known at the moment.
Let’s hope this list will not become too long :-)
Contacts
Discord
You can contact us on the dedicated Discord server for help/bug report/feedbacks.
Twitter
You can also contact us on Twitter