A python module for controlled image and video recording for the Rasperry Pi
AnimRec is a python package build to help facilitate automated recording using the RPi, with easy, customized, repeated image and video recording. It is specifically designed with the Behavioural Scientist in mind and easily installed and usable for people with limited knowledge of coding.
AnimRec consists of a main recorder module and a number of helper methods that facilitate setting-up the Raspberry Pi camera, configuring the camera, scheduling recordings, and converting recorded media.
This software is created with the Behavioural Scientist in mind but should be of interested to the broader academic community and the general code-minded public. If you use AnimRec, please let me know. I would love to hear how you like and it. Also please cite AnimRec using the following DOI:
Jolles, J. W. (2018) AnimRec: A python module for controlled image and video recording for the Rasperry Pi v1.0.0. Zenodo. https://doi.org/10.5281/zenodo.2529516
To install AnimRec, open a terminal window and enter:
pip install git+https://github.com/JolleJolles/animrec.git
AnimRec is written in Python. It builds strongly on the picamera package and makes use of various utility functions of the associated AnimLab package. Scheduling makes use of CronTab and the associated python-crontab package. Converting requires ffmpeg and OpenCV. AnimRec is created specifically for automated recording with the Raspberry Pi, but its functionality is easily adaptable to a broader range of possible instances.
For installing ffmpeg with h264 support on Raspberry Pi, follow the tutorial here.
The main functionality of AnimRec is the
Recorder class. This class initiates a Recorder instance that sets up the Raspberry Pi to record either a single image, a sequence of images, or a loop of videos. There are many custom configurations that can be set with the animrec.Recorder class, which are divided into 1) general user recording parameters, 2) camera settings, 3) specific video and 4) specific image recording settings, and 5) custom settings linked to the specific rpi being used. For a detailed overview and description of these settings, read the documentation:
Recorder is run for the first time, it creates a
setup directory in the user's home directory to store all relevant setup files. This directory also contains a log file animrec.log that will store all terminal output from when the AnimRec package is used to keep track of your recording history.
In addition, a default configuration file animrec.conf is created. AnimRec is set up in such a way that it is very easy to set and save custom settings that are then automatically used without further user imput. The configuration file can be updated from the command line with the
set_config() method but also edited with any text editor.
In addition to the main recording module, AnimRec contains a number of other modules to facilitate setting-up the Raspberry Pi camera, configuring the camera, scheduling recordings, and converting recorded media:
setgains(): Method that automatically determines the optimal white balance for the current camera position and lighting conditions.
setroi(): Method that lets the user draw a rectangle on a live stream of the rpi camera to create the region of interest to be used for recording.
schedule(): Method that enables the scheduling of automated image and video recording jobs. Please see the specific documentation:
Converter(): Class that enables converting videos to
.mp4format with the option to resize them and print a frame number in the top left corner. Uses multiprocessing so multiple videos can be converted simultaneously.
AnimRec has three recording modes:
vid. Files are automatically stored in the configured directory (
recdir), by default a directory called
recordings, and are automatically named according to the provided
label, the computer name, the date and time, and the session number or image sequence nr (see examples below).
imgmode: This mode records a single image with the custom settings and then quits. Example of filename: "pilot_180312_PI13_101300.jpg".
imgseqmode: This mode creates a controlled sequence of images based on either a set duration (setting
imgtime) or total number of images to be recorded (setting
imgnr) with a certain delay between images (setting
imgwait). The minimum of imgnr and the calculated number of images based on
imgtimewill be selected. For example, if one wishes to specifically record 100 images 10.0s after one another, one would use the settings:
imgtime=9999, or if one wishes to record images every 0.5s for 10 hours irrespective of their total number one would use:
imgtime=36000. Example of filename: "pilot_180312_PI13_img00231_101300.jpg".
vidmode: This mode records a loop of standardized videos based on the custom settings. After each reording has finished, the user is asked if a new recording should be started or the recorder should exit. Specific settings that can be set for this mode are
vidfps, the framerate of the video;
vidduration, the duration of the video; and
viddelay, extra recording time in seconds that will be added to vidduration, for example to film acclimatisation time for observations but that will be automatically ignored in later tracking of the video. Example of filename: "pilot_180312_PI13_S01_101300.h264".
Record in low light
To record in low light conditions, the
shutterspeed parameter should be set (in microseconds). When recording something that moves at a considerable speed, motion blur becomes clearly visible when a shutter speed is used of above 50000. Tracking might still be possible in some cases, such as when blob detection is used. However, tracking barcodes or other methods that use details of the object, motion blur will likely result in failure.
It is important to note that the frames recorded each second (FPS) will be automatically adapted to accomodate the shutter speed. For example, a shutter speed of 200000 is equivalent to 1/5th of a second and so a maximum fps of 5 would be possible and will therefore be set automatically.
It is default that images and videos are stored in a folder
recordings in the home directory of the RPi. If you want to store in a different folder instead just add the foldername for the parameter
recdir. If the folder does not exist yet it will automatically create one (make sure not to have spaces in the foldername). If
recdir is left empty it will store videos in the home directory.
It is also possible to store recordings on a NAS drive connected to the network. Simply add "NAS" to the
recdir parameter. AnimRec will automatically check if the folder is linked to a mounted drive and if not store in the home directory. Make sure that the NAS drive has been correctly mounted.
- Install the latest version of Raspbian and make sure it is fully up to date and has python installed:
sudo apt-get update && sudo apt-get upgrade.
- Set up the Raspberry Pi with an (IR) camera and position it in such a way that it records the zone of interest (using the
raspistill -t 0 -kcommand).
- Install AnimRec by following the steps above and make sure all dependencies are also installed.
- Carefully read the animrec documentation to understsand the large range of possible settings (
- Run the
animrec.Recorder()class for the first time to create the default setup directory and configuration settings.
- Create the ideal light settings for the camera. This is easiest done by creating a single test image and changing the settings until satisfied with the light levels. Camera light levels depend on the following parameters:
compensation. See the code below for an example how to set the light levels.
- Now set the other configuration settings for the recording, such as the
saturationetc. To see all potential parameters enter:
- When wanting to record coloured images or video, make sure you set the right white balance. The best fitting white balance can automatically determined with the
set_gains()method. Make sure that a white background is provided in the Camera when running this method.
- Now optionally run the
set_roi()method to get the right region of interest to be used for recording, linked to the resolution set with the Recorder class. If not used the full camera screen will be used.
- Now you are ready to run recordings with the
Record()method. It is also possible to schedule recordings in the future! To so so use the
schedule()method after reading its documentation:
- After finishing your recordings you can now potentially convert your media, either folders of images or .h264 files, to .mp4 files with the
To run AnimRec recordings from a script it is important that AnimRec is initiated at least once and has the right configuration settings. To do so, the simplest way is to open an instance of Python and run the following commands:
# Import the package import animrec # Initiate the recorder instance AR = animrec.Recorder() # Create 3 test images for getting the right light levels AR.set_config(label="test", rectype="img", iso=200, compensation=0, contrast=20) AR.set_config(brightness=45) AR.record() AR.set_config(brightness=50) AR.record() AR.set_config(brightness=55) AR.record() # Config for videos AR.set_config(viddims = (1640, 1232), vidfps = 24, vidduration = 5, viddelay = 2) # Dynamically set the Gains AR.set_gains() # Draw the region of interest AR.set_roi()
Now the required AnimRec setup files are created and the configuation is as required, we can simply run the Record function to start recording. One way to do this is to create a very simple script like
import animrec AR = animrec.Recorder() AR.record()
and run that from the terminal:
You could also immideately run the code in terminal:
python -c import animrec; AR=animrec.Recorder(); AR.record()
To make running AnimRec even easier, we can create an alias for our recording script with a custom command. For this we need to open the
.bashrc file in our root directory:
sudo nano ~/.bashrc
and add the following to the bottom of the file:
alias rec='sudo rpirec.py'
Now all you need to enter in terminal to start Animrec is
rec, and AnimRec automatically starts with your custom settings.
A nice alternative is to make use of Jupyter. This is an open-source web application that allows you to create python scripts (among many other coding languages) that contain live code, equations, and visualizations that can be executed on a cell-by-cell basis. Jupyter is a great way to sequentually run parts of your code and problem solve it.
To install Jupyter type in:
python -m pip install jupyter
Then to simply start jupyter type
jupyter notebook in Terminal. An alternative way is to use nteract, a free software package for Mac. You can find it here.
Tutorial notebooks for working with AnimRec are provided in the notebooks folder of the package.
Released under a Apache 2.0 License. See LICENSE for details.