Author: Mark Danks

## Utility objects

There are a number of objects which were written to make it easier to use both GEM and pd. For instance, you often pass around 3 floats at a time in GEM, either for position or colors. To help with this, there are a collection of vector objects. Use the list below to find out about the objects.

These objects used to be in a separate library called MarkEx, but they have now been folded into GEM.

counter - count the number of bangs
average - average a series of numbers together
change - only output when there is a change in the number
invert - invert a number
randomF/randF - floating point random number
tripleLine - line object for 3 values
tripleRand - three random numbers
vector objects - process a series of numbers
hsv2rgb and rgb2hsv - convert between RGB and HSV color space

### counter

The inlets are:
bang (increment or decrement the counter)
set direction (1 = count up, 2 = count down, 3 = count up and down)
set low value
set hight value
The outlet is the current count.

So in this case, the top counter will count up from 1 to 10. The bottom counter will count up from 2 to 5.

The counter also accepts the messages reset and clear. Reset immediately sets the counter to its low value and outputs the value. The clear message means that the next bang will set the counter to its low value.

### average

The average object just averages a series of numbers as they come in. The left inlet accepts a single float. It then outputs the current average. The default number of floats to average together is 10, but that can be changed by sending a new value to the right inlet.

The average object also accepts the messages clear and reset. Clear will immediately set all of the values that the object has been storing for averaging to 0. With the reset message, you must pass in a number to set all of the values.

### change

Change only accepts a number into its left inlet. If the number is the same as the last number sent to the change object, then it does nothing. If the number is different, then the change object will output the new number and store it for the next comparision.

This object is very useful for the == object and others like it, since they send a 0 or a 1 every time they do a comparision, and you usually only care when the state actually changes.

### invert

The invert object is very simple. If the number sent to its left inlet is equal to 0., then invert outputs a 1. If the number is not equal to 0., the invert outputs a 0.

### randomF/randF

One problem with the random object in pd is that it only sends out integers. This a real problem in GEM, where you often want a value between 0 and 1. randomF is exactly like the random object.

When the left inlet gets a bang, randomF outputs a random number between 0 and the given range. The range can be set with a number to the right inlet.

randF is just an alternate name for randomF.

### tripleLine

The line object is really great for dealing with a single number. To do a line with 3 values, like an RGB color value, means that you have to unpack, do a line, then repack the number. Not only is it a pain, but it expensive computationally.

tripleLine behaves just like the line object, only it accepts three numbers to interpolate between. In the example, tripleLine will interpolate from the current values to 1., .2, .4 over 1000 milliseconds. The default output resolution is 50 milliseconds, which is the same default rendering time. Going faster with GEM objects will not produce any benefit, unless you increase the frames per second.

### tripleRand

Just as using tripleLine makes it easier to interpolate between 3 values at once, tripleRand makes it easy to generate three random values. In the above example, when the bang is sent, tripleRand will create three values and output them, with the first between 0 - 1, the second between 0 - .5, and the third from 0 - .8.

### Vector objects

The vector math objects are
vector+ or v+
vector- or v-
vector* or v*
vector/ or v/
All of the above objects perform math on a list of numbers. The left inlet accepts a list of numbers of any length. The right inlet accepts a single value, which is the operand for the computation. In other words, they work just like the normal *, +, -, and / objects, except they can handle more than one number in the left inlet.

There are two other objects which are also useful.

The first is vectorabs or vabs. It computes the absolute value on a list of numbers.

The second object is vectorpack or vpack. vpack accepts a list of numbers in the left inlet and a single number into the right inlet. The output is a single list of numbers that is the vector with the single number appended to the end. This is very useful when you want to change the time for a tripleLine without unpacking and repacking all of the data.

### hsv2rgb and rgb2hsv

These two objects convert three numbers between HSV and RGB color space. HSV stands for hue, saturation, and value. The simple way to think of HSV space is that hue is the "color", such as red, blue, etc, the saturation is how intense the color is, and the value is how bright the color is.

You can get some really nice effects by varying the hue of a color, because the brightness will not change while you do it.

[return]