✎ peripherals:camera [RasPi Journeys]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Pi Camera Board ======

First of all, we'll have to connect the camera ribbon to the Pi's camera port, refer to the official [[https://www.raspberrypi.org/documentation/usage/camera/README.md|Raspberry Pi website article]] explaining how to:
  * Physically connect it
  * Enable it using ''sudo raspi-config''
  * Use the camera via [[https://www.raspberrypi.org/documentation/usage/camera/raspicam/README.md|a shell]] or [[https://www.raspberrypi.org/documentation/usage/camera/python/README.md|using python]]

----
===== PiCamera =====
----

There are a couple of python libraries available for the Pi Camera.\\
The following is a real-life usage sample of [[http://picamera.readthedocs.io|picamera]]:

To make picamera available **for all users** on the system:
<code>
> sudo apt-get update
> sudo apt-get install python-picamera
[> sudo apt-get install python3-picamera]
</code>
to remove your installation:
<code>
> sudo apt-get remove python-picamera
[> sudo apt-get remove python3-picamera]
</code>

To install picamera in a **Virtualenv**:
<code>
> sudo apt-get install python-pip python-virtualenv
> virtualenv sandbox
[> virtualenv -p python3 sandbox]
> source sandbox/bin/activate
(sandbox) $ pip install picamera
[(sandbox) $ pip-3.2 install picamera]
</code>

More about [[http://picamera.readthedocs.io/en/release-1.10/install2.html#virtualenv-installation|upgrading, removing picamera from a virtualenv]].

----
===== TimeLapses =====
----

One of the possible usage of a the Raspberry Pi Camera is for creating timelapses, be it for fun, scientific research, souvenirs or whatever other purpose.

It's quite easy to setup an autonomous RasPi, equipped with a camera, that can run for about 24h. For example, I attached a Raspberry Pi 3 to a [[http://www.aliexpress.com/item/20000-mAh-ROMOSS-Sense-6-Plus-LCD-Portable-Power-Bank-Charger-External-Battery-Fast-Charging-For/32648921429.html|20000mAh Rosmoss Sense 6 battery pack (+/- 25€)]], allowing, while running the timelapse capture code, more than 24h of autonomy. I can just place it anywhere I see fit, start it and leave it there for up to a day, then come back and collect a nice timelapse of the place it was shooting at!

{{ :peripherals:camera:rosmoss-2-web.jpg?direct&200 |}}

I agree it's a little bulky for an "all terrain" ride, but it has the advantage of being incredibly easy to setup.

Here is a quick summary on how to use this with the picamera library and ffmpeg in order to create an autonomous timelapse machine.

==== PiCamera Code ====
----

First we'll create a file containing some short python code, using the PiCamera library, that will let us program the Pi for taking snapshots every specified seconds. It might look like this:

<code>
> cd /path/to/my/raspi/code/
> mkdir images
> nano picam_timelapse.py

import logging
import time
import picamera

# FS CONFIGURATION
path = '/path/to/my/raspi/code/'
pic_dir = 'images/'

# FILE LOGGING
logger = logging.getLogger('timelapse')
hdlr = logging.FileHandler(path + 'timelapse.log')
formatter = logging.Formatter('%(asctime)s %(levelname)s %(message)s')
hdlr.setFormatter(formatter)
logger.addHandler(hdlr) 
logger.setLevel(logging.INFO) # WARNING/DEBUG

# CAMERA CONTROL
with picamera.PiCamera() as camera:
  # configuration
  camera.hflip = True
  camera.vflip = True
  #camera.rotation = 0
  camera.resolution = (1920, 1080)

  # pre-heat
  camera.start_preview()
  time.sleep(2)

  # timelapse sequencing
  for filename in camera.capture_continuous(path + pic_dir + 'pic-{timestamp:%Y%m%d-%H%M%S}.jpg'):
    logger.info('Captured %s' % filename)
    time.sleep(80) # 80 gets us 24h in 45s at 24 fps
</code>

Save this code using ''CTRL-x'' + ''y''. Then try to run it:
<code>
> python picam_timelapse.py
</code>

=== FS configuration ===

Set the location of your script. As the script is potentially going to be used as a service, we need to specify the full path of all file system locations.

=== File logger ===
This example is logging details to a file, you could as well remove this code, along with the ''logger.info('Captured %s' % filename)'' line, or change the log level to ''WARNING''.\\
Anyway it's here as an example in case you need to log things to a file as the Raspberry Pi might well run off power and shutdown.

The ''print'' command is there to give immediate feedback to the user through the console.

=== Camera configuration ===

The "configuration" options are to be set according to your specific situation, you can refer to the [[http://picamera.readthedocs.io/en/release-1.10/api_camera.html|PiCamera API reference]] for a complete description of all available options.

Specifically, you might be interested in learning more about the [[http://picamera.readthedocs.io/en/release-1.10/fov.html#camera-modes|camera modes]] when it comes to it's resolution.

=== Shots periodicity ===

You might want to change the final ''time.sleep(X)'' value in order to adapt to your requirements, you will have to determine the value you'll use for the pause between each shot. For this example, we wanted to have a final timelapse that would cover a 24h period in a 45s, 24fps, movie. Thus the calculation was as follow:
<code>
Timelapse covered time (24h) in seconds:
24 * 60 * 60s = 86400s

Total number of images to be captured over this period (at 24fps):
45s * 24f/s = 1080f

Time required between shots:
86400s / 1080f = 80s/f
</code>

In our case having a 45s seconds timelapse movie, at 24fps, covering a 24h period requires taking one picture every 80 sec.

==== Script Launch at Startup ====
----

There are a few different ways to have scripts launched at boot time. It can be done [[http://www.instructables.com/id/Raspberry-Pi-Launch-Python-script-on-startup/|using cron]], using [[http://www.raspberrypi-spy.co.uk/2015/02/how-to-autorun-a-python-script-on-raspberry-pi-boot/|auto login and the user's profile file]], or as we'll do here [[http://www.raspberrypi-spy.co.uk/2015/10/how-to-autorun-a-python-script-on-boot-using-systemd/|using systemd]].

We already have our Python script from the previous steps, let's say it's location is:\\
**// /path/to/my/raspi/code/picam_timelapse.py//**

=== Create a unit file ===

Let's create a //unit file//, which is a configuration file for systemd:
<code>
> sudo nano /lib/systemd/system/timelapse.service

[Unit]
Description=Timelapse Camera Service
After=multi-user.target

[Service]
Type=idle
ExecStart=/usr/bin/python /path/to/my/raspi/code/picam_timelapse.py
[Install]
WantedBy=multi-user.target
</code>

Save using: ''CTRL-x'' + ''y'' + ''enter''

We have defined a new service called “Timelapse Camera Service” and we are requesting that it is launched once the multi-user environment is available.

The “Type” is set to “idle” ensures the ExecStart command is only run when everything else has loaded.

To have the output of the script dumped to a text file, one could change the ''ExecStart'' to:
<code>
> ExecStart=/usr/bin/python /path/to/my/raspi/code/picam_timelapse.py > /home/pi/timelapse.log 2>&1
</code>

This last option would be redundant with the Python logger functionality of course.

In order to use our unit file, it has to have 644 privileges:
<code>
> sudo chmod 644 /lib/systemd/system/timelapse.service
</code>

=== Configure systemd ===

We have the unit (configuration) file ready, now let's enable our new service with systemd:
<code>
> sudo systemctl daemon-reload
> sudo systemctl enable timelapse.service
</code>

Now, each time your Raspberry Pi will boot, the timelapse.service will be launched. You can control the service status with:
<code>
> sudo systemctl status timelapse
</code>

==== Combining Images into a Movie ====
----

The above code, will generate a number of jpg files that will accumulate in the targeted directory. Once a sufficient amount of images are available, we can convert them to a movie.

ffmpeg will be the tool that we'll use to combine all those pictures into a movie.\\
Unfortunately the ffmpeg package is not immediately available on Raspbian. You have two choices:

=== 1- Transfer the images to a workstation ===

In this scenario, all captured timelapse jpg images will first be transferred to a workstation which has ffmpeg installed. Then they'll be converted to mp4 on this workstation.

This is the easiest solution and has the advantage of not using the RasPi CPU power, which in the case of an autonomous system can be of importance.

There are at least 3 different ways in which the images can be transferred from the Pi to the workstation:

__Using the SD card:__

Well, yes, taking the SD card off the Pi slot and putting it in a card reader connected to the workstation will allow you to transfer files, as long as the workstation OS is capable of reading ext4 formatted filesystems.

The main drawback of this method is that it obviously requires the Raspberry Pi to be turned off during the operation. It also requires physical access to the Pi to remove and re-insert the SD card. 

__Using SFTP__

This second method is quite straightforward, and is probably optimal for manual operations. Although it could be automated, it is more suitable for punctual system interactions, surveillance and maintenance.

Here we consider that all timelapse images were store on the RasPi's SD Card, in **// /path/to/picamera/storage/images//** and we want to copy them onto our workstation's HD at **// /path/to/wks/storage/images//**, all images being grouped in a directory called **//images//**.

From the workstation's command line:
<code>
> mkdir /path/to/wks/storage/images
> cd /path/to/storage/
> sftp pi@your.ras.pi.ip
sftp> cd /path/to/picamera/storage
sftp> get -r images
</code>

This will initiate the transfer of the whole content of the **//images//** directory from the Raspberry Pi to our workstation.

Please note that, to use the ''get -r'' option, one needs to have the **destination** directory already existing, that is why we created it first.

=== 2- Process files on the Raspberry Pi ===

This will require us to install ffmpeg on the Raspberry Pi. The process for doing this is described on [[http://www.jeffreythompson.org/blog/2014/11/13/installing-ffmpeg-for-raspberry-pi/|jeffreythompson.org's blog]].

Once this is done you should be able to execute the ffmpeg commands right on the Raspberry Pi itself.\\
Be advised that this process uses **a lot of CPU power**, and that's the reason why the first option, transferring files to a workstation to process them, is probably the most efficient one.

But, of course, processing the mp4 file drastically reduces the space usage. For example, a 942 jpg timelapse occupying 382.1MB gets reduced to a 20.2MB mp4 file. So there might obviously be some use cases where one would want to process the files on the RasPi itself, removing jpg files after the conversion process in order to spare storage space.

=== Use ffmpeg to convert .jpg's to a movie ===

The options used are described on [[http://thompsonng.blogspot.be/2013/10/ffmpeg-creating-timelapse-with-ffmpeg.html|thompsonng.blogspot.be]].

So, here is the ffmpeg command line that can be used to perform the conversion:
<code>
> ffmpeg -f image2 -r 24 -i 'timelapse/%*.jpg' -r 24 -s hd1080 -vcodec libx264 my_timelapse.mp4
</code>

Note that one of the tricky part in the following command line is the file selector parameter '' 'timelapse/%*.jpg' '', because using the single ''*'' character would try to replace existing jpg files.