FW 2.3 support and viz rewrite

* Refactor viz library and add python bindings
* Add FW 2.3 support
* Add conan support
* C++ and new viz documentation in progress

CHANGELOG.rst

@@ -2,6 +2,40 @@
 Changelog
 =========
 
+[unreleased]
+============
+
+* update supported vcpkg tag to 2022.02.23
+* update to manylinux2014 for x64 linux ``ouster-sdk`` wheels
+
+ouster_client
+-------------
+* fix the behavior of ``BeamUniformityCorrector`` on azimuth-windowed data by ignoring zeroed out
+  columns
+* add overloads in ``image_processing.h`` to work with single-precision floats
+* add support for new ``RNG19_RFL8_SIG16_NIR16`` single-return and ``RNG15_RFL8_NIR8`` low-bandwidth
+  lidar UDP profiles introduced in firmware 2.3
+
+ouster_viz
+----------
+* switch to glad for OpenGL loading. GLEW is still supported for developer builds
+* breaking change: significant API update of the ``PointViz`` library. See documentation for details
+* the ``simple_viz`` example app and ``LidarScanViz`` utility have been removed. Equivalent
+  functionality is now provided via Python
+* add basic support for drawing 2d and 3d text labels
+* update to OpenGL 3.3
+
+python
+------
+* fix a bug where incorrectly sized packets read from the network could cause the client thread to
+  silently exit, resulting in a timeout
+* fix ``client.Scans`` not raising a timeout when using the ``complete`` flag and receiving only
+  incomplete scans. This could cause readings scans to hang in rare situations
+* added bindings for the new ``PointViz`` API and a new module for higher-level visualizer utilities
+  in ``ouster.sdk.viz``. See API documentation for details
+* the ``ouster-sdk`` package now includes an example visualizer, ``simple-viz``, which will be
+  installed on that path for the Python environment
+
 
 [20220107]
 ============
@@ -72,6 +106,7 @@ ouster_viz
 ----------
 * the second CLI argument of simple_viz specifying the UDP data destination is now optional
 * fixed bug in AutoExposure causing more points to be mapped to near-zero values
+* add functionality to display text over cuboids
 
 python
 ------

CMakeLists.txt

@@ -12,12 +12,18 @@ option(BUILD_SHARED_LIBS "Build shared libraries." OFF)
 option(BUILD_PCAP "Build pcap utils." OFF)
 option(BUILD_TESTING "Build tests" OFF)
 option(BUILD_VIZ "Build Ouster visualizer." ON)
+option(BUILD_EXAMPLES "Build C++ examples" OFF)
 
-# when building as a top-level project
+# when building as a top-level project and not as conan library
 if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
-  set(CMAKE_CXX_STANDARD 11)
+  if(NOT "${CMAKE_CXX_STANDARD}")
+    set(CMAKE_CXX_STANDARD 11)
+  endif()
   set(CMAKE_CXX_STANDARD_REQUIRED ON)
-  set(CMAKE_CXX_EXTENSIONS OFF)
+
+  if(NOT "${CMAKE_CXX_EXTENSIONS}")
+    set(CMAKE_CXX_EXTENSIONS OFF)
+  endif()
 
   if(MSVC)
     add_compile_options(/W3)
@@ -32,14 +38,18 @@ endif()
 # === Subdirectories ===
 add_subdirectory(ouster_client)
 
-if(BUILD_PCAP)
+if(BUILD_PCAP OR BUILD_EXAMPLES)
   add_subdirectory(ouster_pcap)
 endif()
 
 if(BUILD_VIZ)
   add_subdirectory(ouster_viz)
 endif()
 
+if(BUILD_EXAMPLES)
+  add_subdirectory(examples)
+endif()
+
 if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
   message(STATUS "Ouster SDK client: Using EIGEN_MAX_ALIGN_BYTES = 32")
   target_compile_definitions(ouster_client PUBLIC EIGEN_MAX_ALIGN_BYTES=32)
@@ -91,4 +101,3 @@ set(CPACK_DEBIAN_PACKAGE_DEPENDS "cmake, libjsoncpp-dev, libtclap-dev, libeigen3
   libglfw3-dev, libglew-dev")
 
 include(CPack)
-

LICENSE-bin

@@ -179,3 +179,28 @@ License: BSD 3-clause
     CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
     OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Name: gltext
+Description: compiled-in header-only library
+Availability: https://github.com/vallentin/glText
+License: Zlib License
+    Copyright (c) 2013-2018 Christian Vallentin
+
+    This software is provided 'as-is', without any express or implied
+    warranty. In no event will the authors be held liable for any damages
+    arising from the use of this software.
+
+    Permission is granted to anyone to use this software for any purpose,
+    including commercial applications, and to alter it and redistribute it
+    freely, subject to the following restrictions:
+
+    1. The origin of this software must not be misrepresented; you must not
+       claim that you wrote the original software. If you use this software
+       in a product, an acknowledgment in the product documentation would
+       be appreciated but is not required.
+
+    2. Altered source versions must be plainly marked as such, and must not
+       be misrepresented as being the original software.
+
+    3. This notice may not be removed or altered from any source
+       distribution.

README.rst

@@ -1,6 +1,19 @@
-===================
-Ouster Example Code
-===================
+.. image:: docs/images/Ouster_Logo_TM_Horiz_Black_RGB_600px.png
+    :align: center
+
+
+==========================================================
+Ouster SDK - libraries and tools for Ouster Lidar Sensors
+==========================================================
+
+**Quick links:** `Python SDK <https://static.ouster.dev/sdk-docs/index.html>`_  |  `Python Quick
+Start <https://static.ouster.dev/sdk-docs/quickstart.html>`_  |  `Changelog
+<https://static.ouster.dev/sdk-docs/changelog.html>`_  |  `Sensor Docs
+<https://static.ouster.dev/sensor-docs>`_  | `Sample Data
+<https://static.ouster.dev/sdk-docs/quickstart.html#using-sample-data>`_  |  `Issues
+<https://github.com/ouster-lidar/ouster_example/issues>`_
+
+------------------------------------------------------
 
 :Description: Sample code provided for working with Ouster sensors
 
@@ -21,7 +34,7 @@ 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
+* `python <python/>`_ contains the code for the ouster sensor python SDK (``ouster-sdk`` Python package)
 
 
 Sample Client and Visualizer
@@ -69,10 +82,10 @@ for dependencies. Follow the official documentation to set up your build environ
   <https://docs.microsoft.com/en-us/cpp/build/cmake-projects-in-visual-studio?view=vs-2019>`_
 * `Visual Studio CPP Support
   <https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=vs-2019>`_
-* `Vcpkg, at tag "2021.05.12" installed and integrated with Visual Studio
+* `Vcpkg, at tag "2022.02.23" installed and integrated with Visual Studio
   <https://docs.microsoft.com/en-us/cpp/build/vcpkg?view=msvc-160#installation>`_
 
-**Note** You'll need to run ``git checkout 2021.05.12`` in the vcpkg directory before bootstrapping
+**Note** You'll need to run ``git checkout 2022.02.23`` in the vcpkg directory before bootstrapping
 to use the correct versions of the dependencies. Building may fail unexpectedly if you skip this
 step.
 
@@ -82,7 +95,7 @@ Don't forget to integrate vcpkg with Visual Studio after bootstrapping::
 
 You should be able to install dependencies with::
 
-    .\vcpkg.exe install --triplet x64-windows glfw3 glew tclap jsoncpp eigen3
+    .\vcpkg.exe install --triplet x64-windows glfw3 glad[gl-api-33] tclap jsoncpp eigen3
 
 After these steps are complete, you should be able to open, build and run the ``ouster_example``
 project using Visual Studio:
@@ -96,7 +109,7 @@ project using Visual Studio:
 5. In the menu bar at the top of the screen, select **Build > Build All**.
 6. To use the resulting binaries, go to **View > Terminal** and run, for example::
 
-    .\out\build\x64-Release\ouster_client\ouster_client_example.exe -h
+    .\out\build\x64-Release\ouster_client\ouster_client_example.exe
 
 .. _building in release mode: https://docs.microsoft.com/en-us/visualstudio/debugger/how-to-set-debug-and-release-configurations?view=vs-2019
 
@@ -123,13 +136,23 @@ sensor data.
 Running the Sample Visualizer
 -----------------------------
 
-Navigate to ``ouster_viz`` under the build directory, which should contain an executable named
-``simple_viz`` . Run::
+Visualization is written in C++ and viz examples provided through Python bindings:
+
+- ``ouster_viz`` C++ library provides functions to build simple point cloud visualizers and comes
+  with Python bindings.
+- ``simple-viz`` Python application can be used as an entrypoint for a more sophisticated custom
+  point cloud visualizations.
 
-    ./simple_viz [flags] <sensor hostname> [udp data destination]
+After you have Python environment sourced and ``ouster-sdk`` package installed you can run::
 
-where ``<sensor hostname>`` can be the hostname (os-99xxxxxxxxxx) or IP of the sensor and ``[udp
-data destingation]`` is an optional hostname or IP to which the sensor should send lidar data.
+   $ simple-viz --sensor <sensor hostname> [--no-auto-dest] [--lidar-port PORT]
+
+where ``<sensor hostname>`` can be the hostname (os-99xxxxxxxxxx) or IP of the sensor.
+
+.. todo::
+
+   Add more info about available arguments in ``simple-viz``. ``-x``, ``--lidar-port``, and pcap
+   replay.
 
 The sample visualizer does not currently include a GUI, but can be controlled with the mouse and
 keyboard:
@@ -139,31 +162,31 @@ keyboard:
 * Scroll adjusts how far away the camera is from the vehicle
 
 Keyboard controls:
-
-    ============= ============================================
-        Key       What it does
-    ============= ============================================
-    ``p``         Increase point size
-    ``o``         Decrease point size
-    ``m``         Cycle point cloud coloring mode
-    ``b``         Cycle top 2D image
-    ``n``         Cycle bottom 2D image
-    ``shift + r`` Reset camera
-    ``e``         Change size of displayed 2D images
-    ``;``         Increase spacing in range markers
-    ``'``         Decrease spacing in range markers
-    ``r``         Toggle auto rotate
-    ``w``         Camera pitch up
-    ``s``         Camera pitch down
-    ``a``         Camera yaw left
-    ``d``         Camera yaw right
-    ``1``         Toggle first return point cloud visibility
-    ``2``         Toggle second return point cloud visibility
-    ``0``         Toggle orthographic camera
-    ``=``         Zoom in
-    ``-``         Zoom out
-    ``shift``     Camera Translation with mouse drag
-    ============= ============================================
+    ==============  ===============================================
+        Key         What it does
+    ==============  ===============================================
+    ``o``           Toggle on-screen display
+    ``p/P``         Increase/decrease point size
+    ``m``           Cycle point cloud coloring mode
+    ``b``           Cycle top 2D image
+    ``n``           Cycle bottom 2D image
+    ``R``           Reset camera
+    ``e/E``         Increase/decrease size of displayed 2D images
+    ``'/"``         Increase/decrease spacing in range markers
+    ``w``           Camera pitch up
+    ``s``           Camera pitch down
+    ``a``           Camera yaw left
+    ``d``           Camera yaw right
+    ``1``           Toggle first return point cloud visibility
+    ``2``           Toggle second return point cloud visibility
+    ``0``           Toggle orthographic camera
+    ``=/-``         Dolly in/out
+    ``(space)``     Toggle pause
+    ``./,``         Step one frame forward/back
+    ``ctrl + ./,``  Step 10 frames forward/back
+    ``>/<``         Increase/decrease playback rate (during replay)
+    ``shift``       Camera Translation with mouse drag
+    ==============  ===============================================
 
 For usage and other options, run ``./simple_viz -h``
 

cmake/FindGTest.cmake

@@ -5,7 +5,7 @@ function(find_gtest)
   set(CMAKE_MODULE_PATH "")
 
   # using the cmake-provided find module succeeds, but the resulting GTest::GTest and
-  # GTest::Maintargets cause link errors with vcpkg 2021.05.12 on macos. Try CONFIG-only first
+  # GTest::Main targets cause link errors with vcpkg 2021.05.12 on macos. Try CONFIG-only first
   find_package(GTest CONFIG QUIET)
 
   if (GTest_CONFIG AND TARGET GTest::gtest AND TARGET GTest::gtest_main)

cmake/Findjsoncpp.cmake

@@ -2,7 +2,10 @@
 
 include(FindPackageHandleStandardArgs)
 
-find_package(jsoncpp CONFIG)
+# Recent jsoncpp cmake config fails if called twice
+if(NOT jsoncpp_FOUND)
+  find_package(jsoncpp CONFIG)
+endif()
 
 # This target exists on ubuntu / debian. For some reason debian bullseye doesn't
 # ship a static lib / define the jsoncpp_lib_static target.

cmake/OusterSDKConfig.cmake.in

@@ -6,12 +6,27 @@ include(CMakeFindDependencyMacro)
 find_dependency(Eigen3)
 find_dependency(jsoncpp)
 
+set(BUILD_VIZ @BUILD_VIZ@)
+
 # viz dependencies
-set(OpenGL_GL_PREFERENCE GLVND)
-find_dependency(OpenGL)
-find_dependency(Threads)
-find_dependency(GLEW)
-find_dependency(glfw3)
+if (${BUILD_VIZ})
+  set(OpenGL_GL_PREFERENCE GLVND)
+  find_dependency(OpenGL)
+  find_dependency(Threads)
+
+  find_package(glad QUIET)
+  if(glad_FOUND)
+    message(STATUS "  OusterSDK: Found glad ${glad_CONFIG}")
+    set(GL_LOADER glad::glad)
+  else()
+    message(STATUS "  OusterSDK: glad NOT found, falling back to GLEW")
+    find_package(GLEW REQUIRED)
+    set(GL_LOADER GLEW::GLEW)
+    add_definitions("-DOUSTER_VIZ_GLEW")
+  endif()
+
+  find_dependency(glfw3)
+endif()
 
 # pcap dependencies (no cmake config on debian 10)
 # find_dependency(libtins)

conan/test_package/CMakeLists.txt

@@ -0,0 +1,19 @@
+cmake_minimum_required(VERSION 3.1)
+project(PackageTest CXX)
+
+set(CMAKE_CXX_STANDARD 11)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake)
+conan_basic_setup()
+
+find_package(OusterSDK REQUIRED)
+
+add_executable(example_client example_client.cpp)
+target_link_libraries(example_client OusterSDK::ouster_client)
+
+# CTest is a testing tool that can be used to test your project.
+# enable_testing()
+# add_test(NAME example
+#          WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/bin
+#          COMMAND example)

conan/test_package/conanfile.py

@@ -0,0 +1,24 @@
+import os
+
+from conans import ConanFile, CMake, tools
+
+class OusterSDKTestConan(ConanFile):
+    settings = "os", "compiler", "build_type", "arch"
+    generators = "cmake", "cmake_find_package"
+
+    def build(self):
+        cmake = CMake(self)
+        # Current dir is "test_package/build/<build_id>" and CMakeLists.txt is
+        # in "test_package"
+        cmake.configure()
+        cmake.build()
+
+    def imports(self):
+        self.copy("*.dll", dst="bin", src="bin")
+        self.copy("*.dylib*", dst="bin", src="lib")
+        self.copy('*.so*', dst='bin', src='lib')
+
+    def test(self):
+        if not tools.cross_building(self):
+            os.chdir("bin")
+            self.run(".%sexample_client" % os.sep)

conan/test_package/example_client.cpp

@@ -0,0 +1,14 @@
+#include <iostream>
+
+#include <ouster/lidar_scan.h>
+
+int main() {
+    ouster::LidarScan scan{1024, 64};
+
+    for (const auto& f : scan) {
+        std::cout << "Field: " << ouster::sensor::to_string(f.first)
+                  << std::endl;
+    }
+
+    return 0;
+}