release-0.11.1

CHANGELOG.rst

@@ -2,8 +2,33 @@
 Changelog
 =========
 
+[20240510] [0.11.1]
+===================
+
+Important notes
+---------------
+
+* [BREAKING] the ``open_source`` method now returns a ``ScanSource`` by default, not a ``MultiScanSource``.
+
+Python SDK
+----------
+
+* Updated the ``open_source`` documentation.
+* Fixed an issue that caused the viz to redraw when the mouse cursor is moved.
+
+ouster_client
+-------------
+
+* Improved the client initialization latency.
+
+mapping
+-------
+
+* Fixed several issues with the documentation.
+
+
 [20240425] [0.11.0]
-=========================
+===================
 
 Important notes
 ---------------

CMakeLists.txt

@@ -16,7 +16,7 @@ include(VcpkgEnv)
 project(ouster_example VERSION 20231031)
 
 # generate version header
-set(OusterSDK_VERSION_STRING 0.11.0)
+set(OusterSDK_VERSION_STRING 0.11.1)
 include(VersionGen)
 
 # ==== Options ====

docs/cli/mapping-sessions.rst

@@ -4,6 +4,7 @@ Start mapping with the Ouster-CLI
 
 .. _ouster-cli-mapping:
 
+
 Installation
 ------------
 
@@ -29,29 +30,34 @@ Mapping Tools
 After installing the Ouster SDK and mapping dependencies, you can explore various mapping tools
 using a connected Ouster sensor or a PCAP/OSF file.
 
-Use ``ouster-cli`` to view the available commands and options you can use ``--help``. Try the
-following command:
+To explore and configure the parameters of the SLAM algorithm, you can use the ``--help`` flag
+to view the available options.
 
 .. code:: bash
 
-        ouster-cli source <SENSOR_HOSTNAME> / <FILENAME> --help
+        ouster-cli source <SENSOR_HOSTNAME> / <FILENAME> slam --help
 
-Currently, there are two main commands: ``slam`` and ``save``. You can further explore each
-command by accessing their respective submenus using the ``--help`` flag. For example:
+The ``slam`` command can be combined with either or both the ``save`` and ``viz`` commands.
+You can further explore each command in detail by accessing their respective submenus
+using the ``--help`` flag.
 
 .. code:: bash
 
-        ouster-cli source <SENSOR_HOSTNAME> / <FILENAME> slam --help
+        ouster-cli source <SENSOR_HOSTNAME> / <FILENAME> slam save --help
+
+.. code:: bash
+
+        ouster-cli source <SENSOR_HOSTNAME> / <FILENAME> slam viz --help
 
 
 SLAM Command
 ------------
 
-Simultaneous localization and mapping (SLAM) is a technique that enables a system to construct
+Simultaneous Localization and Mapping (SLAM) is a technique that enables a system to construct
 a map of its surroundings while simultaneously determining its own position on that map.
-The Ouster SDK slam command writes lidar scans with per-column poses into an OSF file, an open-source
-custom file format for which Ouster provides conversion capabilities, allowing for the
-reconstruction of a detailed and precise map later.
+
+We use the slam algorithm to determine the lidar movement trajectory, correct motion
+distortion and reconstruct a detailed and precise point cloud map.
 
 Connect to a sensor or use a PCAP/OSF file :ref:`Download Sample PCAP File <sample-data-download>`
 
@@ -64,24 +70,88 @@ Then execute the following command:
 
 .. code:: bash
 
-        ouster-cli source <SENSOR_HOSTNAME> / <FILENAME> slam viz -o sample.osf
+        ouster-cli source <SENSOR_HOSTNAME> / <FILENAME> slam viz -e exit save sample.osf
 
 .. note::
 
         Please replace <HOSTNAME> with the corresponding hostname or IP of your sensor, and replace
         <FILENAME> with the actual file path and name of the PCAP/OSF file. Similarly, make the
         necessary substitutions in the subsequent commands.
 
-The terminal will display details such as the output filename and the processing duration. The
-output filename must have the .osf extension in order to be used by the ``save`` command.
 
-You can adjust settings such as point size, color, switch between 2D images, and pause playback in the visualizer, among other options. More details can be found at the :ref:`Ouster Visualizer <viz-run>`
+Save Command
+------------
+
+The ``save`` command stores the lidarscan and the lidar movement trajectory into a OSF file by
+specifying a filename with a .osf extension. This OSF file will be used for accumulated point
+cloud generation and the other post-process tools we offer in the future.
+
+.. code:: bash
+
+        ouster-cli source <SENSOR_HOSTNAME> / <FILENAME> slam save sample.osf
+
+The ``save`` command can also be used to generated an accumulated point cloud map using a
+SLAM-generated OSF file in LAS (.las), PLY (.ply), or PCD (.pcd) format.
+The output format depends on the extension of the output filename.
+For example, to convert the OSF file we generated using the ``slam`` command to PLY format,
+we can simply use the following:
+
+.. code:: bash
+
+        ouster-cli source sample.osf save output.ply
+
+You can utilize the ``slam`` command with the ``save`` command to directly generate a cumulative
+point cloud map. However, please be aware that this combined process can be resource-intensive.
+We recommend using this approach with a PCAP/OSF file rather than with a live sensor to avoid
+SLAM performance degradation.
+
+.. code:: bash
+
+        ouster-cli source <FILENAME> slam save output.ply
+
+The accumulated point cloud data is automatically split and downsampleed into multiple files to
+prevent exporting a huge size file. The terminal will display details, and you will see the
+following printout for each output file:
+
+.. code:: bash
+
+        Output file: output-000.ply
+        3932160 points accumulated during this period,
+        154228 near points are removed [3.92 %],
+        1475955 down sampling points are removed [37.54 %],
+        2213506 zero range points are removed [56.29 %],
+        88471 points are saved [2.25 %].
+
+Use the ``--help`` flag for more information such as adjusting the minimal range, selecting
+different fields as values, and changing the point cloud downsampling scale etc.
+
+You can use an open source software `CloudCompare`_ to import and view the generated point cloud
+data files.
+
 
+Viz Command
+-----------
 
-Accumulated Scan in SLAM command visulizer
-------------------------------------------
+The ``viz`` command enables visualizing the accumulated point cloud generation during the
+SLAM process. By default, the viz operates in looping mode, meaning the visualiation will
+continuously replay the source file.
+
+.. code:: bash
+
+        ouster-cli source <SENSOR_HOSTNAME> / <FILENAME> slam viz
+
+When combining the ``viz`` and ``save`` commands, the saving process will automatically terminate
+after the first iteration, and then the SLAM process restarts for each subsequent lidar scan iteration.
+To end the SLAM and visualization processes after the save operation completes, you can use ``ctrl + c``.
+Alternatively, you can add ``-e exit`` to the ``viz`` command to terminate the process after a
+complete iteration.
+
+.. code:: bash
 
-Within the Ouster Visualizer, there is a visualization feature known as **ScansAccumulator**. This functionality represents a continuation of efforts to visualize lidar data by incorporating SLAM-generated poses stored within the ``LidarScan.pose`` property."
+        ouster-cli source <SENSOR_HOSTNAME> / <FILENAME> slam viz -e exit save sample.osf
+
+
+**Scans Accumulation**: The viz command allows the user to customize ...
 
 Available view modes
 ~~~~~~~~~~~~~~~~~~~~~
@@ -127,9 +197,10 @@ Dense accumulated clouds view (with every point of a scan)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To obtain the densest view use the ``--accum-num N --accum-every 1`` params where ``N`` is the
-number of clouds to accumulate (``N`` up to 100 is generally small enough to avoid slowing down the viz interface)::
+number of clouds to accumulate (``N`` up to 100 is generally small enough to avoid slowing down
+the viz interface)::
 
-   ouster-cli source <SENSOR_HOSTNAME> / <FILENAME> slam viz --accum-num 20 -o sample.osf
+   ouster-cli source <SENSOR_HOSTNAME> / <FILENAME> slam viz --accum-num 20 save sample.osf
 
 and the dense accumulated clouds result:
 
@@ -141,53 +212,25 @@ and the dense accumulated clouds result:
 Overall map view (with poses)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-One of the main tasks we frequently need is a preview of the overall map. We can test this by using the generated OSF file, which was created with the above command and contains the SLAM-generated ``LidarScan.pose`` property.
+One of the main tasks we frequently need is a preview of the overall map. We can test this by using
+the generated OSF file, which was created with the above command and contains the
+SLAM-generated ``LidarScan.pose`` property.
 ::
 
    ouster-cli source sample.osf viz --accum-num 20 \
    --accum-every 0 --accum-every-m 10.5 --accum-map -r 0 -e stop
 
 
-Here is a preview example of the overall map generated from the accumulated scan results. By utilizing the '-e stop' option, the visualizer stops once the replay process finishes, displaying the preview of the lidar trajectory:
+Here is a preview example of the overall map generated from the accumulated scan results.
+By utilizing the '-e stop' option, the visualizer stops once the replay process finishes,
+displaying the preview of the lidar trajectory:
 
 .. figure:: /images/scans_accum_map_all_scan.png
 
    Data fully replayed with map and accum enabled (last current scan is displayed here in grey
    palette)
 
 
-Save Command
-------------
-
-The ``save`` command can be used to convert the SLAM-generated OSF file to a point cloud data file
-format such as LAS (.las), PLY (.ply), or PCD (.pcd). The output file format depends on the
-extension of the output filename. Let's use the OSF file generated from the SLAM command
-and convert it to a PLY file:
-
-.. code:: bash
-
-        ouster-cli source sample.osf save output.ply
-
-The ``save`` command automatically splits and downsamples the trajectory-adjusted point cloud into
-several files to prevent exporting a huge size file. The terminal will display details, and you
-will see the following printout for each output file:
-
-.. code:: bash
-
-        Output file: output1.ply
-        3932160 points accumulated during this period,
-        154228 near points are removed [3.92 %],
-        1475955 down sampling points are removed [37.54 %],
-        2213506 zero range points are removed [56.29 %],
-        88471 points are saved [2.25 %].
-
-You can adjust the minimal range, select different fields as values, and change the voxel size by
-referring to the ``--help`` flag for more information.
-
-You can use an open source software `CloudCompare`_ to import and view the generated point cloud
-data files.
-
-
 .. _Networking Guide: https://static.ouster.dev/sensor-docs/image_route1/image_route3/networking_guide/networking_guide.html
 
 .. _CloudCompare: https://www.cloudcompare.org/

docs/python/slam-api-example.rst

@@ -26,7 +26,7 @@ between consecutive scans
    from ouster.sdk import open_source
    from ouster.mapping.slam import KissBackend
    import numpy as np
-   scans = open_source(pcap_path, sensor_idx=0)
+   scans = open_source(pcap_path)
    slam = KissBackend(scans.metadata, max_range=75, min_range=1, voxel_size=1.0)
    last_scan_pose = np.eye(4)
 
@@ -59,7 +59,7 @@ as well as for demonstration and feedback purposes.
    from functools import partial
    from ouster.viz import SimpleViz, ScansAccumulator
    from ouster.mapping.slam import KissBackend
-   scans = open_source(pcap_path, sensor_idx=0)
+   scans = open_source(pcap_path)
    slam = KissBackend(scans.metadata, max_range=75, min_range=1, voxel_size=1.0)
 
    scans_w_poses = map(partial(slam.update), scans)

docs/python/using-scan-source.rst

@@ -24,38 +24,39 @@ can be accomplished as follows:
    >>> pcap_path = '<SAMPLE_DATA_PCAP_PATH>'
    >>> metadata_path = '<SAMPLE_DATA_JSON_PATH>'
    >>> from ouster.sdk import open_source
-   >>> source = open_source(pcap_path, sensor_idx=0, meta=[metadata_path])
+   >>> source = open_source(pcap_path, meta=[metadata_path])
 
 
 The ``source`` handle here acts the same as the handle returned by the ``pcap.Pcap`` constructor, with some
 extra capabilities that we will cover later.  
 
-Notice here that besides the ``pcap_path`` we pass two additional parameters: ``sensor_idx`` with a value
-of zero, and ``meta`` which we set to the ``metadata_path`` to point to the sensor metadata associated with
-the pcap file we are trying to open. Both parameters are optional and can be omitted. In case the ``meta``
-parameter was not omitted, the ``open_source`` method will attempt to locate the metadata associated with
-the pcap file based on location and the pcap file prefix. That being said, if ``SAMPLE_DATA_JSON_PATH`` is
-located in the same folder as ``SAMPLE_DATA_PCAP_PATH`` and the two files share a prefix we can simplify the
-above call to:
+Notice here that rather than we try to load and parse the metadata ourselves we only need to pass to metadata
+to the method through ``meta`` parameter and the method will take care of loading it and associating it with the
+source object. The ``meta`` parameter however is optional and can be omitted. When the ``meta`` parameter is not
+set explicity the ``open_source`` method will attempt to locate the metadata automatically for us and we can reduce
+the call to:
 
 .. code:: python
-   >>> source = open_source(pcap_path, sensor_idx=0)
+   >>> source = open_source(pcap_path)
 
+However if metadata file is not in the same folder as the pcap and don't have a shared name prefix the method will
+fail.
 
-The second parameter, ``sensor_idx``, allows users to select a specific sensor from the selected source.
-That is because starting with ouster-sdk v0.11 Ouster added support for working with sensor data collected from
-multiple sensors. The ``open_source`` method by default returns the more complete interface ``MultiScanSource``
-which has the capability to interact with multiple sensor streams, which we will in next section. Setting the
-value of ``sensor_idx`` to zero tells ``open_source`` we are only interested in LidarScan data coming from the
-first sensor from this specific pcap file in case the file had more than one sensor. By doing so, the
-``open_source`` method returns a less sophisticated interface ``ScanSource`` which is more familiar to SDK users
-from previous versions.
 
-The main different between the ``MultiScanSource`` and the ``ScanSource`` is the expected return of some
-of the object methods. For example, when creating an iterator for a ``ScanSource`` object, the user would get
-a single ``LidarScan`` object per iteration. Iterating over the contents of a ``MultiScanSource`` object always
-yields a **list** of ``LidarScan(s)`` per iteration corresponding to the number of sensors stored in the pcap
-file or whatever source type is being used. This is true even when the pcap file contains data for a single sensor.
+.. note::
+  Another optional but important parameter for the ``open_source`` method is ``sensor_idx``. This paramter is to zero
+  by default, which should always be the case unless the pcap file that you are using (or osf or any LidarScan storage)
+  contains scans from more than one sensor, in this case, users can set the ``sensor_idx`` to a any value between zero 
+  and ``sensors_count -1`` to access and manipulate scans from a specific sensor by the order they appear in the file.
+  Alternatively, if users set the value of ``sensor_idx`` to ``-1`` then ``open_source`` will return a slightly differnt
+  interface from ``ScanSource`` which is the ``MultiScanSource`` this interface and as the name suggests allows users to
+  work with sensor data collected from multiple sensors at the same time.
+
+  The main different between the ``MultiScanSource`` and the ``ScanSource`` is the expected return of some of the object
+  methods. For example, when creating an iterator for a ``ScanSource`` object, the user would get a single ``LidarScan``
+  object per iteration. Iterating over the contents of a ``MultiScanSource`` object always yields a **list** of
+  ``LidarScan(s)`` per iteration corresponding to the number of sensors stored in the pcap file or whatever source type
+  is being used. This is true even when the pcap file contains data for a single sensor.
 
 
 On the other hand, if the user wants to open an osf file or access the a live sensor, all that changes is url
@@ -65,7 +66,7 @@ of the source. For example, to interact with a live sensor the user can execute
 
    >>> sensor_url = '<SENSOR-HOSTNAME-OR-IP>'
    >>> from ouster.sdk import open_source
-   >>> source = open_source(sensor_url, sensor_idx=0)
+   >>> source = open_source(sensor_url)
 
 
 Obtaining sensor metadata
@@ -96,8 +97,7 @@ scans. We can achieve that using:
    ...     if ctr == 10:
    ...         break
 
-
-As we noted earlier, if we don't supply ``sensor_idx=0`` to the ``open_source`` method, the method will construct a
+As we noted earlier, if we set ``sensor_idx=-1`` when invoking ``open_source`` method, the method will construct a
 ``MultiScanSource``, which always addresses a group of sensors. Thus, when iterating over the ``source`` the user
 receives a collated set of scans from the addressed sensors per iteration. The ``MultiScanSource`` examines the
 timestamp of every scan from every sensor and returns a list of scans that fit within the same time window as single
@@ -126,7 +126,6 @@ Note that when iterating over a ``MultiScanSource`` object, it always a list of
 source has only a single sensor. In this case, the iterator will yield a list with a single element per iteration.
 
 
-
 Using indexing and slicing capabilities of a ScanSource
 ========================================================
 
@@ -142,7 +141,7 @@ source as an indexed one upon opening. Revisitng the previous pcap open example,
 
    >>> pcap_path = '<SAMPLE_DATA_PCAP_PATH>'
    >>> from ouster.sdk import open_source
-   >>> source = open_source(pcap_path, sensor_idx=0, index=True)
+   >>> source = open_source(pcap_path, index=True)
 
 First note that we omitted the ``meta`` parameter since it can be populated automatically as we explained earlier.
 Second you will noticed that we introduced a new parameter ``index`` with its value set to ``True`` (default is false),

docs/versions.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.11.0",
+    "tags": {
+      "sdkx": "sdk/0.11.0",
+      "sdk": "sdk/0.11.0"
+    }
+  },
   {
     "version": "0.10.0",
     "tags": {