GridFlow 0.9.0 - Reference Manual: Format Classes
Objects for Input/Output
method init (format, format_specific_part...) If no arguments given, creates an input object for an unspecified format. You then need to use the "open" command to link a format handler to it. If arguments given, the "open" command is immediately called with those arguments. 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. The format called "file" is a special shortcut that autodetects the type of file (by name suffix) and picks up the appropriate handler.
inlet 0 method open (filename) This is a shortcut for "open file" followed by a filename. The filename must contain a dot, else it will be seen as a handler name.
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 set (frame_number) selects one picture from a multi-picture format, to be displayed by the next 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 grid(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...) Obsolete. the word "option" is optional now.
inlet 0 method rewind () rewinds to beginning of file if applicable.
inlet 0 method loop (bool flag) controls the automatic looping of movies.
outlet 1 method int () frame number of frame just sent, for formats that have frame numbers.
outlet 1 method bang () tried to read a frame that does not exist (signals end of file)
method init (format, format_specific_part...) If no arguments given, creates an output object for an unspecified format. You then need to use the "open" command to link a format handler to it. If arguments given, the "open" command is immediately called with those arguments. 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 window" and "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 method open file () The format called "file" is a special shortcut that autodetects the type of file (by name suffix) and picks up the appropriate handler.
inlet 0 method open (filename) This is a shortcut for "open file" followed by a filename. The filename must contain a dot, else it will be seen as a handler name.
inlet 0 method grid (grid grid) this is format-specific. most formats expect grid(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...) Obsolete. Omit the word "option" now.
inlet 0 method 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.
inlet 0 method rewind () rewinds to beginning of file if applicable. will overwrite the previous data.
outlet 0 method bang () sent when a complete grid has been received.
This object class only works with a X11-based version of Pd. (e.g. on Linux, BSD, but not MacOS X).
Similar to [#out window], except it creates an inset in the patch you put it in, and a scaled version of the picture appears in the inset. It also emits the same messages as [#out window] and automatically scales cursor position according to the current scale factor. The scale factor is decided automatically.
method init (int height, int width)
All other methods are as in [#out window].
This will process the "position" messages emitted by [#out] or [#peephole] in useful ways.
outlet 0 method list () y,x coords of a click
outlet 1 method list () y,x coords of a drag (any button is kept pressed)
outlet 2 method list () y,x coords of an unclick
outlet 3 method list () y,x coords of a move (no button is pressed)
outlet 4 method float () button 1 status
outlet 5 method float () button 2 status
outlet 6 method float () button 3 status
outlet 7 method float () wheel difference: -1 = roll up; 1 = roll down.
Works about like [#in videodev] except you can right-click-open it to access all of the camera settings visually.
Picture/Movie Formats
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.
method open ppm gzfile (symbol filename) same but for .ppm.gz files
method grid (grid(rows columns {r g b}) grid) values 0-255
Support for RGB-24 (3 channels) and RGBA-32 (4 channels)
method open targa file (symbol filename) opens the specified file, taken from the current directory.
method open targa gzfile (symbol filename) same but for .tga.gz files
method grid (grid(rows columns 3) grid) RGB-24
method grid (grid(rows columns 4) grid) RGBA-32
Support for RGB non-progressive
method open jpeg file (symbol filename) opens the specified file, taken from the current directory.
method grid (grid(rows columns 3) grid) RGB-24
Support for RGB non-progressive
method open png file (symbol filename) opens the specified file, taken from the current directory.
method grid (grid(rows columns 1) grid) Y-8 (greyscale)
method grid (grid(rows columns 2) grid) YA-16 (greyscale and transparency)
method grid (grid(rows columns 3) grid) RGB-24 (colour)
method grid (grid(rows columns 4) grid) RGBA-32 (colour and transparency)
Support for .mov files.
This format supports frame-seek and frame-tell.
Uses the HW-QuickTime library aka QuickTime4Linux (libquicktime.so). There is also a variant on the same library and that project is just called LibQuickTime.
Some versions of those libraries may include support for different codecs, and some also may support entirely different wrapper formats such as AVI.
On Macintosh, Apple QuickTime is used instead, but several of the following messages may not be available.
method open quicktime file (symbol filename)
method codec (symbol codec) Allowed values are at least: raw, jpeg, png, mjpa, yuv2, yuv4. Some other values may allowed, depending on the version of the library and which codec plugins are installed. Must be set before the first frame is written. only applies to [#out]. Choosing a codec is important because codecs influence greatly the speed of encoding, the speed of decoding, the size of the written file, and its fidelity to the original content. Note that there exist other Apple-QuickTime codecs that are not supported by HW-QuickTime.
method parameter (symbol key, int value) Sets special codec-specific settings. For example: "parameter jpeg_quality 75"
method framerate (int fps) Sets the framerate of the file. This is not used by GridFlow when reading a file, but other programs usually care.
method colorspace (symbol colorspace) Allowed values are rgb, rgba, bgr, bgra, yuv, yuva. Normally you don't need this.
method size (int height, int width) Forces a window size when writing. Usually this has to be used after setting the framerate and codec and before setting the codec-parameters. (Strange. Sorry.)
method force_size (int height, int width) forces a window size when reading. this is a workaround for a problem in HW-QuickTime.
support for .mpeg files
this format supports frame-seek and frame-tell.
Two different libraries are available for dealing with MPEG files. Those have different details, capabilities and quirks.
In any case, GridFlow does not support importing audio from those files.
If you use the HeroineWarrior library, you may open several mpeg files at once, but not with the GregWard library.
Libraries 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).
Supports Rewind and Frame Select.
method open mpeg file (symbol filename) opens the specified file, taken from the current directory.
This is GridFlow's special file format. This is the only I/O format that can hold anything that the [#store] object can.
This is the picture format that would support TCP connections if that feature actually worked. More on this later.
method open grid file (symbol filename) opens the specified file, taken from the current directory.
method open grid gzfile (symbol filename) same but for .grid.gz files
method open grid tcp (symbol hostname, integer port) dials an specified hostname/port on the InterNet or compatible network. the TCP protocol is used.
method open grid 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 type int32 () output will be as 32 bit signed integers.
method type uint8 () output will be as 8 bit unsigned integers.
method headerful () cancels "headerless" (and back to reading .grid)
method headerless (dimensions...) instead of reading .grid files with header, will read raw data, faking a .grid header to itself. It will use the hereby specified dimension list, as well as two other settings: type and endian.
When writing "raw" data, a file may be considered a long string of
base 256 digits (called bytes), but different computers have different
conventions for dealing with them:
method endian ()
- 1 : big: A number will be written starting with the biggest digit. This is the natural way on the Macintosh, Sun, Amiga, and so on.
- 2 : little: A number will be written starting with the smallest digit. This is the natural way on the Intel 386/Pentium.
- 3 : same: A number will be written in whichever way is more natural on this computer. The natural way is slightly faster to handle. This is the default setting.
Acquisition Devices
method open (device)
Video4Linux-1 devices, RGB-24 only. Variable picture size.
We have been testing it using cards of the BT-848 family, such as Miro DC10plus and Hauppauge WinTV, using the bttv.o linux driver. Also we have been testing using Logitech QuickCam (and similar Labtec hardware), but don't use the qce-ga driver, which is buggy and obsolete: the qc-usb works better.
Some hardware doesn't support RGB, so you may have to select a YUV colorspace (see below) and then use [#yuv_to_rgb]. Don't forget to also do [# min 255] and [# max 0].
If for some reason there's a bug that causes a driver to produce BGR instead of RGB, so that red and blue are swapped, you can swap them back by filtering through a RGB-BGR converter, such as [#inner * + 0 {3 3 # 0 0 1 0 1 0 1 0 0}].
color adjustments:
method brightness (0-65535 level)
method hue (0-65535 level)
method colour (0-65535 level)
method contrast (0-65535 level)
method whiteness (0-65535 level)
method get (symbol attr) gets a specific attribute. a message is sent through right outlet. valid attributes are: brightness, hue, colour, contrast, whiteness.
method get () gets all attributes.
other options:
method channel (integer )
method tuner (integer )
method norm (integer )
method frequency (integer )
method transfer (symbol(read|mmap) , integer )
- 1 : mmap: This is the normal (and fast) way of transferring pictures from the camera.
- 2 : read: Some cameras/drivers only support this instead of mmap.
method colorspace (symbol colorspace) Allowed values are: RGB24, YUV420P. Use this if your driver doesn't support RGB24.
method size (height, width) sets the input size, especially when using a video digitalizer device.
Window Output
supports 15,16,24,32-bit truecolor displays
now also support 8-bit indexed displays, using a private colormap configured as 3:3:2 RGB. When using 8-bit you can specify the "use_stripes" option to use a completely different color scheme involving R,G,B diagonal stripes, a kind of 6:6:6 RGB spread over three pixels.
If you are using Windows or MacOS 10: you will have to install a X11 server. This will emulate Unix display on your OS. (note: Unix systems also need a X11 server, but it's built-in and handles the video driver directly). In the case of MacOS 10 and QNX that both use non-X11 display technology on top of a basically Unix OS, the OS comes with a X11 server, but it may be on a "bundled software" CD.
method open x11 () synonym of "open x11 here".
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. Port number will be 6000 plus the display number, because of the X11 standard.
method grid (grid(rows columns {red green blue}) grid) 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 the design of Xlib, or if any of the connections involved crashes, then the whole program 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 out_size (integer height, integer width) changes the window's size, just like sending a grid dim(height,width,3) would. this affects the size of screen captures too.
method draw () forces a redraw of the window's contents.
method autodraw (0,1,2 level)
- 0 : draw() is never automatically invoked
- 1 : draw() is invoked after each grid is finished
- 2 : draw() is invoked incrementally after each row is received. (but buffering may cause lines to come in groups anyway)
method 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 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. This is also emitted when a mouse button is pressed.
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
NOTE: This message form may become longer in the future, but the already defined parts will stay the same.
outlet 0 method keypress (integer y, integer x, integer buttons, symbol keyname)
Similar to position above, but this is emitted when a keyboard key is pressed while this format handler's window is active. Keynames follow the X11 standard, similarly to PureData's [keyname] object. The only exception is that keynames that are digits get prefixed by a capital D so that they don't get mistaken for actual numbers.
NOTE: This message form may become longer in the future, but the already defined parts will stay the same.
outlet 0 method keyrelease (integer y, integer x, integer buttons, symbol keyname) Same as keypress but when a key gets released instead.
NOTE: This message form may become longer in the future, but the already defined parts will stay the same.
The equivalent of format x11 on MacOS 10.x, but with less features (sorry).
method open () opens a dim(240,320,3) rgb window (default).
method grid (grid(rows columns {red green blue}) grid) Sends image to screen. Window will be resized to fit the image exactly.
method open () Opens a dim(240,320,3) rgb window (default).
method grid (grid(rows columns {red green blue}) grid) Sends image to screen. Window will be resized to fit the image exactly.
method open aalib (driver, args...)
method grid (grid(rows columns {white}) grid) converts a greyscale image to an ascii image and possibly displays it. note that the image is typically downscaled by a factor of 2 by aalib itself.
method grid (grid(rows columns {ascii attr}) grid) the inverse of "dump". Both together in a loop allow to post-process aalib's buffer before displaying. Goes well with "draw", "autodraw".
method print (int y, int x, int attr, symbol text)
method autodraw () like X11's autodraw.
method draw () like X11's draw.
method dump () produces a Dim[y,x,2] grid whose two channels are ascii character codes and character attributes.
method open window () Equivalent to "open x11", but this can be set by putting a line like this in the config file: GridFlow.formats[:window] = GridFlow.formats[:x11] (and similarly other aliases can be created too)
GridFlow 0.9.0 Documentation
Copyright © 2001-2007 by Mathieu Bouchard
matju@artengine.ca