Mushroomer

Demonstrations

• Demonstration Video by Josh Wedlake and Henri Hebeisen
• Demonstration Blend File updated for release 4

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 & Version History

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 4, known to work with Python 3.1.2 on Blender r31856
• Tube Trunk Mushroomer release 3, known to work with Python 3.1.2 on Blender r31744, confirmed broken in r31838
• Tube Trunk Mushroomer release 2, known to work with Python 3.1.2 on Blender r31726, confirmed broken in r31742
• 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.

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

Original Mushroom Prerequisites

The original mushrooms should have any rotation or scaling applied to them to avoid confusion. They should not have any animation on their location, and object level scale or rotation animation will likely be problematic. The object origins of the original mushooms 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. To enable the auto sizing of mushroom instances (known as 'packing') each original mushroom should fit inside an infinite cylinder of radius 1 blender unit centered on their origins. If they fit exactly the 'packed' mushrooms will just touch. For gaps between mushrooms a radius of less than 1 should be used. Mushroom instances can always be scaled manually around their individual centers after the script has been executed.

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.

See also: Example Image

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. 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: 'anim4','anim5','anim9','anim10'

See also: Example Image

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: 'life1','life2','life4','random1','random2','bend5','bend6'
• OB: 'flower', Shapes: 'life1','life10','life15','random6','random8','bend1'
• OB: 'robot_arm', Shapes: 'life0','life100','life200','random6754'
  • Note: in this case there is no 'bend...' shape on 'robot_arm'. The script will warn the user with the text "[NOT ALWAYS AVAILABLE]" in the UI dropdown. If the user selects 'bend...' the script will not be able to create animation, drivers or variation on mushroom instances duplicated from original mushrooms which do not have shape keys prefixed by 'bend'.

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.

Target Object Prerequisites

By default the script will pick a random mushroom from the selection of original mushrooms present when the script is invoked. The script can also choose a specific mushroom on a per face basis if required. To use this feature the target mesh must be painted with vertex group weights whose names correspond to the names of the original mushrooms prefixed with the letters 'OB'. To use the original mushroom called “tallmushroom” then painting a group called “OBtallmushroom” on the target object will ensure that the specific mushroom “tallmushroom” is used on the painted faces. By painting more than one group on any given face, the amount of each mushroom type used on that face will be roughly proportional to the weight of the named group divided by the sum of the total group weights (whose names correspond to original mushrooms) on that face.

By default the script will keep materials associated with their objects. Optionally the script can swap materials from one mushroom to another if the target object is painted with vertex groups whose names correspond to the names of materials present on the original mushrooms prefixed by 'MA'. Only materials found on the original mushrooms can be used, not any materials from the scene.

Example Setup

• Input Original Mushrooms:
  • OB: 'tall_mushroom' MA: 'red'
  • OB: 'flowery_moss' MA: 'mushy_green'

Example Face 1

• Vertex Group Weights:
  • 'OBtall_mushroom' 1
  • 'OBflowery_moss' 0.5

• Resulting Composition of Mushrooms:
  • 'tall_mushroom' with 'red' material 66%
  • 'flowery_moss' with 'mushy_green' material 33%

Example Face 2

• Vertex Group Weights:
  • 'OBtall_mushroom' 0.5
  • 'OBflowery_moss' 0.5
  • 'MAred' 1
  • 'MAmushy_green' 0

• Resulting Composition of Mushrooms:
  • 'tall_mushroom' 50%
  • 'flowery_moss' 50%
  • mushroom instances with the material 'red' 100%
  • mushroom instances with the material 'mushy_green' 0%

By default the pathing algorithm will consider any face as available to grow mushroom instances on. The available faces can be limited to a selection by appending them to a vertex group. The name of this vertex group is not important other than it must not be prefixed by 'MA' or 'OB'.

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.

Family Settings

• 1st and Last Generation Mushroom Family Size: Each face will be populated with a 'family' of mushrooms. To choose how many mushrooms are in each family the user sets the first and the last family sizes, 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 generation family size is 1 and the last generation family size is 5 and you have 0 jitter, the sizes will be 1,2,3,4,5.

• Child Bearing Age: How old a generation gets (in number of frames) before it grows a family of mushrooms on a neighboring face. In other words the length of time between generations. Optionally with jitter.

• Death Age: The length of time (in frames) between the first animated shape on a mushroom instance to the last. If using manual animation the 100 frames of keyed animation data are stretched to fit the life of each mushroom.

• Generational Spread: To ensure the animation looks more organic the children in any one generation can be born over a length of time (referred to as generational spread) rather than all at once. If you do not want variation in birth times and would prefer each family of mushrooms to be born simultaneously then set this to 0. Optionally with jitter.

• Packing Algorithm: The script tries to size the mushrooms so they don’t bump into each other. The original mushroom mesh must fit in a 1 blender unit radius about its origin in the XY plane if you want this feature to work. 'Lazy Pack' is a fast algorith but leaves more gaps as it does not search exhaustively, '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).

• Randomize Materials: If you want the material to be selected completely at random, check the randomize materials box. If this is unchecked and no vertex groups prefixed with 'MA' are found on the target object then the materials for each mushroom instance will be the same as those used for the original mushroom which the instance was duplicated from. See Target Object prerequisites for information on how to influence the material choice using vertex group weights on the target object.

Spread & Conquer Settings

• Limit to Vertex Group: This limits the paths of mushrooms to existing only on faces in the given group. See target object prerequisites.

• Growth Method: There are different algorithms for pathing (selecting faces sequentially on the target object to populate with mushroom instances).
  • “Splurge” grows paths out at random from the start face. The paths can cross and coexist on the same face. It differs from "Simple Selection Increase" in that by growing paths it does not necessarily cover every single surrounding face.
  • “Crossed Paths” grows paths which try to avoid each other but will cross if there is nowhere else to go.
  • “Forked Paths” grows paths which fork but will never cross.
  • “Simple Selection Increase” has the same effect as pressing Ctrl+ to grow a selection.
  • “Conways” is a very slow implementation of the game of life.

• Upwards Attraction: The chance that a path will prefer faces with higher Z values (ie vertically above). Evaluated at each generation.

• Probability of Fork: The chance that a path will prefer to fork. Evaluated at each generation. Whether the path forks depends on the type of growth method chosen and the availability of neighbour faces.

• Family Wipeout Chance: The chance that any given fork will die out. Evaluated at each generation.

Shape Key Settings

Shape key settings are vital for the script to be able to create meaningful animation. They are the one part of the script's UI which should not be left at their default values unless the user is certain the default is correct. The drop down boxes also display important warnings to the user, such as if a prefix could not be found on all of the original mushrooms. Although the script will run, it is not usually useful to provide it with both original mushrooms with pre-animation and original mushrooms with sequentially named shape keys, as at least one type of mushroom instance will end up with no animation data.

• Animation: Manual/Lifecycle Shape Set: This dropdown contains a list of the valid shape key sets (see Original Mushroom Prerequisites) which can be used for auto-animation. It also contains the options "Don't Use" and "Duplicate and retime pre-existing animations".
  • If "Don't Use" is selected the script will generate neither automated nor retimed manual animation lifecycle animation on the mushroom instances. The mushrooms will only be placed.
  • If "Duplicate and retime pre-existing animations" is selected, any animation data on the shape keys from frames 1-100 will be retimed on the mushroom instances (scaled on the time axis and jittered). Choose this option if you have already animated all of your original mushrooms on frames 1-100.
  • If the prefix of a lifecycle shape set is chosen followed by the text "[available on all mushrooms]" this indicates that the prefix has been successfully found on all of the original mushrooms and as a result all mushroom instances will receive autogenerated animation using this set of shape keys.
  • If the prefix of a lifecycle shape set is chosen followed by the text "[NOT ALWAYS AVAILABLE]" this indicates that the prefix has not been found on all of the original mushrooms and as a result, mushroom instances duplicated from original mushrooms which do not have the selected shape key set will not receive animation.

• Random Shape Set: This dropdown contains a list of the valid shape key sets (see Original Mushroom Prerequisites) which can be used to add random variation to the mushroom instances. It also contains the option "Don't Use" which disables this feature. If a shape key set is selected, the script will pick a random shape key from the set and smoothly animate a random variation shape's value from 0 to 1 to 0 over the course of the lifecycle animation.

• Bend Upwards Shape Set: This dropdown contains a list of the valid shape key sets (see Original Mushroom Prerequisites) which can be used to add an upwards bend to the mushroom instances. It also contains the option "Don't Use" which disables this feature. If a shape key set is selected, the script will pick a random shape key from the set and add a driver which increases the value of the shape as the mushroom instance is tilted away from the vertical. The driver includes a gaussian distribution multiplier which approximately adjusts the shape's maximum possible value from 0 to 1 to 0 over the course of the lifecycle animation.

• Vertex Group for Shrinkwrap: This vertex group will be passed to the shrinkwrap modifier which is added to each mushroom instance. If "(Do not use shrinkwrapping)" is selected, shrinkwrap modifiers will not be added to the mushroom instances.

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.