{"id":20209764,"url":"https://github.com/srmainwaring/gz-python","last_synced_at":"2026-03-03T11:39:22.876Z","repository":{"id":42987539,"uuid":"444885729","full_name":"srmainwaring/gz-python","owner":"srmainwaring","description":"Python bindings for gz-msgs and gz-transport","archived":false,"fork":false,"pushed_at":"2024-04-30T14:52:03.000Z","size":70,"stargazers_count":17,"open_issues_count":7,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-24T11:56:54.803Z","etag":null,"topics":["gazebo","gz-msgs","gz-transport","protobuf","pybind11","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/srmainwaring.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-05T17:07:24.000Z","updated_at":"2024-08-16T09:37:28.000Z","dependencies_parsed_at":"2024-05-06T03:00:32.087Z","dependency_job_id":null,"html_url":"https://github.com/srmainwaring/gz-python","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srmainwaring%2Fgz-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srmainwaring%2Fgz-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srmainwaring%2Fgz-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srmainwaring%2Fgz-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/srmainwaring","download_url":"https://codeload.github.com/srmainwaring/gz-python/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248225653,"owners_count":21068078,"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":["gazebo","gz-msgs","gz-transport","protobuf","pybind11","python"],"created_at":"2024-11-14T05:42:16.743Z","updated_at":"2026-03-03T11:39:17.815Z","avatar_url":"https://github.com/srmainwaring.png","language":"Python","readme":"# Gazebo Python Bindings\n\nThis project provides Python bindings for [`gz-msgs`](https://github.com/gazebosim/gz-msgs) and [`gz-transport`](https://github.com/gazebosim/gz-transport).\n\n[![ubuntu-build](https://github.com/srmainwaring/gz-python/actions/workflows/ubuntu-build.yml/badge.svg)](https://github.com/srmainwaring/gz-python/actions/workflows/ubuntu-build.yml)\n\n## Building with CMake\n\n### Install Gazebo\n\nFollow the installation instructions for [Gazebo Garden](https://gazebosim.org/docs/garden).\nThis project depends directly on [`gz-msgs`](https://github.com/gazebosim/gz-msgs) and [`gz-transport`](https://github.com/gazebosim/gz-transport). These may be either available as system installs or in a source install in a local workspace folder which we assume is `~/gz_ws`.\n\n### Install `gz-python`\n\nClone this repo into the workspace source directory:\n\n```bash\ncd ~/gz_ws/src\ngit clone https://github.com/srmainwaring/gz-python.git\n```\n\n### Build with CMake\n\nCurrently our use of [`pybind11_protobuf`](https://github.com/pybind/pybind11_protobuf) requires the protobuf compiler to generate the Python implementation of the Python protobuf bindings. This is configured with the environment variable:\n\n```bash\nexport PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=python\n```\n\nSet the environment variable determing the Gazebo version.\nThe default is `garden`:\n\n```bash\nexport GAZEBO_VERSION=garden\n```\n\nThen create a build directory, configure and make:\n\n```bash\nmkdir -p ~/gz_ws/src/gz-python/build\ncd ~/gz_ws/src/gz-python/build\ncmake ..\nmake\n```\n\n### Update the Python environment\n\nUpdate the PYTHONPATH to include the location of the extension modules and the\ngenerated Python protobuf bindings.\n\n```bash\ncd ~/gz_ws/src/gz-python\nexport PYTHONPATH=${PYTHONPATH}:$(pwd)/build/python\n```\n\n## Usage\n\n### `gz-msg` bindings \n\nThe Python bindings for `gz-msgs` are the standard generated protobuf code\nfor Python. For example `gz-msgs/proto/gz/msgs/time.proto` may be used as follows: \n\n```python\n# example.py\nfrom gz.msgs.time_pb2 import Time\n\nmsg = Time()\nmsg.sec = 15\nmsg.nsec = 21\nprint(msg)\n```\n\n### `gz-transport` bindings \n\nThe Python bindings for `gz-transport` are contained in a module called `transport`.\nThe object naming and usage for the most part follows the C++ interface,\nso the C++ Gazebo Tutorials are a good guide on how to use the library.\n\nPublish:\n\n```python\nfrom gz.msgs.stringmsg_pb2 import StringMsg\n\nfrom gz.transport import AdvertiseMessageOptions\nfrom gz.transport import Node\n\n# Create a transport node\nnode = Node()\n\n# Advertise a topic\ntopic = \"/foo\"\nmsg_type_name = StringMsg.DESCRIPTOR.full_name\npub_options = AdvertiseMessageOptions()\npub = node.advertise(topic, msg_type_name, pub_options)\n\n# Publish a message\nmsg = StringMsg()\nmsg.data = \"hello\"\npub.publish(msg)\n```\n\nSubscribe:\n\n```python\nimport time\nimport typing\n\nfrom gz.msgs.stringmsg_pb2 import StringMsg\n\nfrom gz.transport import SubscribeOptions\nfrom gz.transport import Node\n\ndef cb(msg: StringMsg) -\u003e None:\n    print(\"Msg: [{}] from Python\".format(msg.data))\n\n# Create a transport node\nnode = Node()\n\n# Subscribe to a topic by registering a callback\ntopic = \"/foo\"\nmsg_type_name = StringMsg.DESCRIPTOR.full_name\nsub_options = SubscribeOptions()\n\nnode.subscribe(topic, cb, msg_type_name, sub_options)\n```\n\n## Examples\n\nA number of examples in C++ and Python are provided. In the following we suppose that\nthey are being run from the project directory `~/gz_ws/src/gz-python`.\n\n---\n\n`src/msg_example.cc` is a copy of the [`gz-msgs` tutorial example](https://gazebosim.org/api/msgs/8.1/cppgetstarted.html):\n\n```bash\n$ ./build/msg_example\nPoint1:\nx: 1\ny: 3\nz: 5\n\nPoint2:\nx: 2\ny: 4\nz: 6\n```\n\n---\n\n`src/publisher.cc` and `src/subscriber.cc` is copied from the [`gz-transport` messages tutorial example](https://gazebosim.org/api/transport/11.0/messages.html).\n\nFrom terminal 1:\n\n```bash\n$ ./build/publisher\nPublishing hello on topic [/foo]\nPublishing hello on topic [/foo]\n...\n```\n\nFrom terminal 2:\n\n```bash\n$ ./build/subscriber\nMsg: hello\nMsg: hello\n...\n```\n\n---\n\n`src/rover_publisher.cc` and `src/rover_subscriber.cc` comprise another publish / subscribe\nexample that publishes the pose and twist of a rover moving in a circle with constant\nangular velocity.\n\nFrom terminal 1:\n\n```bash\n$ ./build/rover_publisher\nPublishing pose on topic [/pose], twist on topic [/twist]\nPublishing pose on topic [/pose], twist on topic [/twist]\n...\n```\n\nFrom terminal 2:\n\n```bash\n$ ./build/rover_subscriber\nheader {\n  stamp {\n    sec: 10\n    nsec: 45483925\n  }\n}\nname: \"base_link\"\nid: 20\nposition {\n  x: 2.7015115293406988\n  y: 4.2073549240394827\n}\norientation {\n  z: 0.479425538604203\n  w: 0.87758256189037276\n}\nheader {\n  stamp {\n    sec: 10\n    nsec: 45483925\n  }\n}\nlinear {\n  x: -0.42073549240394825\n  y: 0.27015115293406988\n}\nangular {\n  z: 0.1\n}\n```\n\n---\n\n`python/msgs_example.py` is a Python example that uses the generated Python protobuf libraries for `gz-msgs`:\n\n```bash\n$ ./python/msgs_example.py\nGazebo Protobuf Example\n\nproto api type: python\n----------------------------------------\n\u003cclass 'gz.msgs.time_pb2.Time'\u003e\nsec: 15\nnsec: 21\n...\n```\n\n---\n\n`python/publisher.py` is a Python version of the C++ `src/publisher.cc` described above.\nYou can listen to the messages using the C++ subscriber as before.\n\nFrom terminal 1:\n\n```bash\n$ ./python/publisher.py \nAdvertising gz.msgs.StringMsg on topic [/foo]\nPublishing hello on topic [/foo]\nPublishing hello on topic [/foo]\n...\n```\n\nFrom terminal 2:\n\n```bash\n$ ./python/subscriber.py \nSubscribing to type gz.msgs.StringMsg on topic [/foo]\nMsg: [hello] from Python\nMsg: [hello] from Python\n...\n```\n\n---\n\n`python/rover_publisher.py` is a Python version of the C++ `src/rover_publisher.cc` example.\n\nFrom terminal 1:\n\n```bash\n./python/rover_publisher.py\nAdvertising gz.msgs.Pose on topic [/pose]\nAdvertising gz.msgs.Twist on topic [/twist]\nPublishing pose on topic [/pose], twist on topic [/twist]\nPublishing pose on topic [/pose], twist on topic [/twist]\n...\n```\n\nFrom terminal 2:\n\n```bash\n./python/rover_subscriber.py\nSubscribing to type gz.msgs.Pose on topic [/pose]\nSubscribing to type gz.msgs.Twist on topic [/twist]\nheader {\n  stamp {\n    sec: 2\n    nsec: 511006000\n  }\n}\nname: \"base_link\"\nid: 5\nposition {\n  x: 4.900332889206208\n  y: 0.9933466539753061\n}\norientation {\n  z: 0.09983341664682815\n  w: 0.9950041652780257\n}\n\nheader {\n  stamp {\n    sec: 2\n    nsec: 511006000\n  }\n}\nlinear {\n  x: -0.09933466539753061\n  y: 0.4900332889206208\n}\nangular {\n  z: 0.1\n}\n...\n```\n\n--- \n\n`python/gz_topic_list.py` is a Python version of the command `gz topic -l`\n\n```bash\n$ ./python/gz_topic_list.py \n/foo\n```\n\n--- \n\n`python/gz_topic_info.py` is a Python version of the command `gz topic -i -t /foo`\n\n```bash\n$ ./python/gz_topic_info.py -t /foo\nPublishers [Address, Message Type]:\n  tcp://127.0.0.1:60328, gz.msgs.StringMsg\n```\n\n--- \n\n`python/gz_topic_echo.py` is a Python version of the command `gz topic -e -t /foo`\n\n```bash\n$ ./python/gz_topic_echo.py -t /foo\nSubscribing to topic [/foo]\ndata: \"hello\"\n\ndata: \"hello\"\n\ndata: \"hello\"\n```\n\n--- \n\n`python/gz_service_list.py` is a Python version of the command `gz service -l`\n\n```bash\n$ ./python/gz_service_list.py \n/gazebo/resource_paths/add\n/gazebo/resource_paths/get\n/gazebo/worlds\n/gui/camera/view_control\n/gui/follow\n...\n```\n\n--- \n\n`python/gz_service_info.py` is a Python version of the command `gz service -i -s /gazebo/worlds`\n\n```bash\n$ ./python/gz_service_info.py -s /gazebo/worlds\nService providers [Address, Request Message Type, Response Message Type]:\n  tcp://127.0.0.1:63657, gz.msgs.Empty, gz.msgs.StringMsg_V\n```\n\n\n## Building with Bazel\n\nOn macOS the project may also be built with Bazel. This is experimental and depends upon\na modified version of the Bazel build rules for Gazebo in the [`gz-bazel`](https://github.com/gazebosim/gz-bazel) project.\n\n\n### Installing Bazel\n\nOn macOS Bazel can be installed with `brew`:\n\n```bash\nbrew install bazel\n```\n\nThe [Google protocol buffers compiler](https://github.com/protocolbuffers/protobuf) version `3.19` is also required and can be installed with:\n\n\n```bash\nbrew install protobuf\n```\n\n\n### Setting up the workspace\n\nMake a directory to contain this package and all the Gazebo packages and dependencies:\n\n```bash\nmkdir ~/gz/\ncd ~/gz/\n```\n\nClone each of the packages using the `bazel.repos` file and [vcstool](https://github.com/dirk-thomas/vcstool). The forked version of [`gz-bazel`](https://github.com/srmainwaring/gz-bazel/tree/bazel-macos) contains modified build rules and repo references for macOS.\n\n```bash\nwget https://raw.githubusercontent.com/srmainwaring/gz-bazel/bazel-macos/example/bazel.repos\nvcs import . \u003c bazel.repos\n```\n\nNext, symlink the following files into the workspace directory:\n\n```bash\ncd ~/gz\nln -sf ./gz_bazel/example/WORKSPACE.example ./WORKSPACE\nln -sf ./gz_bazel/example/BUILD.example ./BUILD.bazel\nln -sf ./gz_bazel/example/bazelrc.example ./.bazelrc\nln -sf ./gz_python/gz-msgs9.BUILD ./gz-msgs9.BUILD\n```\n\nFinally, [`pybind11_protobuf`](https://github.com/pybind/pybind11_protobuf) requires a patch to the protobuf archive which must be available in the subdirectory `~/gz/external`. It must be copied rather than symlinked:\n\n```bash\ncd ~/gz\nmkdir external\ncp ./gz_python/external/com_google_protobuf_build.patch external\n```\n\n### Build with Bazel\n\nCurrently our use of `pybind11_protobuf` requires the Python implementation of the Python protobuf generator. This is configured with the environment variable:  \n\n```bash\nexport PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=python\n```\n\nThen build the examples with:\n\n```bash\nbazel build //gz_python:all\nbazel build //gz_python/python:all\n```\n\nNote: on macOS not all Gazebo projects will build with Bazel, so the command:\n\n```bash\nbazel build //... \n```\n\nwill result in a number of errors.\n\n### Usage in Bazel builds\n\nThe Bazel build file `gz-msgs9.BUILD` defines targets for a selection of messages.\nFor example the targets for `proto/gz/msgs/time.proto` are:\n\n```bash\n# proto_library\n@gz-msgs9//:time_proto\n\n# cpp_proto_library\n@gz-msgs9//:time_cc_proto\n\n# python_proto_library\n@gz-msgs9//:time_py_pb2\n```\n\nTo use the message bindings for C++ targets:\n\n```bash\n# BUILD.bazel\n\ncc_binary(\n  name = \"main\",\n  srcs = [\"main.cc\"],\n  deps = [\n      \"@gz-msgs9//:time_cc_proto\",\n  ],\n)\n```\n\nTo use the bindings for Python targets:\n\n```bash\n# BUILD.bazel\n\npy_binary(\n  name = \"example\",\n  srcs = [\"example.py\"],\n  data = [\n    \"@com_google_protobuf//:proto_api\",\n  ],\n  deps = [\n    \"@gz-msgs9//:time_py_pb2\",\n  ],\n)\n```\n\n## Notes\n\n### Protobuf compiler version\n\nThe project depends on `protoc` version `3.19.1`. You must ensure that the version of `protoc` installed by `brew` matches (otherwise the examples will segfault).\n\n```bash\n$ protoc --version\nlibprotoc 3.19.1\n```\n\n### Protobuf generated Python libraries\n\nThe `brew` installation of `protobuf` defaults to use the C++ implementation\nof the generated Python protobuf library. When using this with `pybind11_protobuf`\nthere are some cases when C++ wrapped protobuf objects returned from an extension module are not\nrecognised as their Python equivalents. The Python implementation will work in these cases\nand to enable this set the following environment variable before building the project:\n\n```bash\nexport PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=python\n```\n\n### CI Testing\n\n\n\n### Repos used to build Gazebo on macOS with Bazel\n\nThe table summarises the dependencies (repo and branch) on the Gazebo libraries.\n\n| library | repo | branch | build | test |\n| --- | --- | --- | --- | --- |\n| | | | | |\n|gz_python|https://github.com/srmainwaring/gz-python|main|pass|-|\n| | | | | |\n|gz-bazel|https://github.com/srmainwaring/gz-bazel|bazel-macos|pass|pass|\n|gz-math|https://github.com/srmainwaring/gz-math|bazel-macos/gz-math6|pass|pass|\n|gz-utils|https://github.com/srmainwaring/gz-utils|bazel-macos/gz-utils1|pass|pass|\n|gz-common|https://github.com/srmainwaring/gz-common|bazel-macos/gz-common4|pass|pass|\n|gz-msgs|https://github.com/srmainwaring/gz-msgs|bazel-macos/gz-msgs9|pass|pass|\n|sdformat|https://github.com/gazebosim/sdformat| bazel-sdf10|pass|pass|\n|gz-plugin|https://github.com/srmainwaring/gz-plugin|bazel-macos/gz-plugin1|pass|pass|\n|gz-transport|https://github.com/srmainwaring/gz-transport|bazel-macos/gz-transport12|pass|1 fail|\n|gz-physics|https://github.com/srmainwaring/gz-physics|bazel-macos/gz-physics5|pass|pass|\n|gz-tools|https://github.com/srmainwaring/gz-tools|bazel-macos/gz-tools1|partial|-|\n|gz-rendering|https://github.com/gazebosim/gz-rendering|bazel-rendering4|fail|fail|\n|gz-gui|https://github.com/gazebosim/gz-gui|bazel-gui4|fail|fail|\n|gz-sensors|https://github.com/gazebosim/gz-sensors|bazel-sensors4|fail|fail|\n|gz-gazebo|https://github.com/gazebosim/gz-gazebo|bazel-gazebo4|fail|fail|\n| | | | | |\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrmainwaring%2Fgz-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsrmainwaring%2Fgz-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrmainwaring%2Fgz-python/lists"}