Mushroomer

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.

Development from the wider blender community is welcomed and encouraged. Please add (do not remove) any GPL licensed branches you create based on the Mushroomer below, and note the blender revision which the script runs on:

• Tube Trunk Mushroomer release 2, known to work with Python 3.1.2 on Blender r31726
• Tube Trunk Mushroomer release 1, known to work with Python 3.1.2 on Blender r31675, confirmed broken in r31726

This documentation always refers to the latest version of the Tube Trunk Mushroomer.

Prerequisites

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. The letters only prefix can be whatever you want - the script UI displays a dropdown box for the user to select a set of shapes. 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 bend shape's 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 lifecycle shapes. Again the value of the prefix is not important as the user is given the choice to select the set of bend shapes from a dropdown in the script's UI. Even if you only have 1 bend shape, you must suffix the name with a number (for example 'bend5' is acceptable, 'bend' is not)

Optionally the script can add a random variation to each mushroom using 'random shapes'. The script animates the value of the random shape smoothly from 0 to 1 and back to 0 throughout the life of the mushroom instance. Naming conventions for bend shapes also apply to random shapes.

Some possible example combinations of mushrooms and their shapes are shown below:

• OB: 'mushroom_low_poly', Shapes: 'life01','life02','life04','random1','random2','bend5','bend6'
• OB: 'flower', Shapes: 'life01','life10','life15','random6','random8','bend01'
• OB: 'robot_arm', Shapes: 'life000','life100','life200','random6754','bend0'

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. It can be named whatever you want.

Basic Usage

Ensure you have completed pre-requisites.

Select the original mushrooms and holding shift select the target object making it active. Tab into edit mode in the target object keeping the original mushrooms in the selection. Select one or more faces where you wish to start the pathing algorithm (selecting no faces will result in a single face being selected at random by the script). Hit space then type 'Mushroomer' and hit enter. Set parameters as described below, Hit OK and wait. It is recommended that blender is started from a terminal (currently the default on Windows)

Parameters

Group To Append Mushrooms To: Mushroom instances get added to a group, so you can delete them easily when you realise that glowing mushrooms are no longer in vogue.

Generations of Mushrooms: The script works by populating the selected face and then looking for neighboring faces to crawl onto and populate. This variable sets how many times the face crawling algorithm will run.

Start Frame: The frame number to start the animation 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.