JeVois  1.20
JeVois Smart Embedded Machine Vision Toolkit
Share this page:
Advanced topic: Video mappings and configuring machine vision modes

Your JeVois camera is capable of running a wide range of machine vision algorithms. The selection of which algorithm runs is defined by a configuration file which establishes a mapping between camera resolution, framerate, and pixel format, a USB output resolution, and pixel format, and the corresponding machine vision processing module.

The definitions are stored in a file called videomappings.cfg which is at JEVOIS:/config/videomappings.cfg on your microSD card (source at ~/jevois/Config/videomappings.cfg). You can inspect and edit this file.

Some mappings stream USB video to a host computer, which is intended either for viewing by humans (demo modes), or for further processing by the host computer. These mappings define what the video format, resolution and frame rate is, what the corresponding camera sensor format, resolution and frame rate is, and which machine vision module is used to compute the output video frames from the camera sensor frames. These mappings must be known at the time the Linux kernel boots on the small computer inside the JeVois camera, and hence they cannot be changed at runtime. This so that the list of supported video formats, resolutions, and frame rates over USB can be announced to the host computer when it first detects and configures the JeVois smart camera.

Some mappings do not provide any video output to USB, and are intended for use by Arduino or similar. The machine vision modules using such mappings usually do output strings to serial port, to indicate what they see in a very compact format. These mappings specify camera sensor format, resolution and frame rate is, and which machine vision module is used to process the camera frames. These mappings can both be specified in the videomappings.cfg file, or can be defined at runtime (see the setmapping2 command in Command-line interface user guide).

On JeVois-Pro, some mappings draw overlays over the live camera view and support GUI widgets.

Below is an example videomappings.cfg file. Lines that start with a # sign are commented out and ignored by the smart camera.

Note
The videomapping.cfg file may be automatically updated as you install new modules. In addition, in the (hopefully near) future, a simple user interface to it will be provided. In the meantime, adding or removing vision processing modes to your JeVois camera is achieved by adding or deleting (or commenting out) some lines in the videomapping.cfg file.
Warning
There is a limit on how many active mappings (not commented out) your videomapping.cfg file may have, which is about 50. This is limited by a statically-allocated buffer in the Linux kernel that is used to communicate the information about supported USB resolutions to the host computer. If your JeVois camera is not detected by your host computer anymore, maybe you have too many active mappings.
Note
Some video mappings which work are commented out in videomappings.cfg on the pre-installed microSD image. This is because Mac OSX will stop detecting the JeVois camera as soon as it exposes any BAYER or RGB565 video formats. So, for maximum compatibility of the pre-installed microSD image, those are disabled by default. If you are using Linux or Windows, try un-commenting (remove the # sign) some of these to activate them.

To avoid having your JeVois smart camera just hang because of parsing errors, for example in case of malformed or duplicate video mappings in the videomappings.cfg file, the following policy has been adopted:

  • if a mapping is malformed (missing fields, wrong fields, etc), it will be skipped.
  • if there is no mapping with USB output in the file, one will be added, YUYV 640x480 @ 30fps PassThrough.
  • if there is no default mapping (marked with a * at the end), the first mapping with USB output will be selected as default.
  • if two mappings have identical USB output pixel format, resoltion, and frame rate, the second one will be slowed down by 1 fps (and so on if more than two conflicts).

See jevois::videoMappingsFromStream() for more info.

The latest list of mappings for JeVois-A33 is [here]{https://github.com/jevois/jevois/blob/master/Config/videomappings-A33.cfg}, and for JeVois-Pro see [here]{https://github.com/jevois/jevois/blob/master/Config/videomappings-Pro.cfg}.

Here is an example for a JeVois-A33 camera:

######################################################################################################################
#
# JeVois Smart Embedded Machine Vision Toolkit - Copyright (C) 2016 by Laurent Itti, the University of Southern
# California (USC), and iLab at USC. See http://iLab.usc.edu and http://jevois.org for information about this project.
#
# This file is part of the JeVois Smart Embedded Machine Vision Toolkit.  This program is free software; you can
# redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software
# Foundation, version 2.  This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
# without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
# License for more details.  You should have received a copy of the GNU General Public License along with this program;
# if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
#
# Contact information: Laurent Itti - 3641 Watt Way, HNB-07A - Los Angeles, CA 90089-2520 - USA.
# Tel: +1 213 740 3527 - itti@pollux.usc.edu - http://iLab.usc.edu - http://jevois.org
######################################################################################################################
#
# JeVois smart camera operation modes and video mappings
#
# Format is: <USBmode> <USBwidth> <USBheight> <USBfps> <CAMmode> <CAMwidth> <CAMheight> <CAMfps> <Vendor> <Module> [*]
#
# CamMode can be only one of: YUYV, BAYER, RGB565
# USBmode can be only one of: YUYV, GREY, MJPG, BAYER, RGB565, BGR24, NONE

# USB to camera mode mappings (when USBmode is not NONE) are organized according to output format, which should be
# unique (no two entries in this file should have same USBmode/USBwidth/USBheight/USBfps). Indeed, these modes can only
# be selected by the host computer's video grabbing software, and they are selected by picking an output format in that
# software. These modes cannot be chosen by the JeVois system itself. For these modes, the Module's process(inframe,
# outframe) function will be called on every frame.

# Camera-only modes (when USBmode is NONE) mode mappings have no video output over USB, and are selected by interacting
# with the JeVois hardware over serial ports. When USBmode is NONE, USBwidth, USBHeight, and USBfps are ignored and
# should be set to 0 here. For these modes, the Module's process(inframe) function will be called on every frame. These
# modes are usually the ones you would use when interfacing the JeVois camera to an Arduino or similar system that
# cannot stream video over USB and will just receive data from the JeVois camera over a serial port.

# The optional * at the end of one line indicates the format that should be the default one announced by the device to
# the USB host. This is the one that most webcam programs will select by default when you start them. Note that the
# guvcview program on linux seems to ignore this and to instead select the last mode you had selected the last time you
# used the camera. This * cannot be on a mapping that has NONE USBmode. There should be only one * in the whole file.

# Model JeVois-A33 camera sensor supported resolutions and frame rates:
#
#  SXGA (1280 x 1024): up to 15 fps
#   VGA ( 640 x  480): up to 30 fps
#   CIF ( 352 x  288): up to 60 fps
#  QVGA ( 320 x  240): up to 60 fps
#  QCIF ( 176 x  144): up to 120 fps
# QQVGA ( 160 x  120): up to 60 fps
# QQCIF (  88 x   72): up to 120 fps

# Frame rates can be set to any value from 0.1fps to the maximum supported for the selected resolution. This is very
# useful to avoid dropping frames. For example if you have an algorithm that runs at 26.3fps after all possible
# optimizations, you can set the camera (and usb) frame rate to 26.3 and you will not drop frames (unless your algorithm
# momentarily performs slower, hence adding a small margin may be a good idea, e.g., select 26.1fps camera and usb
# rates). This is better than setting the frame rate to 30.0 as this would mean that every so often you would miss the
# next camera frame and then have to wait for the next one to be captured. If your algorithm really runs at 26.3fps but
# you specify 30.0fps camera frame rate, then the frames will actually end up being pumped to USB at only 15.0fps (i.e.,
# by the time you finish processing the current frame, you have missed the next one from the camera, and you need to
# wait for the following one).

# Note on USB transfer rate: the maximum actual pixel data transfer rate is 3070*8000 = 23.9 Mbytes/s (which is 3kb/USB
# microframe, max "high bandwidth" setting). Although USB 2.0 has a maximum theoretical rate of 480 Mbit/s, this
# includes protocol overhead and not all of the bandwidth is available for isochronous (real-time stream) transfers,
# which we use.  This means that SXGA YUYV (2 bytes/pixel) can only transfer at a max rate of ~9.3 fps over the USB
# link, although the camera can grab SXGA YUYV at 15 fps. SXGA in Bayer can achieve 15 fps transfer over USB since it
# only uses 1 byte/pixel.

# To test various video formats on a Linux host, the best is usually to use guvcview. However, this has two issues: 1)
# it adds some formats which we do not natively support, like RGB3, YU12, YV12, etc, probably by doing some pixel
# conversion internally over the actual supported modes; 2) support for RGB565 seems brittle, guvcview often crashes
# when changing resolutions in RGB565 (called RGBP for RGB Packed).
#
# Hence, you may want to also try ffplay from the ffmpeg project, which can display all our supported modes and will
# reject a mode if it does not exactly match what the hardware supports. Example:
#
#   ffplay /dev/video0 -pixel_format yuyv422 -video_size 640x480
#
# The pixel_format values are: 'yuyv422' for YUYV, 'gray' for GRAY, 'rgb565' for RGB565, 'mjpeg' for MJPG, 'bgr24' for
# BGR24, and 'bayer_rggb8' for BAYER. You can run 'ffplay -pix_fmts' to see the list of pixel formats that ffplay
# supports.
#
# Here is another example where we record the output of JeVois to a file:
#
#   ffmpeg -f v4l2 -pixel_format rgb565 -video_size 320x240 -framerate 22 -i /dev/video0 output.mp4

# On Mac OSX, we recommend using the CamTwist app, as described in the JeVois documentation. You can also use ffplay for
# OSX: Download the pre-compiled ffplay binary from the ffmpeg web site, and then run:
#
#   ~/bin/ffplay -f avfoundation -i "JeVois" -video_size 640x300 -framerate 60 -pixel_format yuyv422
#
# (assuming you saved ffplay into your ~/bin/ directory).

# Mac compatibility notes: The JeVois smart camera is correctly detected on Macs and works with PhotoBooth as long as:
# 1) you have a mapping that outputs YUYV 640x480 (this is the one that PhotoBooth will select (at least on recent OSX
# like El Capitan, etc); beware that it will also flip the image horizontally); 2) you have no active (not
# commented-out) mapping with BAYER, RGB565, or BGR24 output. If you have any un-commented mapping with BAYER, RGB565,
# or BGR24 in your videomappings.cfg, your JeVois smart camera will still be detected by your Mac, PhotoBooth will start
# and try to use the camera, but it will only display a black screen. Our guess is that this is a bug in the Mac camera
# driver. It is ok to have additional mappings with YUYV output, as well as mappings with MJPG or GREY output.

####################################################################################################
### Pass-through and simple pixel format conversion modes:
####################################################################################################

#BAYER 640 480 26.8 YUYV 640 480 26.8 JeVois Convert
#BGR24 640 480 26.8 YUYV 640 480 26.8 JeVois Convert
GREY 640 480 26.8 YUYV 640 480 26.8 JeVois Convert
#RGB565 640 480 26.8 YUYV 640 480 26.8 JeVois Convert

#MJPG 640 480 20.0 YUYV 640 480 20.0 JeVois Convert
MJPG 352 288 60.0 BAYER 352 288 60.0 JeVois Convert
MJPG 320 240 30.0 RGB565 320 240 30.0 JeVois Convert
MJPG 320 240 15.0 YUYV 320 240 15.0 JeVois Convert
MJPG 320 240 60.0 RGB565 320 240 60.0 JeVois Convert
MJPG 176 144 120.0 BAYER 176 144 120.0 JeVois Convert
MJPG 160 120 60.0 YUYV 160 120 60.0 JeVois Convert
MJPG 88 72 120.0 RGB565 88 72 120.0 JeVois Convert

#BAYER 1280 1024 15.0 BAYER 1280 1024 15.0 JeVois PassThrough
#BAYER 640 480 30.0 BAYER 640 480 30.0 JeVois PassThrough
#BAYER 352 288 60.0 BAYER 352 288 60.0 JeVois PassThrough
#BAYER 320 240 60.0 BAYER 320 240 60.0 JeVois PassThrough
#BAYER 176 144 120.0 BAYER 176 144 120.0 JeVois PassThrough
#BAYER 160 120 60.0 BAYER 160 120 60.0 JeVois PassThrough
#BAYER 88 72 120.0 BAYER 88 72 120.0 JeVois PassThrough

#RGB565 1280 1024 15.0 RGB565 1280 1024 15.0 JeVois PassThrough
#RGB565 640 480 30.0 RGB565 640 480 30.0 JeVois PassThrough
#RGB565 320 240 60.0 RGB565 320 240 60.0 JeVois PassThrough
#RGB565 176 144 120.0 RGB565 176 144 120.0 JeVois PassThrough
#RGB565 160 120 60.0 RGB565 160 120 60.0 JeVois PassThrough
#RGB565 88 72 120.0 RGB565 88 72 120.0 JeVois PassThrough

#YUYV 1280 1024 7.5 YUYV 1280 1024 7.5 JeVois PassThrough
#YUYV 640 480 30.0 YUYV 640 480 30.0 JeVois SaveVideo
#YUYV 640 480 19.6 YUYV 640 480 19.6 JeVois PassThrough
#YUYV 640 480 12.0 YUYV 640 480 12.0 JeVois PassThrough
#YUYV 640 480 8.3 YUYV 640 480 8.3 JeVois PassThrough
#YUYV 640 480 7.5 YUYV 640 480 7.5 JeVois PassThrough
#YUYV 640 480 5.5 YUYV 640 480 5.5 JeVois PassThrough

YUYV 320 240 60.0 YUYV 320 240 60.0 JeVois SaveVideo
#YUYV 320 240 30.0 YUYV 320 240 30.0 JeVois SaveVideo
#YUYV 320 240 15.0 YUYV 320 240 15.0 JeVois SaveVideo

YUYV 160 120 60.0 YUYV 160 120 60.0 JeVois SaveVideo
#YUYV 160 120 30.0 YUYV 160 120 30.0 JeVois PassThrough

YUYV 352 288 60.0 YUYV 352 288 60.0 JeVois SaveVideo
#YUYV 352 288 30.0 YUYV 352 288 30.0 JeVois PassThrough

YUYV 176 144 120.0 YUYV 176 144 120.0 JeVois SaveVideo
#YUYV 176 144 60.0 YUYV 176 144 60.0 JeVois PassThrough
#YUYV 176 144 30.0 YUYV 176 144 30.0 JeVois PassThrough

YUYV 88 72 120.0 YUYV 88 72 120.0 JeVois SaveVideo
#YUYV 88 72 60.0 YUYV 88 72 60.0 JeVois PassThrough
#YUYV 88 72 30.0 YUYV 88 72 30.0 JeVois PassThrough

####################################################################################################
### Save video to disk, no preview over USB
####################################################################################################

NONE 0 0 0 YUYV 320 240 60.0 JeVois SaveVideo
NONE 0 0 0 YUYV 320 240 30.0 JeVois SaveVideo
NONE 0 0 0 YUYV 176 144 120.0 JeVois SaveVideo

####################################################################################################
### Demo: Saliency + gist + face detection + object recognition
####################################################################################################

YUYV 640 312 50.0 YUYV 320 240 50.0 JeVois DemoSalGistFaceObj

####################################################################################################
### Demo: JeVois intro movie, then Saliency + gist + face detection + object recognition
####################################################################################################

YUYV 640 360 30.0 YUYV 320 240 30.0 JeVois JeVoisIntro
YUYV 640 480 30.0 YUYV 320 240 30.0 JeVois JeVoisIntro

####################################################################################################
### Demo: Saliency and gist
####################################################################################################

#YUYV 176 90 120.0 YUYV 88 72 120.0 JeVois DemoSaliency
#YUYV 320 150 60.0 YUYV 160 120 60.0 JeVois DemoSaliency
#YUYV 352 180 120.0 YUYV 176 144 120.0 JeVois DemoSaliency
#YUYV 352 180 100.0 YUYV 176 144 100.0 JeVois DemoSaliency
YUYV 640 300 60.0 YUYV 320 240 60.0 JeVois DemoSaliency *
#YUYV 704 360 30.0 YUYV 352 288 30.0 JeVois DemoSaliency
#YUYV 1280 600 15.0 YUYV 640 480 15.0 JeVois DemoSaliency

####################################################################################################
### Production: Saliency and gist
####################################################################################################

# saliency + feature maps + gist
#GREY 120 25 60.0 YUYV 320 240 60.0 JeVois SaliencyGist

# saliency + feature maps
#GREY 120 15 60.0 YUYV 320 240 60.0 JeVois SaliencyGist

# saliency + gist
#GREY 20 73 60.0 YUYV 320 240 60.0 JeVois SaliencyGist

# saliency only
#GREY 20 15 60.0 YUYV 320 240 60.0 JeVois SaliencyGist

# gist only
#GREY 72 16 60.0 YUYV 320 240 60.0 JeVois SaliencyGist

####################################################################################################
### Demo: Background subtraction
####################################################################################################

#YUYV 640 240 15.0 YUYV 320 240 15.0 JeVois DemoBackgroundSubtract
YUYV 320 120 30.0 YUYV 160 120 30.0 JeVois DemoBackgroundSubtract

####################################################################################################
### Demo: QR-code and barcode detection and decoding
####################################################################################################

#YUYV 640 526 15.0 YUYV 640 480 15.0 JeVois DemoQRcode
YUYV 320 286 30.0 YUYV 320 240 30.0 JeVois DemoQRcode
#NONE 0 0 0 YUYV 640 480 15.0 JeVois DemoQRcode
#NONE 0 0 0 YUYV 320 240 30.0 JeVois DemoQRcode

####################################################################################################
### Road following using vanishing point
####################################################################################################

NONE 0 0 0 YUYV 320 240 30.0 JeVois RoadNavigation
#NONE 0 0 0 YUYV 176 144 120.0 JeVois RoadNavigation
YUYV 320 256 30.0 YUYV 320 240 30.0 JeVois RoadNavigation
YUYV 176 160 120.0 YUYV 176 144 120.0 JeVois RoadNavigation

####################################################################################################
### Demo of ARM-Neon SIMD image processing
####################################################################################################

YUYV 960 240 30.0 YUYV 320 240 30.0 JeVois DemoNeon

####################################################################################################
### Dense SIFT using VLfeat library
####################################################################################################

# very slow, min keypoint step is 17
#YUYV 448 240 5.0 YUYV 320 240 5.0 JeVois DenseSift

# slow too, min keypoint step is 11
#YUYV 288 120 5.0 YUYV 160 120 5.0 JeVois DenseSift

# raw keypoints only, assuming step=11, binsize=8
GREY 128 117 5.0 YUYV 160 120 5.0 JeVois DenseSift

####################################################################################################
### Salient regions
####################################################################################################

YUYV 64 192 25.0 YUYV 320 240 25.0 JeVois SalientRegions
#YUYV 100 400 10.0 YUYV 640 480 10.0 JeVois SalientRegions

####################################################################################################
### Superpixel image segmentation/clustering
####################################################################################################

GREY 320 240 30.0 YUYV 320 240 30.0 JeVois SuperPixelSeg

####################################################################################################
### Eye tracking using the openEyes toolkit
####################################################################################################

#GREY 640 480 30.0 YUYV 640 480 30.0 JeVois DemoEyeTracker
#GREY 320 240 60.0 YUYV 320 240 60.0 JeVois DemoEyeTracker
GREY 176 144 120.0 YUYV 176 144 120.0 JeVois DemoEyeTracker

####################################################################################################
### Demo: ArUco augmented-reality markers detection and decoding
####################################################################################################

NONE 0 0 0.0 YUYV 320 240 30.0 JeVois DemoArUco
YUYV 320 260 30.0 YUYV 320 240 30.0 JeVois DemoArUco
YUYV 640 500 20.0 YUYV 640 480 20.0 JeVois DemoArUco

####################################################################################################
### Edge detection using Canny
####################################################################################################

GREY 640 480 29.0 YUYV 640 480 29.0 JeVois EdgeDetection
GREY 320 240 59.0 YUYV 320 240 59.0 JeVois EdgeDetection
#GREY 176 144 119.0 YUYV 176 144 119.0 JeVois EdgeDetection

####################################################################################################
### Edge detection using 4 Canny filters in parallel, with different settings
####################################################################################################

GREY 320 960 45.0 YUYV 320 240 45.0 JeVois EdgeDetectionX4

####################################################################################################
### Color-based object tracker
####################################################################################################

NONE 0 0 0.0 YUYV 320 240 60.0 JeVois ObjectTracker
YUYV 320 254 60.0 YUYV 320 240 60.0 JeVois ObjectTracker

####################################################################################################
### GPU color image processing demo
####################################################################################################

#RGB565 320 240 22.0 YUYV 320 240 22.0 JeVois DemoGPU

####################################################################################################
### Combo CPU multithreaded saliency/gist + 4x GPU grayscale image processing demo
####################################################################################################

GREY 160 495 60.0 YUYV 160 120 60.0 JeVois DemoCPUGPU

####################################################################################################
### Fast optical flow computation
####################################################################################################

GREY 176 288 100 YUYV 176 144 100 JeVois OpticalFlow

####################################################################################################
### Object detection using SURF keypoints
####################################################################################################

YUYV 320 252 30.0 YUYV 320 240 30.0 JeVois ObjectDetect

####################################################################################################
### Salient region detection and identification using SURF keypoints
####################################################################################################

YUYV 320 288 30.0 YUYV 320 240 30.0 JeVois SaliencySURF

####################################################################################################
### CPU + GPU + NEON burn test
####################################################################################################

YUYV 640 300 10.0 YUYV 320 240 10.0 JeVois BurnTest