Update for fw 2.1. See changelog for details. (#259)

* Add support for the new signal_multiplier config parameter
* Add support for the new 8-bit reflectivity format in simple_viz
* Update Python ouster-sdk package to version 0.2.1, bugfix release
* Remove viz_node and graphics packages from ROS build dependencies
* Ensure ouster_ros dependencies can be satisfied using rosdep
* Various improvements to the ROS img node output

.dockerignore

@@ -0,0 +1,2 @@
+python/Dockerfile
+ouster_ros/Dockerfile

CHANGELOG.rst

@@ -2,27 +2,60 @@
 Changelog
 =========
 
-[unreleased]
-============
 
-Added
------
-* first release of Python bindings for the provided C++ code. See the README under the ``python``
-  directory for details and links to documentation
-* early version of a C++ API covering the full sensor configuration interface
-* preliminary C++ API for working with pcap files containing a single sensor packet capture
-
-
-Changed
--------
-
-* reflectivity visualization for changes in the upcoming 2.1 firmware
-* moved most of the visualizer code out of public headers and hid some implementation details
+[20210608]
+==========
 
-Fixed
------
+ouster_client
+-------------
+* update cmake package version to 0.2.0
+* add support for new signal multiplier config parameter
+* add early version of a C++ API covering the full sensor configuration interface
+* increase default initialization timeout to 60 seconds to account for the worst case: waking up
+  from STANDBY mode
+
+ouster_pcap
+-----------
+* ``record_packet()`` now requires passing in a capture timestamp instead of using current time
+* work around libtins issue where capture timestamps for pcaps recorded on Windows are always zero
+* add preliminary C++ API for working with pcap files containing a single sensor packet capture
+
+ouster_ros
+----------
+* update ROS package version to 0.2.0
+* add Dockerfile to easily set up a build environment or run nodes
+* ``img_node`` now outputs 16-bit images, which should be more useful. Range image output is now in
+  units of 4mm instead of arbitrary scaling (addresses #249)
+* ``img_node`` now outputs reflectivity images as well on the ``reflec_image`` topic
+* change ``img_node`` topics to match terminology in sensor documentation: ``ambient_image`` is now
+  ``nearir_image`` and ``intensity_image`` is now ``signal_image``
+* update rviz config to use flat squares by default to work around `a bug on intel systems
+  <https://github.com/ros-visualization/rviz/issues/1508>`_
+* remove viz_node and all graphics stack dependencies from the package. The ``viz`` flag on the
+  launch file now runs rviz (addresses #236)
+* clean up package.xml and ensure that dependencies are installable with rosdep (PR #219)
+* the ``metadata`` argument to ouster_ros launch file is now required. No longer defaults to a name
+  based on the hostname of the sensor
+
+ouster_viz
+----------
+* update reflectivity visualization for changes in the upcoming 2.1 firmware. Add new colormap and
+  handle 8-bit reflectivity values
+* move most of the visualizer code out of public headers and hide some implementation details
+* fix visualizer bug causing a small viewport when resizing the window on macos with a retina
+  display
+
+python
+------
+* update ouster-sdk version to 0.2.1
+* fix bug in determining if a scan is complete with single-column azimuth windows
+* closed PacketSource iterators will now raise an exception on read
+* add examples for visualization using open3d (see: ``ouster.sdk.examples.open3d``)
+* add support for the new signal multiplier config parameter
+* preserve capture timestamps on packets read from pcaps
+* first release: version 0.2.0 of ouster-sdk. See the README under the ``python`` directory for
+  details and links to documentation
 
-* visualizer bug causing a small viewport when resizing the window on macos with a retina display
 
 [20201209]
 ==========
@@ -47,6 +80,7 @@ Changed
 * add client version field to metadata json, logs, and help text
 * client API renaming to better reflect the Sensor Software Manual
 
+
 [1.14.0-beta.14] - 2020-08-27
 =============================
 
@@ -79,16 +113,19 @@ Fixed
 * the reference frame of point cloud topics in ``ouster_ros`` is now correctly reported as the "sensor
   frame" defined in the user guide
 
+
 [1.14.0-beta.12] - 2020-07-10
 =============================
 
 *no changes*
 
+
 [1.14.0-beta.11] - 2020-06-17
 =============================
 
 *no changes*
 
+
 [1.14.0-beta.10] - 2020-05-21
 =============================
 
@@ -117,6 +154,7 @@ Fixed
   origin offset
 * minor regression with destaggering in img_node output in previous beta
 
+
 [1.14.0-beta.4] - 2020-03-17
 ============================
 
@@ -134,6 +172,7 @@ Changed
 
 * use random ports for lidar and imu data by default when unspecified
 
+
 [1.13.0] - 2020-03-16
 =====================
 
@@ -157,6 +196,7 @@ Fixed
 * use correct name for json dependency in ``package.xml`` (PR #116)
 * handle udp socket creation error gracefully in client
 
+
 [1.12.0] - 2019-05-02
 =====================
 
@@ -177,6 +217,7 @@ Fixed
 * visualizer issue where the point cloud would occasionally occasionally not be displayed using
   newer versions of Eigen
 
+
 [1.11.0] - 2019-03-26
 =====================
 
@@ -199,6 +240,7 @@ Fixed
 * misplaced sine in azimuth angle calculation (addresses #42)
 * populate timestamps on image node output (addresses #39)
 
+
 [1.10.0] - 2019-01-27
 =====================
 

CMakeLists.txt

@@ -10,6 +10,7 @@ project(ouster_example)
 option(CMAKE_POSITION_INDEPENDENT_CODE "Build position independent code." ON)
 option(BUILD_SHARED_LIBS "Build shared libraries." OFF)
 option(BUILD_VIZ "Build Ouster visualizer." ON)
+option(BUILD_PCAP "Build pcap utils." OFF)
 
 set(CMAKE_CXX_STANDARD 11)
 if(MSVC)
@@ -21,7 +22,10 @@ endif()
 
 # === Subdirectories ===
 add_subdirectory(ouster_client)
-add_subdirectory(ouster_pcap)
+
+if(BUILD_PCAP)
+  add_subdirectory(ouster_pcap)
+endif()
 
 if(BUILD_VIZ)
   add_subdirectory(ouster_viz)

README.rst

@@ -12,14 +12,16 @@ Summary
 =======
 
 To get started building the client and visualizer libraries, see the `Sample Client and Visualizer`_
-section below. For instructions on ROS, start with the `Example ROS Code`_ section.
+section below. For instructions on ROS, start with the `Example ROS Code`_ section. Python SDK users
+should proceed straight to our `python SDK homepage <python/>`_.
 
 This repository contains sample code for connecting to and configuring ouster sensors, reading and
 visualizing data, and interfacing with ROS.
 
 * `ouster_client <ouster_client/>`_ contains an example C++ client for ouster sensors
 * `ouster_viz <ouster_viz/>`_ contains a basic point cloud visualizer
 * `ouster_ros <ouster_ros/>`_ contains example ROS nodes for publishing point cloud messages
+* `python <python/>`_ contains the code for the ouster sensor python SDK
 
 
 Sample Client and Visualizer
@@ -35,7 +37,7 @@ Building on Linux / macOS
 To install build dependencies on Ubuntu, run::
 
     sudo apt install build-essential cmake libglfw3-dev libglew-dev libeigen3-dev \
-         libjsoncpp-dev libtclap-dev libtins-dev libpcap-dev
+         libjsoncpp-dev libtclap-dev
 
 On macOS, install XCode and `homebrew <https://brew.sh>`_ and run::
 
@@ -52,6 +54,7 @@ where ``<path to ouster_example>`` is the location of the ``ouster_example`` sou
 CMake build script supports several optional flags::
 
     -DBUILD_VIZ=OFF                      Do not build the sample visualizer
+    -DBUILD_PCAP=ON                      Build pcap tools. Requres libpcap and libtins dev packages
     -DBUILD_SHARED_LIBS                  Build shared libraries (.dylib or .so)
     -DCMAKE_POSITION_INDEPENDENT_CODE    Standard flag for position independent code
 
@@ -142,11 +145,10 @@ Keyboard controls:
     ``p``         Increase point size
     ``o``         Decrease point size
     ``m``         Cycle point cloud coloring mode
-    ``v``         Toggle color cycling in range image
+    ``v``         Toggle range cycling
     ``n``         Toggle display near-IR image from the sensor
-    ``r``         Toggle auto-rotating
     ``shift + r`` Reset camera
-    ``e``         Change range and signal image size
+    ``e``         Change size of displayed 2D images
     ``;``         Increase spacing in range markers
     ``'``         Decrease spacing in range markers
     ``r``         Toggle auto rotate
@@ -180,9 +182,9 @@ Building
 The build dependencies include those of the sample code::
 
     sudo apt install build-essential cmake libglfw3-dev libglew-dev libeigen3-dev \
-         libjsoncpp-dev libtclap-dev libtins-dev libpcap-dev
+         libjsoncpp-dev libtclap-dev
 
-and, additionally::
+Additionally, you should install the ros dependencies::
 
     sudo apt install ros-<ROS-VERSION>-ros-core ros-<ROS-VERSION>-pcl-ros \
          ros-<ROS-VERSION>-tf2-geometry-msgs ros-<ROS-VERSION>-rviz
@@ -191,6 +193,7 @@ where ``<ROS-VERSION>`` is ``kinetic``, ``melodic``, or ``noetic``.
 
 
 Alternatively, if you would like to install dependencies with `rosdep`::
+
     rosdep install --from-paths <path to ouster example>
 
 To build::
@@ -226,14 +229,14 @@ where:
 
 * ``<sensor hostname>`` can be the hostname (os-99xxxxxxxxxx) or IP of the sensor
 * ``<udp data destination>`` is the hostname or IP to which the sensor should send data
-* ``<path to metadata json>`` is an optional path to json file to save calibration metadata
+* ``<path to metadata json>`` is the path to the json file to which to save calibration metadata
 * ``<lidar mode>`` is one of ``512x10``, ``512x20``, ``1024x10``, ``1024x20``, or ``2048x10``, and
 * ``<viz>`` is either ``true`` or ``false``: if true, a window should open and start displaying data
   after a few seconds.
 
-Note that if the ``metadata`` parameter is not specified, this command will write metadata to
-``${ROS_HOME}``. By default, the name of this file is based on the hostname of the sensor, e.g.
-``os-99xxxxxxxxxx.json``.
+Note that by default the working directory of all ROS nodes is set to ``${ROS_HOME}``, generally
+``$HOME/.ros``, so if ``metadata`` is a relative path, it will write to that path inside
+``${ROS_HOME}``. To avoid this, you can provide an absolute path to ``metadata``.
 
 Recording Data
 --------------
@@ -245,10 +248,10 @@ another terminal, run::
 
 This will save a bag file of recorded data in the current working directory. 
 
-You should copy and save the metadata file alongside your data. The metadata file be saved either at
-the provided path to `roslaunch` or at ``$(ROS_HOME)/<sensor_hostname>.json`` if you did not provide
-a metadata argument to `roslaunch`. If you do not save the metadata file, you will not be able to
-replay your data later.
+You should copy and save the metadata file alongside your data. The metadata file will be saved at
+the provided path to `roslaunch`. If you run the node and cannot find the metadata file, try looking
+inside your ``${ROS_HOME}``, generally ``$HOME/.ros``. Regardless, you must retain the metadata
+file, as you will not be able to replay your data later without it.
 
 .. _rosbag record: https://wiki.ros.org/rosbag/Commandline#rosbag_record
 
@@ -269,16 +272,11 @@ to obtain the metadata file when recording your data.
 
 .. _rosbag play: https://wiki.ros.org/rosbag/Commandline#rosbag_play
 
-Visualizing Data in Rviz
-------------------------
-
-To display sensor output using built-in ROS tools (rviz), follow the instructions above for running
-the example ROS code with a sensor or recorded data. Then, run::
 
-    rviz -d ouster_example/ouster_ros/viz.rviz
+Ouster Python SDK
+=================
 
-in another terminal with the ROS environment set up. To view lidar signal, near-IR, and range
-images, add ``image:=true`` to the ``roslaunch`` command above.
+Python SDK users should proceed straight to the `Ouster python SDK homepage <python/>`_.
 
 
 Additional Information

ouster_client/CMakeLists.txt

@@ -2,7 +2,7 @@ cmake_minimum_required(VERSION 3.1.0)
 
 # ==== Project Name ====
 project(ouster_client VERSION 0.2.0)
-set(ouster_client_VERSION_SUFFIX "-dev0")
+set(ouster_client_VERSION_SUFFIX "")
 
 # ==== Requirements ====
 find_package(Eigen3 REQUIRED)
@@ -24,7 +24,7 @@ target_include_directories(ouster_build INTERFACE ${CMAKE_CURRENT_BINARY_DIR}/in
 add_dependencies(ouster_build generate_build_header)
 
 # ==== Libraries ====
-add_library(ouster_client src/client.cpp src/types.cpp src/netcompat.cpp src/lidar_scan.cpp)
+add_library(ouster_client src/client.cpp src/types.cpp src/netcompat.cpp src/lidar_scan.cpp src/image_processing.cpp)
 target_link_libraries(ouster_client PUBLIC jsoncpp_lib Eigen3::Eigen ouster_build)
 if(WIN32)
   target_link_libraries(ouster_client PUBLIC ws2_32)

ouster_client/include/ouster/client.h

@@ -53,7 +53,7 @@ std::shared_ptr<client> init_client(const std::string& hostname,
                                     lidar_mode mode = MODE_UNSPEC,
                                     timestamp_mode ts_mode = TIME_FROM_UNSPEC,
                                     int lidar_port = 0, int imu_port = 0,
-                                    int timeout_sec = 30);
+                                    int timeout_sec = 60);
 
 /**
  * Block for up to timeout_sec until either data is ready or an error occurs.
@@ -98,7 +98,7 @@ bool read_imu_packet(const client& cli, uint8_t* buf, const packet_format& pf);
  * @param timeout_sec how long to wait for the sensor to initialize
  * @return a text blob of metadata parseable into a sensor_info struct
  */
-std::string get_metadata(client& cli, int timeout_sec = 30);
+std::string get_metadata(client& cli, int timeout_sec = 60);
 
 /**
  * Get sensor config from the sensor

ouster_client/include/ouster/types.h

@@ -114,6 +114,7 @@ struct sensor_config {
     optional<MultipurposeIOMode> multipurpose_io_mode;
 
     optional<AzimuthWindow> azimuth_window;
+    optional<int> signal_multiplier;
 
     optional<Polarity> nmea_in_polarity;
     optional<bool> nmea_ignore_valid_char;

ouster_client/src/client.cpp

@@ -339,6 +339,11 @@ bool set_config_helper(SOCKET sock_fd, const sensor_config& config,
         !set_param("azimuth_window", to_string(config.azimuth_window.value())))
         return false;
 
+    if (config.signal_multiplier &&
+        !set_param("signal_multiplier",
+                   std::to_string(config.signal_multiplier.value())))
+        return false;
+
     if (config.sync_pulse_out_angle &&
         !set_param("sync_pulse_out_angle",
                    std::to_string(config.sync_pulse_out_angle.value())))
@@ -446,8 +451,6 @@ bool set_config(const std::string& hostname, const sensor_config& config,
     std::string res;
     bool success = true;
 
-    success = set_config_helper(sock_fd, config, config_flags);
-
     if (config_flags & CONFIG_UDP_DEST_AUTO) {
         if (config.udp_dest) {
             impl::socket_close(sock_fd);
@@ -458,6 +461,10 @@ bool set_config(const std::string& hostname, const sensor_config& config,
         success &= res == "set_udp_dest_auto";
     }
 
+    if (success) {
+        success = set_config_helper(sock_fd, config, config_flags);
+    }
+
     impl::socket_close(sock_fd);
 
     return success;
@@ -548,7 +555,7 @@ std::shared_ptr<client> init_client(const std::string& hostname,
 
     // wake up from STANDBY, if necessary
     success &= do_tcp_cmd(
-        sock_fd, {"set_config_param", "operating_mode", "NORMAL"}, res);
+        sock_fd, {"set_config_param", "auto_start_flag", "1"}, res);
     success &= res == "set_config_param";
 
     // reinitialize to activate new settings

ouster_client/src/example.cpp

@@ -68,7 +68,7 @@ int main(int argc, char* argv[]) {
     // azimuth_window config param reduce the amount of valid columns per scan
     // that we will receive
     int column_window_length =
-        std::abs(column_window.second - column_window.first) + 1;
+        (column_window.second - column_window.first + w) % w + 1;
 
     std::cerr << "  Firmware version:  " << info.fw_rev
               << "\n  Serial number:     " << info.sn

ouster_client/src/netcompat.cpp

@@ -75,7 +75,7 @@ bool socket_exit() {
 
 int socket_set_non_blocking(SOCKET value) {
 #ifdef _WIN32
-    u_long non_blocking_mode = 0;
+    u_long non_blocking_mode = 1;
     return ioctlsocket(value, FIONBIO, &non_blocking_mode);
 #else
     return fcntl(value, F_SETFL, fcntl(value, F_GETFL, 0) | O_NONBLOCK);