Explain all functions

code/overlay_functions.py

@@ -1,18 +1,16 @@
-# With credit to Ben Nuttall and for the original version of this code
-
 from PIL import Image
-from time import gmtime, strftime
 from itertools import cycle
 
-# Change these values for your own setup
+# EDIT THESE VALUES ------------------------
 overlays_dir = "/home/pi/allseeingpi/overlays"
-pictures_dir = "/home/pi/allseeingpi"
 overlays = ['girl', 'cowboy', 'top', 'pink', 'glassesnose', 'moustache', 'sunglasses', 'elvis', 'emo', 'blackhat', 'emo2', 'baseball', 'flowers', 'santa', 'alps', 'mop', 'glasses']
-overlay = overlays[0]
+# ------------------------------------------
+
+
+overlay = overlays[0] # Starting value
 
-# Overlay functions 
 def _get_overlay_image(overlay):
-
+    
     # Open the overlay as an Image object
     return Image.open(overlays_dir + "/" + overlay + ".png")
 
@@ -27,16 +25,10 @@ def _pad(resolution, width=32, height=16):
     )
 
 def remove_overlays(camera):
-
+    
     # Remove all overlays from the camera preview
     for o in camera.overlays:
-        camera.remove_overlay(o)
-
-def gen_filename():
-
-    # Generate a filename with a timestamp
-    filename = strftime(pictures_dir + "/image-%d-%m %H:%M.png", gmtime())
-    return filename
+        camera.remove_overlay(o) 
 
 
 def preview_overlay(camera=None, overlay=None):

software.md

@@ -1,14 +1,21 @@
 # Software Installation
+This 'make' resource requires a lot of additional library software. You will need to be connected to the internet to install these extra libraries.
 
 To install the software you need, run the following commands in the terminal:
 
+```bash
+sudo apt-get install python3-picamera python3-pip
+sudo pip3 install guizero
+sudo pip3 install twython
+sudo apt-get install python-PIL
+```
+
+If you are using the Raspberry Pi touch screen to make this resource, you will also need to enter the following commands:
+
 ```bash
 sudo apt-get update
 sudo apt-get upgrade
 sudo apt-get dist-upgrade
 sudo apt-get install raspberrypi-ui-mods
 sudo apt-get install raspberrypi-net-mods
-sudo apt-get install python3-picamera python3-pip
-sudo pip3 install guizero
-sudo pip3 install twython
 ```

worksheet.md

@@ -31,10 +31,12 @@ If you don't have fancy buttons or a touch screen, that's OK too - you can still
 
 1. Situate the buttons in your chosen housing. In the software, the button connected to GPIO 23 will select the next overlay, and the button connected to GPIO 25 will take the picture. (Don't worry if you accidentally wire your buttons up the other way around, simply swap the pin numbers in the code!)
 
-    ![All Seeing Pi in a laser cut box](images/asp-laser.png)
+    ![All Seeing Pi in a laser cut box](images/asp-lasercut.png)
 
 ## Finishing the set up
 
 1. To write the software, you will also need to connect a keyboard and mouse to your Raspberry Pi, as well as a display if you are not using the touchscreen.
 
-1. Power on your Raspberry Pi and check that the touchscreen works if you are using one. Once you have set up your hardware, head over to [worksheet 2](worksheet2.md) to find out how to write the software to control your All Seeing Pi.
+1. Power on your Raspberry Pi and check that the touchscreen works if you are using one.
+
+Once you have set up your hardware, head over to [worksheet 2](worksheet2.md) to find out how to write the software to control your All Seeing Pi.

worksheet2.md

@@ -114,9 +114,17 @@ With the hardware set up, we can begin to program the software that will make ev
 
 1. Create a subfolder within your `allseeingpi` folder called `overlays` and place your overlay images inside it.
 
-1. We will need some functions to be able to work with our overlays. If you would like to use our [pre-written overlay functions](code/overlay_functions.py), download a copy of the file and save it as `overlay_functions.py` **making sure to save it in your `allseeingpi` directory where the `allseeingpi.py` script is also saved**. If you would like to see a full explanation of what these functions do, or you would prefer to write them yourself, head to the [overlay functions explanation page](worksheet3.md) to find out how to do this.
+1. We will need some functions to be able to work with our overlays. If you would like to use our [pre-written overlay functions](code/overlay_functions.py), download a copy of the file and save it as `overlay_functions.py` **making sure to save it in your `allseeingpi` directory where the `allseeingpi.py` script is also saved**. If you would like to see a full explanation of what these functions do, or you would prefer to write them yourself, head to the [overlay functions explanation page](worksheet3.md) to find out how to do this, then resume the tutorial at the following step.
 
-1. Next to the other `import` statements in your program, add another one to import this file:
+1. In the `overlay_functions.py` file, find the comment `# EDIT THESE VALUES ------------------------`. You will need to change this code to specify two things
+  - Set the `overlays_dir` to the directory where your overlays are stored. If you are following the resource exactly you will not need to change this
+  - Set the `overlays` to be a list of the filenames of the overlays (without extension), surrounded by quotes and separated by commas. For example if you had overlay images called `rock.png`, `paper.png` and `scissors.png` your line of code would look like this:
+
+  ```python
+  overlays = ['rock', 'paper', 'scissors']
+  ```
+
+1. Now go back to your `allseeingpi.py` program. Next to the other `import` statements in your program, add another one to import this file:
 
   ```python
   from overlay_functions import *

worksheet3.md

@@ -1,5 +1,110 @@
 # The All Seeing Pi (Overlay Functions)
 
-This page explains the overlay functions
+This page is for more advanced learners as it explains in detail what the code and functions inside `overlay_functions.py` do. It is possible to make the All Seeing Pi without understanding what these functions do - simply save a copy of the file [overlay_functions.py](code/overlay_functions.py) into the folder with your code and they will be available.
 
-## Making the photo booth
+## Importing necessary libraries
+
+These statements import functions from the `PIL` library to process and save the images and the `itertools` library so that we can cycle through the overlays.
+
+```python
+  from PIL import Image
+  from itertools import cycle
+```
+
+
+## Setting up the variables
+
+This part sets up the directory where the overlays are saved, and the names of the various overlays. The overlay variable is initialised with the first value in the list.
+
+```python
+# EDIT THESE VALUES ------------------------
+overlays_dir = "/home/pi/allseeingpi/overlays"
+overlays = ['girl', 'cowboy', 'top', 'pink', 'glassesnose', 'moustache', 'sunglasses', 'elvis', 'emo', 'blackhat', 'emo2', 'baseball', 'flowers', 'santa', 'alps', 'mop', 'glasses']
+# ------------------------------------------
+overlay = overlays[0] # Starting value
+```
+
+## Get the overlay as a PIL Image
+
+This function is only used within other functions in this file. Given the name of an overlay as a string, it creates a PIL Image object of that overlay and returns it.
+
+```python
+def _get_overlay_image(overlay):
+
+    # Open the overlay as an Image object
+    return Image.open(overlays_dir + "/" + overlay + ".png")
+```
+
+## Pad the overlay
+
+This function ensures that the overlay is padded correctly so it can be displayed on the preview.
+
+```python
+def _pad(resolution, width=32, height=16):
+    # Pads the specified resolution
+    # up to the nearest multiple of *width* and *height*; this is
+    # needed because overlays require padding to the camera's
+    # block size (32x16)
+    return (
+        ((resolution[0] + (width - 1)) // width) * width,
+        ((resolution[1] + (height - 1)) // height) * height,
+    )
+```
+## Remove all overlays
+
+This function iterates over all overlays attached to the `camera` object, and removes them.
+
+```python
+def remove_overlays(camera):
+
+    # Remove all overlays from the camera preview
+    for o in camera.overlays:
+        camera.remove_overlay(o)
+```
+
+# Put the overlay on the camera preview
+
+This function is passed a `PiCamera` object (`camera`) and a string (`overlay`). It removes all overlays currently associated with the camera object, creates a PIL Image object of the chosen overlay called `overlay_img`, pads that image to display correctly and then adds it to the camera preview. The alpha of the preview is set to 128 so that the overlay is semi transparent. If the overlay was made fully opaque it would obscure the camera preview.
+
+```python
+def preview_overlay(camera=None, overlay=None):
+
+    # Remove all overlays
+    remove_overlays(camera)
+
+    # Get an Image object of the chosen overlay
+    overlay_img = _get_overlay_image(overlay)
+
+    # Pad it to the right resolution
+    pad = Image.new('RGB', _pad(camera.resolution))
+    pad.paste(overlay_img, (0, 0))
+
+    # Add the overlay
+    camera.add_overlay(pad.tobytes(), alpha=128, layer=3)
+```
+
+# Save picture with overlay
+
+This function takes the location to save to (`output`) and the given overlay (`overlay`), both as strings. It then creates a PIL Image object of the specified overlay, creates an blank PIL Image to save the output to, and then combines the photograph at the location of `output` with the overlay, re-saving the finished photograph at the `output` location.
+
+```python
+def output_overlay(output=None, overlay=None):
+
+    # Take an overlay Image
+    overlay_img = _get_overlay_image(overlay)
+
+    # ...and a captured photo
+    output_img = Image.open(output).convert('RGBA')
+
+    # Combine the two and save the image as output
+    new_output = Image.alpha_composite(output_img, overlay_img)
+    new_output.save(output)
+```
+
+# Overlays cycle
+
+This code creates an iterable object called a `cycle` which can be used when the `next_overlay_btn` is pressed in order to receive the next overlay in the list. The cycle is needed because when the end of the list of overlays is reached, we want to begin again with the first overlay.
+
+```python
+all_overlays = cycle(overlays)
+```