Difference between revisions of "Image acquisition package"

From Octave
Jump to navigation Jump to search
m (fixed header level)
m (Remove redundant Category:Packages.)
 
(20 intermediate revisions by 4 users not shown)
Line 1: Line 1:
The {{Forge|image_acquisition}} package is part of the [[Octave Forge]] project.
+
The {{Forge|image-acquisition}} package is part of the [[Octave Forge]] project.
  
There is not release package yet but you can get the source here [http://sourceforge.net/p/octave/image-acquisition/ci/default/tree/]
+
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
  
Simply do
+
If you see complains about a missing mkoctfile: [[FAQ#I_cannot_install_a_package._Octave_complains_about_a_missing_mkoctfile.]]
  
  $ hg clone http://hg.code.sf.net/p/octave/image-acquisition octave-image-acquisition
+
If you want to report a bug: [[Image_acquisition_package#Reporting_bugs]]
  $ tar czf image-acquisition.tar.gz octave-image-acquisition
 
  octave:>> pkg install image-acquisition.tar.gz
 
  
If you want to report a bug see [[Image_acquisition_package#Reporting_bugs]]
+
'''image-acquisition will not work on Windows as far as there is not port of v4l2 (standing for ''Video for Linux 2'')'''
  
 
== Example session ==
 
== Example session ==
  
Lines starting with octave> are executed on the octave prompt.
+
Lines starting with "octave:>" are executed on the octave prompt.
  
 
=== Load the package and list available hardware ===
 
=== Load the package and list available hardware ===
  
  octave> pkg load image-acquisition
+
  octave:> pkg load image-acquisition
  octave> imaqhwinfo
+
  octave:> imaqhwinfo
 
  ans =
 
  ans =
 
 
   scalar structure containing the fields:
 
   scalar structure containing the fields:
 
 
     driver = uvcvideo
 
     driver = uvcvideo
 
     card = UVC Camera (046d:0825)
 
     card = UVC Camera (046d:0825)
     bus_info = usb-0000:00:16.2-2
+
     bus_info = usb-0000:00:12.2-4
     version = 3.2.51
+
     version = 3.16.7
     capabilities = 83886081
+
     capabilities =   2.2314e+09
 
     device = /dev/video0
 
     device = /dev/video0
  
 
=== Open the v4l2 device and output the result ===
 
=== Open the v4l2 device and output the result ===
  octave> obj = videoinput("v4l2", "/dev/video0")
+
 
 +
  octave:> obj = videoinput("v4l2", "/dev/video0")
 
  obj = videoinput for v4l2
 
  obj = videoinput for v4l2
       device             = /dev/video0
+
       device               = /dev/video0
       driver             = uvcvideo
+
       driver               = uvcvideo
       card               = UVC Camera (046d:0825)
+
       card                 = UVC Camera (046d:0825)
       VideoInput         = 0
+
       VideoInput           = 0
       VideoResolution   = 320 x 240 px
+
       VideoResolution     = 320 x 240 px
       VideoFrameInterval = 1/30 s (30.0 fps)
+
       VideoFormat          = YUYV
  
 
=== Query which properties are available for the used device ===
 
=== Query which properties are available for the used device ===
The first 6 ones, starting with an upper letter are fixed, the other specific to the used v4l2 device.
+
 
  octave> get(obj)
+
The first 8 ones, starting with an upper letter are fixed, the other specific to the used v4l2 device.
 +
  octave:> get(obj)
 
  ans =  
 
  ans =  
 
  {
 
  {
 
   [1,1] = SelectedSourceName
 
   [1,1] = SelectedSourceName
   [2,1] = DeviceCapabilities
+
   [2,1] = ReturnedColorSpace
   [3,1] = VideoInput
+
  [3,1] = BayerSensorAlignment
   [4,1] = VideoResolution
+
  [4,1] = DeviceCapabilities
   [5,1] = VideoFrameInterval
+
   [5,1] = VideoInput
   [6,1] = VideoFormat
+
   [6,1] = VideoResolution
   [7,1] = brightness
+
   [7,1] = VideoFrameInterval
   [8,1] = contrast
+
   [8,1] = VideoFormat
   [9,1] = saturation
+
   [9,1] = brightness
   [10,1] = white_balance_temperature_auto
+
   [10,1] = contrast
   [11,1] = gain
+
   [11,1] = saturation
   [12,1] = power_line_frequency
+
   [12,1] = white_balance_temperature_auto
   [13,1] = white_balance_temperature
+
   [13,1] = gain
   [14,1] = sharpness
+
   [14,1] = power_line_frequency
   [15,1] = backlight_compensation
+
   [15,1] = white_balance_temperature
   [16,1] = exposure_auto
+
   [16,1] = sharpness
   [17,1] = exposure_absolute
+
   [17,1] = backlight_compensation
   [18,1] = exposure_auto_priority
+
   [18,1] = exposure_auto
 +
   [19,1] = exposure_absolute
 +
   [20,1] = exposure_auto_priority
 
  }
 
  }
  
=== Get device capabilities ===
+
=== Set VideoFormat to RGB3 aka RGB24 ===
  octave> get(obj, "DeviceCapabilities")
+
 
ans =
+
  octave:> set(obj, "VideoFormat", "RGB3");
 
  scalar structure containing the fields:
 
 
    driver = uvcvideo
 
    card = UVC Camera (046d:0825)
 
    bus_info = usb-0000:00:16.2-2
 
    version = 3.2.51
 
    capabilities =  83886081
 
  
 
=== List available video resolutions ===
 
=== List available video resolutions ===
  octave> set(obj, "VideoResolution")
+
 
 +
  octave:> set(obj, "VideoResolution")
 
  ans =
 
  ans =
 
   
 
   
Line 103: Line 97:
 
=== Set the video resolution to 320x240px ===
 
=== Set the video resolution to 320x240px ===
  
  octave> set(obj, "VideoResolution", [320 240])
+
  octave:> set(obj, "VideoResolution", [320 240])
  
 
=== Get the current brightness value ===
 
=== Get the current brightness value ===
  octave> get(obj, "brightness")
+
 
 +
  octave:> get(obj, "brightness")
 
  ans =  100
 
  ans =  100
  
 
=== Query possible range for brightness ===
 
=== Query possible range for brightness ===
  octave> set(obj, "brightness")
+
 
 +
  octave:> set(obj, "brightness")
 
  ans =
 
  ans =
 
   
 
   
Line 121: Line 117:
  
 
=== Set a new value for brightness ===
 
=== Set a new value for brightness ===
  octave> set(obj, "brightness", 100)
+
 
 +
  octave:> set(obj, "brightness", 100)
  
 
=== Start preview ===
 
=== Start preview ===
  octave> preview(obj)
+
 
 +
  octave:> preview(obj)
 +
 
 
Close it with CTRL+C or with [X] on the preview window
 
Close it with CTRL+C or with [X] on the preview window
  
 
=== Use higher resolution and start streaming with 2 buffers ===
 
=== Use higher resolution and start streaming with 2 buffers ===
  octave> set(obj, "VideoResolution", [640 480]);
+
 
  octave> start(obj, 2)
+
  octave:> set(obj, "VideoResolution", [640 480]);
 +
  octave:> start(obj, 2)
  
 
=== Get an image from the buffers, view and save it ===
 
=== Get an image from the buffers, view and save it ===
  octave> img = getsnapshot(obj);
+
 
  octave> image(img)
+
  octave:> img = getsnapshot(obj);
  octave> imwrite(img, "ex1_a.png")
+
  octave:> image(img)
  octave> [img, seq, t] = getsnapshot(obj);
+
  octave:> imwrite(img, "ex1_a.png")
  octave> seq
+
  seq =  1
+
  octave:> [img, seq, t] = getsnapshot(obj);
  octave> t
+
  octave:> seq
  t =
+
seq =  1
 +
  octave:> t
 +
t =
 
   
 
   
 
   scalar structure containing the fields:
 
   scalar structure containing the fields:
 
   
 
   
     tv_sec =  19618
+
     tv_sec =  10281
     tv_usec =  346553
+
     tv_usec =  779303
  
 
=== Stop streaming ===
 
=== Stop streaming ===
  octave> stop(obj)
+
 
 +
  octave:> stop(obj)
  
 
== Using v4l2loopback for tests ==
 
== Using v4l2loopback for tests ==
If you don't have a v4l2 device but test the package you could create a loopback device:
+
If you don't have a v4l2 device but want to test the package you could create a loopback device:
 
  modprobe v4l2loopback
 
  modprobe v4l2loopback
 
  gst-launch-0.10 videotestsrc ! v4l2sink device=/dev/video0
 
  gst-launch-0.10 videotestsrc ! v4l2sink device=/dev/video0
Line 173: Line 176:
 
There might be some warnings like "warning: function xyz shadows a built-in function" at start.
 
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
+
Exit octave and add libv4l2_debug.log to your bug report. The logfile libv4l2_debug.log is overwritten between open/close so you have to rename it if you run different scripts.
  
 
Consider running the included tests:
 
Consider running the included tests:
Line 181: Line 184:
 
  octave> test @videoinput/set
 
  octave> test @videoinput/set
 
  octave> test @videoinput/getsnapshot
 
  octave> test @videoinput/getsnapshot
 +
 +
Run the compliance check (perhaps also with -s)
 +
 +
v4l2-compliance -d /dev/video0
 +
 +
== 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 and build it yourself. The build dependencies for Debian GNU/Linux jessie 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/
 +
$ make install
  
 
== make check ==
 
== make check ==
If you have cloned the hg repo you can run the test scripts to see if all works.
+
 
 +
If you have cloned the hg repo you can also run the test scripts to see if all works.
  
 
  $ cd octave-image-acquisition/devel
 
  $ cd octave-image-acquisition/devel
 
  $ make check
 
  $ make check
 
+
 
  octave -q run_tests.m
 
  octave -q run_tests.m
libv4l2: error setting pixformat: Device or resource busy
+
  ../src/__v4l2_handler__.cc........................ PASS 3/3
INFO: this error is expected because /dev/video0 is still streaming
+
  @videoinput/videoinput............................ PASS 1/1
  ../src/__v4l2_handler__.cc........................ PASS 3/3  
+
  @videoinput/get................................... PASS 4/4
libv4l2: error getting capabilities: Inappropriate ioctl for device
+
  @videoinput/set................................... PASS 7/7
  @videoinput/videoinput............................ PASS 3/3
+
  @videoinput/getsnapshot........................... PASS 4/4
  @videoinput/get................................... PASS 4/4  
+
  imaqhwinfo........................................ PASS 1/1
  @videoinput/set................................... PASS 6/6
 
  @videoinput/getsnapshot........................... PASS 1/1
 
  imaqhwinfo........................................ PASS 1/1  
 
 
   
 
   
 
  Summary:
 
  Summary:
+
   PASS  20
   PASS  18
 
 
   FAIL  0
 
   FAIL  0
  
The two errors are expected, see test scripts.
+
If there are tests which FAIL, then please have a look at the generated fntest.log and add it to your bug report.
 +
 
 +
[[Category:Octave Forge]]

Latest revision as of 04:13, 10 June 2019

The 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

image-acquisition will not work on Windows as far as there is not port of v4l2 (standing for Video for Linux 2)

Example session[edit]

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

Load the package and list available hardware[edit]

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[edit]

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[edit]

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[edit]

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

List available video resolutions[edit]

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[edit]

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

Get the current brightness value[edit]

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

Query possible range for brightness[edit]

octave:> set(obj, "brightness")
ans =

 scalar structure containing the fields:

   min = 0
   max =  255
   step =  1
   default =  128

Set a new value for brightness[edit]

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

Start preview[edit]

octave:> preview(obj)

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

Use higher resolution and start streaming with 2 buffers[edit]

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

Get an image from the buffers, view and save it[edit]

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[edit]

octave:> stop(obj)

Using v4l2loopback for tests[edit]

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[edit]

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. The logfile libv4l2_debug.log is overwritten between open/close so you have to rename it if you run different scripts.

Consider running the included tests:

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

Run the compliance check (perhaps also with -s)

v4l2-compliance -d /dev/video0

Build source from mercurial repository[edit]

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 and build it yourself. The build dependencies for Debian GNU/Linux jessie 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/
$ make install

make check[edit]

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.