D 2018-07-31T09:12:51.955
L uvc
P d25eeaff4673087d04e61fea5d8a4fb336248aee
U chw
W 11237
<h2>Name</h2>
<b>uvc</b> - Interface to UVC cameras using <tt>libuvc</tt>
<h2>Synopsis</h2>
<tt>package require tcluvc</tt><br>
<tt>uvc <i>option</i> ?<i>arg ...</i>?</tt>
<h2>Description</h2>
This command provides several operations to interface UVC USB cameras using the infrastructure provided by <tt>libuvc</tt> and <tt>libusb</tt> which is available on common Linux, FreeBSD, and MacOSX platforms and sometimes found working on Android devices. <tt><i>option</i></tt> indicates what to carry out. Any unique abbreviation for <tt><i>option</i></tt> is acceptable. The valid options are:
<tt>uvc close <i>devid</i></tt>
Closes the device identified by <tt><i>devid</i></tt> which has been opened before using <tt>uvc open</tt>.
<tt>uvc convmode <i>devid</i> ?<i>flag</i>?</tt>
Reports or modifies the conversion mode for frames acquired from the opened device identified by <tt><i>devid</i></tt>. Conversion mode 1 (on/true) performs frame format/color space conversions in the special UVC thread which controls the USB transfers, mode 0 (off/false) does this instead in the normal Tcl event loop. The default mode is 1.
<tt>uvc counters <i>devid</i></tt>
Reports a three element list of statistic counters on the device identified by <tt><i>devid</i></tt>. The first element is the number of video frames received, the second the number of video frames processed with <tt>uvc image</tt>, and the third the number of video frames dropped.
<tt>uvc devices</tt>
Returns device information which can be used for <tt>uvc open</tt> as a list. Each device adds three elements to the list: the first element is the device name as a colon separated string with two or three fields being vendor ID (hexadecimal, 0x prefix is optional), product ID (hexadecimal, 0x prefix is optional), and bus/device numbers separated by a dot; the second and third list elements are the vendor name, and the product name. To open the device, its name (the colon separated string) must be used, the other two items are available for presentation purposes. If <tt>udev</tt> support is available (Linux specific), this list is refreshed on plug and unplug of devices. Otherwise, the list is a snapshot of suitable devices currently connected.
<tt>uvc format <i>devid</i> ?<i>index fps</i>?</tt>
Returns or changes the frame format of the device identified by <tt><i>devid</i></tt>. The optional parameter <tt><i>index</i></tt> is an integer number giving the index of the frame format returned in <tt>uvc listformats</tt>. The optional parameter <tt><i>fps</i></tt> is the frame rate. If omitted, the currently active index and frame rate are returned. Changing the frame format and rate is only possible if the device is not capturing images.
<tt>uvc greyshift <i>devid</i> ?<i>shift</i>?</tt>
Returns or sets the bit shift to be applied on grey images with a bit depth higher than 8 which are captured from device <tt><i>devid</i></tt>. The default value is 4, which is suitable for greyscale cameras with 12 bit resolution. The shift is not applied when the <tt>image</tt> subcommand retrieves raw byte array data.
<tt>uvc image <i>devid</i> ?<i>photoImage</i>?</tt>
Copies the most recent captured image of the device <tt><i>devid</i></tt> into the photo image identified by <tt><i>photoImage</i></tt> and returns non-zero on success or zero if no data transfer has taken place. If <tt><i>photoImage</i></tt> is omitted, a four element list is returned with the first element being the image width, the second the image height, the third the number of bytes per pixel, and the last the image's RGB values with 3 bytes per pixel in red, green, blue order as a byte array. In this case an error is indicated by throwing an exception.
<tt>uvc info ?<i>devid</i>?</tt>
Returns information on open devices. If <tt><i>devid</i></tt> is specified,
a list of two elements is returned, the first being the device nameand
the second the image callback command for that device, i.e. the same
arguments which were used on <tt>uvc open</tt>. If <tt><i>devid</i></tt> is omitted, a list of <tt><i>devid</i></tt>s, i.e. all currently opened devices is returned.
<tt>uvc listen ?<i>callback</i>?</tt>
Retrieves or sets the callback command called on plug and unplug of devices. When a device is plugged or unplugged that callback is invoked with two additional arguments: the type of event (<tt>add</tt> or <tt>remove</tt>) and the device name (see <tt>uvc devices</tt> for the naming convention) which was added or removed. Only usable if <tt>udev</tt> support is available.
<tt>uvc listformats <i>devid</i></tt>
Returns a dictionary keyed by a format index as integer with the values being another dictionary with information about the frame size and rate of the respective frame format. The returned indices can be used in in <tt>uvc format</tt> to switch to another frame size and/or to change the frame rate.
<tt>uvc mbcopy <i>bytearray1 bytearray2 mask</i></tt>
Copies the content of RGB byte array <tt><i>bytearray2</i></tt> into the byte array <tt><i>bytearray1</i></tt> using an RGB <tt><i>mask</i></tt>. Both byte arrays must have identical length which must be a multiple of 3 (for RGB). The main purpose of this command is to combine images from two cameras into an anaglyph 3D, where (for a red-cyan anaglyph) the left camera image uses mask 0xFF0000 (red component) and the right camera image uses mask 0x00FFFF (green and blue components).
<tt>uvc mcopy <i>photo1 photo2 mask</i></tt>
Copies the content of the photo image <tt><i>photo2</i></tt> into the photo image <tt><i>photo1</i></tt> using an ARGB <tt><i>mask</i></tt>. Both photo images must have identical width, height, and depth. The main purpose of this command is to combine images from two cameras into an anaglyph 3D, where (for a red-cyan anaglyph) the left camera image uses mask 0x00FF0000 (red component) and the right camera image uses mask 0x0000FFFF (green and blue components).
<tt>uvc mirror <i>devid</i> ?<i>x y</i>?</tt>
Retrieves or sets flags to mirror captured images along the X or Y axis. Parameters <tt><i>x</i></tt> and <tt><i>y</i></tt> if specified must be boolean values.
<tt>uvc open <i>devname callback</i></tt>
Opens the device with device name <tt><i>devname</i></tt> and establishes <tt><i>callback</i></tt> as command to be invoked on captured images and finally returns a <tt><i>devid</i></tt>, i.e. a handle to further deal with the device. An additional parameter is appended when <tt><i>callback</i></tt> is invoked: the <tt><i>devid</i></tt> of the device. For the format of <tt><i>devname</i></tt> see the description of <tt>uvc devices</tt>.
<tt>uvc orientation <i>devid</i> ?<i>degrees</i>?</tt>
Retrieves or sets the orientation of captured images regarding image rotation. <tt><i>degrees</i></tt> if specified must be an integer number.
<tt>uvc parameters <i>devid</i> ?<i>key value ...</i>?</tt>
Returns or changes device parameters for the device identified by <tt><i>devid</i></tt> given as key-value pairs, e.g. <tt>brightness 100</tt> will change the brightness setting of captured images to the device dependent value 100. The command returns the current device parameters (after the potential change, when keys and values were given) as a key-value list which can be processed with <tt>array set</tt> or <tt>dict get</tt>.
<tt>uvc record <i>devid</i> frame <i>width height bpp bytearray</i></tt>
Transcodes the frame described by <tt><i>width</i></tt>, <tt><i>height</i></tt>, <tt><i>bpp</i></tt>, and <tt><i>bytearray</i></tt> to JPEG and writes the result to the recording file or stream. The recording must have been started with the <tt>-user</tt> option. An integer number is returned as result: 1 indicates successful write, 0 no write due to frame rate constraints, and -1 an error during the write.
<tt>uvc record <i>devid</i> pause</tt>
Pauses recording to a file or stream.
<tt>uvc record <i>devid</i> resume</tt>
Continues recording to a file or stream.
<tt>uvc record <i>devid</i> start <i>options ...</i></tt>
Starts recording to a file or stream. <tt><i>options</i></tt> control the data format, frames per second, and output channel. The option <tt>-fps</tt> specifies the approximate rate in frames per second as a floating point number. The option <tt>-chan</tt> specifies the channel to which the frames are written. This channel is detached from the Tcl interpreter and controlled solely by the <tt>uvc record</tt> command. The <tt>-boundary</tt> option specifies a MIME multipart boundary string and selects the MIME type <tt>multipart/x-mixed-replace</tt> suitable for streaming to a web browser. The content type delivered to the browser is <tt>image/jpeg</tt>. If the <tt>-boundary</tt> option is omitted, the output format is raw AVI and requires the channel to be seekable. The option <tt>-mjpeg</tt> forces the recorded data to JPEG format, i.e. a transcoding to JPEG will be performed in software, if the device doesn't
already deliver a JPEG stream. The option <tt>-user</tt> turns off automatic frame write operations to the recording file or stream when a frame is
delivered from the device. Instead, <tt>uvc record <i>devid</i> frame</tt> must be invoked in the callback function. The <tt>-user</tt> option implies <tt>-mjpeg</tt>.
<tt>uvc record <i>devid</i> state</tt>
Returns the current recording state as <tt>stop</tt>, <tt>recording</tt>, <tt>pause</tt>, or <tt>error</tt>. The state <tt>error</tt> indicates a write error on the file or stream. In this case no further frames will be written.
<tt>uvc record <i>devid</i> stop</tt>
Finishes recording to a file or stream and closes the underlying channel.
<tt>uvc start <i>devid</i></tt>
Starts capturing images of the device identified by <tt><i>devid</i></tt>. When an image is ready, the callback command set on <tt>uvc open</tt> is invoked.
<tt>uvc state <i>devid</i></tt>
Returns the image capture state of the device identified by <tt><i>devid</i></tt>. The result is the string <tt>capture</tt> if the device is started, <tt>stopped</tt> if the device is stopped, or <tt>error</tt> if an error has been detected while image capture was active.
<tt>uvc stop <i>devid</i></tt>
Stop capturing images of the device identified by <tt><i>devid</i></tt>.
<tt>uvc tophoto <i>width height bpp bytearray</i> ?<i>rot mirrorx mirrory</i>?</tt>
Makes the RGB (<tt><i>bpp</i></tt> is 3) or gray (<tt><i>bpp</i></tt> is 1) byte array <tt><i>bytearray</i></tt> of <tt><i>width</i></tt> times <tt><i>height</i></tt> pixels into a Tk photo image. Optionally, the data is rotated by <tt><i>rot</i></tt> degrees (possible values 0, 90, 180, 270) and/or mirrored along the X and/or Y axis as specified by the boolean values <tt><i>mirrorx</i></tt> and <tt><i>mirrory</i></tt>.
The <tt>uvc</tt> command tries to lazy load Tk, thus allowing to use it from a normal <tt>tclsh</tt>. Only when a photo image is required by a subcommand, Tk must be available and an attempt to load it is made.
Z e2ed523701c08c4ebc365e4a8fbbf60a