PMS-grabber package 0. Copyright ============ (c) Wolfgang Koehler, wolf@first.gmd.de, Dec. 1994 Kiefernring 15 14478 Potsdam, Germany 0331-863238 The "GNU Public Lincense" policy applies to all programs of this package This package comes without any warranty, as it is. It may be freely copied and distributed to whatever - except military - purposes. 1. Purpose ========== This package was developed to make use of the PC frame grabber card "Pro MovieStudio" (PMS) by MediaVision under Linux. My main task is the online grabbing of single pictures for an image processing program. However, it can also be used as a video-viewer, assumed you have a really fast computer - otherwise the frame rate will be boringly slow (if you want to have a fast view you may resize the window to say 100x80 pixel - the smaller the higher frame rates you will get). This slowness is mainly due to the concept of this card : the captured image is transferred through memory access and not with a feature connector directly to the video card like other frame grabber cards do. The program is in an experimental state and will be developed further. Remember, however, my main intention is to use it for image processing. The program is not a driver so it requires no kernel rebuilding, it runs simply as a program at user level. On the other hand this means there is no protection against misuse. If you start it twice on the same computer it will probably crash. 2. Main features of the programs ================================ * captures frames of the "Pro MovieStudio" frame grabber card * runs under X-Window in a normal window with various setting options * online view or capturing of single frames * arbitrarily resizing of view window (via window manager) (up to 500x500) * up to 256 colors on display (the upper limit of X-window) * frame grabbing in rgb555-mode (32768 colors) (24bit TrueColor also possible) * computing of optimal color palettes from a given image * popup menu for all option settings of the PMS-card * popup menu for viewing and editing the registers (only for experiments) * simple image analyzing tools (with mouse cursor in view window) * save and load functions for ximages, captures and palettes * comes together with a generally useful X-window package * a standalone program for displaying saved images that runs without PMS-card on any computer with X-window 3. Basics of the use of the PMS-card with Linux ================================================ The part of the program that deals directly with the card was adopted from another program from MediaVision ("grabber.c", "SetMVV.c"). So don't blame me for this code. I modified it in a few points: I wanted not to bother myself with interrupts under Linux so I use a polling mechanism. The capturing function was rewritten from Assembler to C. The Pro MovieStudio board has to be configured by software since it has no jumpers or DIPs. It uses 3 IO-ports which are selected by writing to port 0x9A01. This means under Linux : ** IT CAN ONLY BE RUN AS ROOT **. You may set the SUID-bit to enable normal users to use it. By default the used ports are 0x250 .. 0x252. If you need other ports because they are used by another card, simply change the variable "mvpi" in "grabber.c". Besides this the PMS uses a memory window of 4k in lower PC memory. Default value is 0xD0000. Since Linux usually does not utilize this region there should be no problem. Otherwise, again if it conflicts with another hardware driver simply change "mvv_base" in "grabber.c". possible resolutions : I have not been able to get a horizontal resolution above 512 - this corresponds to the buffer size of 1k. If anyone can tell me if that is possible or principally not I would appreciate it. The original source from MediaVision gives not much help for this. Also, setting vertical resolution above 255 is a little bit tricky. I solved this by capturing two half frames - one with even the other with odd lines - and interlacing them. This can give muddled images in life mode if the frame rate is too high. colors : The PMS has several color modes : up to True Color with 8 bit for each basic color red,green,blue. I used only the 5bit-rgb mode ie. each pixel is transmitted as 16bit word (with the highest bit 0). The problem is that X can only show up to 256 colors at once, regardless of the video card you have. For displaying images I use a palette vector, ie. a mapping from 32**3 to 256 X-color values. Each X-color entry again corresponds to RGB-value which is set by XStoreColor. The use of the right palette is a quite complicated task. You also have to keep in mind that a X-application should be co-operative with respect to limited resources like color tables. Ie. if one application grabs all free entries all others programs running parallel will fail. The program "PMS-view" does exactly this : it grabs all it can get. However, the resulting color mapping is nevertheless quite poor. The standard palette which is used by default uses a mapping to RGB332 values, ie. red and green are represented as 3 bit values, blue by 2 bits. However, there is a method implemented to generate optimized palettes for given images, which usually produces very good results. It is accessible through the "eval"-menu (see below). compression : the PMS allows to compress images, this feature is not used here. 3. Building & Files =================== The package you got should contain the following files: PMS-view.c : main program for online viewing of images from the PMS-board, controlling the settings, etc. see below image-view.c : a standalone program for displaying saved images, it may be run at any computer with X-windows (not Linux-specific) and requires no PMS-card view.c : view.h : functions for displaying an image under X-window Makefile : for building the executables SetMVV.c : basic setting functions for PMS-board, included by grabber.c evaluation.c : palette & image processing; eval-popup evaluation.h grabber.c : Linux specific, port setting, memory mapping, capture function grabber.h ximage.c : functions for XImage file saving & loading window.h : window.c : all functionality to deal with X-Window, display, buttons, popup menus, pulldown menus, etc. eventnames.h, icon.h : belong to window.c image.pix : a sample picture (my little niece) that should demonstrate the power of the palette computing algorithm (340x255 pixels in 203 colors) loadable from the file menu in PMS-view or image-view (see below) For a building it should normally be sufficient to invoke "make". 4. program PMS-view.c ===================== This is the demonstration program for the whole package. Here I will shortly describe how to use its control buttons. After starting a window pops up with life video from the PMS-card (if all settings are correct). On the top is a menu bar with control buttons : grab : capture a single frame (not in life mode) life : a toggle button between continuous capture / single frame capture MVV set : gives a popup menu for all basic functions of the PMS card (frame rate, horizontal start, vertical start, Hue, Color Killer, switch sensitivity, ....) It has 10 scrollbars for numerical values, 5 toggle buttons and 10 pulldown menues for selection. The "default" button resets them all to the initial values. (the initial values can be changed in "SetMVV.c" by modifying the 4th column of struct "option_vector" to fit personal needs) Note: after a selection is made a new capture is automatically done to show the effect (in continuous mode not necessary). Setting "frame rate" only has the effect that too low frame rates will result in grabbing the same frame more than once. Too high rates have almost no effect at all. Not all selections are active. MVV regs : gives a popup menu for viewing and playing with the registers of the PMS. This is only useful for experimenting with the board but not for normal operation. There is also a small edit window "edit regs" which allows to set a register interactively (most useful in life mode). To change a value enter hex. register index followed by dec. value. If value > 255 the high byte is set into reg+1. The edit window accepts following keys : ESC (clears), Backspace, delete, Enter (confirms). Note: the edit only works if the cursor is inside the small frame ! The display color of a register changes to red if the value changes. The reset button sets all back to black. set pal : is a pulldown menu for selecting the display palette. (The capture mode is not affected from this). You may choose between : standard palette (RGB332), grey scale palette (96 scales), and captured palette (see below for explanation) eval : gives a popup menu, mainly for palette computation first it has a scrollbar to set the numerical value of the colors to use for this palette. To perform computing use the button "new palette" The computing method uses the current image displayed to choose those colors for display that are mostly relevant for the image. The method is a recursive splitting of the 3-dimension color space. As optimizing criterion the resulting variance reduction is used. However, while this gives quite brilliant results for a single image, or similiar images the computed palette will be useless for other images. file : a pulldown menu for saving and loading files. Each entry pops up a file selection box (either for reading or writing) Before overwriting existing files a confirmation is queried. The file names should be "*.pix" "*.cap555" and "*.pal555". "image.pix" uses a format similiar to XImage, ie. one byte per pixel, "capture" uses the direct capture format as rgb555, "palette" saves a computed palette together with its XColor values. Note that if you load a "image"-file there is no corresponding capture in the memory. That means the info line will display garbage. Secondly, loading an image file requires a certain number of free colors (depending on the saved file). If there are too much allocated by other X-programs the loading will fail. At the bottom of the display there is an "info line" which shows some statistics of the captured frame, mainly the times for capturing and displaying in life mode. If you switch to single mode you are able to inspect the captured image. The info line then shows the RGB- values of the pixel under the cursor, the luminance value, the percentages of each color (or the displayed color normalized to the range 0..31). Resizing : The usual window resizing feature (from the window manger by drawing the window borders) performs an resolution adaption. That means, if you make the window smaller the resolution of the grabbed frame will also diminish which results in a drastic acceleration of the grabbing. 5. program image-view ===================== This program is an extract of PMS-view that implements a viewer for saved images independently of the PMS-board. Therefore it is also usable on any computer that runs X-window. It has the buttons "set palette" , "evaluate" and "file" which work like described above. If you start it in this directory it will come up with the loaded image from "franzi.pix". 6. window functionality ======================= This functionality is implemented in "window.c" and "window.h". I will not describe it here, since this is part of a larger package which will be published these days (possibly under comp.sources.misc). If you want to understand more have a look at window.c and window.h. If you want to get the whole thing beforehand send me an EMail. 7. personal remarks =================== If you find this package useful it would be nice to send me message about this. If you have improvements or remarks that can be considered of public interest send them to me I will try to implement them and possibly republish the improved package. However, I'm not sure how widespread this PMS-board so I don't know how many Linuxers might use it.