Video4jmax 0.2.2 - reference index

Grid Protocol

each element of a grid is an integer. the range of allowed integer values is called signed 32-bit and is -2147483648 to 2147483647 (which is -2³¹ to 2³¹-1).

There is a sequence in which elements of a Grid are stored and transmitted.

Dimension 0 is called "outer" or "first" and dimension N-1 is called "inner" or "last". This inner/outer relationship may also be thought of this way: a Grid is an array of array of array of...; for example, a picture is an array of lines; a line is an array of pixels; a pixel is an array of integers.

At each such level, elements are sent/stored in their numeric order, and are numbered using natural numbers starting at 0. This ordering usually does not matter, but sometimes it does. Most notably, @import, @export and @redim care about it.

On the other hand, order of dimensions usually does matter; this is what distinguishes rows from columns and channels, for example. Most objects care about the distinction.

Picture Protocol

A picture is a three-dimensional Grid:

• 0 : rows
• 1 : columns
• 2 : channels

Channels for the RGB color model are:

• 0 : red
• 1 : green
• 2 : blue

Because Grids are made of 32-bit integers, a three-channel picture uses 96 bpp (bits per pixel), and have to be downscaled to 24 bpp (or 16 bpp) for display. That huge amount of slack is there because when you create your own effects you often have intermediate results that need to be of higher precision than a normal picture. Especially, results of multiplications are big and should not overflow before you divide them back to normal; and similarly, you can have negative values all over, as long as you take care of them before they get to the display.

In the final conversion, high bits are just truncated. The black value is 0 and the maximum intensity value is 255; negative values are wrapped and values above 255 are wrapped too. If you want to clip them, you may use "@ max 0" and "@ min 255" objects.

Objects for Input/Output

@video_out

Each @video_out object creates a window when it is created. It is constructed with two parameters. If you want to create a window that is 240 pixels high and 320 pixels wide: @video_out 240 320. @video_out will use three channels in RGB with values ranging 0-255.

grid(rows,columns,channels)
will be displayed if channels = 3 (RGB color model is assumed) The picture's height and width must match the window's.

bang
asks for a repaint of the window. Usually not needed, as windows normally repaint automatically. (normally.)

autodraw integer
sets the drawing mode:

• 0 makes all drawing manually activated (by bang).
• 1 displays when a whole picture has been received. (default)
• 2 displays every line as it comes. (but buffering may cause lines to come in groups anyway)

Notes: @video_out sends a bang on its outlet when it has finished receiving a picture. Destroying the object should close the window. Because of how jMax works, this may be delayed until you do something else. Closing the window yourself will make jMax crash.

@video_out_file

grid(rows,columns,channels)
will be written to file if channels = 3 (RGB color model is assumed). the file must be open first.

open filename [format]
you must open a file first. You do this by sending the message "open" with a filename parameter. you may append the symbol "targa" for .tga files, or "videodev" for video4linux 1.x digitalizer input, or "ppm" (but ppm is the default)

close
you can send a "close" to close the file, but it's usually not necessary. Sending a 2nd picture overwrites the first, like what happens to the video buffer inside a @video_out object.

@video_in_file

This class is similar to @video_out_file in that it operates on files. However some aspects of it are backwards because it's reading, not writing. Objects of this class don't have a grid inlet, they have a grid outlet instead.

open filename [format]
as for @video_out_file.

close
close may be necessary if you operate on "/dev/video", which can only be read by one at a time. otherwise it's not necessary.

bang
causes the object to send the picture from an open file through its outlet. Several bangs reread the same picture over and over.

size height width

option property value

• channel integer
• tuner integer
• brightness integer
• hue integer
• colour integer
• contrast integer
• whiteness integer

@import

Objects of this class have an inlet that can receive integers and reset as well as Grid outlet. You specify the dimensions (all of them) in the constructor. For a 240-row 320-column picture you'd say: @import 240 320 3

An import object accumulates the integers you send to it. They should be in the 0-255 range. When you send 3 of them, they represent the red, green and blue values of one pixel. Successive pixels are ordered left to right and when there are enough of them they form a line. Successive lines are ordered top to bottom and when there are enough of them they form a frame. After a frame is completed a new frame begins replacing the previous one.

@export

Objects of this class have a Grid inlet and a 0.1-compatible outlet. They do the opposite of @import and take no parameters.

Transformation Objects

@fold

@fold makes the last dimension of a grid disappear by combining elements
together in each innermost array. For example, @fold + 0 on a RGB image
will output a channelless image in which every value is the sum of
red/green/blue values in a pixel. The zero is the starting value, so that
is actually 0+r+g+b. You can get the number of values in a grid by passing
it through @dim and then through @fold * 1.

@redim

@redim outputs a grid of the dimensions provided in the constructor, based
on serializing the input grid and reserializing it to those dimensions. If
the new grid is bigger, incoming data is repeated to fill the grid; if the
new grid is smaller, extra data is dropped.

ex: with a 240 320 RGB image, @redim 120 640 3 will visually separate the
even lines (left) from the odd lines (right). contrary to this, @redim 640
120 3 will split every line and put its left half on a even line and the
right half on the following odd line. @redim 480 320 3 will repeat the
input image twice in the output image. @redim 240 50 3 will only keep the
50 top lines.

@store

A @store object can store exactly one Grid. You store it via its right inlet. You fetch it by sending a bang through its left inlet, which sends the Grid on the outlet. You may also perform all kinds of coordinate transforms with @store. You send in the left inlet a Grid whose two channels are Y and X coordinates of pixels of the stored grid. Values too large or too small are wrapped around (using uniform modulo). @store is even more flexible than that: you can address whole lines and pixel parts too, by sending appropriately-sized grids (non-3D). Advanced users can figure it out; beginners should simply ignore it.

If you send to @store a grid of 2 dimensions consisting of rows (y) and channels, in which the channel ... see the example

TODO @store takes one argument specifying its size, int32 (default) or uint8 (native format for ppm or tga formats)

@outer

When given a grid of Dim(3) and a grid of Dim(5) [@outer] will produce a grid of Dim(3,5) with the selected binary operation applied on each of the possible pairs combinations between numbers from the left grid and the ones from the right. for example : (10,20,30) [@outer +] (1,2,3) will give : ((11,12,13),(21,22,23),(31,32,33))

Reporting Objects

@dim

Returns list of dimensions as a grid. Given a grid sized like Dim(240,320,4), @dim will return a grid like Dim(3), whose values are 240, 320, 4.

Binary Operators

@

This object computes a Grid by combining each of its elements with an integer in its right inlet. This is not unlike built-in arithmetic objects, except that the left inlet, and the outlet, work with Grids. This runs up to 10 times faster than equivalent built-ins (but still probably slower than equivalent DSP built-ins. Construction takes 2 parameters: a first one is the operation's symbol, and a second optional one is the default value for the right inlet. Operations provided are listed below in the "binary operations" section. Many of them have no equivalent in "plain jMax".

where A is the left value, and B is the right value.

operator	meaning
	A + B
	A - B
	B - A
	A * B
	A / B, rounded downwards
	B / A, rounded downwards
	A % B, non-negative remainder
	B % A, non-negative remainder
	A or B, bitwise
	if A is zero then B else A
	A xor B, bitwise
	A and B, bitwise
	if A is zero then zero else B
	A * (2**(B % 32)), which is left-shifting
	A / (2**(B % 32)), which is right-shifting
	the lowest value in A,B
	the highest value in A,B
	is A equal to B ? 1=true, 0=false
	is A not equal to B ?
	is A greater than B ?
	is A not greater than B ?
	is A less than B ?
	is A not less than B ?
	cmp gives -1 if A<B; 0 if A=B; 1 if A>B
	B * sin(A), where A is in hundredths of degrees
	B * cos(A)
	tanh(A) where A is in hundredths of degrees (yes, really)
	floor(pow(a/256.0,256.0/b)*256.0)
pow

Unary Operators

Compound Objects

@contrast

@contrast adjusts the intensity in an image. values outside 0-255 are
automatically trimmed.

Sending an integer to inlet 2 sets the intensity of incoming white to a certain fraction between output black and output white. normal value is 256; may be set smaller or bigger.

Sending an integer to inlet 1 sets the intensity of incoming black to a certain fraction between output black and inlet 2 value. normal value is 256; may be set smaller or bigger.

Sending a grid to inlet 0 filters it to outlet 0.

@identity_transform

@identity_transform builds a pixel-level transform grid suitable for using with inlet 0 of @store.

Sending an integer to inlet 2 sets the width of the resulting picture.

Sending an integer to inlet 1 sets the height of the resulting picture.

Sending a grid to inlet 0 generates said grid and sends it to inlet 0. Not guaranteed to be fast (use an intermediate @store as a cache if needed)

@posterize

@posterize reduces the number of intensities in an image.

Sending an integer to inlet 1 sets the number of possible levels. Minimum value is 2. Simulate 216-color palette with 6. Simulate 15-bit depth with 32. The effect is mostly apparent with small values.

Sending a grid to inlet 0 filters it to outlet 0.

@scale_to

@scale_to is normally fed the same inlet 1,2 values as @identity_transform, and chained from @identity_transform and to @store. This will scale an image of any size to the size specified in inlets 1,2. If it doesn't correspond the values of @identity_transform, part of the image will be trimmed and/or duplicated.

@spread

@spread scatters the pixels in an image. Not all original pixels will appear, and some may get duplicated (triplicated, etc) randomly. Some wrap-around effect will occur close to the edges.

Sending an integer to inlet 1 sets the amount of spreading in maximum number of pixels + 1. even values translate the whole image by half a pixel due to rounding.

@three

@three builds a Dim(3) grid using integers sent in inlets 0, 1, 2.

Sending an integer guarantees an update to outlet 0 (currently it's doing redundant updates -- sorry)

@two

@two builds a Dim(2) grid using integers sent in inlets 0, 1.

Sending an integer guarantees an update to outlet 0 (currently it's doing redundant updates -- sorry)

External Picture Formats

Video4jmax 0.2.2 Documentation
by Mathieu Bouchard matju@sympatico.ca and
Alexandre Castonguay acastonguay@artengine.ca