
Home
FAQ
Player
Utilities
Stage
Gazebo
Contrib
Documentation
Publications
Contributors
Users

Python bindings (libgazebo_py)

Python bindings for libgazebo are generated automatically using SWIG. The bindings are object-oriented, using standard Python classes (for those familiar with SWIG, these are standard SWIG shadow classes). Refer to the libgazebo instructions for general information on how to use this library.

General usage

Programs using the libgazebo Python bindings will generally have the following structure:

#!/usr/bin/env python

# Desc: Move an object along a sinusoidal path
# Author: Andrew Howard

import math
import time

from gazebo import *


if __name__ == '__main__':

    server = 'default'
    id = 'object1'

    # Connect to server
    client = gz_client()
    if client.connect(server) != 0:
        raise gz_error_str()

    # Open the interface
    truth = gz_truth()
    if truth.open(client, id) != 0:
        raise gz_error_str()

    truth.lock(1)
    start_time = truth.data.time
    start_pos = truth.data.pos[:]
    truth.unlock()

    for i in range(1000):
        time.sleep(0.1)
        
        dt = truth.data.time - start_time
        new_pos = (start_pos[0] + 1.0 * dt,
                   start_pos[1] + 1.0 * math.sin(dt),
                   start_pos[2])
        
        truth.lock(1)
        truth.data.cmd_new = 1
        truth.data.cmd_pos = new_pos
        truth.unlock()

The steps in this program mirror those described for standard C program. The key syntactical difference between the C-version and the Python version is the use of Python's object-oriented features.

This example can be demonstrated using the follow world file:

<?xml version="1.0"?>

<gz:world 
  xmlns:gz='http://playerstage.sourceforge.net/gazebo/xmlschema/#gz'
  xmlns:model='http://playerstage.sourceforge.net/gazebo/xmlschema/#model'
  xmlns:window='http://playerstage.sourceforge.net/gazebo/xmlschema/#window'
  xmlns:params='http://playerstage.sourceforge.net/gazebo/xmlschema/#params'>

  <params:GlobalParams>
    <gravity>0.0 0.0 -9.8</gravity>
  </params:GlobalParams>

  <model:ObserverCam>
    <id>userCam0</id>
    <xyz>-0.279 -4.715 4.388</xyz>
    <rpy>0 28 85</rpy>
    <window>
      <title>Gazebo1</title>
      <size>640 480</size>
    </window>
  </model:ObserverCam>

  <model:LightSource>
    <id>light0</id>
    <xyz>-10.000 -10.000 10.000</xyz>
  </model:LightSource>

  <model:GroundPlane>
    <id>ground1</id>
  </model:GroundPlane>

  <model:SimpleSolid>
    <xyz>0.000 -0.000 -0.000</xyz>
    <shape>box</shape>
    <size>0.70 0.70 1.50</size>
    <color>1.0 1.0 1.0</color>
    <model:TruthWidget>
      <id>object1</id>
    </model:TruthWidget>
  </model:SimpleSolid>

</gz:world>

Proxy reference

Generally speaking, the Python bindings are one-to-one mappings to the libgazebo API. Thus, the C documentation can be used as a guide, so long as one makes some minor mental translations; e.g.:

pos = gz_position_alloc(...);    ->   pos = gz_position(...)
gz_position_open(pos, ...);      ->   pos.open(...)

Detailed information for each C proxy can be found in the Reference section.