diff --git a/SDK/C++/private/pipeline_impl.cpp b/SDK/C++/private/pipeline_impl.cpp index ea58b18587568640ec20ec4606a910245fc2c533..114f73ad4b19a0bf8db3053bdc25b6260e63351c 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 5231efd178e7e008e3df549c970ccec3d1c204fa..432e7b63568ee8d5bd62d1649c98bf30f79e0f3e 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 c7531f1dcbfbd84412c09b3eabb92072db461628..f8a201bac088192866886505050b2bce07b51acd 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 5e7ba8c42a36b07578277042c90877ea628e1f61..87f0f070cc3fae52bd52a6046c6cd4ae299680ea 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.