How compositions process data

Data is information such as numbers, text, and images. Nodes use the data in their input ports to control how they do their job. The goal of a composition is almost always to create or transform data in some way.

Data types

Numbers, text, and images are all examples of data — but they’re not all the same type of data. You can do things with a number (such as calculate the square root) that wouldn’t make sense with a sentence of text. Similarly, you can do things with an image (such as applying a kaleidoscope filter) that wouldn’t make sense with a number.

In Vuo, data is categorized by data type. A node can only input and output certain data types that make sense with the job that the node does, such as calculating numbers or filtering images.

Basic data types

Here are the most common data types in Vuo:

Name Examples Description
Integer -5; 0; 103 A positive or negative whole number
Real -1.2; 0.0; 33.333 A positive or negative decimal number
Text Thank you! A sequence of characters
Boolean true; false Yes (true) or no (false)
2D Point (0.1, -1.5) A position in 2-dimensional space
3D Point (0.1, -1.5, 0.8) A position in 3-dimensional space
4D Point (0.1, -1.5, 0.8, 1.0) A position in 4-dimensional space
Color A combination of hue, saturation, and lightness
Image A rectangular grid of pixels
Layer A 2D shape or image that can be stacked with others
Scene Object A 3D shape that can be placed with others in a scene

If your computer is configured to use a comma instead of a period for the decimal mark (System Preferences > Language & Region), then Vuo displays numerical types accordingly.

Vuo has dozens of other data types, many of them specific to certain tasks (such as processing audio or receiving keyboard input). You’ll learn about those data types in the process of learning how to perform the tasks.

You can see which data type a port has by clicking on the port to open its port popover.

When you start dragging a cable from a port, Vuo shows you which ports you can connect the other end of the cable to — ports that have a compatible data type — by fading out all other ports. Ports that remain opaque have the same data type as the original port. Ports that are slightly faded have a data type that is different but related, so it’s possible to convert from one data type to the other.

Type-converter nodes

The Quartz Composer equivalent to a type-converter node is represented as a darker red line in QC. The benefit of exposing these conversions is greater control over how your data is interpreted.

The two ports at either end of a cable always have the same data type. If you need to connect an output port of one data type to an input port of a different but related data type, you can insert a type-converter node. A type-converter node’s job is to translate data from one type to another.

When you drop a cable endpoint onto a port of a different but compatible data type, either Vuo will ask you to choose which type-converter node to use or, if there’s only one type-converter node available for that pair of data types, Vuo will go ahead and insert it.

For example, if you want to connect a Real output port to an Integer input port, you can choose the Round, Round Up, or Round Down node to convert the Real (number with a decimal point) to an Integer (number without a decimal point).

Vuo inserts the type-converter node in a collapsed form to save space. You can still click on the node to see its uncollapsed form and description in the Node Documentation Panel.

List data types

For every single-value data type in Vuo, there’s a corresponding list data type.

For example, the Split Text node inputs a single Text and separates it into parts. Each part is a Text. The node outputs the collection of parts as a List of Text.

A list is a sequence of data items. Lists are useful when you want to work with a collection of data items instead of just one.

Dictionary data types

With a list, each item is identified by its position in the sequence. With a different kind of collection called a dictionary, each item is instead identified by a name or key.

For example, the Calculate node’s Values input port has a dictionary data type, specifically Dictionary of Text keys and Real values. The keys are the names of variables in a math expression. The values are the numerical values that the node should substitute in place of the variables to calculate the result.

Ports with changeable data types

Some nodes can work with many different types of data. For example, the Add node can add Integers, Reals, 2D Points, 3D Points, or 4D Points. The Hold Value node can hold a 3D Point, an Image, a Color — or, in fact, any single-value type of data.

When using nodes that are flexible about the type of data they can work with, you can choose the data type that suits your composition.

To see the data types that a port can be changed to, right-click on the port and look at the Set Data Type submenu. (Only ports with changeable types have a Set Data Type submenu.)

The Generic menu item means that the port has a generic data type — a stand-in for when the port’s data type hasn’t been decided yet.

You can connect a cable from a port that has a generic data type to a port that has any of the data types in the first port’s Set Data Type menu. When you connect the cable, the first port’s data type automatically changes to match the second port.

On some nodes, multiple ports share the same data type. When you change one to Generic, all become Generic. When you change one to 2D Point, all become 2D Point.

An example is the Subtract node. All of its ports share the same type. When you subtract one 2D Point from another, the result is a 2D Point. The same goes for other data types that the Subtract node can work with.

On a few nodes, one group of ports shares the same data type and a separate group of ports shares another data type. The Process List node is an example. The Start Processing port has a list data type, and the Item port outputs the items of that list. So if Start Processing has type List of Text, Item must have type Text. Similarly, the Finished Processing port has a list data type, and its items must match the type of Processed Item. But Processed Item doesn’t have to match the type of Item. You can see which ports on a node share a data type by selecting Set Data Type > Generic for each port, then opening the port popovers and observing the numbers on the generic data types (generic #1, generic #2, etc.).

You can connect a generic port to any port that has a compatible data type (which may be either generic or non-generic). When you start dragging a cable, Vuo fades out the incompatible ports, so you can easily see which ports it’s possible to connect to.