Overlay feature and example

[FoamyGuy]

This adds support for overlay and overlay_transparency_color properties which can be used to specify a .bmp file to use as an overlay or frame for the image. The overlay will be shown on the preview if set, and a new function .blit_overlay_into_last_capture() can be used to create and save a combined version of the most recent photo and save it on the SDCard.

This functionality requires: adafruit/Adafruit_CircuitPython_BitmapSaver#34

pre-commit made a few code format tweaks to the basic_camera example code.py which were unrelated to the rest of this PR. Though the new overlay example is built from the basic camera one, and only differs by a few lines.

resolves: #27

There are two basic 320x240 overlay .bmp images included that I used during development and testing of this feature.

In order to be used an overlay images should be .bmp format and contain 24 bit RGB888 Colorspace.

[FoamyGuy]

I don't think I recall seeing before the way this library contains mock/ in the docs folder with portions of displayio mocked out.

I initially added displayio to the mock docs in the conf file (unsuccessfully with improper syntax). But noticed the way this was working afterward and removed the one in conf.py and added mocked out classes for the rest of the things used by the new functionality. I am not certain if I've made the mocked ones correctly though.

[FoamyGuy]

Theoretically many or all of the new imports could be made conditional upon whether the user is using the overlay feature. But since overlay is a property that can be set at any time it would require waiting until the user sets it the first time to import those libraries and pylint doesn't like doing imports from places other than the top of the code.

I think it might be worth it to do it that way and add the pylint exception because then it keeps these libraries from being hard requirements that must be installed in order for PyCamera to be importable.

Right now the required external libraries are listed in optional-requirements.txt, but upon thinking about it more while writing this comment I'm realizing that the way the code is now those requirements are not actually optional. I think it would fail to import if they were missing.

We will need to either do the imports outside the top level as described above, or move those reqs to requirements.txt instead of optional-requirements.txt.

I lean towards making the import conditional upon the first usage of overlay to save disk space and RAM for anyone not actually using the overlay feature. I'll make a new commit with that change. That being said I don't have a super strong opinion if anyone else believes non-optional is better I can swap to that.

[FoamyGuy]

The latest commit adds a second version of the overlay example. In the original version a single overlay file is hardcoded and must be changed by the user if they want to change overlays.

In the new version code_select.py it will now look inside of /sd/overlays/ directory and cycle through all files it finds inside of there when you press the select button. So user can paste all overlays they want inside that directory then with this version they don't need to modify the code in order to change overlays, simply press the select button to go thru them.

I envision adding x,y offsets for the overlay and using the D-Pad buttons to control it's placement. Currently it's hardcoded to 0,0 so it works with full sized frame overlays and similar

[jepler]

didn't test but I love the idea