SpcaView & SpcaTools Howto

1 Overview:

This set of tools are provide to test WebCam under Linux. Especially camera based on Sunplus chips, but that should work with some others cameras too.You need knowledge of Linux to use these tools and we don't provide any GUI interface for a large public area. These tools are design to: test, improve, perform our Kernel module in a lot of situations and provide usefull API for developer . As others projects in the Linux World we don't have any help, documentation from SunPlus compagny. All that great work use Reverse Engeneering to provide interoperabilities of our WebCam device. At this times, we support up to 40 Webcams from a lot of compagnies: (Aiptek, Mustek, Intel, Grandtec, Maxell, Genius, Dlink, Kodak, Creative, Logitech, Benq, ViewQuest.. ) and only one driver can deal with all, strange Linux World :)

Our kernel module spca50x or spca5xx is developed outside the kernel tree. that way provide a more reactive stuff according our support product life, we are more free, to develop here part of code like specific decompressor .

Why spca50x ,spca5xx ? spca50x was originally developed by Joel Crip on the Omnivision OV511 code.it is the official branch .spca5xx is an experimental stuff, i have begin in january 2003, i don't need to start another project with the same objective, so when that stuff is know to be stable, it will be integrate in the spca50x CVS tree. I did not have any responsabilities if that stuff, become or not in a release, ask the maintener Miah Gregory for that. At the moment spca50x is know to be very ``static'' and spca5xx very ``reactive'' .

Also if your distro clearelly patch the kernel and become uncompatible with the others Linux stuff.we cannot offer support . The best way get a vanilla kernel from http://www.kernel.org it should work with our module.

 

1.1 Camera Type

Our webcams are all USB and can be managed in three familly of chips who stream nativelly in :

Jpeg	Yuv	Bayer
Spca500	Spca501	Spca561a
Spca504a	Spca505
Spca504b	Spca506
Spca533a	Spca508

Yuv and Bayer can be encoded with specific compressor from Sunplus. As we don't know that proprietary stuff ,we cannot provide any support of the compressed mode, we use instead uncompressed stream.

Jpeg is more atractive that we know how the stream is encoded . A peace of code from the bootsplash project as be rewrite to support our raw jpeg stream ( Michael Shroeder (Suse), Till Adam, Michel Xhaard).

 

1.2 Probing the Camera

At the USB probe function ,Webcam device is registered and the struct provide :

 

• spca50x->bridge the know chip
• spca50x->desc camera modele identifier
• spca50x->cameratype what stream we are in use

Some Webcam have a know sensor we can access trought i2c bus the struct register in

 

• spca50x-sensor the know sensor chip

Spca50x->sensor = SENSOR_INTERNAL mean we don't care about sensor (unknow or didn't have any know command)

Each Webcam is now registered and should work with the driver.

 

1.3 What the driver do ?

 

1.3.1 V4L layer

The first step provide a V4L layer to the userspace software .That mean Ioctl will be implemented to provide different kind of choice : Palette ,Capture Size, Picture setting.

All that chips didn't have the same capabilities:

Palette setting we courrently support for all cameras :

 

• VIDEO_PALETTE_RGB565 16 Bits Video palette
• VIDEO_PALETTE_RGB24 24 Bits Video palette
• VIDEO_PALETTE_RGB32 32 Bits Video palette ( Not really a good idea )
• VIDEO_PALETTE_YUV420P Planar yuv 4.2.0 palette (Best performance according Bandwith)
• VIDEO_PALETTE_RAWJPEG 8 Bits raw stream ( Not really a good idea some webcam are not jpeg and can be use in raw mode )

 

1.3.2 Capture Size:

All camera didn't support nativelly the whole set of picture size setting .Because Kernel space is not a good place to provide upscaling we have only developed a peace of code to provide intermediate resolution. These intermediate setting are get by crop the first available hardware mode also we only decode the surface need by the application software.VIDIOCGCAP Ioctl will get the capabilities of your cam .

Maximum expected size:

``Vga'' size 640x480 is provide by :

 

• Spca500 Spca501 Spca504a Spca504b

``Sif'' size 352x288 is provide by:

 

• Spca505 Spca506 Spca508 Spca561

Spca533 is weird and can do 464x480 that need to upscale on 640x480

Default Maxsize is set to 352x288

Minimum expected Size:

``QCif'' size 160x120 is provide by:

 

• Spca501 Spca505 Spca506 Spca508 Spca561

``QSif'' size 176x144 is provide by:

 

• Spca504a Spca504b Spca533 (Jpeg decoding need Height and Width modulo size of MacroBlock 16x16)

 

1.3.3 Pictures setting:

Unfortunatelly all Webcams didn't have an easy way to perform adjustement of Contrast, Brightness, Colors but exept some model we have implented those features via VIDIOCSPICT and VIDIOCGPICT Ioctl.

 

1.3.4 Asking Data from the Drivers

The driver implement VIDIOCMCAPTURE and VIDIOCSYNC to provide a good way for asking a frame and wait until that frame will be ready.At the moment our driver use four frames in the framebuffer get trought VIDIOCGMBUF Ioctl .

Read and Mmap method can be use to get video data from kernel space to usersland.

 

1.3.5 Usb Isochronous

As soon as the open function will be ask, driver allocate the whole memory ressource need by the grabbing stuff and install the callback function of the Interrupt Handler then the Urb is submitted to the usb host controller .If all are right with the initialize of the camera the isochronous stream become and, for each iso packet the driver will consume the data until a video frame start is found. A start of frame is a least the end of preceding frame, a new buffer for grabbing is asked and a tasklet will be schedule to perform the video decoding. If something goes wrong in the iso stuff the tasklet will not be schedule and the wrong frame will be recycled for a new one .

All that stuff are in interrupt context and need more attention to prevent Kernel ``crash''.

at the end of the process close function will stop the iso stream and remove all the grabbing memory in use.

 

1.3.6 Video Decoding

When the tasklet was schedule a whole frame is grabbing and is present in the frame temporary buffer.Also all the camera setting are set in the frame struct . the outpicture function first test what camera familly are responsive of that stream then the good decoding function are ask .Because proprietary stuff are always strange we have to deal with a lot pixels arrangement for exemple yuv become yuyv yyuv yuvy .

Tasklet work in safe times and so didn't corrupt the iso interrupt handler stuff.

A gamma set of tables are available to correct some sensor setting That need to experiment and choice the good setting for your cam if necessary. Spcatools is design to help you for that work.

 

1.3.7 Miscaneallus function

A set of usefull functions are implemented to get right parameters for:

frame size, picture setting , The setting of those parameters will find the good parameters for the usb stuff: pipe size Alternate setting according to frame size

 

2 Spcaview Grabber

 

2.1 Why a new grabber in Linux World ?

Our spca50x spca5xx have specific feature that was not supported with others userspace apps .for example rawjpeg stream .We need a grabber to test our module in that way also able to ask our set of palette size and so on. Tha's not really a good idea to merge bugs or unsupported feature from: xawtv, gnomemeeting and the pwlib, gqcam, vic, camstream and so on and our module. a lot of confusing will be result that way and we don't want to spend times with that. At least, if our module works fine with spcaview it should work with the others apps. Spcaview was developed with that objective so it cannot do what gnomemeeting gstreamer mplayer xawtv ...do :)

 

2.2 What Spcaview Grabber can do ?

Grab of course, in all supported palettes and sizes of our module no more no less. The resulting video stream are decoded and appears in a SDL window ( That mean you need the great libsdl to compile, but now all serious distro will offer libsdl from Loki just don't forget to install devel package too).

When the stream are displayed you can change the picture setting by pressing some key:

 

• 'n' brightness up
• 'b' brightness down
• 'v' color up
• 'c' color down
• 'x' contrast up
• 'w' contrast down

 

2.3 Picture Grabbing

Of course you can ask for a picture when grabbing spcaview will build a picture name according the frame number and freeze the picture .jpg for jpeg grabbing and pnm for all the others palettes.That mean if you have ask for an yuv420p palette that the stream is converted to a RGB24 before writing in the picture file. To get a picture only press key 's' from your keyboard.

 

2.4 Can i record video Stream ?

Sure ,when streaming it is also possible to record the resulting video in an avi file .We use the great ``avilib'' from Rainer Johanni all the necessary file are include in our package so you have nothing to install .

 

2.4.1 What are the suported codec ?

Some Fourcc are always supported in most Linux or Mac OSX, Windoze ,Player The raw jpeg camera can use ``MJPG'' the others have ``I420'' for yuv420p palette .

because we can also record RGB non standard Fourcc are in use :

 

• RGB2 for 16bits stream
• RGB3 for 24 bits stream
• RGB4 for 32bits stream

asking spcaview to record an avi will automatiquely set the right fourcc code :

spcaview -f yuv -o myavifile.avi start record an avi with I420

spcaview -f r16 -o myavifile.avi start record an avi with RBG2

spcaview -f r24 -o myavifile.avi start record an avi with RBG3

spcaview -f r32 -o myavifile.avi start record an avi with RBG4

And the MJPG ?

If your cam are jpeg compatible

spcaview -o myavifile.avi start the record with MJPG

 

2.4.2 Is There A Way to Record Raw Data ?

Sure RawData can be ask to the driver with

spcaview -v -o myrawdata.avi

That mean the grabber screen will be black but the data are writting directly to the drive and so can be process in a second times with SpcaTools .The fourcc was RAWD of course

 

2.4.3 Record avi from RGB or YUV give large file what can we do ?

Spcaview have a smart compressor that can compress in real times .

Differential Pixels Static Huffmann Encoding is GPL and are writting by Alexander Sikamov (Russian) and me (French)

You can expect 50% less in size without any loss in data . The fourcc was DPSH of course .

spcaview -z -o myavifile.avi record compressed DPSH yuv stream in an avi

 

2.4.4 Is there a way to add sound with video picture ?

Why not ? Sndlib from Bill Schottstaedt provide a great interface for that and is include in the package too so

spcaview -a 1 -o myavifile.avi will record an avi in MJPG with sound from the microphone .

spcaview -a 2 -f yuv -o myavifile.avi will record an avi file in I420 with sound from the mixer.

Some camera have an Usb Microphone device that will be a good idea if someone can experiment that :)

 

3 Spcaview Player

 

3.1 Why a new player in Linux world?

As designed in Spcaview grabbing some video encoding are specific . So we provide a great tools to read the avi get by spcaview grabber .All the Fourcc code from spcaview grabber are supported exept RAWD that need spcatools to be decoded.

 

3.2 What Spcaview Player can do ?

Play the video stream of course. All the setting are get trought the avi header so we have nothing todo exept looking the SDL output of your screen and listen the sound trought your loudspeaker .

just use:

spcaview -i myavifile.avi

tha's all

 

3.2.1 Is there a way to play frame by frame ?

Yes press

 

• down key will stop the stream
• up key restart the stream
• right key go one frame forward
• left go one frame backward

 

3.2.2 I want a picture ?

Press the down key to stop the stream select the right one with left and right then press s

a Picture name is build from the avi name and the frame number .The Picture will be record according your palette Rawjpeg give jpg picture all the others give pnm 24 Bits

 

4 How Spcaview can be installed ?

Spcaview is an unique package for grabbing or playing, only the command line argument select the right mode.

http://mxhaard.free.fr/download.html

Spcaview come with all library exept libsdl and libjpeg you have to install first.

just type

make

make install

tha's all :)

what spcaview can't do ?

The Cafe of course .

 

5 Spcatools

Spcatools perform frame analisys from the raw data get with spcaview grabber .That way we can in userspace decode the frame extract from the avi file .As in kernel spcace spcadecoder (the same) perform the decoding according parameters send by the user on command line. That tools is not for a large public audience you need knowledge of what you are doing before use .

you will first specify what is the camera type with -f parameter that also specify the incoming stream

 

• -f yuyv
• -f yyuv
• -f yuvy
• -f gbrg
• -f jpeg

also output palette are need with -p parameters

 

• -p r16 for RGB16 bits
• -p r24 for RGB24 bits
• -p r32 for RGB32 bits
• -p yuv for yuv420p

The incoming avi rawdata file are set with -i parameter

incoming width and height are get from the avi file header. at least you can specify an outcoming size with -s parameters.You only need that the output size is smaller that input size and for jpeg camera modulo 16

for exemple a spca561 based camera have gbrg bayer stream the raw data are get in 352x288 in the file raw561.avi we want an yuv420p output with 176x144 .Let go

spcatools -i raw561.avi -f gbrg -p yuv -s 176x144

 

5.1 Spcatools extract

Some time we need to perform a raw frame analisys so we have to extract the frame from the avi file.

spcatools -i raw561.avi -f gbrg -p yuv -e

will extract all frame from the avi file the file name is build with avifile name number of frame and the stream type extension.

 

5.2 Spcatools Edit

Well now what can we do with those frames ? After extracting a picture editor are open.some keys are used to perform picture setting .

 

• Right goes next frame
• Left goes last frame
• f Filter RGB to BGR
• s Take a Picture in pnm
• Space bar enter in Edit mode
• q Exit Spcatools

 

5.2.1 Edit Mode Commands

That mode allow to change parameters of the Colors setting . Each Color channel can move with an Offset [+128..-128] and Gain [1/2 .. 2] The resulting change is applied trought a gamma corrector curve [0.4545.. 2.2]

All the setting are set with the keyboard :

 

• F1 Adjust gamma +
• F2 Adjust gamma -
• f Filter RGB to BGR
• r Enter Red Channel Change
• g Enter Green Channel Change
• b Enter Blue Cannel Change
• UP Increase Offset for Channel
• DOWN Decrease Offset for Channel
• RIGHT Up Gain Value for Channel
• LEFT Down Gain Value for Channel
• s Take a picture in pnm
• l or Space Lock the change and go back Edit frame

 

5.3 Spcatools Picture

Is there a way to save a picture with that setting ?

Sure press key s will get a picture name according avifile name and frame number and save the file in pnm format.

 

5.4 Spcatools more ?

That tools are new and we can add some stream or frame process in a small C function.

an exemple is given for a Labteck Camera we need to detect iso packet and remove header part at the beginning and the end of the each iso packet .

static processFilter(unsigned char *inbuff, unsigned char *outbuff,int size)

{ char val;

int i,p,k,lastp;

int frameseq = 0x80;

for (i = 0, p=1 ,lastp=0,k=0;i < size; i ++){

if (inbuff[p] == 0xFF && inbuff[p+1]== 0xFF){

printf ("found Packet End at 0x%04X size 0x%04X isoseq: 0x%03X frameseq: 0x%03X /n",p,p-lastp,inbuff[p-1],frameseq++);

lastp=p;

p += 2; /* advance 2 Bytes so skip the header of 2 iso desc Frame 0xFF 0xFF Nbyte*/

k -= 8; /* rewind 8 bytes remove end marquer */

}

outbuff[k++] = inbuff[p++];

}

}