Code Docs

Setting Up a PyBullet Simulation with Ark

Welcome to this tutorial on setting up a PyBullet-based simulation using Ark! This guide walks you through everything—from writing your first simulator node to configuring the simulation environment—step by step.

What is a Sim Node?

A sim node is the heart of your simulation. It's responsible for:

• Initializing the simulation world
• Setting up robots, sensors, and objects
• Managing the simulation loop

Creating Your First Sim Node

Let's start by creating a file called sim_node.py. This will be our main simulation file.

Here's the code with explanations:

# Import necessary modules
from ark.client.comm_infrastructure.base_node import main
from ark.system.simulation.simulator_node import SimulatorNode
from ark.tools.log import log

# Path to your configuration file
CONFIG_PATH = "config/global_config.yaml"

# Create your custom simulator by inheriting from SimulatorNode
class MySimulatorNode(SimulatorNode):

    def initialize_scene(self):
        """
        This function is called after objects are loaded but before simulation starts.
        Use it to set up your scene, modify parameters, or add custom objects.
        """
        pass
    
    def step(self):
        """
        This function is called at each simulation step.
        Use it for debugging or implementing custom behaviors during simulation.
        
        Examples:
        - Print debug info: log.info("Current position: ", self.robot.get_position())
        - Apply forces: self.apply_force(...)
        - Check conditions: if self.check_collision(): ...
        """
        pass

# Entry point - this runs your node with the specified configuration
if __name__ == "__main__":
    main(MySimulatorNode, CONFIG_PATH)

Understanding the Key Components

1. Configuration Path

The CONFIG_PATH points to your global configuration file (YAML format) that contains settings for your simulation world, including physics parameters, robot specifications, and more.

2. MySimulatorNode Class

This is your custom simulator class that inherits functionality from the base SimulatorNode. You'll add your specific simulation logic here.

3. initialize_scene() Method

This is called once after all objects defined in your config are loaded but before the simulation starts running. It's the perfect place to:

• Add additional objects to the scene
• Configure robots or sensors
• Set up initial positions or states
• Modify parameters that can't be set through config files

4. step() Method

This is called during each simulation cycle (typically many times per second). Use it to:

• Monitor the simulation state
• Log information for debugging
• Implement custom behaviors or controls
• Respond to events in the simulation

Simulation Configuration Setup - A Step-by-Step Guide

The global configuration file is where you define all the parameters for your simulation environment. Let's break down how to set up this file properly.

1. Basic Simulator Configuration

Create a file called global_config.yaml in your project's config directory with these essential settings:

simulator:
  name: "my_first_simulator"              # A unique name for your simulator node
  backend_type: "pybullet"                # The physics engine we're using
  node_frequency: 240                     # How often your node's step() function runs (Hz)
  config:
    connection_mode: "GUI"                # GUI for visual interface, DIRECT for headless mode
    gravity:                              # Gravity vector [x, y, z] in m/s²
      - 0
      - 0
      - -9.81                             # Standard Earth gravity
    sim_frequency: 240                    # Physics simulation steps per second

2. Understanding Each Parameter

• name: Identifies your simulator in the ARK system. Choose something descriptive and unique.
• backend_type: The physics engine - we're using PyBullet, a fast and flexible physics simulator.
• node_frequency: How many times per second your node's step() function will be called.
• connection_mode:
  • "GUI" shows a visual interface where you can see and interact with the simulation.
  • "DIRECT" runs headless (without visuals) for faster performance when debugging isn't needed.
• gravity: The gravitational force vector in your world. Default is Earth's gravity along the z-axis.
• sim_frequency: How many physics steps are calculated per second. Higher values give more accurate physics but require more computing power.

3. Rendering Configuration for Visualization

If you're on macOS or need to save simulation frames (for debugging or creating videos), add the following rendering configuration:

simulator:
  # ... previous settings ...
  save_render: 
    save_path: "render"                   # Directory where rendered frames will be saved
    remove_existing: false                # Whether to clean the directory before starting
    render_interval: 0.1                  # Save a frame every 0.1 seconds (10 FPS)
    overwrite_file: true                  # Overwrite existing files instead of creating new ones

4. Camera Configuration

To control how your simulation is viewed and rendered, add these camera settings:

simulator:
  # ... previous settings ...
  save_render:
    # ... previous render settings ...
    extrinsics:                           # How the camera is positioned
      look_at: [0.5, 0.0, 0.5]            # Point the camera is focused on [x, y, z]
      distance: 2.0                       # Distance from look_at point (in meters)
      azimuth: 135                        # Horizontal angle (degrees) - 0 is -y, 90 is +x
      elevation: 20                       # Vertical angle (degrees) - higher values look down
    intrinsics:                           # Camera lens properties
      width: 1280                         # Output image width in pixels
      height: 720                         # Output image height in pixels
      field_of_view: 60                   # Field of view in degrees
      near_plane: 0.01                    # Closest visible distance
      far_plane: 100.0                    # Furthest visible distance

5. Configuration Best Practices

• Start simple: Begin with the basic configuration and add complexity as needed.
• Match frequencies: Generally, keep sim_frequency at 240Hz to match the real world for Pybullet
• Test different views: Experiment with camera extrinsics to find the best angle for visualizing your simulation.
• Performance tuning: If your simulation runs slowly, try switching to DIRECT mode.

With these settings in place, your simulation environment will be properly configured and ready for adding robots and objects, which we'll cover in the next section

Running Your Simulation: What to Expect

After setting up your configuration, it's time to test your simulation by running sim_node.py. Here's what you should expect depending on your configuration mode:

If Using "GUI" Mode:

• A PyBullet GUI window should appear automatically
• You'll see an empty 3D environment with a grid representing the ground plane
• The window should remain responsive and allow you to rotate the view using your mouse

If Using "DIRECT" Mode:

• No GUI window will appear (this is normal for headless mode)
• A folder named "render" should be created in your project directory
• Inside this folder, you'll find PNG image named "render.png", this will constantly be updated based on the latest render.

Troubleshooting Common Issues:

• If no window appears in GUI mode, check that PyBullet is properly installed
• If no render folder appears in DIRECT mode, verify your save_render configuration
• If you see Python errors, double-check your configuration file syntax

Code can be found:

https://github.com/Robotics-Ark/franka_gym_example

Table of Contents