RivetCam

RivetCam is a photographic software for Linux operating system, where you can capture still images with full screen live-view. The software was design to be used to create stop-motion videos.

Key features

  • Utilizes the full screen for viewing images,
  • All actions are taken with the computer keyboard (thus no mouse is needed to use),
  • Works with all v4l (video4linux) cameras (UVC webcams),
  • Built with stop-motion in mind:
    • Onion skins,
    • Motion preview,
    • Manual camera controls, e.g. manual focus.
    • Images can be organized to batches.
  • Camera specific configurations can be applied by the user,
  • Resolution of the live-view can be set to match your screen resolution and have better fps.
  • Open source with Java language.

Users guide

Please note, that at this state of the software RivetCam is not recommended for beginners. You will need to run commands in Linux terminal, edit configuration files to access camera specific features, etc.

Install

Requirements

  • Linux
  • Web camera

This software uses v4l (video4linux), so obviously a Linux PC with a compatible web camera is required for this application to work. Java-Runtime needs to be installed (either Oracle JRE, or OpenJDK RE 1.8 or higher) but that is usually already available on most Linux installations.

Steps

Download: https://github.com/prampec/RivetCam/releases

  1. Download the ZIP release from the project page above, or you can alternatively build your own release from the sources.
  2. Unzip the RivetCam.zip archive to a desired place. (You want create a subfolder to unzip the content on that folder.)

Some helper scripts are provided for specific platforms. (As the v4l requires some native libraries to work with java).

Startup

To run the program you can use the provided helper scripts e.g. use the start-x86-64.sh . After startup you should see the preview of the connected webcam in full screen. Now you can use the keyboard to capture a still image, or modify options. See the “Keys” section for details.

You are very likely to want to specify custom configurations (most likely the capture device and resolutions) in the setup.properties. See “Configuration” for details.

A diagnostic tool is also provided see “Diagnostics” for details.

Keys

All the user interaction is done by the keyboard. Thus it is essential to know the keyboard shortcuts. Which are:

Key Function Description
Esc Quit Exit from the application.
Space Capture Captures a still image
L Live view Turns between live-view/preview
Left/Right arrow Navigate in playback When in playback mode, with the arrow keys you can step to a previous and a next image.
P Playback Turns into Playback mode, where the last (some) images are played back in a high fps.
O Onion skin Toggles onion skins on/off: no onion, 1 layer, 2 layers
Backspace Remove last Removes the last captured image.
B New batch Creates new batch for storing further images.
[custom] Control You can configure keys to modify camera-specific controls.

Other keyboard actions can be associate with camera controls in the configuration. See the “Configuration” for details.

Features in details

When the program starts up, you will see a live view of the webcam image. The live-view is likely to be in a lower resolution and lower image quality than the captured image. In RivetCam you can configure different resolution for live-view and for capture. This way the live view can be smooth with high fps. On the down side of this, webcams likely to loose controls when switching. Meaning: e.g. the focus you have set previously are lost when switching to a higher resolution. This is why manual configuration needs to persisted before switching, and loaded in the new resolution.

In preview mode however you will see the actual captured image. In preview mode you can step back and forward within the previously captured photos. We have a cache here with a default of 20 images to choose from.

Playback mode actually the same as the preview mode, but in this mode the last frames played back automatically in a constant frequency.

Onion skin – With this option, previously captured images are also appears on the live view with a transparency. This is very handy when forming moves in a stop-motion video shoot.

Note, the aspect ratio of the still image (preview and onion skin) and the aspect ratio of the live-view may differs according to your configuration. That might cause onion skin pointless, so please consider setting up the still-image and the live-view with same aspect ratio in the configuration.

When removing the last captured photo, it will delete the image from both the filesystem, and the cache. You can delete more images one after an other.

Batch is a group of images. You can organize your shots in batches to simplify further processing. When the software starts up, it always creates photos in a new batch.

Probably to most powerful feature of the application is the camera-specific setup. You can configure your own keyboard shortcuts, that controls the camera. See “Configuration” for details.

Configuration

Many of the software behavior can be changed by a configuration file. A sample configuration file is provided (setup-sample.properties) where you can find samples of the available configurations.

The configuration file is in java-properties format, and should be saved with name “setup.properties” in the launching folder.

If you want to create your own configuration file, I recommend you to start from the provided file like follows:

  1. Copy the existing “setup-sample.properties” file.
  2. Paste it into the same (installation) folder. (Make a duplication.)
  3. Rename the newly created file to become “setup.properties”.
  4. Edit the new setup.properties file, to apply your configuration.

Note that all configurable parameters are optional, and has a default value. This way you do not even need to provide any setup.properties file.

Parameter Description Default
videoDevice Video device file name /dev/video0 (or videoDeviceName, if provided)
videoDeviceName Let RivetCam to look up the video device by a provided name. This time do not provide a videoDevice value. -
imageCacheSize Preview/playback images count 10
playbackFps Instant playback FPS 20
onionAlpha Onion skin transparency (0.1 means not transparent, 0.9 barely to see) 0.6
liveView.resolution Webcam mode for preview 960×544
stillImage.resolution Webcam mode for photo capture 1280×720
stillImage.delayMs Wait milliseconds before take a still image. It is a good idea to let the camera initialize itself after mode switching. 1000
baseDirectoryPath Path for storing batches .
directoryPrefix Prefix when creating batch folders batch-
directoryIndexDigits Number of digits used for batch numbering 2
filePrefix Prefix of photo files img-
filePostfix Postfix of photo files .jpg
fileIndexDigits Number of digits used for file numbering 4
restartFileIndexWithNewDirectory Define whether numbering should be reset to zero when creating a new batch False
manual List of manual control ids
manual.<id>.name Name of the control (as seen on "Diagnostics")
manual.<id>.value Value of the control to set manual mode.
preserve List of ids for persistent controls
preserve.<id>.name Name of the control to preseve (as seen on "Diagnostics")
keys List of ids for custom controls
keys.<id>.name Name of the control to utilize key (as seen on "Diagnostics")
keys.<id>.inc Key to increment the control value. Use java.awt.event.KeyEvent constants, e.g. VK_Q
keys.<id>.dec Same as before, but to decrement the value.

Sample:


videoDevice = /dev/video0
#videoDeviceByName = UVC Camera (046d:0823)

## -- User settings
imageCacheSize = 10
playbackFps = 20
onionAlpha = 0.6

## -- Camera specific settings
liveView.resolution = 960x544
stillImage.resolution = 1280x720
stillImage.delayMs = 1000

manual = focus
manual.focus.name = Focus, Auto
manual.focus.value = 0

preserve = focus
preserve.focus.name = Focus (absolute)

keys = focus
keys.focus.name = Focus (absolute)
keys.focus.inc = VK_Q
keys.focus.dec = VK_W

## -- Files and folders
directoryPrefix = batch-
directoryIndexDigits = 2
filePrefix = img-
filePostfix = .jpg
fileIndexDigits = 4
baseDirectoryPath = .
restartFileIndexWithNewDirectory = False

Diagnostics

List devices

You can list available v4l devices by specifying the “–devices” startup option.

E.g.:

$ ./start-x86-64.sh --devices
[ libvideo.c:68 ] Using libvideo version 0.9-UNKNOWN
Found video devices:
  /dev/video0 - UVC Camera (046d:0823)

Device information

RivetCam provides a diagnostic feature where you can get detailed information of your webcam device.

$ ./start-x86-64.sh --info /dev/video0
[ libvideo.c:68 ] Using libvideo version 0.9-UNKNOWN
Info for device /dev/video0:
  Name: UVC Camera (046d:0823)
  Resolutions: 
    MJPEG - 640x480 160x120 176x144 320x176 320x240 432x240 352x288 544x288 640x360 752x416 800x448 864x480 960x544 1024x576 800x600 1184x656 960x720 1280x720 1392x768 1504x832 1600x896 1280x960 1712x960 1792x1008 1920x1080 1600x1200 2048x1536 2592x1944
    YUYV - 640x480 160x120 176x144 320x176 320x240 432x240 352x288 544x288 640x360 752x416 800x448 864x480 960x544 1024x576 800x600 1184x656 960x720 1280x720 1392x768 1504x832 1600x896 1280x960 1712x960 1792x1008 1920x1080 1600x1200 2048x1536 2592x1944

  Attributes: 
    "Backlight Compensation" = 0 (0..1/1)
    "Brightness" = 128 (0..255/1)
    "Contrast" = 32 (0..255/1)
    "Exposure (Absolute)" = 664 (3..2047/1)
    "Exposure, Auto" = 3 (1: Manual, 2: Shutter priority, 0: Auto, 3: Aperture priority)
    "Exposure, Auto Priority" = 1 (0..1/1)
    "Focus (absolute)" = 68 (0..255/17)
    "Focus, Auto" = 0 (0..1/1)
    "Gain" = 128 (0..255/1)
    "Pan (Absolute)" = 0 (-36000..36000/3600)
    "Power Line Frequency" = 2 (1: 50 Hz, 0: Disabled, 2: 60 Hz)
    "Saturation" = 32 (0..255/1)
    "Sharpness" = 72 (0..255/1)
    "Tilt (Absolute)" = 0 (-36000..36000/3600)
    "White Balance Temperature" = 4000 (2800..6500/1)
    "White Balance Temperature, Auto" = 1 (0..1/1)
    "Zoom, Absolute" = 1 (1..5/1)

Frequently asked questions

  • Will it run on Android? – I don’t think so.
  • Will it run on RaspberryPi? – I believe so. Please test it!

Known bugs

  • Playback FPS is not stable.

Planned improvements

  • Do not crash, when facing with wrong configuration.
  • Continue file numbering when starting up from previous batch.
  • Support more platforms and cameras according to user tests.
  • Use RGB or YUV format instead of mpg when creating a snapshot.
  • Force to use strict FPS while playback.
  • Introduce camera-type¬† based configuration system.
  • Introduce modular access to the main system, e.g. attach a GPIO based control module.
  • On-screen-display message items to have a validity.
  • Multilingual messages

Found a bug or want to Contact me?

Please fill free to contact me with feature requests. If found a problem, please check issues for possible solution at GitHub issues page, where you can also report bugs.

Notes

Run the following command to join the image sequences into an AVI:


ffmpeg -i img-%04d.jpg -r 20 -vcodec libx264 test.avi