From 50cd9b828c1d99047d4fd2d03c14ebe20c6b76e5 Mon Sep 17 00:00:00 2001
From: Nicolas Pope <nwpope@utu.fi>
Date: Sat, 7 Nov 2020 18:16:35 +0200
Subject: [PATCH] Add doc and license to SDK
---
SDK/C++/private/observer_impl.cpp | 2 +-
SDK/C++/public/LICENSE | 19 +++
SDK/C++/public/README.md | 1 +
SDK/C++/public/include/voltu/defines.hpp | 6 +
SDK/C++/public/include/voltu/feed.hpp | 6 +
SDK/C++/public/include/voltu/initialise.hpp | 6 +
SDK/C++/public/include/voltu/observer.hpp | 6 +
SDK/C++/public/include/voltu/opencv.hpp | 6 +
SDK/C++/public/include/voltu/operator.hpp | 6 +
SDK/C++/public/include/voltu/pipeline.hpp | 6 +
SDK/C++/public/include/voltu/room.hpp | 6 +
SDK/C++/public/include/voltu/system.hpp | 108 ++++++++++++++++--
.../public/include/voltu/types/channel.hpp | 6 +
SDK/C++/public/include/voltu/types/errors.hpp | 8 +-
SDK/C++/public/include/voltu/types/frame.hpp | 6 +
SDK/C++/public/include/voltu/types/image.hpp | 6 +
.../public/include/voltu/types/intrinsics.hpp | 6 +
.../public/include/voltu/types/pointcloud.hpp | 6 +
.../public/include/voltu/types/property.hpp | 6 +
SDK/C++/public/include/voltu/voltu.hpp | 6 +
SDK/C++/public/voltu.cpp | 6 +
SDK/C++/public/voltu_cv.cpp | 6 +
22 files changed, 227 insertions(+), 13 deletions(-)
create mode 100644 SDK/C++/public/LICENSE
create mode 100644 SDK/C++/public/README.md
diff --git a/SDK/C++/private/observer_impl.cpp b/SDK/C++/private/observer_impl.cpp
index abdd38f8f..8315df3d2 100644
--- a/SDK/C++/private/observer_impl.cpp
+++ b/SDK/C++/private/observer_impl.cpp
@@ -166,7 +166,7 @@ voltu::FramePtr ObserverImpl::getFrame()
voltu::PropertyPtr ObserverImpl::property(voltu::ObserverProperty)
{
- throw voltu::exceptions::InvalidProperty();
+ throw voltu::exceptions::NotImplemented();
}
std::shared_ptr<ftl::data::FrameSet> ObserverImpl::_makeFrameSet()
diff --git a/SDK/C++/public/LICENSE b/SDK/C++/public/LICENSE
new file mode 100644
index 000000000..2e5d48af4
--- /dev/null
+++ b/SDK/C++/public/LICENSE
@@ -0,0 +1,19 @@
+Copyright (c) 2020 Nicolas Pope
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
\ No newline at end of file
diff --git a/SDK/C++/public/README.md b/SDK/C++/public/README.md
new file mode 100644
index 000000000..980ab1abd
--- /dev/null
+++ b/SDK/C++/public/README.md
@@ -0,0 +1 @@
+# VolTu - Volumetric Capture SDK
\ No newline at end of file
diff --git a/SDK/C++/public/include/voltu/defines.hpp b/SDK/C++/public/include/voltu/defines.hpp
index 4f5ded24e..19f2416f2 100644
--- a/SDK/C++/public/include/voltu/defines.hpp
+++ b/SDK/C++/public/include/voltu/defines.hpp
@@ -1,3 +1,9 @@
+/**
+ * @file system.hpp
+ * @copyright Copyright (c) 2020 Sebastian Hahta, MIT License
+ * @author Sebastian Hahta
+ */
+
#pragma once
#ifndef PY_API
diff --git a/SDK/C++/public/include/voltu/feed.hpp b/SDK/C++/public/include/voltu/feed.hpp
index 0a19d3017..d863cf894 100644
--- a/SDK/C++/public/include/voltu/feed.hpp
+++ b/SDK/C++/public/include/voltu/feed.hpp
@@ -1,3 +1,9 @@
+/**
+ * @file feed.hpp
+ * @copyright Copyright (c) 2020 Nicolas Pope, MIT License
+ * @author Nicolas Pope
+ */
+
#pragma once
#include "defines.hpp"
diff --git a/SDK/C++/public/include/voltu/initialise.hpp b/SDK/C++/public/include/voltu/initialise.hpp
index e44799a67..aeae10f6c 100644
--- a/SDK/C++/public/include/voltu/initialise.hpp
+++ b/SDK/C++/public/include/voltu/initialise.hpp
@@ -1,3 +1,9 @@
+/**
+ * @file initialise.hpp
+ * @copyright Copyright (c) 2020 Nicolas Pope, MIT License
+ * @author Nicolas Pope
+ */
+
#pragma once
#include <memory>
#include <voltu/system.hpp>
diff --git a/SDK/C++/public/include/voltu/observer.hpp b/SDK/C++/public/include/voltu/observer.hpp
index f42ffaf9a..e5d99325f 100644
--- a/SDK/C++/public/include/voltu/observer.hpp
+++ b/SDK/C++/public/include/voltu/observer.hpp
@@ -1,3 +1,9 @@
+/**
+ * @file observer.hpp
+ * @copyright Copyright (c) 2020 Nicolas Pope, MIT License
+ * @author Nicolas Pope
+ */
+
#pragma once
#include "defines.hpp"
diff --git a/SDK/C++/public/include/voltu/opencv.hpp b/SDK/C++/public/include/voltu/opencv.hpp
index 467a793e8..7119cbc87 100644
--- a/SDK/C++/public/include/voltu/opencv.hpp
+++ b/SDK/C++/public/include/voltu/opencv.hpp
@@ -1,3 +1,9 @@
+/**
+ * @file opencv.hpp
+ * @copyright Copyright (c) 2020 Nicolas Pope, MIT License
+ * @author Nicolas Pope
+ */
+
#pragma once
#include <opencv2/core/mat.hpp>
diff --git a/SDK/C++/public/include/voltu/operator.hpp b/SDK/C++/public/include/voltu/operator.hpp
index a7f4ce996..5231efd17 100644
--- a/SDK/C++/public/include/voltu/operator.hpp
+++ b/SDK/C++/public/include/voltu/operator.hpp
@@ -1,3 +1,9 @@
+/**
+ * @file operator.hpp
+ * @copyright Copyright (c) 2020 Nicolas Pope, MIT License
+ * @author Nicolas Pope
+ */
+
#pragma once
#include <voltu/types/property.hpp>
diff --git a/SDK/C++/public/include/voltu/pipeline.hpp b/SDK/C++/public/include/voltu/pipeline.hpp
index c9894f063..c7531f1dc 100644
--- a/SDK/C++/public/include/voltu/pipeline.hpp
+++ b/SDK/C++/public/include/voltu/pipeline.hpp
@@ -1,3 +1,9 @@
+/**
+ * @file pipeline.hpp
+ * @copyright Copyright (c) 2020 Nicolas Pope, MIT License
+ * @author Nicolas Pope
+ */
+
#pragma once
#include <voltu/defines.hpp>
diff --git a/SDK/C++/public/include/voltu/room.hpp b/SDK/C++/public/include/voltu/room.hpp
index 4971439b8..28fd3ba62 100644
--- a/SDK/C++/public/include/voltu/room.hpp
+++ b/SDK/C++/public/include/voltu/room.hpp
@@ -1,3 +1,9 @@
+/**
+ * @file room.hpp
+ * @copyright Copyright (c) 2020 Nicolas Pope, MIT License
+ * @author Nicolas Pope
+ */
+
#pragma once
#include "defines.hpp"
diff --git a/SDK/C++/public/include/voltu/system.hpp b/SDK/C++/public/include/voltu/system.hpp
index 0f35bc88c..72e933bf3 100644
--- a/SDK/C++/public/include/voltu/system.hpp
+++ b/SDK/C++/public/include/voltu/system.hpp
@@ -1,3 +1,9 @@
+/**
+ * @file system.hpp
+ * @copyright Copyright (c) 2020 Nicolas Pope, MIT License
+ * @author Nicolas Pope
+ */
+
#pragma once
#include "defines.hpp"
@@ -6,47 +12,127 @@
#include <voltu/feed.hpp>
#include <voltu/pipeline.hpp>
#include <list>
+#include <string>
namespace voltu
{
+/**
+ * @brief Voltu semantic versioning information.
+ */
struct Version
{
- int major; // API Incompatible change
- int minor; // Possible binary incompatible, extensions
- int patch; // Internal only fixes.
+ int major; ///< API Incompatible change
+ int minor; ///< Possible binary incompatible, extensions
+ int patch; ///< Internal only fixes.
};
/**
- * Singleton Voltu system instance. Provides access to the key components such
- * as opening streams or files and creating virtual cameras.
+ * @brief Singleton Voltu system instance.
+ *
+ * Provides access to the key components such as opening streams or files and
+ * creating virtual cameras. Use `voltu::instance()` to obtain the object. All
+ * object instances in VolTu are managed by shared smart pointers.
*/
class System
{
public:
virtual ~System() = default;
- /** Get the semantic version information. */
+ /**
+ * @brief Get the semantic version information.
+ *
+ * @return Always returns semantic versioning structure.
+ */
virtual voltu::Version getVersion() const = 0;
- /** Make a virtual room or composite room. */
+ /**
+ * @brief Make a virtual room or composite room.
+ *
+ * @return A new virtual room instance.
+ */
PY_API virtual voltu::RoomPtr createRoom() = 0;
- /** Create a virtual observer. This renderers virtual camera views. */
+ /**
+ * @brief Create a virtual observer.
+ *
+ * An observer renderers virtual camera views, audio and other data from
+ * submitted framesets. It is possible and recommended that a single
+ * observer instance be used to renderer multiple different views, rather
+ * than creating lots of observers. This saves memory resources.
+ *
+ * @return A new observer instance.
+ */
PY_API virtual voltu::ObserverPtr createObserver() = 0;
- /** Open a file, device or network stream using a URI. */
+ /**
+ * @brief Open a file, device or network stream using a URI.
+ *
+ * All data sources in VolTu are represented by Universal Resource
+ * Identifiers (URIs), with some non-standard additions. A few examples
+ * are:
+ * * `file:///home/user/file.ftl`
+ * * `tcp://localhost:9001/*`
+ * * `ftl://my.stream.name/room1`
+ * * `ws://ftlab.utu.fi/lab/`
+ * * `./file.ftl`
+ * * `device:camera`
+ * * `device:screen`
+ *
+ * Note that returning from this call does not guarantee that the source
+ * is fully open and operational, this depends on network handshakes or
+ * file processing that occurs asynchronously.
+ *
+ * @throw voltu::exceptions::BadSourceURI If an unrecognised URI is given.
+ * @return A feed management object for the data source.
+ */
PY_API virtual voltu::FeedPtr open(const std::string &uri) = 0;
+ /**
+ * @brief Get a list of all available rooms.
+ *
+ * A room is a 3D captured physical space, or a combination of such spaces,
+ * and is represented by a unique identifier within the local system. This
+ * method obtains a list of all available rooms from all sources. To obtain
+ * rooms, either use `open` or `createRoom`.
+ *
+ * @return A list of room ids, which can be empty.
+ *
+ * @see getRoom
+ * @see open
+ */
PY_API virtual std::list<voltu::RoomId> listRooms() = 0;
+ /**
+ * @brief Get a room instance from identifier.
+ *
+ * A room instance enables access to all data frames associated with that
+ * room, including image data. Calling `getRoom` with the same ID
+ * multiple times will return different smart pointers to room instances
+ * but provides access to the same data regardless and is valid. An invalid
+ * room ID will throw an exception.
+ *
+ * @throw voltu::exceptions::InvalidRoomId If the ID does not exist.
+ * @return Room instance or accessing room data.
+ */
PY_API virtual voltu::RoomPtr getRoom(voltu::RoomId room) = 0;
/** Make a file or streaming feed, to which you can send frames. */
PY_API virtual voltu::FeedPtr createFeed(const std::string &uri) = 0;
- /** Make an empty operator pipeline for frame processing. */
+ /**
+ * @brief Make an empty operator pipeline for frame processing.
+ *
+ * A pipeline allows a sequence of processing operations to be applied to
+ * a data frame. These operations include stereo correspondence, fusion,
+ * data evaluation and various image processing operations. Only some
+ * of these operators are exposed in the SDK. Once a pipeline instance
+ * is obtained, you can add specific operators to it, configure them and
+ * then submit frames from processing.
+ *
+ * @return A unique pipeline instance.
+ */
PY_API virtual voltu::PipelinePtr createPipeline() = 0;
};
-}
+} // namespace voltu
diff --git a/SDK/C++/public/include/voltu/types/channel.hpp b/SDK/C++/public/include/voltu/types/channel.hpp
index 07b7c9aba..e9e86324e 100644
--- a/SDK/C++/public/include/voltu/types/channel.hpp
+++ b/SDK/C++/public/include/voltu/types/channel.hpp
@@ -1,3 +1,9 @@
+/**
+ * @file channel.hpp
+ * @copyright Copyright (c) 2020 Nicolas Pope, MIT License
+ * @author Nicolas Pope
+ */
+
#pragma once
namespace voltu {
diff --git a/SDK/C++/public/include/voltu/types/errors.hpp b/SDK/C++/public/include/voltu/types/errors.hpp
index bbb8be620..a69e97630 100644
--- a/SDK/C++/public/include/voltu/types/errors.hpp
+++ b/SDK/C++/public/include/voltu/types/errors.hpp
@@ -1,3 +1,9 @@
+/**
+ * @file errors.hpp
+ * @copyright Copyright (c) 2020 Nicolas Pope, MIT License
+ * @author Nicolas Pope
+ */
+
#pragma once
#include <exception>
@@ -30,7 +36,7 @@ VOLTU_EXCEPTION(LibraryVersionMismatch, Exception, "Wrong version of library fou
VOLTU_EXCEPTION(BadSourceURI, Exception, "Bad source URI");
VOLTU_EXCEPTION(InvalidFrameObject, Exception, "Invalid Frame object");
VOLTU_EXCEPTION(InternalRenderError, Exception, "Internal renderer error");
-VOLTU_EXCEPTION(InvalidProperty, Exception, "Unknown property enum");
+VOLTU_EXCEPTION(InvalidRoomId, Exception, "Room identifier does not exist");
VOLTU_EXCEPTION(PropertyUnavailable, Exception, "Property currently not available");
VOLTU_EXCEPTION(BadPropertyName, Exception, "Not a valid property name");
VOLTU_EXCEPTION(BadPropertyType, Exception, "Incorrect property data type");
diff --git a/SDK/C++/public/include/voltu/types/frame.hpp b/SDK/C++/public/include/voltu/types/frame.hpp
index eebc557ea..4209cc80c 100644
--- a/SDK/C++/public/include/voltu/types/frame.hpp
+++ b/SDK/C++/public/include/voltu/types/frame.hpp
@@ -1,3 +1,9 @@
+/**
+ * @file frame.hpp
+ * @copyright Copyright (c) 2020 Nicolas Pope, MIT License
+ * @author Nicolas Pope
+ */
+
#pragma once
#include "../defines.hpp"
diff --git a/SDK/C++/public/include/voltu/types/image.hpp b/SDK/C++/public/include/voltu/types/image.hpp
index 406c81df8..c9c342f27 100644
--- a/SDK/C++/public/include/voltu/types/image.hpp
+++ b/SDK/C++/public/include/voltu/types/image.hpp
@@ -1,3 +1,9 @@
+/**
+ * @file image.hpp
+ * @copyright Copyright (c) 2020 Nicolas Pope, MIT License
+ * @author Nicolas Pope
+ */
+
#pragma once
#include "../defines.hpp"
diff --git a/SDK/C++/public/include/voltu/types/intrinsics.hpp b/SDK/C++/public/include/voltu/types/intrinsics.hpp
index 70d1dfe2c..cc4ee4caa 100644
--- a/SDK/C++/public/include/voltu/types/intrinsics.hpp
+++ b/SDK/C++/public/include/voltu/types/intrinsics.hpp
@@ -1,3 +1,9 @@
+/**
+ * @file intrinsics.hpp
+ * @copyright Copyright (c) 2020 Nicolas Pope, MIT License
+ * @author Nicolas Pope
+ */
+
#pragma once
namespace voltu
diff --git a/SDK/C++/public/include/voltu/types/pointcloud.hpp b/SDK/C++/public/include/voltu/types/pointcloud.hpp
index c602a4f6a..8ea53712a 100644
--- a/SDK/C++/public/include/voltu/types/pointcloud.hpp
+++ b/SDK/C++/public/include/voltu/types/pointcloud.hpp
@@ -1,3 +1,9 @@
+/**
+ * @file pointcloud.hpp
+ * @copyright Copyright (c) 2020 Nicolas Pope, MIT License
+ * @author Nicolas Pope
+ */
+
#pragma once
#include <memory>
diff --git a/SDK/C++/public/include/voltu/types/property.hpp b/SDK/C++/public/include/voltu/types/property.hpp
index 2a5fbe53c..f2f781b94 100644
--- a/SDK/C++/public/include/voltu/types/property.hpp
+++ b/SDK/C++/public/include/voltu/types/property.hpp
@@ -1,3 +1,9 @@
+/**
+ * @file property.hpp
+ * @copyright Copyright (c) 2020 Nicolas Pope, MIT License
+ * @author Nicolas Pope
+ */
+
#pragma once
#include "../defines.hpp"
diff --git a/SDK/C++/public/include/voltu/voltu.hpp b/SDK/C++/public/include/voltu/voltu.hpp
index 17f251ed5..a2c4c0a14 100644
--- a/SDK/C++/public/include/voltu/voltu.hpp
+++ b/SDK/C++/public/include/voltu/voltu.hpp
@@ -1,3 +1,9 @@
+/**
+ * @file voltu.hpp
+ * @copyright Copyright (c) 2020 Nicolas Pope, MIT License
+ * @author Nicolas Pope
+ */
+
#pragma once
// Bump these for each release
diff --git a/SDK/C++/public/voltu.cpp b/SDK/C++/public/voltu.cpp
index 25b0f4019..4aef0ba97 100644
--- a/SDK/C++/public/voltu.cpp
+++ b/SDK/C++/public/voltu.cpp
@@ -1,3 +1,9 @@
+/**
+ * @file voltu.cpp
+ * @copyright Copyright (c) 2020 Nicolas Pope, MIT License
+ * @author Nicolas Pope
+ */
+
#include <voltu/initialise.hpp>
#include <voltu/types/errors.hpp>
#include <voltu/voltu.hpp>
diff --git a/SDK/C++/public/voltu_cv.cpp b/SDK/C++/public/voltu_cv.cpp
index 0fae30711..31cd29aa6 100644
--- a/SDK/C++/public/voltu_cv.cpp
+++ b/SDK/C++/public/voltu_cv.cpp
@@ -1,3 +1,9 @@
+/**
+ * @file voltu_cv.cpp
+ * @copyright Copyright (c) 2020 Nicolas Pope, MIT License
+ * @author Nicolas Pope
+ */
+
#include <voltu/opencv.hpp>
#include <voltu/types/errors.hpp>
--
GitLab