MultiCamera Data Player

Multi-Camera Data Player

This application is a tool for using and modifying image and video streams gathered using a number of software applications at the QUT CyPhy Lab, allowing users to perform debayering, undistortion and renaming of image data to fit the formats required by further applications. It has a number of built in functions to work on the data formats in this dataset.

Requires

  • Any 32-bit or 64-bit x86 computer
  • A recent version of linux like Ubuntu or Windows
  • CMake
  • OpenCV 1.1 or later (compatible with both OpenCV <=2.1 and >=2.2)
  • VXL 2.0 or later

Download and Install (Linux)

First: get git and cmake. For Ubuntu, type into a terminal:

$ sudo apt-get install git cmake

Also, get OpenCV and VXL and install them. The main dependency on OpenCV is highgui and on VXL is vul. You will likely have success using a package manager like apt-get to install these libraries without having to install from source.

Currently, the code is available as a git repository at:

https://bitbucket.org/michaeldwarren/multicamera_data_player/

To checkout, simply type into a terminal:

$ git clone https://bitbucket.org/michaeldwarren/multicamera_data_player/trunk/ ./multicamera_data_player

This will copy the source into the local multicamera_data_player folder

Make a build directory and change into it:

$ mkdir multicamera_data_player_build; cd multicamera_data_player_build

Generate the makefile

$ cmake ../multicamera_data_player

Make

$ make

Done!

Download and Install (Windows)

The easiest way to use the application on Windows is to download the 32-bit executable multicamera_data_player.rar (4.0MB) or 64-bit executable multicamera_data_player (x64).rar (4.5MB)

If you would like to build the executable yourself, then follow these steps:

Get Visual Studio 2008, the CMake GUI, the OpenCV source and VXL source.

Use the CMake GUI to configure and generate Visual Studio Solution Files in the build environment you prefer (32 or 64 bit) for OpenCV and VXL.
Build these using Visual Studio and make sure you run the INSTALL command.

Get Git.

Once installed, use Git to get the MultiCameraDataPlayer source at:

https://bitbucket.org/michaeldwarren/multicamera_data_player/trunk/

Use the CMake GUI to build MultiCameraDataPlayer for Visual Studio. Point VXL_PATH in the CMake config to the VXL install directory (usually in Program Files) and OPENCV_PATH to the OpenCV install directory if using OpenCV <=2.1 or OPENCV2_PATH to the OpenCV install directory if using OpenCV >=2.2.

Build MultiCameraDataPlayer in Visual Studio. Done! You should now be able to run MultiCameraDataPlayer in your Windows environment.

Running examples

Below are some common use cases with the datasets provided by the CyPhy lab. There are a myriad other use cases and additional functions provided by the player, simply run multicamera_data_player with "-?" to see all the command line arguments for the application.

For the following examples we will assume that the imagery is in a folder titled /Data/101215_153851_MultiCamera0/ and XML intrinsics files are located in /Data/intrinsics/. Modify these folder locations to suit your purposes.

Displaying Imagery

$ ./multicamera_data_player -in /Data/101215_153851_MultiCamera0/ -n 2 -in_format bmp

  • n: Indicates number of image streams. For a stereo pair, this number will be two.
  • in_format: the extension or format of the images. In this case, they are bitmap (.bmp) files.

Input from a list of images without the standard naming convention

$ ./multicamera_data_player -in /Data/101215_153851_MultiCamera0/ -n 2 -list /Data/101215_153851_MultiCamera0/list1.txt,/Data/101215_153851_MultiCamera0/list2.txt

  • n: Indicates number of image streams. For a stereo pair, this number will be two.
  • in_format: the extension or format of the images. In this case, they are bitmap (.bmp) files.
  • list: the path to the list containing the local file names (relative to the path given by the '-in' argument) of each image, with each image name on a new line. Each list corresponds to a particular camera, and the names of the list files are separated by commas in the input argument above.

i.e. list1:

imgleft0001.bmp
imgleft0002.bmp
imgleft0003.bmp
imgleft0004.bmp

list2:

imgright0001.bmp
imgright0002.bmp
imgright0003.bmp
imgright0004.bmp

Input from video files

$ ./multicamera_data_player -in /Data/101215_153851_MultiCamera0/ -n 2 -in_format MP4 -list /Data/101215_153851_MultiCamera0/list1.txt,/Data/101215_153851_MultiCamera0/list2.txt

  • n: Indicates number of image streams. For a stereo pair, this number will be two.
  • in_format: the extension or format of the video files. Video files are restricted to 'avi', 'mpg', 'mpeg' and 'MP4'. In this case, they are MP4 files.
  • list: the path to the list containing the local file names (relative to the path given by the '-in' argument) of the videos, with only one video file on one line of the file. Each list corresponds to a particular camera, and the names of the list files are separated by commas in the input argument above.

i.e. list1:

video1.MPG

list2:

video2.MPG

Displaying Only a Subsection, skipping 5 frames at a time

$ ./multicamera_data_player -in /Data/101215_153851_MultiCamera0/ -n 2 -in_format bmp -start 10 -end 500 -stride 5

  • start: The start image number
  • end: The end image number
  • stride: How many frames to skip per update. A stride of 5 in this case will display images 10, 15, 20, 25 etc.
  • n: Indicates number of image streams. For a stereo pair, this number will be two.
  • in_format: the extension or format of the images. In this case, they are bitmap (.bmp) files.

Debayering

$ ./multicamera_data_player -in /Data/101215_153851_MultiCamera0/ -n 2 -in_format bmp -bayer 33

  • bayer: The debayering method for each image stream. The numbers range from 0 to 3, and related to BayerGR8, BayerGB8, BayerBG8 etc. Practice with the numbers until the image colour looks correct for each stream. The number must have the same number of elements as image streams. For one stream use '3', for two use '33' etc.

Inverting

$ ./multicamera_data_player -in /Data/101215_153851_MultiCamera0/ -n 2 -in_format bmp -invert 1

  • invert: The stream numbers to invert. Specify the numbers (limited to single digit image streams) of the streams to invert. i.e. '-invert 1' will invert stream 1, '-invert 01' will invert both streams 0 and 1.

Undistortion

$ ./multicamera_data_player -in /Data/101215_153851_MultiCamera0/ -n 2 -in_format bmp -bayer 33 -undistort /Data/intrinsics/

  • undistort: This will undistort the images in each stream using the intrinsics and distortion parameters located in /Data/intrinsics/

Output to images

$ ./multicamera_data_player -in /Data/101215_153851_MultiCamera0/ -n 2 -in_format bmp -bayer 33 -output_images -out_format png -out /Data/image_output/

  • output_images: A flag that is required if outputting image data from the input
  • out_format: The output format of the images
  • out: The output directory the new images will go in.
  • overwrite: Force overwriting of the directory name and any other files with the same name in the output folder.

The above command will export images in the output folder with the same naming convention as the input, but debayering colour pngs.
In this case, we are not undistorting.

Output to video

$ ./multicamera_data_player -in /Data/101215_153851_MultiCamera0/ -n 2 -in_format bmp -output_video -out_codec HFYU -out_format avi -out /Data/video_output/

  • output_video: A flag that is required if outputting video data from the input
  • out_codec: The codec of the output video, dependent on the codecs ffmpeg supports. This uses the 4 character 'FOURCC' description. We use HuffYUV (HFYU), a lossless but very compatible codec that is easily readable and writable on Linux and Windows.
  • out_format: The output video container that the data should go in. In this case, an avi.
  • out: The output directory the video will go in.
  • overwrite: Force overwriting of the directory name and any other files with the same name in the output folder.

The above command will export two videos in the folder video_output called cam0_HFYU.avi and cam1_HFYU.avi
In this case, we are not undistorting or debayering.

Full example

$ ./multicamera_data_player -in /Data/101215_153851_MultiCamera0/ -n 2 -in_format bmp -bayer 33 -undistort /Data/intrinsics/ -output_video -out_codec HFYU -out_format avi -out /Data/video_output/ -suppress -start 100 -end 5000 -stride 5

  • suppress: This will suppress GUI output to speed up processing.

Changelog

v0.1alpha

  • Initial public release

Help!

I welcome feedback including bugs and comments on any confusing parts of this application. Please use the following form to submit your query:

Calendar November 10, 2020