SpcaView & SpcaTools Howto

1 Overview:

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

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

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

Also if your distro clearelly patch the kerneland become uncompatible with the others Linux stuff.we cannot offersupport . The best way get a vanilla kernel from http://www.kernel.orgit 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 :

JpegYuvBayerSpca500Spca501Spca561aSpca504aSpca505 Spca504bSpca506 Spca533aSpca508 

Yuvand Bayer can be encoded with specific compressor from Sunplus. As wedon't know that proprietary stuff ,we cannot provide any support of thecompressed mode, we use instead uncompressed stream.

Jpeg ismore atractive that we know how the stream is encoded . A peace of codefrom the bootsplash project as be rewrite to support our raw jpegstream ( 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

Thefirst step provide a V4L layer to the userspace software .That meanIoctl 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:

Allcamera didn't support nativelly the whole set of picture size setting.Because Kernel space is not a good place to provide upscaling we haveonly developed a peace of code to provide intermediate resolution.These intermediate setting are get by crop the first available hardwaremode also we only decode the surface need by the applicationsoftware.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:

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

 

1.3.4 Asking Data from the Drivers

Thedriver implement VIDIOCMCAPTURE and VIDIOCSYNC to provide a good wayfor asking a frame and wait until that frame will be ready.At themoment our driver use four frames in the framebuffer get troughtVIDIOCGMBUF Ioctl .

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

 

1.3.5 Usb Isochronous

Assoon as the open function will be ask, driver allocate the whole memoryressource need by the grabbing stuff and install the callback functionof the Interrupt Handler then the Urb is submitted to the usb hostcontroller .If all are right with the initialize of the camera theisochronous stream become and, for each iso packet the driver willconsume the data until a video frame start is found. A start of frameis a least the end of preceding frame, a new buffer for grabbing isasked and a tasklet will be schedule to perform the video decoding. Ifsomething goes wrong in the iso stuff the tasklet will not be scheduleand 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

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

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

Agamma set of tables are available to correct some sensor setting Thatneed to experiment and choice the good setting for your cam ifnecessary. 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:

framesize, picture setting , The setting of those parameters will find thegood parameters for the usb stuff: pipe size Alternate settingaccording to frame size

 

2 Spcaview Grabber

 

2.1 Why a new grabber in Linux World ?

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

 

2.2 What Spcaview Grabber can do ?

Grabof course, in all supported palettes and sizes of our module no more noless. The resulting video stream are decoded and appears in a SDLwindow ( That mean you need the great libsdl to compile, but now allserious distro will offer libsdl from Loki just don't forget to installdevel 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

Ofcourse you can ask for a picture when grabbing spcaview will build apicture name according the frame number and freeze the picture .jpg forjpeg grabbing and pnm for all the others palettes.That mean if you haveask for an yuv420p palette that the stream is converted to a RGB24before 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 anavi file .We use the great ``avilib'' from Rainer Johanni all thenecessary file are include in our package so you have nothing toinstall .

 

2.4.1 What are the suported codec ?

SomeFourcc are always supported in most Linux or Mac OSX, Windoze ,PlayerThe raw jpeg camera can use ``MJPG'' the others have ``I420'' foryuv420p 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

Thatmean the grabber screen will be black but the data are writtingdirectly to the drive and so can be process in a second times withSpcaTools .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?

Asdesigned in Spcaview grabbing some video encoding are specific . So weprovide a great tools to read the avi get by spcaview grabber .All theFourcc code from spcaview grabber are supported exept RAWD that needspcatools to be decoded.

 

3.2 What Spcaview Player can do ?

Playthe video stream of course. All the setting are get trought the aviheader so we have nothing todo exept looking the SDL output of yourscreen 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

aPicture name is build from the avi name and the frame number .ThePicture will be record according your palette Rawjpeg give jpg pictureall 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

Spcatoolsperform frame analisys from the raw data get with spcaview grabber.That way we can in userspace decode the frame extract from the avifile .As in kernel spcace spcadecoder (the same) perform the decodingaccording parameters send by the user on command line. That tools isnot for a large public audience you need knowledge of what you aredoing 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

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

forexemple a spca561 based camera have gbrg bayer stream the raw data areget in 352x288 in the file raw561.avi we want an yuv420p output with176x144 .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

willextract all frame from the avi file the file name is build with avifilename number of frame and the stream type extension.

 

5.2 Spcatools Edit

Wellnow what can we do with those frames ? After extracting a pictureeditor 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

Thatmode allow to change parameters of the Colors setting . Each Colorchannel can move with an Offset [+128..-128] and Gain [1/2 .. 2] Theresulting 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.

anexemple is given for a Labteck Camera we need to detect iso packet andremove 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++];

}

}