GridFlow 0.6.3 - reference




GridFlow 0.6.3 - reference index

	Objects for Input/Output Objects for Generating Objects for Computing @scan Objects for Coordinate Transforms Objects for Reporting @print rubyprint printargs Objects for Picture Processing Special Objects rtmetro pingpong External Picture Formats format sdl @out Objects for Scripting ruby class FObject extending Data ruby class GridObject extending FObject ruby class BitPacking Objects for Internals C++ class GridInlet C++ class GridOutlet C++ class Dim C++ class Grid C++ class Operator1 C++ class Operator2 C++ class GridClass C++ class GFBridge

Objects for Input/Output
class @in
		method init () Creates an input object for an unspecified format. You need to use the `open` command to decide that. Remember that most formats produce Dim[rows,columns,3] grids with 0-255 values. (Most.) inlet 0 method open (format, format_specific_part...) This is the command that gives a particular resource to a @out object. This is done through a "format" (there is a list of formats in this manual). The other arguments depend on the chosen format. The format may be a file format or a protocol or a hardware device, etc. inlet 0 method close () close may be necessary if you operate on "/dev/video", which can only be read by one at a time. otherwise it's usually not necessary. inlet 0 method int (frame_number) selects one picture from a multi-picture format and then does the same as a bang. inlet 0 method bang () sends a grid through the outlet. the grid may be the result of reading from a file, acquiring from a device, capturing from the screen etc. this is format-specific. most formats produce dim(rows columns {red green blue}). In formats that read from a file, reading another picture will continue if there are several pictures in the same file, but if the end of file is reached instead, it will rewind and send the first picture again. see section "External Picture Formats". inlet 0 method option (symbol selector, stuff...) for format-specific options. (usually in devices that masquerade as formats). see section "External Picture Formats".
class @out
		method init () Creates an output object for an unspecified format. You need to use the `open` command to decide that. Remember that most formats expect dim(rows,columns,3) grids with 0-255 values. (Most.) method init (integer rows, integer columns) This alternate way to create an @out automatically calls "open x11 here" and "option out_size rows columns". inlet 0 method open (format, format_specific_part...) This is the command that gives a particular resource to a @out object. This is done through a "format" (there is a list of formats in this manual). The other arguments depend on the chosen format. The format may be a file format or a protocol or a hardware device, etc. inlet 0 grid this is format-specific. most formats expect dim(rows columns {red green blue}). In formats that write to a file, sending a 2nd picture overwrites the first. see section "External Picture Formats". inlet 0 method close () closes the file. usually not necessary. inlet 0 method option (symbol selector, stuff...) for format-specific options. (usually in devices that masquerade as formats). see section "External Picture Formats". inlet 0 method option timelog (0,1 status) when status=1, current time (unix clock) and time since last frame-end are printed in the console. when status=0, it is off. default is 0. outlet 0 method bang () sent when a complete grid has been received.
class @import
		This object allows you to import non-grid jMax data, such as integers and lists of integers. This object also reframes/resyncs integers and grids so that multiple grids may be joined together, or single grids may be split. method init (list(+integer) dims) a list specifying a grid shape that the numbers will fit into. inlet 0 method int () begins a new grid if there is no current grid. puts that integer in the current grid. ends the grid if it is full. the constructed grid is not stored: it is streamed. the stream is buffered, so the output is in packets of about a thousand numbers. inlet 0 method reset () aborts the current grid if there is one. inlet 0 grid dim(dims...) this is the equivalent of filtering this grid through an @export object and sending the resulting integers to this @import object, except that it's about 10 times faster. inlet 1 grid dim(rank) this grid is a dimension list that replaces the one specified in the constructor. outlet 0 grid the grid produced from incoming integers and/or grids.
class @export
		this object is the opposite of @import. method init () this object is not configurable because there isn't anything that could possibly be configured here. inlet 0 grid dim(dims...) transforms this grid into a sequence of integer messages. outlet 0 method int () elements of the incoming grid.
class @export_list
		this object is another opposite of @import, which puts all of its values in a jMax list. method init () this object is not configurable because there isn't anything that could possibly be configured here. inlet 0 grid dim(dims...) transforms this grid into a single message containing a list of integers. outlet 0 method list () elements of the incoming grid.
class @two
		holds two values, defaulting to (0,0). each time one is changed (by sending an integer in that inlet), a Dim(2) grid of those values is sent through the outlet. method init () no arguments. inlet 0 method int () inlet 1 method int () outlet 0 grid dim(2)
class @three
		holds three values, defaulting to (0,0,0). each time one is changed (by sending an integer in that inlet), a Dim(3) grid of those values is sent through the outlet. method init () no arguments. inlet 0 method int () inlet 1 method int () inlet 2 method int () outlet 0 grid dim(3)
class @four
		holds four values, defaulting to (0,0,0,0). each time one is changed (by sending an integer in that inlet), a Dim(4) grid of those values is sent through the outlet. method init () no arguments. inlet 0 method int () inlet 1 method int () inlet 2 method int () inlet 3 method int () outlet 0 grid dim(4)


Objects for Generating
class @for
		when given scalar bounds, works like a regular [for] object plugged to a [@import] tuned for a Dim(size) where size is the number of values produced by a bang to that [for]. when given vector bounds, will work like any number of [for] objects producing all possible combinations of their values in the proper order. This replaces the old [@identity_transform] object. method init (integer from, integer to, integer step) inlet 0 grid dim(index) replaces the "from" value and produces output. inlet 1 grid dim(index) replaces the "to" value. inlet 2 grid dim(index_steps) replaces the "step" value. outlet 0 grid dim(size) where size is floor((to-from+1)/step) [for scalar bounds] outlet 0 grid dim(size,dimension) where size is floor((to-from+1)/step) [for vector bounds]


Objects for Computing
class @
		This object outputs a grid by computing "in parallel" a same operation on each left-hand element with its corresponding right-hand element. This is a massively parallel version of jMax's builtin arithmetic operators. In case you wonder, it's only parallel in the sense that all those computations are independent; there's no guarantee about how many of them will actually be computed at once. method init (symbol operator, integer\|grid value) the operator is one picked in the table of the 30 two-input operators. the value (optional, zero by default) becomes the initial value of the right inlet. it may be a grid. inlet 0 grid dim(dims...) on each element of this grid, perform the operation together with the corresponding element of inlet 1. in the table of operators (at the top of this document) elements of inlet 0 are called "A" and elements of inlet 1 are called "B". the resulting grid is the same size as the one in inlet 0. inlet 1 grid dim(dims...) any grid, preferably shaped like the one that will be put in the left inlet, or like a subpart of it (the contents will be redim'ed on the fly to fit the grid of inlet-0, but the stored grid will not be modified itself) inlet 1 method int () stores a single int in the right inlet; the same int will be applied in all computations; this is like sending a Dim(1) or Dim() grid with that number in it. outlet 0 grid
class @!
		This object computes a grid by computing "in parallel" a same operation on each element of the grid. method init (symbol operator) the operator is one picked in the table of the 3 one-input operators. inlet 0 grid outlet 0 grid
class @fold
		1 : [@fold +] computes totals 2 : [@fold inv+] is an alternated sum (+/-) 3 : [@fold * 1] can compute the size of a grid using its dimension list 4 : [@fold & 1] can mean "for all" 5 : [@fold \| 0] can mean "there exists (at least one)" 6 : [@fold ^ 0] can mean "there exists an odd number of..." 7 : [@fold ^ 1] can mean "there exists an even number of...". method init (symbol operator, integer base, grid right_hand) the base value is optional and defaults to 0. the operator is one from the table of two-input operators. inlet 0 grid dim(dims..., last) replaces every Dim(last) subgrid by the result of a cascade on that subgrid. Doing that with base value 0 and operation + on grid "2 3 5 7" will compute ((((0+2)+3)+5)+7) find the total "17". produces a Dim(dims) grid. inlet 1 method int () changes the base value to use.
class @scan
		[@scan +] computes subtotals. method init (symbol operator, integer base) the base value is optional and defaults to 0. the operator is one from the table of two-input operators. inlet 0 grid dim(dims..., last) replaces every Dim(last) subgrid by all the result of a cascade on that subgrid. Doing that with base value 0 and operation + on grid "2 3 5 7" will compute 0+2=2, 2+3=5, 5+5=10, 10+7=17, and gives the subtotals "2 5 10 17". produces a Dim(dims,last) grid. inlet 1 method int () changes the base value to use.
class @outer
		method init (symbol operator, grid value) the operator must be picked from the table of two-input operators. the grid is optional and corresponds to inlet 1. inlet 0 grid dim(anyA...) produces a grid of size Dim(anyA..., anyB...), where numbers are the results of the operation on every element of A and every element of B. the resulting array can be very big. Don't try this on two pictures (the result will have 6 dimensions) inlet 1 grid dim(anyB...) stores the specified grid, to be used when inlet 0 is activated. 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 two-input 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))
class @inner
		think of this one as a special combination of [@outer], [@] and [@fold]. this is one of the most complex operations. It is very useful for performing linear transforms like rotations, scalings, tilts, and color remappings. A linear transform is done by something called matrix multiplication, which happens to be [@inner * + 0]. This object has been renamed from @inner to @inner2 because a different @inner object will be added in the future. method init (symbol op_para, symbol op_fold, integer base, grid right_hand) op_para and op_fold are two operators picked from the table of two-input operators. the base value has to be specified (has no default value yet). inlet 0 grid dim(anyA..., lastA) Splits the Dim(anyA...,lastA) left-hand grid into Dim(anyA...) pieces of Dim(lastA) size. Splits the Dim(firstB,anyB...) right-hand grid into Dim(anyB...) pieces of Dim(firstB) size. On every piece pair, does [@] using the specified op_para operation, followed by a [@fold] using the specified op_fold operator and base value. creates a Dim(anyA...,anyB...) grid by assembling all the results together. (note: lastA must be equal to firstB.) inlet 1 method int () changes the base value to that. inlet 2 grid dim(anyB..., lastB) changes the right-hand side grid to that.
class @inner2
		a variant on @inner. This object used to be called @inner. method init (symbol op_para, symbol op_fold, integer base, grid right_hand) op_para and op_fold are two operators picked from the table of two-input operators. the base value has to be specified (has no default value yet). inlet 0 grid dim(anyA..., lastA) Splits the Dim(anyA...,lastA) left-hand grid into Dim(anyA...) pieces of Dim(lastA) size. Splits the Dim(anyA...,lastB) right-hand grid into Dim(anyB...) pieces of Dim(lastB) size. On every piece pair, does [@] using the specified op_para operation, followed by a [@fold] using the specified op_fold operator and base value. creates a Dim(anyA...,anyB...) grid by assembling all the results together. (note: lastA must be equal to lastB.) inlet 1 method int () changes the base value to that. inlet 2 grid dim(anyB..., lastB) changes the right-hand side grid to that.


Objects for Coordinate Transforms
class @redim
		method init (list(+integer) dims) a list specifying a grid shape that the numbers will fit into. (same as with @import) inlet 0 grid dim(dims...) the elements of this grid are serialized. if the resulting grid must be larger, the sequence is repeated as much as necessary. if the resulting grid must be smaller, the sequence is truncated. then the elements are deserialized to form the resulting grid. inlet 1 grid dim(rank) this grid is a dimension list that replaces the one specified in the constructor. (same as with @import) outlet 0 grid redimensioned grid potentially containing repeating data. example: 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.
class @store
		A @store object can store exactly one grid, using the right inlet. You fetch it back, or selected subparts thereof, using the left inlet. method init (int32 \| uint8 number_type) The number type argument is optional and by default is int32, which allows the usual range of plus/minus two billions. With uint8, values are wrapped into the 0..255 interval, and stored in four times less memory. inlet 0 method bang () the stored grid is fully sent to the outlet. inlet 0 grid dim(dims..., indices) in this grid, the last dimension refers to subparts of the stored grid. sending a Dim(200,200,2) on a @store that holds a Dim(240,320,3) will cause the @store to handle the incoming grid as a Dim(200,200) of Dim(2)'s, where each Dim(2) represents a position in a Dim(240,320) of Dim(3)'s. therefore the resulting grid will be a Dim(200,200) of Dim(3) which is a Dim(200,200,3). in practice this example would be used for generating a 200200 RGB picture from a 200200 XY map and a 240320 RGB picture. this object can be logically used in the same way for many purposes including color palettes, tables of probabilities, tables of statistics, whole animations, etc. inlet 1* grid dim(dims...) the received grid is stored. if the storage type is uint8, the input is filtered to fit 0..255. grids as stored, as indexed, or as assembled from multiple indexings.
class @identity_transform
		OBSOLETE AND REMOVED. USE @for INSTEAD.
class @scale_to
		method init () no arguments. inlet 0 grid a 3-channel picture to be scaled. inlet 1 method int () a height. inlet 2 method int () a width. outlet 0 grid a scaled 3-channel picture. @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.
class @scale_by
		method init (+integer factor) factor is optional (2 by default). method init (factor_y, factor_x) future use: will scale by those factors. inlet 0 grid dim(y x {r g b}) identical to @scale_to with arguments that are exactly twice those of the incoming grid. It is several times faster. outlet 0 grid dim((factory) (factorx) {r g b})
class @spread
		typically you plug a @identity_transform into this object, and you plug this object into the left side of a @store. it will scatter pixels around, giving an "unpolished glass" effect. method init () no arguments. inlet 0 grid a coordinate map. inlet 1 method int () a spread factor. outlet 0 grid a coordinate map. @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.


Objects for Reporting
class @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. method init () no arguments. inlet 0 grid dim(dims...) ignores any data contained within. sends a grid dim(length of dims) containing dims. outlet 0 grid dim(rank) the list of dimensions of the incoming grid.
class @print
		method init () inlet 0 grid dim(dims...) prints the dimensions of the grid. prints all the grid data if there are 2 dimensions or less.
class rubyprint
		method init () inlet 0 method () prints the message to the console.
class printargs
		method init (any...) prints everything.


Objects for Picture Processing
class @convolve
		this is the object for blurring, sharpening, finding edges, embossing, and many other uses. method init (symbol op_para, symbol op_fold, integer base, grid right_hand) inlet 0 grid dim(rows columns rest...) splits the incoming grid into dim(rest...) parts. for each of those parts at (y,x), a rectangle of such parts, centered around (y,x), is combined with the convolution grid like a [@] of operation op_para. Then each such result is folded like [@fold] of operation op_fold and specified base. the results are assembled into a grid that is sent to the outlet. near the borders of the grid, coordinates wrap around. this means the whole grid has to be received before production of the next grid starts. inlet 1 grid dim(rows2 columns2) this is the convolution grid and it gets stored in the object. rows2 and columns2 must be odd numbers. outlet 0 grid dim(rows columns rest...)
class @contrast
		method init () no arguments. inlet 0 grid dim(rows columns channels) produces a grid like the incoming grid but with different constrast. @contrast adjusts the intensity in an image. resulting values outside 0-255 are automatically clipped. inlet 1 method int () this is the secondary contrast. it makes the incoming black correspond to a certain fraction between output black and the master contrast value. no effect is 256. default value is 256. inlet 2 method int () this is the master contrast. it makes the incoming white correspond to a certain fraction between output black and output white. no effect is 256. default value is 256. outlet grid dim(rows columns channels)
class @posterize
		@posterize reduces the number of possible intensities in an image; it rounds the color values.The effect is mostly apparent with a low number of levels. method init () no arguments. inlet 0 grid dim(rows columns channels) produces a posterized picture from the input picture. inlet 1 method int () this is the number of possible levels per channel. the levels are equally spaced, with the lowest at 0 and the highest at 255. the minimum number of levels is 2, and the default value is 2. example: simulate the 216-color "web" palette using 6 levels. simulate a 15-bit display using 32 levels.


Special Objects
class rtmetro
		this is like jMax's builtin metro object. metro ensures that there is at least a given delay between bangs. rtmetro ensures that on average there is a given delay between bangs: it will compensate too long delays by shorter delays. of course this won't work if the system cannot keep up with the amount of work.
class pingpong
		send a value in inlet 1 first. if successive increasing values are sent in inlet 0, then output values will be successive increasing until they reach the right inlet value and then decrease to zero. the formula is stateless and so same inputs give always same output.
class @global
		objects of this class do nothing by themselves and are just an access point to features that don't belong to any object in particular. method profiler_reset () resets all the time counters. method profiler_dump () displays the time counters in decreasing order, with the names of the classes those objects are in. this is an experimental feature. like most statistics, it could be vaguely relied upon if only you knew to which extent it is unreliable. more on this in a future section called "profiling".


External Picture Formats
class format ppm @in/@out
		Subformat P6 only. Max-number can only be 255 (24-bit RGB). method open ppm file (symbol filename) opens the specified file, taken from the current directory or one of the jMax-specified data directories. grid dim(rows columns 3) values 0-255
class format targa @in
		Support for RGB-24 (3 channels). If you bug me a bit you'll get ARGB-32 too. method open ppm file (symbol filename) opens the specified file, taken from the current directory or one of the jMax-specified data directories. grid dim(rows columns 3) values 0-255
class format mpeg @in
		Support for MPEG Video Stream only. Does not support MPEG System Stream (that is, files that contain both audio and video). Can only open one file at once (libmpeg.so limitation). May scream error messages in a rude way. By opposition to PPM and TARGA, this format driver only allows a single MPEG stream per file (you cannot "cat" several MPEG files together). Rewind / Frame Select not supported. method open mpeg file (symbol filename) opens the specified file, taken from the current directory or one of the jMax-specified data directories.
class format grid @in/@out
		method open file (symbol filename) opens the specified file, taken from the current directory or one of the jMax-specified data directories. method open tcp (symbol hostname, integer port) dials an specified hostname/port on the InterNet or compatible network. the TCP protocol is used. method open tcpserver (integer port) waits for a call (and answers) for this port on the local machine via InterNet or compatible network. Answers the call. method option type int32 () output will be as 32 bit signed integers. method option type uint8 () output will be as 8 bit unsigned integers. This is GridFlow's special file format. This is the only I/O format that can hold absolutely anything that the [@store] object can. However this can only be stored in 32 bits-per-value. This is the only picture format that currently supports TCP connections. This is still somewhat clunky: the socket only opens in client mode only; and upon bang, jMax freezes until the whole grid is received.
class format videodev @in
		method open (device) method open noinit (device) This is the same except it is gentle with bad-tempered drivers. Video4Linux-1 devices, RGB-24 only. Variable picture size. should work for bttv based cards and the dc1/dc10plus from Miro. If you suffer from color inversion, you may feed the list "`3 3 # 0 0 1 0 1 0 1 0 0`" to the right side of a `[@inner2 * + 0]`. Use that @inner2 object as a RGB-BGR converter. color adjustments: method option brightness (0-65535 level) method option hue (0-65535 level) method option colour (0-65535 level) method option contrast (0-65535 level) method option whiteness (0-65535 level) other options: method option channel (integer ) method option tuner (integer ) method option norm (integer ) method option frequency (integer ) method option transfer mmap () This is the normal (and fast) way of transferring pictures from the camera. method option transfer read () Some cameras/drivers only support this instead of mmap. method option size (height, width) sets the input size, especially when using a video digitalizer device
class format sdl @out
		method open () opens a dim(480,640,3) rgb window. grid dim(rows columns {red green blue}) sends frame to screen. window is NOT resized.
class format x11 @in/@out
		method open x11 here () connects to the default X11 server, according to your environment variable "DISPLAY". method open x11 local (integer display_number) connects to a display server on this machine. method open x11 remote (symbol host_name, integer display_number) connects to a remote X11 display server using TCP. Sorry, IP addresses are not supported (jMax limitation). Port number will be 6000 plus the display number, because of the X11 standard. grid dim(rows columns {red green blue}) resizes the window to the size of the grid; encodes that grid in the display's pixel format; also displays it if autodraw > 0 the values must be in range 0-255, or else they will be "wrapped". Destroying the object (or sending "close") should close the window. Because of how jMax works, this may be delayed until you do something else. because of the design of Xlib, or if any of the connections involved crashes, then the whole program (fts) has to be terminated. (don't you love xlib). Something similar happens if you close any of the windows yourself, but IIRC this could be fixed. only one window may be used per connection (to simplify matters; this doesn't reduce flexibility). there is an additional argument that may be added to every "open" message; if you don't put it, a new toplevel window is created. if you put "root" then the screen's wallpaper will be used instead (it may fail to work with some popular window managers). You can also put a window number, e.g. `0x28003ff`, you may connect to an existing window; you can find out the number of a window by using a tool like `xwininfo`, part of X11 standard tools. method option out_size (integer height, integer width) changes the window's size, just like sending a grid dim(height,width,3) would. method option draw () forces a redraw of the window's contents. method option autodraw (0,1,2 level) 0 : option draw() is never automatically invoked 1 : option draw() is invoked after each grid is finished 2 : option draw() is invoked incrementally after each row is received. (but buffering may cause lines to come in groups anyway) method option setcursor (0..63 cursor) Selects one of the 64 predefined cursors of X11. (Note that if your cursor table has them numbered from 0 to 126 using only even numbers, then those cursor numbers are all doubled compared to the ones GridFlow uses.) method option hidecursor () This makes the cursor invisible. outlet 0 method position (integer y, integer x, integer buttons) This is emitted every time the cursor moves inside the window connected to this format handler. This is also emitted when the cursor is dragging from inside to outside the window. The y and x coordinates are relative to the upper right corner of the window. Specific button states may be extracted from the button value by applying [>> buttonnumber] and then checking whether the result is odd. Button numbers normally are: 0 : Shift 1 : CapsLock 2 : Control 3 : Alternate 4 : NumLock 5 : ??? 6 : Meta 7 : ScrollLock 8 : Left Button 9 : Middle Button 10 : Right Button 11 : Wheel Up 12 : Wheel Down


Objects for Scripting
class ruby class FObject extending Data
		Provides inlets and outlets to Ruby Objects.
class ruby class GridObject extending FObject
		Provides grid support to FObjects.
class ruby class BitPacking
		A BitPacking is a simple two-way converter between different numeric layouts.


Objects for Internals
class C++ class GridInlet
		GridInlets represent inlets that accept grids.
class C++ class GridOutlet
		GridOutlets represent outlets that send grids.
class C++ class Dim
		Dim represents a list of dimensions.
class C++ class Grid
		Grid represents a grid that is fully stored in memory.
class C++ class Operator1
		This represents a one-input operator.
class C++ class Operator2
		This represents a two-input operator.
class C++ class GridClass
		This represents a class of GridObjects.
class C++ class GFBridge
		This holds linkage information about jMax and PureData and such.


GridFlow 0.6.3 Documentation by Mathieu Bouchard matju@sympatico.ca and Alexandre Castonguay acastonguay@artengine.ca

GridFlow 0.6.3 - reference index

Objects for Input/Output

Objects for Generating

Objects for Computing

Objects for Coordinate Transforms

Objects for Reporting

Objects for Picture Processing

Special Objects

External Picture Formats

Objects for Scripting

Objects for Internals