From 70bb37bb1fdb6216473cee0948356f580f5ad33c Mon Sep 17 00:00:00 2001
From: Nicolas Pope <nwpope@utu.fi>
Date: Sat, 7 Nov 2020 19:50:17 +0200
Subject: [PATCH] Pipeline documentation
---
SDK/C++/private/pipeline_impl.cpp | 2 +
SDK/C++/public/include/voltu/operator.hpp | 27 ++++++++---
SDK/C++/public/include/voltu/pipeline.hpp | 58 +++++++++++++++++++++++
SDK/C++/public/include/voltu/room.hpp | 2 +
4 files changed, 83 insertions(+), 6 deletions(-)
diff --git a/SDK/C++/private/pipeline_impl.cpp b/SDK/C++/private/pipeline_impl.cpp
index ea58b1858..114f73ad4 100644
--- a/SDK/C++/private/pipeline_impl.cpp
+++ b/SDK/C++/private/pipeline_impl.cpp
@@ -49,6 +49,8 @@ bool PipelineImpl::waitCompletion(int timeout)
voltu::OperatorPtr PipelineImpl::appendOperator(voltu::OperatorId id)
{
+ if (static_cast<int>(id) <= 0) throw voltu::exceptions::BadParameterValue();
+
switch (id)
{
case voltu::OperatorId::kFusion : return std::make_shared<voltu::internal::OperatorImpl>(graph_->append<ftl::operators::Fusion>("fusion"));
diff --git a/SDK/C++/public/include/voltu/operator.hpp b/SDK/C++/public/include/voltu/operator.hpp
index 5231efd17..432e7b635 100644
--- a/SDK/C++/public/include/voltu/operator.hpp
+++ b/SDK/C++/public/include/voltu/operator.hpp
@@ -12,23 +12,38 @@
namespace voltu
{
+
+/**
+ * @brief Operation type identifier.
+ */
enum class OperatorId
{
kInvalid = 0,
- kDepth = 1,
- kGTEvaluator = 2,
- kFusion = 3,
- kClipping = 4,
- kAruco = 5,
- kPixelAnalysis = 6
+ kDepth = 1, ///< Calculate depth map from stereo images
+ kGTEvaluator = 2, ///< Ground truth quality evaluation
+ kFusion = 3, ///< Fuse multiple depth maps together
+ kClipping = 4, ///< Use a clip box to remove unwanted data
+ kAruco = 5, ///< Aruco tag detector
+ kPixelAnalysis = 6 // TODO: Change this
};
+/**
+ * @brief Manage operator settings.
+ */
class Operator
{
public:
virtual ~Operator() = default;
+ /**
+ * @brief Get a named operator property.
+ *
+ * @throw voltu::exceptions::BadPropertyName If name not valid.
+ * @return Property accessor object.
+ */
PY_API virtual voltu::PropertyPtr property(const std::string &name) = 0;
+
+ // TODO: Get list of properties supported
};
typedef std::shared_ptr<Operator> OperatorPtr;
diff --git a/SDK/C++/public/include/voltu/pipeline.hpp b/SDK/C++/public/include/voltu/pipeline.hpp
index c7531f1dc..f8a201bac 100644
--- a/SDK/C++/public/include/voltu/pipeline.hpp
+++ b/SDK/C++/public/include/voltu/pipeline.hpp
@@ -14,15 +14,73 @@
namespace voltu
{
+/**
+ * @brief Manage a pipeline of frame procesing operations.
+ *
+ * A frame processing pipeline can be constructed from a range of different
+ * operators. One example is the fusion operator that merges all input data
+ * together with a model. The pipeline of operators runs asynchonously but in
+ * sequential order and modifies the frames internal data.
+ *
+ * @see voltu::Frame
+ * @see voltu::Operator
+ */
class Pipeline
{
public:
virtual ~Pipeline() = default;
+ /**
+ * @brief Send a frame for processing.
+ *
+ * This method is non-blocking and will therefore return before operator
+ * processing has been completed. The data inside the frame object is
+ * modified during this process, so the data should not be accessed until
+ * the pipeline is completed.
+ *
+ * @note
+ * You must not submit multiple frames to the same pipeline without
+ * ensuring completion. You must also not access frame data during
+ * processing. The room object associated with the frame must remain valid
+ * for the duration of processing.
+ *
+ * @param frame A room data frame.
+ *
+ * @throw voltu::exceptions::InvalidFrameObject If the frame is invalid
+ * @throw voltu::exceptions::IncompatibleOperation If the pipeline given
+ * cannot be applied to the frame for some reason.
+ */
PY_API virtual void submit(const voltu::FramePtr &frame) = 0;
+ /**
+ * @brief Block until all processing is completed.
+ *
+ * If a frame has been submitted, this can be used to block until all
+ * processing has finished. If no frame has been submitted then this
+ * method will currently block until timeout.
+ *
+ * @todo Allow timeout of -1 and exception on no frame.
+ *
+ * @param timeout Millisecond timeout, or 0 for non-blocking check.
+ * @return True if completed
+ */
PY_API virtual bool waitCompletion(int timeout) = 0;
+ /**
+ * @brief Add an operator to this pipeline.
+ *
+ * Each operator is appended to the pipeline in the order added, and
+ * therefore will be processed sequentially in that same order. One type
+ * of operator can be appended multiple times, useful if different settings
+ * are to be used each time. Settings can be accessed from the returned
+ * operator management instance.
+ *
+ * @see voltu::Operator
+ *
+ * @throw voltu::exceptions::BadParameterValue For invalid operators
+ * @throw voltu::exceptions::NotImplemented If operator not implemented for SDK
+ * @return Operator management instance for settings.
+ */
PY_API virtual voltu::OperatorPtr appendOperator(voltu::OperatorId id) = 0;
};
diff --git a/SDK/C++/public/include/voltu/room.hpp b/SDK/C++/public/include/voltu/room.hpp
index 5e7ba8c42..87f0f070c 100644
--- a/SDK/C++/public/include/voltu/room.hpp
+++ b/SDK/C++/public/include/voltu/room.hpp
@@ -60,6 +60,7 @@ public:
* 2) If `timeout` < 0 then it blocks without timeout.
* 3) If `timeout` > 0 then it blocks for maximum `timeout` milliseconds.
*
+ * @note
* Note that for composite rooms with multiple physical rooms, a new
* frame occurs whenever any of the physical rooms provides a new frame,
* even if other rooms do not.
@@ -88,6 +89,7 @@ public:
* marks the data as seen, and therefore causes a subsequent call to
* `waitNextFrame` to block until more data arrives.
*
+ * @note
* Each call to `getFrame` can return a different smart pointer for the same
* frame data, this is valid. The room object must remain in existence for
* as long as any frame objects are held.
--
GitLab