Editing Image acquisition package

The {{Forge|image-acquisition}} package is part of the [[Octave Forge]] project.

Build dependencies for Debian GNU/Linux are '''libv4l-dev''' and '''libfltk1.3-dev''' or '''libfltk1.1-dev'''. You can install it on GNU/Linux in octave with
  octave> pkg install -forge image-acquisition

If you see complains about a missing mkoctfile: [[FAQ#I_cannot_install_a_package._Octave_complains_about_a_missing_mkoctfile.]]

If you want to report a bug: [[Image_acquisition_package#Reporting_bugs]]

== Example session ==

Lines starting with "octave:>" are executed on the octave prompt.

=== Load the package and list available hardware ===

 octave:> pkg load image-acquisition
 octave:> imaqhwinfo
 ans =
  scalar structure containing the fields:
    driver = uvcvideo
    card = UVC Camera (046d:0825)
    bus_info = usb-0000:00:12.2-4
    version = 3.16.7
    capabilities =    2.2314e+09
    device = /dev/video0

=== Open the v4l2 device and output the result ===

 octave:> obj = videoinput("v4l2", "/dev/video0")
 obj = videoinput for v4l2
      device               = /dev/video0
      driver               = uvcvideo
      card                 = UVC Camera (046d:0825)
      VideoInput           = 0
      VideoResolution      = 320 x 240 px
      VideoFormat          = YUYV

=== Query which properties are available for the used device ===

The first 8 ones, starting with an upper letter are fixed, the other specific to the used v4l2 device.
 octave:> get(obj)
 ans = 
 {
  [1,1] = SelectedSourceName
  [2,1] = ReturnedColorSpace
  [3,1] = BayerSensorAlignment
  [4,1] = DeviceCapabilities
  [5,1] = VideoInput
  [6,1] = VideoResolution
  [7,1] = VideoFrameInterval
  [8,1] = VideoFormat
  [9,1] = brightness
  [10,1] = contrast
  [11,1] = saturation
  [12,1] = white_balance_temperature_auto
  [13,1] = gain
  [14,1] = power_line_frequency
  [15,1] = white_balance_temperature
  [16,1] = sharpness
  [17,1] = backlight_compensation
  [18,1] = exposure_auto
  [19,1] = exposure_absolute
  [20,1] = exposure_auto_priority
 }

=== Set VideoFormat to RGB3 aka RGB24 ===

 octave:> set(obj, "VideoFormat", "RGB3");

=== List available video resolutions ===

 octave:> set(obj, "VideoResolution")
 ans =
 
    640    480
    160    120
    176    144
    320    176
    320    240
    352    288
    432    240
    544    288
    640    360
    752    416
    800    448
    800    600
    864    480
    960    544
    960    720
   1024    576
   1184    656
   1280    720
   1280    960

=== Set the video resolution to 320x240px ===

 octave:> set(obj, "VideoResolution", [320 240])

=== Get the current brightness value ===

 octave:> get(obj, "brightness")
 ans =  100

=== Query possible range for brightness ===

 octave:> set(obj, "brightness")
 ans =
 
  scalar structure containing the fields:
 
    min = 0
    max =  255
    step =  1
    default =  128

=== Set a new value for brightness ===

 octave:> set(obj, "brightness", 100)

=== Start preview ===

 octave:> preview(obj)

Close it with CTRL+C or with [X] on the preview window

=== Use higher resolution and start streaming with 2 buffers ===

 octave:> set(obj, "VideoResolution", [640 480]);
 octave:> start(obj, 2)

=== Get an image from the buffers, view and save it ===

 octave:> img = getsnapshot(obj);
 octave:> image(img)
 octave:> imwrite(img, "ex1_a.png")
 
 octave:> [img, seq, t] = getsnapshot(obj);
 octave:> seq
 seq =  1
 octave:> t
 t =
 
  scalar structure containing the fields:
 
    tv_sec =  10281
    tv_usec =  779303

=== Stop streaming ===

 octave:> stop(obj)

== Using v4l2loopback for tests ==
If you don't have a v4l2 device but want to test the package you could create a loopback device:
 modprobe v4l2loopback
 gst-launch-0.10 videotestsrc ! v4l2sink device=/dev/video0

== Reporting bugs ==

Please install v4l2-ctl (for example from Debian package v4l-utils),
run the following commands and attach the output.

 $ v4l2-ctl -w --list-devices
 $ v4l2-ctl -w -D
 $ v4l2-ctl -w -L
 $ v4l2-ctl -w -n
 $ v4l2-ctl -w --list-formats

Enable libv4l2 logging:
 $ export LIBV4L2_LOG_FILENAME=libv4l2_debug.log

Start octave and execute your commands/scripts which show the problem.

Please include the whole octave session beginning with the start of octave.
There might be some warnings like "warning: function xyz shadows a built-in function" at start.

Exit octave and add libv4l2_debug.log to your bug report

Consider running the included tests:

 octave> test @videoinput/videoinput
 octave> test @videoinput/get
 octave> test @videoinput/set
 octave> test @videoinput/getsnapshot

== Build source from mercurial repository ==

'''Warning: You really should use the <pkg install -forge> method described above if you are not sure what you are doing here.'''

Get the source here [http://sourceforge.net/p/octave/image-acquisition/ci/default/tree/] and build it yourself. The build dependencies for Debian GNU/Linux wheezy are '''libv4l-dev''' and '''libfltk1.3-dev''' or '''libfltk1.1-dev'''. You also need the GNU autotools to generate the configure script.

 $ hg clone http://hg.code.sf.net/p/octave/image-acquisition octave-image-acquisition
 $ cd octave-image-acquisition/src/ && ./bootstrap
 $ cd ../..
 $ tar czf image-acquisition.tar.gz octave-image-acquisition
 octave:>> pkg install -verbose image-acquisition.tar.gz

== make check ==

If you have cloned the hg repo you can also run the test scripts to see if all works.

 $ cd octave-image-acquisition/devel
 $ make check
 
 octave -q run_tests.m
 ../src/__v4l2_handler__.cc........................ PASS 3/3
 @videoinput/videoinput............................ PASS 1/1
 @videoinput/get................................... PASS 4/4
 @videoinput/set................................... PASS 7/7
 @videoinput/getsnapshot........................... PASS 4/4
 imaqhwinfo........................................ PASS 1/1
 
 Summary:
   PASS  20
   FAIL   0

If there are tests which FAIL, then please have a look at the generated fntest.log and add it to your bug report.