Release 0.11.0 (#590)

See CHANGELOG.rst for more details!

---------

Co-authored-by: Ussama Naal <606033+Samahu@users.noreply.github.com>

.clang-format

@@ -108,9 +108,6 @@ PenaltyBreakTemplateDeclaration: 10
 PenaltyExcessCharacter: 1000000
 PenaltyReturnTypeOnItsOwnLine: 200
 PointerAlignment: Left
-Cpp11BracedListStyle: true
-PenaltyReturnTypeOnItsOwnLine: 200
-PointerAlignment: Left
 RawStringFormats:
   - Language:        Cpp
     Delimiters:

.gitignore

@@ -27,3 +27,4 @@ CTestTestfile.cmake
 generated
 rules.ninja
 *.a
+**/_build

CHANGELOG.rst

@@ -2,8 +2,143 @@
 Changelog
 =========
 
+[20240425] [0.11.0]
+=========================
+
+Important notes
+---------------
+
+* Dropped support for python3.7
+* Dropped support macOS 10.15
+* This will be the last release that supports Ubuntu 18.04.
+* Moved all library level modules under ``ouster.sdk``, this includes ``ouster.client``, ``ouster.pcap``
+  ``ouster.osf``. So the new access name will be ``ouster.sdk.client``, ``ouster.sdk.pcap`` and so on
+* [BREAKING] many of the ``ouster-cli`` commands and arguments have changed (see below.)
+* [BREAKING] moved ``configure_sensor`` method to ``ouster.sdk.sensor.util`` module
+* [BREAKING] removed the ``pcap_to_osf`` method.
+
+
+examples
+--------
+
+* Added a new ``async_client_example.cpp`` C++ example.
+
+
+Python SDK
+----------
+
+* Add support for python 3.12, including wheels on pypi
+* Updated VCPKG libraries to 2023.10.19
+* New ``ScanSource`` API:
+  * Added new ``MultiScanSource`` that supports streaming and manipulating LidarScan frames
+    from multiple concurrent LidarScan sources
+    * For non-live sources the ``MultiScanSource`` have the option to choose LidarScan(s) by index
+    or choose a subset of scans using slicing operation
+    * The ``MultiScanSource`` interface has the ability to fallback to ``ScanSource`` using the 
+      ``single_source(sensor_idx)``, ``ScanSource`` interface yield a single LidarScan on iteration
+      rather than a List
+    * The ``ScanSource`` interface obtained via ``single_source`` method supports same indexing and
+      and slicing operations as the ``MultiScanSource``
+  * Added a generic ``open_source`` that accepts sensor urls, or a path to a pcap recording
+    or an osf file
+  * Add explicit flag ``index`` to index unindexed osf files, if flag is set to ``True`` the osf file
+    will be indexed and the index will be saved to the file on first attempt
+  * Display a progress bar during index of pcap file or osf (if unindexed)
+* Improved the robustness of the ``resolve_metadata`` method used to
+  automatically identify the sensor metadata associated with a PCAP source.
+* [bugfix] SimpleViz complains about missing fields
+* [bugfix] Gracefully handle failed sensor connection attempts with proper error reporting
+* [bugfix] Fix assertion error when using viz stepping on a live sensor
+* [bugfix] Scope MultiLidarViz imports to viz commands
+* [bugfix] LidarScan yielded with improper header/status
+* [bugfix] OSF ScanSource fields property doesn't report the actual fields 
+* Removed ``ouster.sdkx``, the ``open_source`` command is now part of ``ouster.sdk`` module
+* The ``FLAGS`` field is always added to the list fields of any source type by default. In case of a 
+  dual return lidar profile then a second ``FLAGS2`` will also be added. 
+
+
+mapping
+-------
+
+* Updated SLAM API and examples.
+* Added real time frame dropping capability to SLAM API.
+* The ``ouster-mapping`` package now uses ``point-cloud-utils`` instead of ``open3d``.
+* improved per-column pose accuracy, which is now based on the actual column timestamps
+
+
+ouster-cli
+----------
+
+* Many commands can now be chained together, e.g. ``ouster-cli source <src> slam viz``.
+* New ``save`` command can output the result in a variety of formats.
+* Added ``--ts`` option for specifying the timestamps to use when saving an OSF
+  file. Host packet receive time is the default, but not all scan sources have
+  this info. Lidar packet timestamps can be used as an alternative.
+* Changed the output format of ``ouster-cli discover`` to include more information.
+* Added JSON format output option to ``ouster-cli discover``.
+* Added a flag to output sensor user data to ``ouster-cli discover``.
+* Update the minimum required version of ``zeroconf``.
+* Removed ``python-magic`` package from required dependencies.
+* Made the output of ``ouster-cli source <osf> info`` much more
+  user-friendly. (``ouster-cli source <osf> dump`` gives old output.)
+* [breaking] changed the argument format of the ``slice`` command.
+* [breaking] removed the ``--legacy`` and ``--non-legacy`` flags.
+* [breaking] removed the ``ouster-cli mapping``, ``ouster-cli osf``,
+  ``ouster-cli pcap``, and ``ouster-cli sensor`` commands.
+* [bugfix] return a nonzero exit code on error.
+* [bugfix] fix an error that occurred when setting the IMU port using the
+  ``-i`` option.
+
+
+ouster_client
+-------------
+
+* Added a new buffered UDP source implementation ``BufferedUDPSource``.
+* The method ``version_of_string`` is marked as deprecated, use ``version_from_string``
+  instead.
+* Added a new method ``firmware_version_from_metadata`` which works across firmwares.
+* Added support for return order configuration parameter.
+* Added support for gyro and accelerometer FSR configuration parameters.
+* [bugfix] ``mtp_init_client`` throws a bad optional access.
+* [bugfix] properly handle 32-bit frame IDs from the
+  ``FUSA_RNG15_RFL8_NIR8_DUAL`` sensor UDP profile.
+
+
+ouster_osf
+----------
+
+* [breaking] Greatly simplified OSF writer API with examples.
+* [breaking] removed the ``to_native`` and ``from_native`` methods.
+* Updated Doxygen API documentation for OSF C++ API.
+* Removed support for the deprecated "standard" OSF file format. (The streaming
+  OSF format is still supported.)
+* Added ``osf_file_modify_metadata`` that allows updating the sensor info
+  associated with each lidar stream in an OSF file.
+* Warn the user if reading an empty or improperly indexed file.
+
+
+ouster_viz
+----------
+* Added scaled palettes for calibrated reflectivity.
+* Distance rings can now be hidden by setting their thickness to zero.
+* [bugfix] Fix some rendering issues with the distance rings.
+* [bugfix] Fix potential flickering in Viz
+
+
+Known issues
+------------
+
+* ouster-cli discover may not provide info for sensors using IPv6 link-local
+  networks on Python 3.8 or with older versions of zeroconf.
+* ouster-cli when combining ``slice`` command with ``viz`` the program will
+  exit once iterate over the selected range of scans even when
+  the ``--on-eof`` option is set to ``loop``.
+  - workaround: to have ``viz`` loop over the selected range, first perform a
+    ``slice`` with ``save``, then playback the generated file.
+
+
 [20231031] [0.10.0]
-============
+===================
 
 Important notes
 ---------------

CMakeLists.txt

@@ -16,14 +16,14 @@ include(VcpkgEnv)
 project(ouster_example VERSION 20231031)
 
 # generate version header
-set(OusterSDK_VERSION_STRING 0.10.0)
+set(OusterSDK_VERSION_STRING 0.11.0)
 include(VersionGen)
 
 # ==== Options ====
 option(CMAKE_POSITION_INDEPENDENT_CODE "Build position independent code." ON)
 option(BUILD_SHARED_LIBS "Build shared libraries." OFF)
 option(BUILD_PCAP "Build pcap utils." ON)
-option(BUILD_OSF "Build Ouster OSF library." OFF)
+option(BUILD_OSF "Build Ouster OSF library." ON)
 option(BUILD_VIZ "Build Ouster visualizer." ON)
 option(BUILD_TESTING "Build tests" OFF)
 option(BUILD_EXAMPLES "Build C++ examples" OFF)

README.rst

@@ -9,9 +9,10 @@ Ouster SDK - libraries and tools for Ouster Lidar Sensors
 Cross-platform C++/Python Ouster Sensor Development Toolkit
 
 To get started with our sensors, client, and visualizer, please see our SDK and sensor documentation:
+ouster-sdk/index.html
 
 - `Ouster SDK Documentation <https://static.ouster.dev/sdk-docs/index.html>`_
-- `Ouster Sensor Documentaion <https://static.ouster.dev/sensor-docs>`_ 
+- `Ouster Sensor Public Documentaion <https://static.ouster.dev/sensor-docs>`_
 
 This repository contains Ouster SDK source code for connecting to and configuring ouster sensors,
 reading and visualizing data.

cmake/Coverage.cmake

@@ -0,0 +1,9 @@
+# Cmake Functions For Code Coverage
+
+FUNCTION(CodeCoverageFunctionality target)
+  if(DEFINED ENV{CMAKE_COVERAGE_TESTS} AND "$ENV{CMAKE_COVERAGE_TESTS}" MATCHES "true")
+    message(STATUS "Code Coverage Enabled: Target: ${target}")
+    target_link_libraries(${target} PRIVATE gcov)
+    target_compile_options(${target} PRIVATE -O0 --coverage -g)
+  endif()
+ENDFUNCTION()

docs/Doxyfile

@@ -586,13 +586,13 @@ HIDE_COMPOUND_REFERENCE= NO
 # will show which file needs to be included to use the class.
 # The default value is: YES.
 
-SHOW_HEADERFILE        = YES
+#SHOW_HEADERFILE        = YES
 
 # If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of
 # the files that are included by a file in the documentation of that file.
 # The default value is: YES.
 
-SHOW_INCLUDE_FILES     = YES
+#SHOW_INCLUDE_FILES     = YES
 
 # If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each
 # grouped member an include statement to the documentation, telling the reader
@@ -804,7 +804,7 @@ WARN_IF_DOC_ERROR      = YES
 # parameters have no documentation without warning.
 # The default value is: YES.
 
-WARN_IF_INCOMPLETE_DOC = YES
+#WARN_IF_INCOMPLETE_DOC = YES
 
 # This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that
 # are documented, but have no documentation for their parameters or return
@@ -830,7 +830,7 @@ WARN_AS_ERROR          = NO
 # messages should be written. If left blank the output is written to standard
 # error (stderr).
 
-WARN_LOGFILE           =
+WARN_LOGFILE           = "$warn_log_file"
 
 #---------------------------------------------------------------------------
 # Configuration options related to the input files
@@ -845,6 +845,7 @@ WARN_LOGFILE           =
 INPUT                  = ../ouster_client \
                          ../ouster_pcap \
                          ../ouster_viz \
+                         ../ouster_osf \
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1532,7 +1533,7 @@ GENERATE_TREEVIEW      = NO
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-FULL_SIDEBAR           = NO
+#FULL_SIDEBAR           = NO
 
 # The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that
 # doxygen will group on one line in the generated HTML documentation.
@@ -1615,7 +1616,7 @@ USE_MATHJAX            = NO
 # The default value is: MathJax_2.
 # This tag requires that the tag USE_MATHJAX is set to YES.
 
-MATHJAX_VERSION        = MathJax_2
+#MATHJAX_VERSION        = MathJax_2
 
 # When MathJax is enabled you can set the default output format to be used for
 # the MathJax output. For more details about the output format see MathJax
@@ -2278,7 +2279,7 @@ EXTERNAL_PAGES         = YES
 # powerful graphs.
 # The default value is: YES.
 
-CLASS_DIAGRAMS         = YES
+CLASS_DIAGRAMS         = NO
 
 # You can include diagrams made with dia in doxygen documentation. Doxygen will
 # then run dia to produce the diagram and insert it in the documentation. The
@@ -2300,7 +2301,7 @@ HIDE_UNDOC_RELATIONS   = YES
 # set to NO
 # The default value is: NO.
 
-HAVE_DOT               = NO
+HAVE_DOT               = YES
 
 # The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed
 # to run in parallel. When set to 0 doxygen will base this on the number of
@@ -2342,7 +2343,7 @@ DOT_FONTPATH           =
 # The default value is: YES.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-CLASS_GRAPH            = YES
+CLASS_GRAPH            = NO
 
 # If the COLLABORATION_GRAPH tag is set to YES then doxygen will generate a
 # graph for each documented class showing the direct and indirect implementation
@@ -2351,14 +2352,14 @@ CLASS_GRAPH            = YES
 # The default value is: YES.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-COLLABORATION_GRAPH    = YES
+COLLABORATION_GRAPH    = NO
 
 # If the GROUP_GRAPHS tag is set to YES then doxygen will generate a graph for
 # groups, showing the direct groups dependencies.
 # The default value is: YES.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-GROUP_GRAPHS           = YES
+GROUP_GRAPHS           = NO
 
 # If the UML_LOOK tag is set to YES, doxygen will generate inheritance and
 # collaboration diagrams in a style similar to the OMG's Unified Modeling
@@ -2458,7 +2459,7 @@ CALLER_GRAPH           = NO
 # The default value is: YES.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-GRAPHICAL_HIERARCHY    = YES
+GRAPHICAL_HIERARCHY    = NO
 
 # If the DIRECTORY_GRAPH tag is set to YES then doxygen will show the
 # dependencies a directory has on other directories in a graphical way. The
@@ -2467,7 +2468,7 @@ GRAPHICAL_HIERARCHY    = YES
 # The default value is: YES.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DIRECTORY_GRAPH        = YES
+DIRECTORY_GRAPH        = NO
 
 # The DOT_IMAGE_FORMAT tag can be used to set the image format of the images
 # generated by dot. For an explanation of the image formats see the section
@@ -2599,4 +2600,4 @@ GENERATE_LEGEND        = YES
 # files.
 # The default value is: YES.
 
-DOT_CLEANUP            = YES
+DOT_CLEANUP            = NO

docs/_templates/versions.html

@@ -0,0 +1,17 @@
+<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+    <span class="rst-current-version" data-toggle="rst-current-version">
+    Version: {{ current_version }}
+    <span class="fa fa-caret-down"></span>
+    </span>
+    <div class="rst-other-versions">
+        {% if versions %}
+        <dl>
+            <dt>{{ _('Versions') }}</dt>
+            {% for version, url in versions %}
+            <dd><a href="{{ url }}/index.html">{{ version }}</a></dd>
+            {% endfor %}
+        </dl>
+        {% endif %}
+        <br>
+    </div>
+</div>