search

caprica / picam

Unofficial Java API library for the Raspberry Pi camera.
GNU General Public License v3.0
49 stars 11 forks source link

readme

You are currently looking at the development branch for picam-2.0.0, if you are looking for the previous version of picam you should switch to the picam-1.x branch.

At the moment this master branch for 2.0.0 is somewhat experimental in that it uses JNI rather than JNA to access the camera and there is a little bit more involved in getting up and running.

If you want to play it safe, use the picam-1.x branch instead, if you want to experiment, test, or help improve the JNI solution then by all means this master branch is for you!

picam

An easy-to-use Open Source Java library to access the Raspberry Pi camera module.

This library provides a direct Java API to the camera - behind the scenes the native MMAL library is used.

This library does not require any external native processes nor does it wrap any native executable program.

The implementation is based loosely on that used by the native RaspiStill utility.

This project is unofficial and is not affiliated in any way with the Raspberry Pi Foundation.

News

Picam 2.0.0 brings a pure JNI implementation rather than using JNA, this should give a modest but notable performance boost compared to the JNA implementation in picam-1.x.

Version 2.0.0+ of picam brings some small API changes, you may have to make some minor adjustments to your code if you decide to move to the new version.

Release are available at Maven Cental.

Installation

Add the following Maven dependency to your project:

<dependencies>
    <dependency>
        <groupId>uk.co.caprica</groupId>
        <artifactId>picam</artifactId>
        <version>2.0.2</version>
    </dependency>
</dependencies>

No other dependencies are necessary.

Since version 2+ of picam, JNI is used directly via the picam native library project.

You can build this library yourself, or use the pre-built shared library that is bundled in the picam jar file.

Testing the Installation

A very basic capture application is provided with the picam jar file. You can test that everything works like this:

java -jar picam-2.0.0.jar 1280 800 test.jpg

The command-line parameters are width, height and filename respectively.

Basic Usage

The first thing to do is to install the picam JNI native library, you can set this up manually if you want, but the simplest way is to have picam do it for you:

import static uk.co.caprica.picam.PicamNativeLibrary.installTempLibrary;

public class PicamTest {

    public static void main(String[] args) {
        // Extract the bundled picam native library to a temporary file and load it
        installTempLibrary();

        // ... your application code ...
    }

}

Using the library itself is simple, first you create a CameraConfiguration using a convenient "builder" approach:

CameraConfiguration config = cameraConfiguration()
    .width(1920)
    .height(1080)
    .encoding(Encoding.JPEG)
    .quality(85);

You can supply as much or as little configuration as you want, sensible defaults will be provided where needed.

Next, create a Camera with that configuration:

try (Camera camera = new Camera(config)) {
    camera.takePicture(new FilePictureCaptureHandler(new File("picam1.jpg")));
    camera.takePicture(new FilePictureCaptureHandler(new File("picam2.jpg")));
}
catch (CameraException e) {
    e.printStackTrace();
}

Captured images can be directly saved to disk, or returned and processed as a byte[].

The above example used a FilePictureCaptureHandler that saves the captured picture directly to disk. You are free to provide your own implementations of a PictureCaptureHandler to suit your own needs.

That example also created a camera, took only a single picture and automatically cleaned up the camera since Camera implements AutoCloseable. There is no reason why you couldn't keep a camera component and take multiple pictures before finally closing the camera yourself. It is important that whichever approach you use you close the camera when you are finished using it to free up the camera and associated resources.

If the colouration of your captured pictures looks a bit "off", try setting a delay value when you take the picture. The delay value is used to give the camera sensor time to "settle" before capturing the image. Even a delay as small as 5ms can make a significant difference. A longer delay for the first capture is sometimes needed.

You can specify the delay like this:

try (Camera camera = new Camera(config)) {
    camera.takePicture(new FilePictureCaptureHandler(new File("picam-1.jpg")), 3000);
    camera.takePicture(new FilePictureCaptureHandler(new File("picam-2.jpg")));
}
catch (CameraException e) {
    e.printStackTrace();
}

This example code fragment shows waiting 3 seconds (3,000 milliseconds) for the first picture, then no delay for the second picture.

The Camera instance is obviously not thread-safe. You must not attempt to use the camera from multiple threads at the same time.

Javadoc

Tutorials

Some new tutorials are available here.

Status

The current API is stable but nevertheless is still subject to change.

Hundres of thousands of images have been captured, but you might like to have a look at this issue.

Feedback is welcome at the github project.

Most major/useful camera features or effects are implemented:

Trademark Acknowledgement

Raspberry Pi is a trademark of the Raspberry Pi Foundation.

Demo Application

This screenshot shows a Java web application running on the Pi:

picam-demo