Developer’s Quick Start with the Ouster Python SDK

This quickstart guide will walk you through visualizing Ouster sensor data quickly with Python code you write yourself. It assumes that you have followed the steps in Python Installation to install the Ouster Python SDK.

Using this Guide

You’ll want to start an interactive Python session and keep it open through the sections, as we’ll be reusing variables created in earlier parts while explaining what we’re doing as we go.

To get started, open a new console/Powershell window and start a python interpreter:

$ python3

Throughout this guide we will indicate console commands with $ and python interpreter commands with >>>, just as we have above.

If you’d like to start by working with sample data, continue to the next section. If you’d prefer to start by capturing data from a sensor, you can skip to Using an Ouster Sensor below.

Using Sample Data

You can download sample data from the sensor documentation by clicking through the Ouster Data App links and using the Download button. After download, you should have two files, a .pcap file and a .json file.

We will use SAMPLE_DATA_PCAP_PATH to refer to this pcap and SAMPLE_DATA_JSON_PATH to this json in the following. You may find it convenient to assign the paths appropriately in your console.

The downloaded pcap file contains lidar and imu packets captured from the network. You can read more about the IMU Data Format and Lidar Data Format in the Ouster Sensor Documentation. The JSON file contains metadata queried from the sensor TCP interface necessary for interpreting the packet data.

In your open python session, save the two paths to variables:

>>> pcap_path = '<SAMPLE_DATA_PCAP_PATH>'
>>> metadata_path = '<SAMPLE_DATA_JSON_PATH>'

Because our pcap file contains the UDP packet stream but not the sensor metadata, we load the sensor information from metadata_path first, using the client module:

Note

Starting with ouster-sdk v0.11.0, most of core sdk objects have been moved from the ouster namespace into the ouster.sdk namespace.

Note

Starting with ouster-sdk v0.11.0 we introduce a unified ScanSource interface that easier to utilize and is more capable than original objects demonstrated in this quick guide. Please refer to Using ScanSource API for details on how to use the new interface.

>>> from ouster.sdk import client
>>> with open(metadata_path, 'r') as f:
...     info = client.SensorInfo(f.read())

Now that we’ve parsed the metadata file into a SensorInfo, we can use it to read our captured UDP data by instantiating pcap.Pcap. This class acts as a PacketSource and can be used in many of the same contexts as a real sensor.

>>> from ouster.sdk import pcap
>>> source = pcap.Pcap(pcap_path, info)

To visualize data from this pcap file, proceed to Visualizations in 3D examples.

Using an Ouster Sensor

If you have access to sensor hardware, you can start reading data by instantiating a PacketSource that listens for a UDP data stream on a local socket.

Note

Connecting to an Ouster sensor is covered in the Networking Guide section of the Ouster Sensor Documentation.

In the following, <SENSOR_HOSTNAME> should be substituted for the actual hostname or IP of your sensor.

To make sure everything is connected, open a separate console window and try pinging the sensor. You should see some output like:

$ ping -c1 <SENSOR_HOSTNAME>
PING <SENSOR_HOSTNAME> (192.0.2.42) 56(84) bytes of data.
64 bytes from <SENSOR_HOSTNAME> (192.0.2.42): icmp_seq=1 ttl=64 time=0.217 ms

Next, you’ll need to configure the sensor with the config parameters using the client module.

In your open python session, set hostname as <SENSOR_HOSTNAME>:

>>> hostname = '<SENSOR_HOSTNAME>'

Now configure the client:

>>> from ouster.sdk import client
>>> config = client.SensorConfig()
>>> config.udp_port_lidar = 7502
>>> config.udp_port_imu = 7503
>>> config.operating_mode = client.OperatingMode.OPERATING_NORMAL
>>> client.set_config(hostname, config, persist=True, udp_dest_auto = True)

Just like with the sample data, you can create a PacketSource from the sensor:

>>> source = client.Sensor(hostname, 7502, 7503)
>>> info = source.metadata

Now we have a source from our sensor! You’re ready to record, visualize to visualize data from your sensor, proceed to Visualizations in 3D examples. Or you can check out other things you can do with a source in the Python Examples & Concepts.

Next Steps

Now that you know the basics, you can check out our annotated examples for a more detailed look at how to work with our data.

Here are a few things you might be interested in: