Repository files navigation

imagehub receives and stores images and event messages from multiplesources simultaneously. The sources are Raspberry Pi and other computersrunningimaganode to capture and send images and event messages.

Here is a pair of images shown with their corresponding log entries. These werecaptured by a Raspberry Pi PiCamera and an infrared floodlight:

The log shows the coyote motion events (inbold) from "Barn". It also showsevents from 2 other Raspberry Pi computers that were sending at the same time,"WaterMeter" and "BackDeck". Motion events create camera images like the2 shown above. Temperature events are gathered by sensors attached to theRaspberry Pi computers' GPIO pins. This log and these images were saved bythe imagehub program running on a Ubuntu computer that was receiving events andimages from a dozen imagenodes running on Raspberry Pi computers. The logsnippet shows the event messages from 3 of those imagenodes (WaterMeter,BackDeck and Barn) during an hour around midnight.

imagehub is the "receive and store" part of a distributed computer visionpipeline that is run on multiple computers. Multiple Raspberry Pi(and other) computers runimagenode to capture images, detect motion, light,temperature values, etc.Imagenode then sends event messages and selectedimages toimagehub, which files the events and images for lateranalysis. My typical setup has 8 to 12 sending computers for eachimagehub.

By design,imagehub is a very simple program. It does 2 things:

1. It receives images and stores them.
2. It receives event messages and logs them.

It does this from multiple sources simultaneously. The sources are typically abunch of Raspberry Pi computers with PiCameras and temperature sensors. Keepingimagehub simple allows it to be fast enough to reliably store data frommultiple sources. Analysis of images and responses to queriesare handled by other programs. SeeUsing imagenode in distributed computer vision projectsfor a more detailed explanation of the overall project design. See theYin Yang Ranch projectfor more details about the architecture of theimagenode <-->imageZMQ <-->imagehub system.

• Receives and save images from multiple Raspberry Pi's simultaneously.
• Receives and logs event messages from multiple RPi's simultaneously.
• Uses threading for image writing to enhance responsiveness.
• Threading can be replaced with multiprocessing with minimal code changes.

imagehub has been tested with:

• Python 3.5, 3.6 and 3.7
• OpenCV 3.3 and 4.0+
• PyZMQ 16.0+
• imageZMQ 1.1.1
• Recent and current versions of MacOS, Raspberry Pi OS and Ubuntu
  • NOT yet tested with Raspberry Pi OS Bullseye. Waiting for a productionreplacement for the Python PiCamera module to update imageZMQ and imagehub.I expect to test imagehub with Raspberry Pi OS Bullseye after imageZMQ andimagehub have been tested with Bullseye.
  • Not tested with Windows. I don't have a computer running Windows.I have heard from some users that it is being used with Windowssuccessfully.

imagehub usesimageZMQ to receive event messages and images that arecaptured and sent byimagenode. You will need to install and test bothimageZMQ andimagenode before usingimagehub.The instructions for installing and testingimageZMQ are in theimageZMQ GitHub repository.The instructions for installing and testingimagenode are in theimagenode GitHub repository.

imagehub is still in early development, so it is not yet in PyPI. Get it bycloning the GitHub repository:

git clone https://github.com/jeffbass/imagehub.git

Once you have clonedimagehub to a directory on your local machine,you can run the tests using the instructions below. The instructions assume youhave cloned bothimagehub to the user home directory. Itis also important that you have successfully run all the tests forimageZMQand forimagenode. The recommended testing arrangement is to runimagehubon the same Mac (or other display computer) that you used to run theimagezmq/tests/timing_receive_jpg_buf.py program when you testedimagenode.

imagehub should be tested after you have testedimagenode, because youwill be usingimagenode to send test images and event messages toimagehub.

Bothimagehub andimagenode useimageZMQ for sending and receivingimages and event messages. TheimageZMQ package is pip installable. It islikely that you already have it installed from your tests ofimagenode. Ifnot, it should be pip installed in a virtual environment. For example,my virtual environment is namedpy3cv3.

To installimageZMQ using pip:

workon py3cv3# use your own virtual environment namepip install imagezmq

Testimagehub in the same virtualenv that you installedimagenZMQ in.ForimageZMQ andimagenode testing, my virtualenv is calledpy3cv3.

To testimagehub, you will use the same setup as Test 2 forimagenode.You will runimagenode on a Raspberry Pi with a PiCamera, just as you did forimagenode Test 2. You will runimagehub on the same Mac (or other displaycomputer) that you used to display theimagenode test images.

Neitherimagehub orimagenode are far enough along in their developmentto be pip installable. So they should both be git-cloned to the computers thatthey will each be running on. I recommend doing all testing in the user homedirectory. Here is a simplified directory layout for the computer that will berunningimagehub:

~ # user home directory of the computer running imagehub+--- imagehub.yaml  # copied from imagenode/imagenode.yaml in this repository|+--- imagehub    # the git-cloned directory for imagehub|    +--- sub directories include docs, imagehub, tests|+--- imagehub_data   # this directory will be created by imagehub     +--- images      # images will be saved here     +--- logs        # logs containing event messages will be saved here

Theimagehub directory arrangement, including docs,imagehub code,tests, etc. is a common software development directory arrangement on GitHub.Usinggit clone from your user home directory on yourimagehub computer(either on a Mac, a RPi or other Linux computer) will put theimagehubdirectories in the right place for testing. When theimagehub program runs,it creates a directory (imagehub_data) with 2 subdirectories (images andlogs) to store the images and event messages it receives fromimagenoderunning on one or more RPi's or other computers. Runningimagenode requiresa settings file namedimagehub.yaml. To run the tests, copy the exampleimagehub.yaml file from theimagehub directory to your home directory.Theimagehub.yaml settings file is expected to be in your home directory,but you can specify another directory path using the --path optional argument.I recommend putting theimagehub.yaml file in your home directory fortesting. You can move theimagehub.yaml file to a different directory afteryou have completed the tests.

The first test uses a single Raspberry Pi computer runningimagenodewithimagehub running on Mac or other display computer.It tests that theimagehub software is installed correctly and that theimagehub.yaml file has been copied and edited in a way that works.

The second test runsimagenode on 2 Raspberry Pi computers,withimagehub receiving images and event messages from both RPi's atthe same time. The event logs and image files will record what is sentfrom both RPi's.

Further details of running the tests arehere.

Running the test programs requires that you leave a terminal window open, whichis helpful for testing, but not for production runs. I use systemctl / systemdto startimagehub in production. I have provided an exampleimagehub.service unit configuration file that shows how I startimagehubfor the production programs observing my small farm. I have found the systemctl/ systemd system to be best way to start / stop / restart and check status ofimagehub over several years of testing. For those who prefer using a shellscript to startimagehub, I have included an exampleimagehub.sh. It isimportant to runimagehub in the right virtualenv in production, regardlessof your choice of program startup tools.

In production, you would want to set the test options used to print settingstoFalse; they are only helpful during testing. All errors andimagenodeevent messages are saved in the fileimagehub.log which is located in thedirectory you specify in theimagenode.yaml settingdata_directory:

data_directory:imagehub_data

Theimagehub.yaml settings file is expected to be in the users homedirectory by default. You can specify the path to a different directorycontainingimagehub.yaml by using the optional argument--path:

workon py3cv3# use your own virtual environment namepython3 imagenode.py --path directory_name# directory holding imagehub.yaml

• How imagehub works.
• The imagehub Settings and the imagehub.yaml file.
• Version History and Changelog.
• Research and Development Roadmap.
• The imageZMQ classes that allow transfer of images.
• The imagenode program that captures and sends images.
• The larger farm automation / computer vision project.This project shows the overall system architecture. It also containslinks to myPyCon 2020 talk video and slides explaining the project.

imagehub is in early development and testing. I welcome open issues andpull requests, but because the code is still rapidly evolving, it is bestto open an issue with some discussion before submitting any pull requests orcode changes. We can exchange ideas about your potential pull request and howto best incorporate and test your code.

Animagenode &imagehub user and code contributor @sbkirby has designeda completely different approach to building an imagehub and librariancombination using a broad mix of tools in addition to Python including Node-Red,MQTT, MariaDB and OpenCV in Docker containers. He has posted it in thisGithub repository.I like his approach a lot, although I'm still working on a mostly Pythonapproach to my own librarian.

• ZeroMQ is a great messaging library with great documentationatZeroMQ.org.
• PyZMQ serialization examples provided a starting point forimageZMQ.See thePyZMQ documentation.