Skip to content

Commit

Permalink
Betters drivers registration, new version
Browse files Browse the repository at this point in the history
  • Loading branch information
@sarxos
sarxos committed Jul 22, 2012
1 parent a34d759 commit a98f1aa
Show file tree
Hide file tree
Showing 9 changed files with 74 additions and 241 deletions.
220 changes: 4 additions & 216 deletions README.md
View file
@@ -1,224 +1,12 @@
# Java Webcam Capture

Allows you to use your PC webcam directly from Java.
This library allows you to use your build-in or external webcam directly from Java.

[![Build Status](https://secure.travis-ci.org/sarxos/webcam-capture.png?branch=master)](http://travis-ci.org/sarxos/webcam-capture)

## I Want To Use It

[Download complete ZIP](http://www.sarxos.pl/repo/maven2/com/sarxos/webcam-capture/0.2/webcam-capture-0.2-dist.zip)
and include ```webcam-capture-[version].jar``` in your project's classpath. This ZIP file contains sources, examples, all
required dependencies and compiled library JAR.

If you are a [Maven](http://maven.apache.org/) user you can also add this dependency to your project:

```xml
<dependency>
<groupId>com.sarxos</groupId>
<artifactId>webcam-capture</artifactId>
<version>0.2.1</version>
</dependency>
```

For option 4 you have to also add ```<repository>``` to your pom (at least till it is unavailable from central):

```xml
<repository>
<id>sarxos-repo</id>
<url>http://repo.sarxos.pl/maven2</url>
</repository>
```

## Requirements

1. Java 5 (JRE or JDK) or higher installed
2. Webcam connected, installed and configured

## How To Make It Working

This library utilizes several webcam/video frameworks allowing it to gain access
to web cameras available in the system. As for now it's working correctly with
those data sources:

1. LTI-CIVIL - [download](http://lti-civil.org/download.php)
2. JMF (it cannot be used together with FMJ) - [download](http://www.oracle.com/technetwork/java/javase/download-142937.html)
3. FMJ (it cannot be used together with JMF) - [download](http://fmj-sf.net/downloads.php)

JMF and FMJ are replacements - so for both the same ```JMFdataSource``` data source should be used.
Before you choose one of them let me briefly describe the differences:

### LTI-CIVIL

This is a Java library for capturing images from a video devices source such as a USB camera. It provides a
simple API and does not depend on or use JMF. It's easy to use, LGPL-licensed, which means it can be
redistributed along with your binaries (remember to include original license in your software).

To use it as webcam data source you have to download LTI-CIVIL binaries and add those files
into your project:

```
civil.dll
lti-civil-no_s_w_t.jar
```

Please note that civil.dll has to be stored in your project root directory. If you want to put it
somewhere else you will have to change ```java.library.path``` setting passed as the argument
to JVM executable.

Add below's code line somewhere in your ```main()``` method. Remember that data source has to be
registered before you start using webcam.

```java
Webcam.setDataSource(new CivilDataSource());
```

### OpenIMAJ

OpenIMAJ is a collection of libraries for multimedia analysis written in the Java
programming language.

To use it as a data source you can add this dependency in your pom:

```xml
<dependency>
<groupId>com.sarxos.webcam</groupId>
<artifactId>webcam-capture-openimaj-ds</artifactId>
<version>0.3</version>
</dependency>
```

*NOTE!* I found that video capturing (via webcam) is not yet stable in OpenIMAJ, so
I would not recommend it for production systems right now. However whole library seems
to be growing and we can find it to be very usable piece of code in the near future.

To make ```Webcam``` using this data source:

```java
Webcam.setDataSource(new OpenImajDataSource());
```

### JMF (Java Media Framework)

Supported by Oracle (previously Sun), it is really old, first version is from 1998 and 2.0
has been released somewhere between 1999 - 2000. It has not been updated for years. It's very
fast and reliable, however it cannot be redistributed, so if you would like to create pack
where you would like to include all required binaries, you unfortunately cannot do that with JMF.

[Download JMF](http://www.oracle.com/technetwork/java/javase/download-142937.html) and install
it on your computer. Add JMF JARs to the classpath (if not yet there), and set new data source:

```java
Webcam.setDataSource(new JMFDataSource());
```

### FMJ (aka Freedom for Media in Java)
Complete documentation, API, examples, tutorials and many more can be found here:

FMJ is an open-source project with the goal of providing an alternative to Java Media Framework
(JMF), while remaining API-compatible with JMF. It aims to produce a single API/Framework which
can be used to capture, playback, process, and stream media across multiple platforms. It's compatible
with JMF, but to make it working you have to be really patient - there are many binary dependencies
which are not so trivial t resolve (e.g. avformat-51 from ffmpeg is required).
[http://webcam-capture.sarxos.pl/](http://webcam-capture.sarxos.pl/)

To run _webcam-capture_ with FMJ you will have to [download it](http://fmj-sf.net/downloads.php) and
configure (what is not so trivial).

As FMJ API is compatible with JMF you will have to use the same data source:

```java
Webcam.setDataSource(new JMFDataSource());
```

### QTJ (QuickTime for Java)

Not yet supported...

### TWAIN

Not yet supported...

### DSJ (DirectShow for Java)

Not yet supported...

### JavaCV (Java binding for OpenCV)

Not yet supported...

### OpenIMAJ

Not yet supported...

## How To Use It

To get image and save it to disk:

```java
Webcam webcam = Webcam.getWebcams().getDefault();
webcam.open();
ImageIO.write(webcam.getImage(), "JPG", new File("my-webcam-picture.jpg")); // it will be created in project directory
webcam.close();
```

If you have more then one webcam connected to your computer:

```java
Webcam laptop = Webcam.getWebcams().get(0); // first one will be usually build-in one
Webcam kitchen = Webcam.getWebcams().get(1);
```

To display images from webcam in JPanel:

```java
JPanel panel = new WebcamPanel(webcam); // use panel somehow (as content pane, as subcomponents, etc)
```

To detect motion with your webcam - loop solution:

```java
WebcamMotionDetector detector = new WebcamMotionDetector(Webcam.getDefault());
detector.setInterval(100); // one check per 100 ms
detector.start();

while (true) {
if (detector.isMotion()) {
System.out.println("Detected motion I, alarm turn on you have");
}
Thread.sleep(500);
}
```

To detect motion with webcam - listener solution:

```java
public class DetectMotionExample implements WebcamMotionListener {

public DetectMotionExample() {
WebcamMotionDetector detector = new WebcamMotionDetector(Webcam.getDefault());
detector.setInterval(100); // one check per 100 ms
detector.addMotionListener(this);
detector.start();
}

@Override
public void motionDetected(WebcamMotionEvent wme) {
System.out.println("Detected motion I, alarm turn on you have");
}

public static void main(String[] args) throws IOException {
new DetectMotionExample();
System.in.read(); // keeps your program open
}
}
```

Logging (Logback via SLF4J) is already there, so you can enable it simply by adding
```logback.xml``` configuration file somewhere in your filesystem and calling:

```java
WebcamLogConfigurator.configure("path/to/logback.xml");
```

There are more examples available in ```src/example```, don't forget to check!
[![Build Status](https://secure.travis-ci.org/sarxos/webcam-capture.png?branch=master)](http://travis-ci.org/sarxos/webcam-capture)

## License

Expand Down
2 changes: 1 addition & 1 deletion pom.xml
View file
Expand Up @@ -6,7 +6,7 @@

<groupId>com.github.sarxos</groupId>
<artifactId>webcam-capture-parent</artifactId>
<version>0.3.1</version>
<version>0.3.2</version>
<packaging>pom</packaging>

<name>Webcam Capture - Root POM</name>
Expand Down
6 changes: 3 additions & 3 deletions webcam-capture-driver-civil/pom.xml
View file
Expand Up @@ -5,12 +5,12 @@
<parent>
<groupId>com.github.sarxos</groupId>
<artifactId>webcam-capture-parent</artifactId>
<version>0.3.1</version>
<version>0.3.2</version>
</parent>

<artifactId>webcam-capture-driver-civil</artifactId>
<name>Webcam Capture - LTI CIVIL Data Source</name>
<description>This is LTI Civil implementation of webcam data source. It allows you to capture webcam media without JMF installed.</description>
<name>Webcam Capture - LTI CIVIL Driver</name>
<description>This is LTI Civil implementation of webcam video driver. It allows you to capture webcam images using LTI-CIVIL library.</description>

<repositories>
<repository>
Expand Down
4 changes: 2 additions & 2 deletions webcam-capture-driver-jmf/pom.xml
View file
Expand Up @@ -5,11 +5,11 @@
<parent>
<groupId>com.github.sarxos</groupId>
<artifactId>webcam-capture-parent</artifactId>
<version>0.3.1</version>
<version>0.3.2</version>
</parent>

<artifactId>webcam-capture-driver-jmf</artifactId>
<name>Webcam Capture - JMF Data Source</name>
<name>Webcam Capture - JMF Driver</name>
<description>This is JMF implementation of webcam data source. It allows you to capture webcam media with JMF or FMJ installed.</description>

<repositories>
Expand Down
4 changes: 2 additions & 2 deletions webcam-capture-driver-openimaj/pom.xml
View file
Expand Up @@ -5,12 +5,12 @@
<parent>
<groupId>com.github.sarxos</groupId>
<artifactId>webcam-capture-parent</artifactId>
<version>0.3.1</version>
<version>0.3.2</version>
</parent>

<artifactId>webcam-capture-driver-openimaj</artifactId>
<name>Webcam Capture - OpenIMAJ Data Source</name>
<description>Webcam Capture data source using OpenIMAJ libraries</description>
<description>Webcam Capture driver allowing you to capture images using OpenIMAJ library.</description>

<repositories>
<repository>
Expand Down
2 changes: 1 addition & 1 deletion webcam-capture/pom.xml
View file
Expand Up @@ -5,7 +5,7 @@
<parent>
<groupId>com.github.sarxos</groupId>
<artifactId>webcam-capture-parent</artifactId>
<version>0.3.1</version>
<version>0.3.2</version>
</parent>

<artifactId>webcam-capture</artifactId>
Expand Down
61 changes: 49 additions & 12 deletions webcam-capture/src/main/java/com/github/sarxos/webcam/Webcam.java
View file
Expand Up @@ -3,6 +3,7 @@
import java.awt.Dimension;
import java.awt.image.BufferedImage;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

import org.slf4j.Logger;
Expand All @@ -18,6 +19,13 @@ public class Webcam {

private static final Logger LOG = LoggerFactory.getLogger(Webcam.class);

private static final List<String> DRIVERS_LIST = new ArrayList<String>(Arrays.asList(new String[] {
"com.github.sarxos.webcam.ds.openimaj.OpenImajDriver",
"com.github.sarxos.webcam.ds.civil.LtiCivilDriver",
"com.github.sarxos.webcam.ds.jmf.JmfDriver",
"com.github.sarxos.webcam.ds.buildin.DefaultDriver",
}));

private static class ShutdownHook extends Thread {

private Webcam webcam = null;
Expand All @@ -34,13 +42,6 @@ public void run() {
}
}

private static final String[] DRIVERS = new String[] {
"buildin.DefaultDriver",
"openimaj.OpenImajDriver",
"civil.LtiCivilDriver",
"jmf.JmfDriver",
};

private static WebcamDriver driver = null;
private static List<Webcam> webcams = null;

Expand Down Expand Up @@ -213,7 +214,7 @@ public static List<Webcam> getWebcams() {
webcams = new ArrayList<Webcam>();

if (driver == null) {
driver = WebcamDriverUtils.findDriver(DRIVERS);
driver = WebcamDriverUtils.findDriver(DRIVERS_LIST);
}

for (WebcamDevice device : driver.getDevices()) {
Expand Down Expand Up @@ -285,12 +286,48 @@ public static WebcamDriver getDriver() {
}

/**
* Set new data source to be used by webcam.
* Set new video driver to be used by webcam.
*
* @param ds new data source to use (e.g. Civil, JFM, FMJ, QTJ, etc)
* @param driver new video driver to use (e.g. Civil, JFM, FMJ, QTJ, etc)
*/
public static void setDriver(WebcamDriver ds) {
Webcam.driver = ds;
public static void setDriver(WebcamDriver driver) {
Webcam.driver = driver;
}

/**
* Set new video driver class to be used by webcam. Class given in the
* argument shall extend {@link WebcamDriver} interface and should have
* public default constructor, so instance can be created by reflection.
*
* @param driver new video driver class to use
*/
public static void setDriver(Class<? extends WebcamDriver> driverClass) {
WebcamDriver driver = null;
try {
driver = driverClass.newInstance();
} catch (InstantiationException e) {
throw new WebcamException(e);
} catch (IllegalAccessException e) {
throw new WebcamException(e);
}
Webcam.driver = driver;
}

/**
* Register new webcam video driver.
*
* @param clazz webcam video driver class
*/
public static void registerDriver(Class<? extends WebcamDriver> clazz) {
registerDriver(clazz.getCanonicalName());
}

/**
* Register new webcam video driver.
*
* @param clazzName webcam video driver class name
*/
public static void registerDriver(String clazzName) {
DRIVERS_LIST.add(clazzName);
}
}

0 comments on commit a98f1aa

Please sign in to comment.