Skip to content

Commit

Permalink
initial commit
Browse files Browse the repository at this point in the history
  • Loading branch information
@ennerf
ennerf committed May 13, 2016
0 parents commit 6b363f9
Show file tree
Hide file tree
Showing 12 changed files with 1,711 additions and 0 deletions.
13 changes: 13 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
/target/

# Mac
.DS_Store

# Eclipse
.classpath
.project
.settings

# IntelliJ
*.iml
.idea
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
### May 13, 2016
Initial public release

572 changes: 572 additions & 0 deletions LICENSE.txt

Large diffs are not rendered by default.

51 changes: 51 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
HebiCam
======

Introduction
------------

HebiCam is a MATLAB class that supports live video acquisition from a variety of sources. It is similar in functionality to MATLAB's [IP Camera](http://se.mathworks.com/hardware-support/ip-camera.html) support package, but provides support for a wider range of formats. HebiCam uses [JavaCV](https:/bytedeco/javacv), and thus supports all formats that are supported by OpenCV and FFMpeg, including h264 and mjpeg streams. USB cameras are supported as well.

Prerequisites
------------
HebiCam has been tested on Windows7/8, Ubuntu 14.04, and OSX Yosemite using MATLAB 2014a and 2015a. However, it should work on all MATLAB versions after 2009a. It does not require any particular Tooboxes.

Sample Usage
------------
```matlab
%% Connect to a device, e.g., an Axis MJPG stream
url = 'http://<ip address>/mjpg/video.mjpg?resolution=640x480';
cam = HebiCam(url);
%% Live display of continuously acquired frames
figure();
fig = imshow(getsnapshot(cam));
while true
set(fig, 'CData', getsnapshot(cam));
drawnow;
end
```

Sample Use Cases
------------
* [Teleop Taxi](https://youtu.be/zaPtxre4tFc) uses HebiCam to access video from an Android phone. The [IP Webcam](https://play.google.com/store/apps/details?id=com.pas.webcam&hl=en) Android App can be downloaded for free in the Play store.
* [ICRA Demo - 4DOF Arm + Vision](https://youtu.be/R0nQSxt8uic) uses HebiCam to simultaneously access streams of two Axis IP cameras, and MATLAB's computer vision toolbox for 3D stereo vision. The robot trajectories were calculated in the same MATLAB instance.

How it works
------------
The computationally intensive nature of video decoding can be a problem for languages like MATLAB, which limit users to a single thread. MATLAB does offer bindings for other languages (e.g. Java) that enable background threading, but getting high-resolution images back into MATLAB can be prohibitively expensive. This project aims to get around this limitation by using Java/C++ to acquire images, and shared memory to get these images into MATLAB. Synchronization of shared memory is achieved via Java locks.

**Workflow**
* MATLAB creates a Java object, which launches a background thread for video acquisition
* The Java thread uses [JavaCV](https:/bytedeco/javacv), which uses JNI to wrap the C++ bindings for OpenCV and FFMpeg, to establish the connection and continuously acquire images
* Acquired images get converted into MATLAB's column major format
* Converted images are written into shared memory
* MATLAB copies the image from shared memory into a local variable

This enables accessing high quality (1080p h264) video streams with almost no overhead (<50us) to the main MATLAB thread. However, in practice we usually use 640x480 resolution images for any actual computer vision tasks.

Installation from Source
------------
* Setup [Maven](https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html)
* Run `mvn package`
* Copy the resulting *-all*.jar file and all *.m files into a directory on your MATLAB path
182 changes: 182 additions & 0 deletions pom.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,182 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

<modelVersion>4.0.0</modelVersion>

<groupId>us.hebi.matlab</groupId>
<version>1.0-SNAPSHOT</version>
<artifactId>hebicam</artifactId>

<name>HebiCam</name>
<description>MATLAB utility for streaming video acquisition</description>

<licenses>
<license>
<name>Apache License, Version 2.0</name>
<url>http://www.apache.org/licenses/LICENSE-2.0</url>
<distribution>repo</distribution>
</license>
<license>
<name>GNU General Public License (GPL) version 2, or any later version</name>
<url>http://www.gnu.org/licenses/</url>
<distribution>repo</distribution>
</license>
<license>
<name>GPLv2 with Classpath exception</name>
<url>http://www.gnu.org/software/classpath/license.html</url>
<distribution>repo</distribution>
</license>
</licenses>

<developers>
<developer>
<name>Florian Enner</name>
<email>[email protected]</email>
</developer>
</developers>

<scm>
<url>https:/HebiRobotics/HebiCam</url>
<connection>scm:git:git:/HebiRobotics/HebiCam.git</connection>
<developerConnection>scm:git:ssh://[email protected]/HebiRobotics/HebiCam.git</developerConnection>
</scm>

<properties>
<!-- Dependency versions. KEEP IN ALPHABETICAL ORDER-->
<javacv.version>0.11</javacv.version>
<javacpp.version>0.11</javacpp.version>
<junit.version>4.11</junit.version>

<opencv.version>2.4.11</opencv.version>
<ffmpeg.version>2.6.1</ffmpeg.version>

<!-- Target OS Architecture -->
<target.arch>-x86_64</target.arch>

<!-- Default to minimum Java version compatible with MATLAB >2009a -->
<maven.compiler.source>1.6</maven.compiler.source>
<maven.compiler.target>1.6</maven.compiler.target>

<!-- Other Properties -->
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

<dependencies>

<!-- JavaCV source (OpenCV, FFmpeg, etc.) -->
<dependency>
<groupId>org.bytedeco</groupId>
<artifactId>javacv</artifactId>
<version>${javacv.version}</version>
</dependency>

<!-- OpenCV Binaries -->
<dependency>
<groupId>org.bytedeco.javacpp-presets</groupId>
<artifactId>opencv</artifactId>
<version>${opencv.version}-${javacpp.version}</version>
<classifier>windows${target.arch}</classifier>
</dependency>
<dependency>
<groupId>org.bytedeco.javacpp-presets</groupId>
<artifactId>opencv</artifactId>
<version>${opencv.version}-${javacpp.version}</version>
<classifier>macosx${target.arch}</classifier>
</dependency>
<dependency>
<groupId>org.bytedeco.javacpp-presets</groupId>
<artifactId>opencv</artifactId>
<version>${opencv.version}-${javacpp.version}</version>
<classifier>linux${target.arch}</classifier>
</dependency>

<!-- FFmpeg Binaries -->
<dependency>
<groupId>org.bytedeco.javacpp-presets</groupId>
<artifactId>ffmpeg</artifactId>
<version>${ffmpeg.version}-${javacpp.version}</version>
<classifier>windows${target.arch}</classifier>
</dependency>
<dependency>
<groupId>org.bytedeco.javacpp-presets</groupId>
<artifactId>ffmpeg</artifactId>
<version>${ffmpeg.version}-${javacpp.version}</version>
<classifier>macosx${target.arch}</classifier>
</dependency>
<dependency>
<groupId>org.bytedeco.javacpp-presets</groupId>
<artifactId>ffmpeg</artifactId>
<version>${ffmpeg.version}-${javacpp.version}</version>
<classifier>linux${target.arch}</classifier>
</dependency>

<dependency> <!-- Unit Tests -->
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>${junit.version}</version>
<scope>test</scope>
</dependency>
</dependencies>

<build>
<plugins>

<plugin> <!-- Add MATLAB script(s) to target dir to make it easier to find -->
<artifactId>maven-resources-plugin</artifactId>
<version>2.6</version>
<executions>
<execution>
<id>copy-resources</id>
<phase>validate</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${basedir}/target/</outputDirectory>
<resources>
<resource>
<directory>${basedir}/src/main/resources/matlab/</directory>
<filtering>true</filtering>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>

<plugin> <!-- Builds a full-assembly jar and can rename classpaths -->
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>2.3</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<artifactSet>
<excludes>
<!-- Exclude binaries that are not needed, but referenced by JavaCV -->
<exclude>org.bytedeco.javacpp-presets:flycapture:jar:*</exclude>
<exclude>org.bytedeco.javacpp-presets:libdc1394:jar:*</exclude>
<exclude>org.bytedeco.javacpp-presets:libfreenect:jar:*</exclude>
<exclude>org.bytedeco.javacpp-presets:videoinput:jar:*</exclude>
<exclude>org.bytedeco.javacpp-presets:artoolkitplus:jar:*</exclude>
<exclude>org.bytedeco.javacpp-presets:flandmark:jar:*</exclude>
</excludes>
</artifactSet>
</configuration>
</execution>
</executions>
<configuration>
<finalName>${project.artifactId}-${project.version}-all${target.arch}</finalName>
</configuration>
</plugin>

</plugins>
</build>

</project>
Loading

0 comments on commit 6b363f9

Please sign in to comment.