Mushroomer

Demonstrations

• Demonstration Video by Josh Wedlake and Henri Hebeisen
• Demonstration Blend File

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 3, known to work with Python 3.1.2 on Blender r31744
• 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.

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: there is no 'bend...' shape on 'robot_arm'. The script will warn the user and any animation will be omitted.

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.

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.