Blender-ZMQ-add-on (BlendZMQ)

Blender 2.8x - 3.6 add-on that allows streaming of data (from another computer) into Blender over ZeroMQ sockets, without freezing the interface (publisher-subscriber pattern).

Update

• (2023-06-29) Runs fine on Blender 3.6 without making code changes (tested on Ubuntu)
• v1.2.1 (2022-11-13) - Fixed Python libraries (pyzmq) not findable when installed in userspace
  • On Windows, pip installed libraries might be installed outside the Blender dir. When failing to import a library, an extra import attempt adds site.getusersitepackages() to sys.path.
    • Blender on Windows might be installed under: C:\Program Files\Blender Foundation\Blender 3.3\3.3\python\bin\python.EXE. However, even when referring to this binary, libraries might still be installed under e.g. C:\users\{user}\appdata\roaming\python\python310\site-packages
• v1.2 (2022-11-01) - Now supports Blender version 2.93 LTS and 3.3 LTS! Changes:
  • No Blender restart required anymore
  • Python binary has to be accessed from sys.executable from v2.93 (rather than bpy.app.binary_path_python)
  • Slightly refracted code in PIPZMQ_OT_pip_pyzmq
  • Blender < 2.93 functioning unchanged
  • Test scripts moved under utils/
• v1.1 (2020-02-10) - Blender 2.81+ pip support. Changes:
  • In Blender 2.81 pip is enabled by default. This update takes that behavior into account.
    • If the Enable pip & install pyzmq button fails, it still executes ensurepip.bootstrap(). Restart Blender and try again, it will work this time (on Windows make sure you run with admin rights).

Overview

Blender is very powerful software, but if you run your own code that's a bit heavy, you quickly make the interface unresponsive. I.e freezing the interface. This could be solved with Threading/Async, however, this is difficult due Blender's internal loop (which is more like a game engine). Also, in case of threading, you can't manipulate objects in the main loop of Blender without using e.g. a queue system.

Why not take the program logic and manipulation of data outside Blender, and possibly run heavy code on another PC? Enter ZeroMQ.

ZeroMQ (pyzmq - Python wrapper of ZMQ) is a communication protocol library that allows the sending of data packages between programs (even when written in different languages) by using sockets. Therefore, the data can be send over the network (e.g. TCP), meaning you can even run the software on different machines.

This add-on works by setting a timer function (Blender 2.80+) that checks if a ZeroMQ socket has received a message from outside (using zmq.Poller()). If so, process that data to move selected objects. This timer keeps being invoked until the socket has been disconnected. See for a demonstration:

]

You can take this add-on as an example on how to connect your own programs with Blender.

Prerequisite

• Python (tested with 3.10, probably 2.7, 3.5+ works too) on your system with pyzmq for programs outside Blender.
  • Anaconda (recommended to manage Python environments)
    1. Anaconda 3.10+: https://www.anaconda.com/distribution/
    2. conda create --name bzmq python=3.10 # create environment with Python 3.7
    3. conda activate bzmq # activate newly created environment
    4. conda install -c conda-forge pyzmq=24.0 # install pyzmq in this environment
  • System Python: pip install pyzmq=24.0.*

How to use

1. Download this repository as a .zip by:
   • Go to https://github.com/NumesSanguis/Blender-ZMQ-add-on/releases and download the ZIP, or
   • Clicking the green "Clone or download" button and choose "Download ZIP"
2. Start Blender with Administrator right (at least on Windows) to allow enabling of pip and installing pyzmq (does NOT work with a Snap package install of Blender on Linux, see troubleshooting)
3. In Blender, add this add-on by selecting Edit -> Preferences -> Add-ons ->
   1. Install... -> select downloaded ZIP from step 1 -> Install Add-on
   2. Search: blendzmq -> click checkbox to activate
4. Open side panel in 3D view by
   • Pressing n on your keyboard
   • Dragging < to the left
5. Click "bZMQ" -> "Enable pip & install pyzmq" button
6. Click "Connect socket" button. Now it's waiting for data message from outside.
7. Start outside script to send data into blender (Get the script by downloading from the GitHub repo / unzip previously downloaded ZIP):
   1. Get script by:
      • Unziping the .zip downloaded in step 1
      • In terminal: git clone https://github.com/NumesSanguis/Blender-ZMQ-add-on
   2. Open a terminal and navigate to cd *path*/Blender-ZMQ-add-on/utils
   3. Make sure conda / virtual env is active (e.g. conda activate bzmq) with pyzmq
   4. Execute: python zmq_pub_number_gen.py (Change ip or port by adding --ip 192.168.x.x and/or --port 8080)
8. See objects moving!
   • "Dynamic objects" can be selected to update location of current selected objects
   • "Dynamic objects" can be deselected to keep updating only the objects that were active at deselection time.

Troubleshooting

• If Step 5 (enable pip & install pyzmq) does not work (e.g. Couldn't activate pip.), link Blender to e.g. your bzmq conda environment: https://docs.blender.org/api/current/info_tips_and_tricks.html#bundled-python-extensions

Notes

• Blender Artists: https://blenderartists.org/t/blendzmq-open-source-add-on-streaming-data-into-blender-2-8x-without-freezing-the-interface/
• Gumroad: https://gumroad.com/l/blendzmq
• Blender add-on file structure inspired by btrace: https://github.com/sobotka/blender-addons/tree/master/btrace
• More information about ZeroMQ: https://zeromq.org/
• Why not make your outside Blender software easy to deploy, independent of OS? Take a look at ZeroMQ with Docker: https://github.com/NumesSanguis/pyzmq-docker
• When developing Blender Add-ons, reload all add-ons without restarting Blender by executing: bpy.ops.script.reload()

Acknowledgement

• dr.sybren (bunch of small questions)
• joules (multi-selection of previously selected objects)
• Other people at blender.chat, blender.stackexchange.com and the documentation