NodeBox has two features that largely control how it works: list matching and port ranges.

Both features are subtle and can be confusing. But to master NodeBox you really have to understand both features.

LIST MATCHING

List matching is the way nodes deal with multiple input streams of different lengths. If you feed a colorize node a list of 10 shapes and a list of 3 colors, it will match the two lists by repeating the shorter list against the longer list. If your colors are red, green, and blue, the shapes will be colored red, green, blue, red, green, blue, red, green, blue, red. This is explained in more detail near the bottom of this page: https://www.nodebox.net/node/documentation/concepts/concepts

NODE RANGES

When you make your own subnetwork, you can determine the range of each input port using the Metadata dialog. If you set a port range to VALUE, it will take inputs one at a time. If you set a port range to LIST, it will take the whole input list at once. By using different combinations of VALUE and LIST you can completely change the way your subnetwork functions.

Consider a very simple subnetwork consisting of a null node which takes shapes, a color node which takes colors, and a colorize node colors the shapes. By default both the shape and color ports are set to VALUE. If you feed it 10 shapes and 3 colors it will fire 10 times and behave just like a normal colorize node.

BUT, if you change the shape port to LIST, all the shapes will be read in at once and the subnetwork will fire 3 times - one for each color. The first time it fires it will color all shapes red, the next time it will color all shapes green, and the third time it will color all shapes blue. The result is a list with 30 shapes instead of 10.

When you create subnetworks with multiple ports, each with different input streams and different ranges, things can get complicated. This often confuses beginners - and even experts. It takes some practice to get a feel for how these two features can combine.

THE TUTORIAL

Please refer to two screenshots (attached).

Screenshot 1 shows the tutorial. I create three lists:

• FIVE Labels: Alligator, Beaver, Cat, Dog, Elephant
• THREE Shapes: Triangle, Square, Pentagon
• TWO Colors: Blue and Orange

I then feed them into 8 almost identical subnetworks. Each subnetwork feeds the shapes and colors into a colorize node, turns the label into a textpath, then combines and groups them. You can see this subnetwork in Screenshot 2.

The ONLY DIFFERENCE between these 8 subnetworks is the range setting for each of the three input ports. There are 8 possible combinations of VALUE and LIST. Each combination produces a different result.

The output of each combination is shown in the left half of Screenshot 2. Each row shows the combination of ranges for the label, shape, and color ports, the number of groups produced by the subnetwork, the actual groups produced, and what each group looks like unpacked. As you can see, each one is different.

Following is an explanation for each combination:

• VALUE VALUE VALUE. Since there are more labels than anything else, the node fires 5 times and produces 5 groups. Each group consists of the label inside a colored shape. The 3 shapes repeat once to produce Triangle, Square, Pentagon, Triangle Square. The 2 colors repeat twice to produce Blue, Orange, Blue, Orange, Blue.
• VALUE VALUE LIST. Once again the node fires 5 times and produces the same list of shapes. The colorize node inside gets one shape each time the node fires, but receives BOTH colors each time. So that colorize node fires twice, producing two shapes, one blue, one orange. Because the shapes are exactly the same size, they stack on top of each other and you only see the orange shape beneath the label. So while there are still 5 groups, and each group seems to consist of a shape and a label, it actually consists of two shapes and label. Fully unpacked the list would contain 15 paths instead of 10.
• VALUE LIST VALUE. The node still fires 5 times to produce 5 groups, but now each group consists of all three shapes stacked with the label on top. The colorize node inside gets all three shapes at once each time the subnetwork fires. The colors continue to match the labels in their blue, orange, blue, orange, blue pattern, but now it's 3 blue shapes, 3 orange shapes, etc.
• VALUE LIST LIST. Now there is only a single value node, the five labels, so again the subnetwork fires 5 times, but now the colorize node inside is getting a list of 3 shapes and a list of 2 colors at once. Colorize can only apply one color at a time, so with each firing we get a blue triangle, an orange square, and a blue pentagon, with the blue pentagon atop each pile.
• LIST VALUE VALUE. Now the labels are all coming in at once, and since there are more shapes than colors, the subnetwork fires once for each of the three shapes. The colors alternate as before, so we get a single blue triangle, a single orange square, and a single blue pentagon. The five labels come all at once to form the same pile of labels atop each of the three shapes, each a group with one colored shape and five overlapping labels.
• LIST VALUE LIST. Shapes are now the only value port, so the network fires three times, once for each shape. But each time both colors are applied, producing two copies: a blue shape on the bottom and the same shape in orange on top. The five labels all land on top of each of these piles, so each group now has 7 components.
• LIST LIST VALUE. Now the 2 colors are the only value port, so the network only fires twice, once for blue and once for orange. The colorize node is forced to color all three shapes each time, producing first a pile of blue shapes with the blue pentagon on top, and then a pile of orange shapes with the orange pentagon on top. All 5 labels are then sprinkled atop both piles. Two groups, 8 items in each.
• LIST LIST LIST. Finally all three ports are set to take all their lists at once. The subnetwork only fires once. The colorize node inside fires three times, alternating colors, to form a single pile of all 3 shapes (a blue triangle, orange square, and blue pentagon) with all 5 labels on top of that. So now there is just a single group containing the 3 shapes and the 5 labels.

You should not feel bad if you were not able to predict all (or any) of these outcomes, even for this very simple subnetwork. But I hope you are starting to get a feel for the difference between value ports and list ports, and how you can achieve different effects by combining the ranges in different ways.

When I create a new subnetwork I ask myself how many times I expect it to fire, and what it should produce each time it fires. If I want it to fire once for each shape I feed it, I will make sure that shape list is set to value and the other ports are either set to list or set to value but with a list length less than or equal to the number of items in the shape list.

When reading in a data table (using a null node), you can set that port to value if you want to fire once for each row in the table. But if you are going to be filtering that table inside your subnetwork, you will need to set the data port to list (otherwise you will only be filtering one row at a time).

It's also a good habit to switch to data view and count the number of items in each input list, then the number of items in the output list. Nodebox nodes always produce a single list at the end of the day, so if your subnetwork produces 5 items each time it fires, and it fires 3 times (as determined by the input ports), it will output a single list with 15 items. If any of these numbers are not what you expect, you may want to review the range settings for each port.

PLEASE pepper me with questions!

John

P.S. By the way, if you ever need to override Nodebox's normal list matching behavior, you can now use my new match_list node: http://support.nodebox.net/discussions/show-your-work/913-match-lis...