Weave - Grouped and Immediate Callback [Architecture]
fwcam_documentation
1. fwcam: Matlab API for FireWire cameras
Matěj Balga
12th July 2013
1 Installation
To install and run compiled MEX-files you need to add the folder fwcam to your MATLAB path and have
following libraries installed on your system:
libdc1394 Get it using command sudo apt-get install libdc1394-22-dev
libraw1394 Get it using command sudo apt-get install libraw1394-dev
If you’d like to compile the sources, located in the src folder, use libdc1394 in version 2.2.1 and compile with
arguments -std=c99 -lraw1394 -ld1394.
2 Usage
2.1 Functions
2.1.1 fwsimsnap
Using this function, you can quickly capture one frame from the first connected camera. It opens the bus, gets
the camera ready, captures frame and then releases all the resources and closes the camera
Usage:
image = fwsimsnap();
image Image captured from the camera with ID 0 (first camera on the first bus).
2.1.2 fwopen
Function fwopen is in most cases the first function you have to call. Using this function, you acquire a handle
to the camera, which allows you to capture frames or to set feature parameters of the camera.
Usage:
camera_handle = fwopen(camera_id);
camera_handle Acquired handle for the camera
camera_id A number from 0 to n where n is total number of connected cameras minus one. If you have just
one camera connected, enter 0.
2.1.3 fwsnap
Gets one frame using a handle, acquired with function fwopen. This function is designed to capture the video
from the camera and as so, it takes the image from the DMA buffer, which is getting filled with frames constantly
after calling fwopen. This means that if you do not call fwsnap quickly enough, you are getting old frames from
the buffer instead of fresh ones. To be sure to have the latest frame, you can try to flush the buffer using
fwflushbuf or reopen the camera using sucessive call of fwclose and fwopen.
Usage:
image = fwsnap(camera_handle);
image Captured image
camera_handle Camera handle acquired using fwopen.
1
2. 2.1.4 fwclose
Be sure to call this function after you finish working with the camera to release the resources held by camera
and to prevent memory leak. It also flushes the ring buffer with captured frames.
Usage:
fwclose(camera_handle);
camera_handle Camera handle acquired using fwopen.
2.1.5 fwresetbus
If something went wrong and camera is not able to capture frames or open correctly, you can try calling this
function. Be careful about it as it is ’rude’ to other devices on the bus and causes all of them to stop and close.
Usage:
fwresetbus(camera_handle);
camera_handle Camera handle acquired using fwopen.
2.1.6 fwflushbuf
Tries to empty the ring buffer used to store frames that arrived from the camera. Successful emptying of the
buffer depends on speed of the computer and framerate of the camera.
Usage:
fwflushbuf(camera_handle);
camera_handle Camera handle acquired using fwopen.
2.1.7 fwbrightness
Gets or sets brightness. For getting the value use the first notation (with left hand side argument), for setting
the value function produces no output and takes two arguments on right hand side as seen in second notation.
Depending on speed of snaping and framerate, setting the feature value can take effect after a few frames. If you
want it to take effect immediately, try to flush the buffer using fwflushbuf or reopen the camera using sucessive
call of fwclose and fwopen.
Usage:
current_value=fwbrightness(camera_handle);
fwbrightness(camera_handle, desired_value);
camera_handle Camera handle acquired using fwopen.
current_value Current value of the feature.
desired_value Value to be set.
2.1.8 fwexposure
Gets or sets exposure. For getting the value use the first notation (with left hand side argument), for setting
the value function produces no output and takes two arguments on right hand side as seen in second notation.
Depending on speed of snaping and framerate, setting the feature value can take effect after a few frames. If you
want it to take effect immediately, try to flush the buffer using fwflushbuf or reopen the camera using sucessive
call of fwclose and fwopen.
Usage:
current_value=fwexposure(camera_handle);
fwexposure(camera_handle, desired_value);
camera_handle Camera handle acquired using fwopen.
current_value Current value of the feature.
desired_value Value to be set.
2
3. 2.1.9 fwgain
Gets or sets gain. For getting the value use the first notation (with left hand side argument), for setting the
value function produces no output and takes two arguments on right hand side as seen in second notation.
Depending on speed of snaping and framerate, setting the feature value can take effect after a few frames. If
you want it to take effect immediately, try to flush the buffer using fwflushbuf or reopen the camera using
sucessive call of fwclose and fwopen.
Usage:
current_value=fwgain(camera_handle);
fwgain(camera_handle, desired_value);
camera_handle Camera handle acquired using fwopen.
current_value Current value of the feature.
desired_value Value to be set.
2.1.10 fwgamma
Gets or sets gamma. For getting the value use the first notation (with left hand side argument), for setting
the value function produces no output and takes two arguments on right hand side as seen in second notation.
Depending on speed of snaping and framerate, setting the feature value can take effect after a few frames. If you
want it to take effect immediately, try to flush the buffer using fwflushbuf or reopen the camera using sucessive
call of fwclose and fwopen.
Usage:
current_value=fwgamma(camera_handle);
fwgamma(camera_handle, desired_value);
camera_handle Camera handle acquired using fwopen.
current_value Current value of the feature.
desired_value Value to be set.
2.1.11 fwsharpness
Gets or sets exposure. For getting the value use the first notation (with left hand side argument), for setting
the value function produces no output and takes two arguments on right hand side as seen in second notation.
Depending on speed of snaping and framerate, setting the feature value can take effect after a few frames. If you
want it to take effect immediately, try to flush the buffer using fwflushbuf or reopen the camera using sucessive
call of fwclose and fwopen.
Usage:
current_value=fwsharpness(camera_handle);
fwsharpness(camera_handle, desired_value);
camera_handle Camera handle acquired using fwopen.
current_value Current value of the feature.
desired_value Value to be set.
2.1.12 fwshutter
Gets or sets shutter time. For getting the value use the first notation (with left hand side argument), for setting
the value function produces no output and takes two arguments on right hand side as seen in second notation.
Depending on speed of snaping and framerate, setting the feature value can take effect after a few frames. If you
want it to take effect immediately, try to flush the buffer using fwflushbuf or reopen the camera using sucessive
call of fwclose and fwopen.
Usage:
3
4. current_value=fwshutter(camera_handle);
fwshutter(camera_handle, desired_value);
camera_handle Camera handle acquired using fwopen.
current_value Current value of the feature.
desired_value Value to be set.
2.2 Tutorials
2.2.1 Capturing video
% Get camera handle
camera_handle=fwopen(0);
% Capture two succesive frames
f1 = fwsnap(camera_handle);
f2 = fwsnap(camera_handle);
% Close camera
fwclose(camera_handle);
% Display second acquired image
imshow(f2);
2.2.2 Setting camera features
% Get camera handle
camera_handle=fwopen(0);
% Set brightness to 200
fwbrightness(camera_handle, 200);
% Snap
f1 = fwsnap(camera_handle);
% Set brightness to 800
fwbrightness(camera_handle, 800);
% Flush buffer to see the change
fwflushbuf(camera_handle);
% Snap second time
f2 = fwsnap(camera_handle);
% Close camera
fwclose(camera_handle);
% Compare
imshow(f1);
figure;
imshow(f2);
4