Public-Auto-release: v2.17.2

# Added
* Mockup-server, which can simulate a Blickfeld scanner by reading a point cloud recording. The implementation is currently **incomplete**, please read the documentation in the source code and the C++ server example.

# Changed
* Protocol: Improved documentation of algorithms
* Python: Extended set_default_point_cloud_algorithms with static transformation

doc/CHANGELOG.md

@@ -13,6 +13,15 @@ influence the resulting point cloud.
 
 ### Removed
 
+## [2.17.2] - 2021.02.12
+
+### Added
+* Mockup-server, which can simulate a Blickfeld scanner by reading a point cloud recording. The implementation is currently **incomplete**, please read the documentation in the source code and the C++ server example.
+
+### Changed
+* Protocol: Improved documentation of algorithms
+* Python: Extended set_default_point_cloud_algorithms with static transformation
+
 ## [2.17.1] - 2021.02.08
 
 ### Changed

examples/cpp/CMakeLists.txt

@@ -8,6 +8,7 @@
 add_subdirectory(async_fetch_clouds)
 add_subdirectory(reduced_clouds)
 add_subdirectory(fetch_clouds)
+add_subdirectory(server)
 add_subdirectory(set_scan_pattern)
 add_subdirectory(error_handling)
 add_subdirectory(named_scan_pattern)

examples/cpp/server/CMakeLists.txt

@@ -0,0 +1,18 @@
+##
+## Copyright (c) 2020 Blickfeld GmbH.
+## All rights reserved.
+##
+## This source code is licensed under the BSD-style license found in the
+## LICENSE.md file in the root directory of this source tree.
+##
+cmake_minimum_required (VERSION 2.6)
+
+set(CMAKE_CXX_STANDARD 11)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+if (NOT TARGET blickfeld-scanner)
+    find_package(blickfeld-scanner REQUIRED full)
+endif()
+
+add_executable(bf-server main.cpp)
+target_link_libraries(bf-server blickfeld-scanner)

examples/cpp/server/main.cpp

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2020 Blickfeld GmbH.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE.md file in the root directory of this source tree.
+ */
+
+#include <blickfeld/exception.h>
+#include <blickfeld/mockup_server.h>
+
+int example(int argc, char* argv[]) {
+	std::string dump_fn;
+	if (argc > 1)
+		dump_fn = argv[1];
+	else
+		throw blickfeld::str_exception("Please provide filename of recording");
+
+	blickfeld::network::mockup_server server(dump_fn, [](const blickfeld::protocol::stream::Subscribe::PointCloud subscribe) {
+	                                         // Handler is called for each client point cloud subscription.
+	                                         // Variables can be initialized in this step.
+
+	                                         // Return function, which as called for every frame provided to the client.
+						 return [](blickfeld::protocol::data::Frame& frame) {
+	                                         // Process & mutate client frame
+			};
+		});
+	return server.serve_forever();
+}
+
+int main(int argc, char* argv[]) {
+	try {
+		return example(argc, argv);
+	} catch (const std::exception& e) {
+		fprintf(stderr, "main caught exception:\n%s\n", e.what());
+	}
+	return 1;
+}

protocol/blickfeld/config/algorithm.proto

@@ -17,9 +17,11 @@ message Algorithm {
 	 * This message configures the background subtraction.
 	 *
 	 * The algorithm uses a configurable number of reference frames to estimate static points (background) in the scene.
-	 * Once the number of reference frames are processed it removes all static points from the point cloud output.
-	 * The resulting point cloud only contains the non-static points (foreground).
-	 * Points which are a certain time in the foreground and don't move will be added to the background and if some object in the background, like a box is removed, the points will also appear.
+	 * Once the number of reference frames are processed, it removes all static points from the point cloud output.
+	 * The resulting point cloud then only contains the non-static points (foreground).
+	 * Points that are a initially part of the foreground and but then stop moving, will be added to the background and
+	 * thus disappear after a certain amount of time, which is given by the exponential decay rate parameter.
+	 * Conversely, if an object that is already part of the background suddenly starts moving, it will be added to the foreground.
 	 *
 	 */
 	message BackgroundSubtraction {
@@ -31,12 +33,12 @@ message Algorithm {
 	/**
 	 * > Introduced in firmware v1.18
 	 *
-	 * The neighbor filter is a simple noise filter, which uses the knowledge of neighbor points in the scan pattern.
+	 * The neighbor filter is a simple noise filter, which uses neighboring returns in the scan pattern to decide if returns should be filtered.
 	 *
 	 * The algorithm iterates through all returns and removes all, which have zero neighbors.
 	 * A neighbor return must be:
-	 * - to the left / to the right / above / below the current return in the scan pattern
-	 * - close the current range. The maximum range is defined by the angle spacing of the scan pattern and the range of the current return.
+	 * - directly to the left / to the right / above / below the current return in the scan pattern
+	 * - close to the current return. The maximum range, used for this condition, is defined by the angle spacing of the scan pattern and the range of the current return. As with higher distance, neighboring returns are expected to be further away.
 	 *
 	 * No parameters can be configured at the moment.
 	 */

python/blickfeld_scanner/scanner.py

@@ -233,7 +233,19 @@ def file_point_cloud_stream(dump_filename, as_numpy=False):
         """
         return stream.point_cloud(from_file=dump_filename, as_numpy=as_numpy)
 
-    def set_default_point_cloud_algorithms(self, persist=False, background_subtraction=False, neighbor_filter=False):
+    def set_default_point_cloud_algorithms(self, persist=False, background_subtraction=False, neighbor_filter=False, static_transformation=False):
+        """ Sets point cloud algorithms, which are then applied on all point cloud stream subscribe requests of clients.
+        Clients can still actively request other algorithms or disabled them.
+
+        Args:
+            persist (bool, optional): Persist the configuration on the device and activates it after a power-cycle. Defaults to False.
+            background_subtraction (bool, optional): Either enable the background subtraction with default parameters or supply a configuration object. Defaults to False.
+            neighbor_filter (bool, optional): Either enable the neighbor filter with default parameters or supply a configuration object Defaults to False.
+            static_transformation (bool, optional): Either enable the static transformation with default parameters or supply a configuration object. Defaults to False.
+
+        Returns:
+            Currently set advanced config, see :any:`protobuf_protocol` advanced config
+        """
         advanced = self.get_advanced_config()
         del advanced.server.default_point_cloud_subscription.algorithms[:]
 
@@ -252,6 +264,13 @@ def set_default_point_cloud_algorithms(self, persist=False, background_subtracti
             else:
                 cfg.neighbor_filter.CopyFrom(neighbor_filter)
             algorithms.append(cfg)
+        if static_transformation:
+            cfg = algorithm_pb2.Algorithm()
+            if type(static_transformation) == bool:
+                cfg.static_transformation.SetInParent()
+            else:
+                cfg.static_transformation.CopyFrom(static_transformation)
+            algorithms.append(cfg)
 
         advanced.server.default_point_cloud_subscription.algorithms.extend(algorithms)
         return self.set_advanced_config(advanced, persist=persist)