Mapping

A parameter on a Grow is normally one number, and every branch gets it. Mapping replaces that number with a Map node, which works out a value for each element of the tree. Pitch can fall from the base of the tree to the top, a branch can bend more at its tip than at its base, and a decoration can thin out towards the inside of the canopy.

A map only produces a value. It doesn't touch geometry, and it doesn't sit in the geometry stream, so one map can drive several parameters and keep the same decision consistent in more than one place. Mapping is for single numbers; effectors do the same job for directions.

Map a parameter

Click the map button at the end of a parameter's row. The menu offers:

• Constant, Map and Random, which create a map in that mode.
• Map from attribute…, which lists the attributes the tree carries; pick one, then choose where to read it from (Self, Parent and so on).
• Pick from network…, and the maps that already exist, to link one you have.

Once a parameter has a map, the same button offers Insert…, Unlink and Replace…. Unlink drops the map and leaves the node in place, and the parameter goes back to its own value.

Any parameter with a map button can be mapped: on Grow, Assembly Decoration, Surface Decoration and the Simulate's postprocess, as well as effector strengths and trait weights.

Three modes

Constant is one value for everything, shared and swappable rather than typed in twice. Random gives each element its own value within a chosen range. Map reads something the tree already knows about itself, such as u, height or distance_to_root, or an attribute carried from its source point, and remaps it. Map is the mode that lets growth respond to its own shape and to the scene. age is in the list too, but it only varies on the finished tree, so map from it on a decoration, not on a Grow.

u runs from 0 at the base of a branch to 1 at its tip, and it is the attribute you will use most.

Reading an attribute

An attribute map needs two things: which attribute to read, and where to read it from.

Attribute lists the attributes available at this point in the network, including any on the Simulate's source points and any that a Wrangle further up has written. Read From picks the level: Self reads the value on the element being built, Parent reads it from that element's parent, Parent+1 from its parent, and so on up to Parent+4. On a branch, u from Self runs along the branch itself, and u from Parent says how far up the trunk the branch starts.

The same attribute can hold a different value at each level, because attributes are rebuilt as the tree grows. That also means a map can stop doing what you expect after you add steps, insert a node or restructure a repeat, without the map changing. If a map behaves oddly after a network edit, check Read From first.

On an Assembly Decoration, maps on the effector rows, and maps chained into them, read the placed parts as well as the tree. Self reads the part's own value, so u with Self runs along each part, and an effector can bend each part more at its tips than at its base. Parent reads the tree where the part sits. A name the tree also has, such as u, is listed once; attributes only the parts carry are listed as Assembly and the name. Maps that decide where parts spawn, such as Mask, read the tree only.

Ranges and direction

An attribute map remaps one range to another. The first min and max pair is the span of the attribute that matters: values below the minimum are clamped to it, and values above the maximum to that. The second pair is what those values become. The bottom of one pairs with the bottom of the other.

To make something shrink as an attribute grows, put the larger number in the output minimum and the smaller one in the maximum, and the map runs backwards. That is the usual way to shorten branches further out, or to give the lowest branches the widest angle.

The neg and pos buttons beside each field flip its sign, so a field reading 90 can feed in -90. With Ramp on, the ramp shapes the travel between the two ends; the ranges still decide where it starts and finishes.

Set the source range first, from values in your scene. For height, check how tall the tree is and use 0 to that height.

Chain maps

A parameter can be driven by a chain of maps. Select a map in the network view, and the toolbar shows a button for each map type. Click Map (or Map Blend, Map If and so on) and choose Append (left), which adds the new map before the selected one, or Insert (right), which adds it after and takes over as the map the parameter reads. Each map's Blend Mode (replace, add, minus, multiply, divide, max, min) sets how it combines with the map before it.

The arc changes up the tree in the Effectors Cookbook is a worked example.

Interface > Graph > Show Dependency Links on the display toolbar shows which nodes a map is linked to in the network view.

The other map nodes

Besides Map, the toolbar's map buttons (shown while a map is selected) and the Tab menu have:

• Map If: one value when a condition is true, another when it is false, such as one pitch below a height and another above it.
• Map Blend: combines two maps, A and B, with a Mode such as Multiply or Blend (Lerp), and an optional Mask.
• Map Constant (one shared number), Map Attribute (an attribute read without the remap) and Map Random (a value per element within a range).
• Map Remap and Map Wrangle, for remapping and for writing a map in VEX.

Mapping Cookbook has worked examples.

Your own map behaviours

Mapping Template, hidden from the Tab menu in 0.7.3, has example code for writing your own map behaviours; see Mapping Template.

Status

Map Attribute, Map Blend, Map Random, Map Constant, Map Remap and Map Wrangle are experimental. Known issue: on a Grow, mapping Growth % from its own u reads the parent's u.