Difference between revisions of "Mushroomer"
| Line 1: | Line 1: | ||
== Purpose == | == Purpose == | ||
| − | The "Mushroomer" takes a selection of editable mesh objects (the 'mushrooms') and distributes them on the surface of another editable mesh (the 'target object'). The script parents the mushrooms to the nearest three vertices in the target object. The distribution starts from a selected face (or faces), and the script uses pathing algorithms to determine which other faces receive mushrooms. The mushrooms can either be supplied by the user with shape key animation on frames 0-100, or with a set of shape keys which the script will generate an animation of smooth transitions from one shape to the next. | + | The "Mushroomer" takes a selection of editable mesh objects (the 'original mushrooms') and distributes them on the surface of another editable mesh (the 'target object'). The distributed mushroom copies are referred to as 'mushroom instances'. The script parents the mushrooms to the nearest three vertices in the target object. The distribution starts from a selected face (or faces), and the script uses pathing algorithms to determine which other faces receive mushrooms. The mushrooms can either be supplied by the user with shape key animation on frames 0-100, or with a set of shape keys which the script will generate an animation of smooth transitions from one shape to the next. |
== Status == | == Status == | ||
| Line 16: | Line 16: | ||
Currently the script is not an add-on. To use it open it in a text editor and click run script. Press spacebar to search for "Mushroomer". | Currently the script is not an add-on. To use it open it in a text editor and click run script. Press spacebar to search for "Mushroomer". | ||
| − | Both the mushrooms and the target object must be selectable, editable, local meshes. | + | Both the original mushrooms and the target object must be selectable, editable, local meshes. |
| − | + | The original mushrooms should have any rotation or scaling applied to them to avoid confusion. Their origin should be at the center of the base of the mesh. As a guide for modeling the original mushrooms, bear in mind that the origin of the mushroom instances will be placed on the surface of the target object. | |
| − | + | If you simply want the mushrooms to be distributed and not to have any animation data added, you do not need to create 'lifecycle shapes' on the mushrooms. If you want to use a manually timed animation simply create as many shape keys as you wish and animate their values. In the case of manual animation you may name the shapes as you wish. The animation of the mushrooms should be contained within frames 0-100. | |
| + | |||
| + | If you wish to use auto-animation the mushrooms need to have 'lifecycle shapes' whose names are composed of a letters only prefix followed by an integer (eg. life1,life2,life3 is acceptable. lifeA,lifeB,lifeC is not). All of your original mushrooms must use the same letters only prefix if you wish them all to be auto-animated. If you intend to have more than 9 shapes you need to use double digits throughout (eg life01-life99, not life1-life99), likewise if you intend to have more than 99 shapes you need to use triple digits and so on (eg life000-life999). It is possible to have differently numbered shapes on each mushroom, for example the following is acceptable: | ||
| + | |||
| + | *OB: tall_mushroom, Shapes: anim1,anim2,anim5,anim7 | ||
| + | *OB: short_mushroom, Shapes: anim04,anim05,anim09,anim10 | ||
| + | |||
| + | Optionally the script can add a driver to each mushroom instance to make the mushrooms bend upwards. To use this feature the original mushrooms must have a 'bend shape' where they bend up their local Y axis. The script orientates each mushroom instance with its Y axis pointing towards the world Z axis. The script can automatically add a driver to turn up the value as the mushroom instance gets tilted away from the vertical. A selection of 'bend shapes' can be created by the user. Note that the naming convention is the same as for | ||
Optionally the script can add a modifier to each mushroom instance to shrinkwrap the base (or any vertices you wish) to the target object. To use this feature you need to weight paint a vertex group in each mushroom object. This vertex group can then be selected in the script's UI. | Optionally the script can add a modifier to each mushroom instance to shrinkwrap the base (or any vertices you wish) to the target object. To use this feature you need to weight paint a vertex group in each mushroom object. This vertex group can then be selected in the script's UI. | ||
| Line 77: | Line 84: | ||
there are different algorithms for spreading the mushrooms around the surface of the target object. put briefly “splurge” grows forked paths which can cross over each other and grow any which way they want. “crossed paths” grows paths which try to avoid each other but will cross if there’s nowhere else to go. “forked paths” grows paths which fork but will never cross. “simple selection increase” is the same as pressing Ctrl+ to grow a selection. “conways” allows you to play the slowest implementation of the game of life on the face of a mesh. some of the path algorithms read the parameters here: upwards attraction makes the paths prefer to grow up, probability of fork is the chance a path will try to fork (result depending on if there is space to) at each iteration. the family wipeout chance is the chance the fork will just die out. | there are different algorithms for spreading the mushrooms around the surface of the target object. put briefly “splurge” grows forked paths which can cross over each other and grow any which way they want. “crossed paths” grows paths which try to avoid each other but will cross if there’s nowhere else to go. “forked paths” grows paths which fork but will never cross. “simple selection increase” is the same as pressing Ctrl+ to grow a selection. “conways” allows you to play the slowest implementation of the game of life on the face of a mesh. some of the path algorithms read the parameters here: upwards attraction makes the paths prefer to grow up, probability of fork is the chance a path will try to fork (result depending on if there is space to) at each iteration. the family wipeout chance is the chance the fork will just die out. | ||
| + | |||
| + | |||
| + | == Known Issues == | ||
| + | |||
| + | In general the script will not catch user errors or give warnings. As it is currently primarily an in-house tool it is not our intention to program this functionality. If you do find any bugs in the script itself or issues related to open bugs in the blender tracker please note them below. | ||
| + | |||
| + | * Blender Bug #23546 and related #23547: Currently it is not possible to create multiple linked objects and have different shape key and material animation blocks on them without having to duplicate the mesh and/or material blocks (thus unnecessarily eating up huge amount of memory and removing the possibility to edit the mesh for one mushroom and have all of the update). Functionality is currently implemented but disabled by commenting lines relating to deep data path keyframe adding and migrating actions to object level. | ||
| + | * Blender Limitation: It is currently not possible to merge two actions into one. This is necessary if you are moving mesh level and material level animation data back to object level. | ||
| + | * Blender Limitation: It is not possible to copy an fcurve in its entirity, but rather python has to iterate through very slowly copying every handle one by one, and even this is susceptible to some bugs (not yet reported). This is because the collection of fcurves is read only even though each fcurve itself if read/write. | ||
| + | * Blender Bug #23593 and #23594: The script has the ability to handle material animation as well as shape key animation. This functionality is currently disabled (by commenting lines) due to blender's instability. | ||
Revision as of 10:37, 2 September 2010
Purpose
The "Mushroomer" takes a selection of editable mesh objects (the 'original mushrooms') and distributes them on the surface of another editable mesh (the 'target object'). The distributed mushroom copies are referred to as 'mushroom instances'. The script parents the mushrooms to the nearest three vertices in the target object. The distribution starts from a selected face (or faces), and the script uses pathing algorithms to determine which other faces receive mushrooms. The mushrooms can either be supplied by the user with shape key animation on frames 0-100, or with a set of shape keys which the script will generate an animation of smooth transitions from one shape to the next.
Status
The Mushroomer is currently in BETA status.
The latest revision is available here.
Prerequisites
Python must be 3.1.2 or greater. Open a new console window in blender to check which version you are using.
Currently the script is not an add-on. To use it open it in a text editor and click run script. Press spacebar to search for "Mushroomer".
Both the original mushrooms and the target object must be selectable, editable, local meshes.
The original mushrooms should have any rotation or scaling applied to them to avoid confusion. Their origin should be at the center of the base of the mesh. As a guide for modeling the original mushrooms, bear in mind that the origin of the mushroom instances will be placed on the surface of the target object.
If you simply want the mushrooms to be distributed and not to have any animation data added, you do not need to create 'lifecycle shapes' on the mushrooms. If you want to use a manually timed animation simply create as many shape keys as you wish and animate their values. In the case of manual animation you may name the shapes as you wish. The animation of the mushrooms should be contained within frames 0-100.
If you wish to use auto-animation the mushrooms need to have 'lifecycle shapes' whose names are composed of a letters only prefix followed by an integer (eg. life1,life2,life3 is acceptable. lifeA,lifeB,lifeC is not). All of your original mushrooms must use the same letters only prefix if you wish them all to be auto-animated. If you intend to have more than 9 shapes you need to use double digits throughout (eg life01-life99, not life1-life99), likewise if you intend to have more than 99 shapes you need to use triple digits and so on (eg life000-life999). It is possible to have differently numbered shapes on each mushroom, for example the following is acceptable:
- OB: tall_mushroom, Shapes: anim1,anim2,anim5,anim7
- OB: short_mushroom, Shapes: anim04,anim05,anim09,anim10
Optionally the script can add a driver to each mushroom instance to make the mushrooms bend upwards. To use this feature the original mushrooms must have a 'bend shape' where they bend up their local Y axis. The script orientates each mushroom instance with its Y axis pointing towards the world Z axis. The script can automatically add a driver to turn up the value as the mushroom instance gets tilted away from the vertical. A selection of 'bend shapes' can be created by the user. Note that the naming convention is the same as for
Optionally the script can add a modifier to each mushroom instance to shrinkwrap the base (or any vertices you wish) to the target object. To use this feature you need to weight paint a vertex group in each mushroom object. This vertex group can then be selected in the script's UI.
Basic Usage
Parameters
the mushrooms get added to a group, so you can delete them easily when you realise that glowing mushrooms are no longer in vogue.
the mushroomer works by populating the selected face and then looking for neighbouring faces to crawl onto and populate. this variable sets how many times the face crawling algorithm will find run.
the frame number to start the crawling on.
each face will be populated with a family of mushrooms. to choose how many mushrooms are in each family you get to choose the first and the last family size, how these two values are interpolated, and how much jitter is added to the family size. for example if you choose to have 5 generations and the first family size is 1 and the last is 5 and you have 0 jitter, the sizes wil be 1,2,3,4,5.
the “child bearing age” is how old a generation gets (in number of frames) before it grows a family of mushrooms on a neighbouring face. you can add jitter too.
to animate the mushrooms you can either manually create animation data on your mushroom object using shape keys (between frame 0-100), or you can create a sequence of numbered shapes (eg. s1,s2,s3...) which the script will apply in order with smooth transitions between. the death age is the length of time (in frames) between the first animated shape key on that mushroom to the last.
to make sure the animation looks a bit more organic the children in any one generation can be born over a length of time (the generational spread) rather than all at once. if you want your mushrooms to have twins, triplets, quadruplets etc all simultaneously then you can set this to 0. you can even add jitter.
the script tries to size the mushrooms so they don’t bump into each other. your job is to make sure that the mushroom model has any rotation or scaling applied to it, its origin is dead central at the bottom (the origin is the part placed on the surface) and that the mesh fits in a 1 blender unit radius in the XY plane. lazy pack is faster but tends to leave more gaps, tight pack leaves less gaps but is much slower. packing works better with larger family sizes and squarer (rather than rectangular) quads (rather than tris).
by default the script will pick a random mushroom from the selection. you can make the script choose a mushroom (rather than at random) by painting vertex weights on the target object. if one of your mushrooms is called “tallmushroom” then painting a group called “OBtallmushroom” will make sure that the specific mushroom “tallmushroom” is used on those faces. if you paint more than one group on any given face then the amount of each mushroom type used on that face will be roughly proportional to the weights of the different groups.
by default the script will keep materials associated with their objects. if you want all of the mushrooms on any given face to receive the material “red” then you need to paint the face with a group called “MAred”. if you want the material to be selected completely at random, check the randomize materials box.
“limit to vertex group” limits the paths of mushrooms to growing only on faces in the given group.
there are different algorithms for spreading the mushrooms around the surface of the target object. put briefly “splurge” grows forked paths which can cross over each other and grow any which way they want. “crossed paths” grows paths which try to avoid each other but will cross if there’s nowhere else to go. “forked paths” grows paths which fork but will never cross. “simple selection increase” is the same as pressing Ctrl+ to grow a selection. “conways” allows you to play the slowest implementation of the game of life on the face of a mesh. some of the path algorithms read the parameters here: upwards attraction makes the paths prefer to grow up, probability of fork is the chance a path will try to fork (result depending on if there is space to) at each iteration. the family wipeout chance is the chance the fork will just die out.
the mushrooms get added to a group, so you can delete them easily when you realise that glowing mushrooms are no longer in vogue.
the mushroomer works by populating the selected face and then looking for neighbouring faces to crawl onto and populate. this variable sets how many times the face crawling algorithm will find run.
the frame number to start the crawling on.
each face will be populated with a family of mushrooms. to choose how many mushrooms are in each family you get to choose the first and the last family size, how these two values are interpolated, and how much jitter is added to the family size. for example if you choose to have 5 generations and the first family size is 1 and the last is 5 and you have 0 jitter, the sizes wil be 1,2,3,4,5.
the “child bearing age” is how old a generation gets (in number of frames) before it grows a family of mushrooms on a neighbouring face. you can add jitter too.
to animate the mushrooms you can either manually create animation data on your mushroom object using shape keys (between frame 0-100), or you can create a sequence of numbered shapes (eg. s1,s2,s3...) which the script will apply in order with smooth transitions between. the death age is the length of time (in frames) between the first animated shape key on that mushroom to the last.
to make sure the animation looks a bit more organic the children in any one generation can be born over a length of time (the generational spread) rather than all at once. if you want your mushrooms to have twins, triplets, quadruplets etc all simultaneously then you can set this to 0. you can even add jitter.
the script tries to size the mushrooms so they don’t bump into each other. your job is to make sure that the mushroom model has any rotation or scaling applied to it, its origin is dead central at the bottom (the origin is the part placed on the surface) and that the mesh fits in a 1 blender unit radius in the XY plane. lazy pack is faster but tends to leave more gaps, tight pack leaves less gaps but is much slower. packing works better with larger family sizes and squarer (rather than rectangular) quads (rather than tris).
by default the script will pick a random mushroom from the selection. you can make the script choose a mushroom (rather than at random) by painting vertex weights on the target object. if one of your mushrooms is called “tallmushroom” then painting a group called “OBtallmushroom” will make sure that the specific mushroom “tallmushroom” is used on those faces. if you paint more than one group on any given face then the amount of each mushroom type used on that face will be roughly proportional to the weights of the different groups.
by default the script will keep materials associated with their objects. if you want all of the mushrooms on any given face to receive the material “red” then you need to paint the face with a group called “MAred”. if you want the material to be selected completely at random, check the randomize materials box.
“limit to vertex group” limits the paths of mushrooms to growing only on faces in the given group.
there are different algorithms for spreading the mushrooms around the surface of the target object. put briefly “splurge” grows forked paths which can cross over each other and grow any which way they want. “crossed paths” grows paths which try to avoid each other but will cross if there’s nowhere else to go. “forked paths” grows paths which fork but will never cross. “simple selection increase” is the same as pressing Ctrl+ to grow a selection. “conways” allows you to play the slowest implementation of the game of life on the face of a mesh. some of the path algorithms read the parameters here: upwards attraction makes the paths prefer to grow up, probability of fork is the chance a path will try to fork (result depending on if there is space to) at each iteration. the family wipeout chance is the chance the fork will just die out.
Known Issues
In general the script will not catch user errors or give warnings. As it is currently primarily an in-house tool it is not our intention to program this functionality. If you do find any bugs in the script itself or issues related to open bugs in the blender tracker please note them below.
- Blender Bug #23546 and related #23547: Currently it is not possible to create multiple linked objects and have different shape key and material animation blocks on them without having to duplicate the mesh and/or material blocks (thus unnecessarily eating up huge amount of memory and removing the possibility to edit the mesh for one mushroom and have all of the update). Functionality is currently implemented but disabled by commenting lines relating to deep data path keyframe adding and migrating actions to object level.
- Blender Limitation: It is currently not possible to merge two actions into one. This is necessary if you are moving mesh level and material level animation data back to object level.
- Blender Limitation: It is not possible to copy an fcurve in its entirity, but rather python has to iterate through very slowly copying every handle one by one, and even this is susceptible to some bugs (not yet reported). This is because the collection of fcurves is read only even though each fcurve itself if read/write.
- Blender Bug #23593 and #23594: The script has the ability to handle material animation as well as shape key animation. This functionality is currently disabled (by commenting lines) due to blender's instability.