{"id":13737628,"url":"https://github.com/jeffbass/imagezmq","last_synced_at":"2025-05-15T03:06:06.226Z","repository":{"id":37734025,"uuid":"123764682","full_name":"jeffbass/imagezmq","owner":"jeffbass","description":"A set of Python classes that transport OpenCV images from one computer to another using PyZMQ messaging.","archived":false,"fork":false,"pushed_at":"2024-07-18T05:54:58.000Z","size":1606,"stargazers_count":1043,"open_issues_count":35,"forks_count":162,"subscribers_count":36,"default_branch":"master","last_synced_at":"2025-05-13T07:10:13.261Z","etag":null,"topics":["imagezmq","opencv-python","python","pyzmq","raspberry-pi"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jeffbass.png","metadata":{"files":{"readme":"README.rst","changelog":"HISTORY.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-03-04T06:54:33.000Z","updated_at":"2025-05-02T17:34:43.000Z","dependencies_parsed_at":"2022-07-12T15:18:07.723Z","dependency_job_id":"e454a3fa-941c-4d5a-b2fe-8e58ff063ec8","html_url":"https://github.com/jeffbass/imagezmq","commit_stats":{"total_commits":202,"total_committers":9,"mean_commits":"22.444444444444443","dds":0.2524752475247525,"last_synced_commit":"b63377eedcd4a7c2210d40a0d138a2fbbc0f4e4b"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffbass%2Fimagezmq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffbass%2Fimagezmq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffbass%2Fimagezmq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffbass%2Fimagezmq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jeffbass","download_url":"https://codeload.github.com/jeffbass/imagezmq/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254264765,"owners_count":22041793,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["imagezmq","opencv-python","python","pyzmq","raspberry-pi"],"created_at":"2024-08-03T03:01:55.482Z","updated_at":"2025-05-15T03:06:06.197Z","avatar_url":"https://github.com/jeffbass.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"====================================\nimageZMQ: Transporting OpenCV images\n====================================\n\nIntroduction\n============\n\n**imageZMQ** is a set of Python classes that transport OpenCV images from one\ncomputer to another using PyZMQ messaging. For example, here is a screen on a\nMac computer showing simultaneous image streams from 8 Raspberry Pi cameras:\n\n.. image:: docs/images/screenshottest.png\n\nUsing **imageZMQ**, this is possible with 11 lines of Python on each Raspberry\nPi and with 8 lines of Python on the Mac.\n\nFirst, run this receiver program on the Mac (or other display computer):\n\n.. code-block:: python\n\n    # run this program on the Mac to display image streams from multiple RPis\n    import cv2\n    import imagezmq\n    image_hub = imagezmq.ImageHub()\n    while True:  # show streamed images until Ctrl-C\n        rpi_name, image = image_hub.recv_image()\n        cv2.imshow(rpi_name, image) # 1 window for each RPi\n        cv2.waitKey(1)\n        image_hub.send_reply(b'OK')\n\n\nThen, on each Raspberry Pi, run this sender program:\n\n.. code-block:: python\n\n    # run this program on each RPi to send a labelled image stream\n    # you can run it on multiple RPi's; 8 RPi's running in above example\n    import socket\n    import time\n    from picamera2 import Picamera2\n    import imagezmq\n\n    sender = imagezmq.ImageSender(connect_to='tcp://jeff-macbook:5555')\n\n    rpi_name = socket.gethostname() # send RPi hostname with each image\n    picam = Picamera2()\n    picam.start()\n    time.sleep(2)  # allow camera sensor to warm up\n    while True:  # send images as stream until Ctrl-C\n        image = picam.capture_array()\n        sender.send_image(rpi_name, image)\n\n\nWow! A video surveillance system with 8 (or more!) Raspberry Pi cameras in\n19 lines of Python.\n\nSee `About the multiple RPi video streaming examples \u003cdocs/more-details.rst\u003e`_\nfor more details about this example.\n\n.. contents::\n\nWhy use imageZMQ?\n=================\n\n**imageZMQ** is an easy to use image transport mechanism for a distributed image\nprocessing network. For example, a network of a dozen Raspberry Pis with cameras\ncan send images to a more powerful central computer. The Raspberry Pis perform\nimage capture and simple image processing like flipping, blurring and motion\ndetection. Then the images are passed via **imageZMQ** to the central computer for\nmore complex image processing like image tagging, text extraction, feature\nrecognition, etc. An example of using **imageZMQ** can be found\nat `Using imageZMQ in distributed computer vision projects \u003cdocs/imagezmq-uses.rst\u003e`_.\n\nEach **imageZMQ** message is a ``(text_message, image)`` tuple. The text \nportion of the tuple identifies the source and other info about the image. In \nthe example above, the ``text_message`` portion identifies which RPi is sending the\nthe image so that the receiver can put each unique RPi image stream into a\nspecific window. More details about the **imageZMQ** tuples in the above example\nare `here \u003cdocs/more-details.rst\u003e`_.\n\nFeatures\n========\n\n- Sends OpenCV images from one computer to another using ZMQ.\n- Can send jpeg compressed OpenCV images, to lighten network loads.\n- Uses the powerful ZMQ messaging library through PyZMQ bindings.\n- Allows a choice of 2 different ZMQ messaging patterns (REQ/REP or PUB/SUB).\n- Enables the image hub to receive and process images from multiple image senders\n  simultaneously. \n\nWhy ZMQ? Why not some other messaging protocol?\n===============================================\n\nThere are a number of high quality and well maintained messaging protocols for\npassing messages between computers. I looked at MQTT, RabbitMQ, AMQP and ROS as\nalternatives. I chose ZMQ and its Python PyZMQ bindings for several reasons:\n\n- ZMQ does not require a message broker. It is a peer to peer protocol that does\n  not need to pass an image first to a message broker and then to the imagehub.\n  This means fewer running processes and less “double handling” of images.\n  OpenCV images are large compared to simple text messages, so the absence of a\n  message broker is important.\n- ZMQ is very fast for passing OpenCV images. It enables high throughput between\n  image senders and image hubs.\n- ZMQ and its PyZMQ bindings are easy to install.\n\n**imageZMQ** has been transporting images from a dozen Raspberry Pi computers\nscattered around my farm to 2 linux image hub servers for over 5\nyears. The RPi's capture and send dozens to thousands of frames frames a day.\n**imageZMQ** has worked very reliably and is very fast. You can learn more about\nmy \"science experiment urban permaculture farm\" project at\n`Yin Yang Ranch project overview. \u003chttps://github.com/jeffbass/yin-yang-ranch\u003e`_\n\n\nMessaging Patterns: REQ/REP versus PUB/SUB\n==========================================\n\nZMQ allows many different messaging patterns. Two are implemented in **imageZMQ**:\n\n- REQ/REP: Each RPi sends an image and waits for a REPLY from the central image\n  hub. The RPi sends a new image only when the REPLY is received. In the REQ/REP\n  messaging pattern, each image sender must await a REPLY before continuing. It is a\n  \"blocking\" pattern for the sender.\n- PUB/SUB: Each RPi sends an image, but does not expect a REPLY from the central\n  image hub. It can continue sending images without awaiting any acknowledgement\n  from the image hub. The image hub provides no REPLY. It is a \"non-blocking\"\n  pattern for the sender.\n\nThere are advantages and disadvantages for each pattern. For further details,\nsee: `REQ/REP versus PUB/SUB Messaging Patterns \u003cdocs/req-vs-pub.rst\u003e`_.\n**REQ/REP is the default.**\n\n\nDependencies and Installation\n=============================\n\n+--------------+--------+---------------+-----------+-------+\n| |pyversions| | |pypi| | |releasedate| | |license| | |doi| |\n+--------------+--------+---------------+-----------+-------+\n\n.. |pyversions| image:: /docs/images/python_versions.svg\n   :target: https://pypi.org/project/imagezmq/\n\n.. |pypi| image:: /docs/images/pypi_version.svg\n   :target: https://pypi.org/project/imagezmq/\n\n.. |releasedate| image:: /docs/images/release_date.svg\n   :target: https://github.com/jeffbass/imagezmq/tree/v.1.2.0\n\n.. |license| image::  /docs/images/license.svg\n   :target: LICENSE.txt\n\n.. |doi| image::  /docs/images/doi.svg\n   :target: https://zenodo.org/records/12770292\n\n**imageZMQ** has been tested with:\n\n- Python 3.5, 3.6, 3.7, 3.8, 3.9, 3.10 and 3.11\n- PyZMQ 16.0, 17.1, 19.0 and 26.0\n- Numpy 1.13, 1.16, 1.18 and 1.24\n- OpenCV 3.3, 4.0, 4.1 and 4.6\n- Raspberry Pi OS Bookworm and Bullseye using PiCamera2\n- Raspbian OS Buster, Stretch and Raspbian Jessie using legacy PiCamera\n\nOpenCV can be challenging to install. There are many example tutorials on the web. \nFor Raspberry Pi computers with current Raspberry Pi OS versions, the Picamera2 \ndocumentation recommends installing OpenCV using apt. \n\nBe sure to install OpenCV, including Numpy, into a Python Virtual Environment.\nBe sure to install **imageZMQ** into the **same** virtual environment. For\nexample, on a Raspberry Pi running Raspberry Pi OS Bookworm, my virtual\nenvironment is named **py311cv4**.\n\nInstall **imageZMQ** using pip:\n\n.. code-block:: bash\n\n    workon py311cv4  # use your virtual environment name\n    pip install imagezmq\n\n**imageZMQ** has a directory of tests organized into sender and receiver pairs.\nYou will get the \"tests\" directory containing all the test programs by\ncloning the GitHub repository:\n\n.. code-block:: bash\n\n    git clone https://github.com/jeffbass/imagezmq.git\n\nOnce you have cloned the imagezmq directory to a directory on your local machine,\nyou can run the tests per the instructions below. You can use imageZMQ in your\nown code by importing it (``import imagezmq``).\n\n**imageZMQ** and all of the software dependencies must be installed on the\ndisplay computer that will be receiving the images AND it must all be installed\non every Raspberry Pi that will be sending images. If you will be using multiple\nRaspberry Pis to capture and send images it is may be helpful to install the\nsoftware on a single Raspberry Pi and test it using the tests below. Once all\nthe tests have run successfully, clone the SD card as needed to use the software\non multiple Raspberry Pis.\n\nRunning the Tests to verify **imageZMQ** is working\n===================================================\n\nAfter you have installed **imageZMQ** you will want to verify that it installed\ncorrectly. The best way to do this is to run some of the test programs that are \nin the ``tests`` folder. The most basic test is a matched pair of sending and\nreceiving programs. The sender program creates a series of OpenCV numbered\nimages and sends them via **imageZMQ**. The receiving program displays the\nnumbered images. You can run both of these programs on the same computer first, \nthen run them on 2 different computers on the same network. This will confirm\nthat **imageZMQ** installed correctly and that you are able to specify and open \nports for transferring OpenCV images between computers. \n\nThere are also test programs that send images from cameras:\n\n1. Raspberry Pi camera module using the PiCamera2 library with Raspberry Pi OS\n2. Webcam or USB camera using OpenCV's cv2.VideoCapture to capture images\n\nThe Picamera2 library requires Raspberry Pi OS Bullseye or later. There are also\nsome test programs that use the original Picamera library for older Raspberry Pi\nOS versions (Buster and older).\n\nFurther details are in `Running the Test Programs \u003cdocs/running-tests.rst\u003e`_.\n\nAdditional Documentation and Examples\n=====================================\n- `API and Two Simple Example Programs \u003cdocs/api-examples.rst\u003e`_\n- `More details about the multiple RPi video streaming example \u003cdocs/more-details.rst\u003e`_\n- `Running the Test Programs \u003cdocs/running-tests.rst\u003e`_\n- `REQ/REP versus PUB/SUB Messaging Patterns \u003cdocs/req-vs-pub.rst\u003e`_\n- `Examples showing different techniques for using imageZMQ \u003cdocs/examples.rst\u003e`_\n- `Using imageZMQ in distributed computer vision projects \u003cdocs/imagezmq-uses.rst\u003e`_\n- `FAQ: Frequently Asked Questions \u003cdocs/FAQ.rst\u003e`_\n- How **imageZMQ** is used in my own projects connecting multiple\n  Raspberry Pi **imagenodes** to an **imagehub**:\n\n  - My Yin Yang Ranch project to manage a small urban permaculture farm:\n    `Yin Yang Ranch project overview \u003chttps://github.com/jeffbass/yin-yang-ranch\u003e`_\n  - `imagenode: Capture and Send Images and Sensor Data \u003chttps://github.com/jeffbass/imagenode\u003e`_\n  - `imagehub: Receive and Store Images and Event Logs \u003chttps://github.com/jeffbass/imagehub\u003e`_\n\n\nI gave a talk about imageZMQ and its use in my Yin Yang Ranch project at\nPyCon 2020:\n**Jeff Bass - Yin Yang Ranch: Building a Distributed Computer\nVision Pipeline using Python, OpenCV and ZMQ**\n\n`PyCon 2020 Talk Video about the project  \u003chttps://youtu.be/76GGZGneJZ4?t=2\u003e`_\n\n`PyCon 2020 Talk Presentation slides  \u003chttps://speakerdeck.com/jeffbass/yin-yang-ranch-building-a-distributed-computer-vision-pipeline-using-python-opencv-and-zmq-17024000-4389-4bae-9e4d-16302d20a5b6\u003e`_\n\nContributing\n============\n**imageZMQ** is still in active development. I welcome open issues and\npull requests, but because the programs are still evolving, it is best to\nopen an issue for some discussion before submitting pull requests. We can\nexchange ideas about your potential pull request and open a development branch\nwhere you can develop your code and get feedback and testing help from myself\nand others. **imageZMQ** is used in my own long running projects and the\nprojects of others, so backwards compatibility with the existing API is\nimportant.\n\nContributors\n============\nThanks for all contributions big and small. Some significant ones:\n\n+------------------------+-----------------+----------------------------------------------------------+\n| **Contribution**       | **Name**        | **GitHub**                                               |\n+------------------------+-----------------+----------------------------------------------------------+\n| Initial code \u0026 docs    | Jeff Bass       | `@jeffbass \u003chttps://github.com/jeffbass\u003e`_               |\n+------------------------+-----------------+----------------------------------------------------------+\n| Added PUB / SUB option | Maksym Bodnar   | `@bigdaddymax \u003chttps://github.com/bigdaddymax\u003e`_         |\n+------------------------+-----------------+----------------------------------------------------------+\n| HTTP Streaming example | Maksym Bodnar   | `@bigdaddymax \u003chttps://github.com/bigdaddymax\u003e`_         |\n+------------------------+-----------------+----------------------------------------------------------+\n| Fast PUB / SUB example | Philipp Schmidt | `@philipp-schmidt \u003chttps://github.com/philipp-schmidt\u003e`_ |\n+------------------------+-----------------+----------------------------------------------------------+\n\nHelpful Forks of imageZMQ\n=========================\nSome users have come up with Forks of **imageZMQ** that I think will be helpful\nto others, either by using their code or reading their changed code. If\nyou have developed a fork of **imageZMQ** that demonstrates a concept that\nwould be helpful to others, please open an issue describing your fork so we\ncan have a discussion first rather than opening a pull request. Thanks!\n\n+----------------------------+------------+----------------------------------------------------------------------+\n| **Helpful Fork**           | **Name**   | **GitHub repository of fork**                                        |\n+----------------------------+------------+----------------------------------------------------------------------+\n| Add timeouts to image      | Pat Ryan   | `@youngsoul \u003chttps://github.com/youngsoul/imagezmq\u003e`_ See CHANGES.md |\n| sender to fix restarts or  |            |                                                                      |\n| non-response of ImageHub   |            |                                                                      |\n+----------------------------+------------+----------------------------------------------------------------------+\n\nAcknowledgements and Thank Yous\n===============================\n- **ZeroMQ** is a great messaging library with great documentation\n  at `ZeroMQ.org \u003chttp://zeromq.org/\u003e`_.\n- **PyZMQ** serialization examples provided a starting point for **imageZMQ**. See the\n  `PyZMQ documentation \u003chttps://pyzmq.readthedocs.io/en/latest/index.html\u003e`_.\n- **OpenCV** and its Python bindings provide great scaffolding for computer\n  vision projects large or small: `OpenCV.org \u003chttps://opencv.org/\u003e`_.\n- **Picamera2** is a well documented `library \u003chttps://datasheets.raspberrypi.com/camera/picamera2-manual.pdf\u003e`_ for accessing the features and\n  settings of the PiCamera modules for various Raspberry Pi single board\n  computers. \n\nCiting this Software\n====================\nTo cite this software in publications, refer to the CITATION.cff file. Or use either of the following: \n\nAPA: \n\nBass, J. (2024). imageZMQ: Transporting OpenCV Images (Version 1.2.0) [Computer software]. https://doi.org/10.5281/zenodo.12770292\n\nBibTex:\n\n@software{Bass_imageZMQ_Transporting_OpenCV_2024,\nauthor = {Bass, Jeff},\ndoi = {10.5281/zenodo.12770292},\nmonth = July,\ntitle = {{imageZMQ: Transporting OpenCV Images}},\nurl = {https://github.com/jeffbass/imagezmq},\nversion = {1.2.0},\nyear = {2024}\n}\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeffbass%2Fimagezmq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeffbass%2Fimagezmq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeffbass%2Fimagezmq/lists"}