tami/MYNT-EYE-S-SDK
6
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update doc comments

Browse Source
This commit is contained in:
John Zhao 2018-05-16 10:31:31 +08:00
parent de0f0d0639
commit dd2fc88846
11 changed files with 420 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/zh-Hans/api.doxyfile
View File

@ -2100,7 +2100,9 @@ INCLUDE_FILE_PATTERNS =
# recursively expanded use the := operator instead of the = operator.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
PREDEFINED = DOXYGEN_WORKING
PREDEFINED = DOXYGEN_WORKING \
"MYNTEYE_BEGIN_NAMESPACE=namespace mynteye {" \
"MYNTEYE_END_NAMESPACE=}"
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
# tag can be used to specify a list of macro names that should be expanded. The

28
include/mynteye/callbacks.h
View File

@ -29,13 +29,23 @@ MYNTEYE_BEGIN_NAMESPACE
namespace device {
/**
* @ingroup datatypes
* Frame with raw data.
*/
class MYNTEYE_API Frame {
public:
using data_t = std::vector<std::uint8_t>;
/**
* Construct the frame with StreamRequest and raw data.
*/
Frame(const StreamRequest &request, const void *data)
: Frame(request.width, request.height, request.format, data) {}
/**
* Construct the frame with stream info and raw data.
*/
Frame(
std::uint16_t width, std::uint16_t height, Format format,
const void *data)
@ -49,30 +59,37 @@ class MYNTEYE_API Frame {
}
}
/** Get the width. */
std::uint16_t width() const {
return width_;
}
/** Get the height. */
std::uint16_t height() const {
return height_;
}
/** Get the format. */
Format format() const {
return format_;
}
/** Get the data. */
std::uint8_t *data() {
return data_.data();
}
/** Get the const data. */
const std::uint8_t *data() const {
return data_.data();
}
/** Get the size of data. */
std::size_t size() const {
return data_.size();
}
/** Clone a new frame. */
Frame clone() const {
Frame frame(width_, height_, format_, nullptr);
std::copy(data_.begin(), data_.end(), frame.data_.begin());
@ -87,12 +104,23 @@ class MYNTEYE_API Frame {
data_t data_;
};
/**
* @ingroup datatypes
* Device stream data.
*/
struct MYNTEYE_API StreamData {
/** ImgData. */
std::shared_ptr<ImgData> img;
/** Frame. */
std::shared_ptr<Frame> frame;
};
/**
* @ingroup datatypes
* Device motion data.
*/
struct MYNTEYE_API MotionData {
/** ImuData. */
std::shared_ptr<ImuData> imu;
};

8
include/mynteye/glog_init.h
View File

@ -17,8 +17,14 @@
#include <glog/logging.h>
/** Helper to init glog with args. */
struct glog_init {
glog_init(int /*argc*/, char *argv[]) {
/**
* Init glog with args in constructor, and shutdown it in destructor.
*/
glog_init(int argc, char *argv[]) {
(void)argc;
// FLAGS_logtostderr = true;
FLAGS_alsologtostderr = true;
FLAGS_colorlogtostderr = true;

118
include/mynteye/types.h
View File

@ -72,21 +72,21 @@ enum class Stream : std::uint8_t {
* might provide.
*/
enum class Capabilities : std::uint8_t {
/** Provices stereo stream */
/** Provides stereo stream */
STEREO,
/** Provices color stream */
/** Provides color stream */
COLOR,
/** Provices depth stream */
/** Provides depth stream */
DEPTH,
/** Provices point cloud stream */
/** Provides point cloud stream */
POINTS,
/** Provices fisheye stream */
/** Provides fisheye stream */
FISHEYE,
/** Provices infrared stream */
/** Provides infrared stream */
INFRARED,
/** Provices second infrared stream */
/** Provides second infrared stream */
INFRARED2,
/** Provices IMU (accelerometer, gyroscope) data */
/** Provides IMU (accelerometer, gyroscope) data */
IMU,
/** Last guard */
LAST
@ -123,15 +123,35 @@ enum class Info : std::uint8_t {
* @brief Camera control options define general configuration controls.
*/
enum class Option : std::uint8_t {
/** Image gain, setting it if manual-exposure */
/**
* Image gain, valid if manual-exposure
*
* range: [0,48], default: 24
*/
GAIN,
/** Image brightness, setting it if manual-exposure */
/**
* Image brightness, valid if manual-exposure
*
* range: [0,240], default: 120
*/
BRIGHTNESS,
/** Image contrast */
/**
* Image contrast, valid if manual-exposure
*
* range: [0,255], default: 127
*/
CONTRAST,
/** Image frame rate, must set IMU_FREQUENCY together */
/**
* Image frame rate, must set IMU_FREQUENCY together
*
* values: {10,15,20,25,30,35,40,45,50,55,60}, default: 25
*/
FRAME_RATE,
/** IMU frequency, must set FRAME_RATE together */
/**
* IMU frequency, must set FRAME_RATE together
*
* values: {100,200,250,333,500}, default: 200
*/
IMU_FREQUENCY,
/**
* Exposure mode
@ -140,13 +160,29 @@ enum class Option : std::uint8_t {
* 1: disable auto-exposure (manual-exposure)
*/
EXPOSURE_MODE,
/** Max gain, setting it if auto-exposure */
/**
* Max gain, valid if auto-exposure
*
* range: [0,48], default: 48
*/
MAX_GAIN,
/** Max exposure time, setting it if auto-exposure */
/**
* Max exposure time, valid if auto-exposure
*
* range: [0,240], default: 240
*/
MAX_EXPOSURE_TIME,
/** Desired brightness */
/**
* Desired brightness, valid if auto-exposure
*
* range: [0,255], default: 192
*/
DESIRED_BRIGHTNESS,
/** IR control */
/**
* IR control
*
* range: [0,160], default: 0
*/
IR_CONTROL,
/**
* HDR mode
@ -248,13 +284,13 @@ MYNTEYE_API std::size_t bytes_per_pixel(const Format &value);
* Stream request.
*/
struct MYNTEYE_API StreamRequest {
/** width in pixels */
/** Stream width in pixels */
std::uint16_t width;
/** height in pixels */
/** Stream height in pixels */
std::uint16_t height;
/** stream pixel format */
/** Stream pixel format */
Format format;
/** frames per second (unused) */
/** Stream frames per second (unused) */
std::uint16_t fps;
bool operator==(const StreamRequest &other) const {
@ -279,21 +315,21 @@ std::ostream &operator<<(std::ostream &os, const StreamRequest &request);
* Stream intrinsics,
*/
struct MYNTEYE_API Intrinsics {
/** width of the image in pixels */
/** The width of the image in pixels */
std::uint16_t width;
/** height of the image in pixels */
/** The height of the image in pixels */
std::uint16_t height;
/** focal length of the image plane, as a multiple of pixel width */
/** The focal length of the image plane, as a multiple of pixel width */
double fx;
/** focal length of the image plane, as a multiple of pixel height */
/** The focal length of the image plane, as a multiple of pixel height */
double fy;
/** horizontal coordinate of the principal point of the image */
/** The horizontal coordinate of the principal point of the image */
double cx;
/** vertical coordinate of the principal point of the image */
/** The vertical coordinate of the principal point of the image */
double cy;
/** distortion model of the image */
/** The distortion model of the image */
std::uint8_t model;
/** distortion coefficients: k1,k2,p1,p2,k3 */
/** The distortion coefficients: k1,k2,p1,p2,k3 */
double coeffs[5];
};
@ -306,9 +342,12 @@ std::ostream &operator<<(std::ostream &os, const Intrinsics &in);
*/
struct MYNTEYE_API ImuIntrinsics {
/**
* Scale X cross axis cross axis
* cross axis Scale Y cross axis
* cross axis cross axis Scale Z
* Scale matrix.
* \code
* Scale X cross axis cross axis
* cross axis Scale Y cross axis
* cross axis cross axis Scale Z
* \endcode
*/
double scale[3][3];
/* Zero-drift: X, Y, Z */
@ -328,8 +367,8 @@ std::ostream &operator<<(std::ostream &os, const ImuIntrinsics &in);
* Motion intrinsics, including accelerometer and gyroscope.
*/
struct MYNTEYE_API MotionIntrinsics {
ImuIntrinsics accel;
ImuIntrinsics gyro;
ImuIntrinsics accel; /**< Accelerometer intrinsics */
ImuIntrinsics gyro; /**< Gyroscope intrinsics */
};
MYNTEYE_API
@ -340,9 +379,13 @@ std::ostream &operator<<(std::ostream &os, const MotionIntrinsics &in);
* Extrinsics, represent how the different datas are connected.
*/
struct MYNTEYE_API Extrinsics {
double rotation[3][3]; /**< rotation matrix */
double translation[3]; /**< translation vector */
double rotation[3][3]; /**< Rotation matrix */
double translation[3]; /**< Translation vector */
/**
* Inverse this extrinsics.
* @return the inversed extrinsics.
*/
Extrinsics Inverse() const {
return {{{rotation[0][0], rotation[1][0], rotation[2][0]},
{rotation[0][1], rotation[1][1], rotation[2][1]},
@ -427,8 +470,11 @@ struct MYNTEYE_API ImuData {
* Option info.
*/
struct MYNTEYE_API OptionInfo {
/** Minimum value */
std::int32_t min;
/** Maximum value */
std::int32_t max;
/** Default value */
std::int32_t def;
};

10
include/mynteye/utils.h
View File

@ -21,12 +21,19 @@
MYNTEYE_BEGIN_NAMESPACE
/**
* @defgroup utils Utiliities
*/
class Device;
namespace device {
/**
* @ingroup utils
*
* Detecting MYNT EYE devices and prompt user to select one.
*
* @return the selected device, or `nullptr` if none.
*/
MYNTEYE_API std::shared_ptr<Device> select();
@ -36,7 +43,10 @@ MYNTEYE_API std::shared_ptr<Device> select();
namespace utils {
/**
* @ingroup utils
*
* Get real exposure time in ms from virtual value, according to its frame rate.
*
* @param frame_rate the frame rate of the device.
* @param exposure_time the virtual exposure time.
* @return the real exposure time in ms, or the virtual value if frame rate is

113
src/api/api.h
View File

@ -32,20 +32,36 @@ class Synthetic;
namespace api {
/**
* @ingroup datatypes
* API stream data.
*/
struct MYNTEYE_API StreamData {
/** ImgData. */
std::shared_ptr<ImgData> img;
/** Frame. */
cv::Mat frame;
};
/**
* @ingroup datatypes
* API motion data.
*/
struct MYNTEYE_API MotionData {
/** ImuData. */
std::shared_ptr<ImuData> imu;
};
} // namespace api
/**
* The API class to communicate with MYNT® EYE device.
*/
class MYNTEYE_API API {
public:
/** The api::StreamData callback. */
using stream_callback_t = std::function<void(const api::StreamData &data)>;
/** The api::MotionData callback. */
using motion_callback_t = std::function<void(const api::MotionData &data)>;
explicit API(std::shared_ptr<Device> device);
@ -83,54 +99,151 @@ class MYNTEYE_API API {
static std::shared_ptr<API> Create(
int argc, char *argv[], std::shared_ptr<Device> device);
/**
* Get the model.
*/
Model GetModel() const;
/**
* Supports the stream or not.
*/
bool Supports(const Stream &stream) const;
/**
* Supports the capability or not.
*/
bool Supports(const Capabilities &capability) const;
/**
* Supports the option or not.
*/
bool Supports(const Option &option) const;
/**
* Supports the addon or not.
*/
bool Supports(const AddOns &addon) const;
/**
* Get all stream requests of the capability.
*/
const std::vector<StreamRequest> &GetStreamRequests(
const Capabilities &capability) const;
/**
* Config the stream request to the capability.
*/
void ConfigStreamRequest(
const Capabilities &capability, const StreamRequest &request);
/**
* Get the device info.
*/
std::string GetInfo(const Info &info) const;
/**
* Get the intrinsics of stream.
*/
Intrinsics GetIntrinsics(const Stream &stream) const;
/**
* Get the extrinsics from one stream to another.
*/
Extrinsics GetExtrinsics(const Stream &from, const Stream &to) const;
/**
* Get the intrinsics of motion.
*/
MotionIntrinsics GetMotionIntrinsics() const;
/**
* Get the extrinsics from one stream to motion.
*/
Extrinsics GetMotionExtrinsics(const Stream &from) const;
/**
* Log all option infos.
*/
void LogOptionInfos() const;
/**
* Get the option info.
*/
OptionInfo GetOptionInfo(const Option &option) const;
/**
* Get the option value.
*/
std::int32_t GetOptionValue(const Option &option) const;
/**
* Set the option value.
*/
void SetOptionValue(const Option &option, std::int32_t value);
/**
* Run the option action.
*/
bool RunOptionAction(const Option &option) const;
/**
* Set the callback of stream.
*/
void SetStreamCallback(const Stream &stream, stream_callback_t callback);
/**
* Set the callback of motion.
*/
void SetMotionCallback(motion_callback_t callback);
/**
* Has the callback of stream.
*/
bool HasStreamCallback(const Stream &stream) const;
/**
* Has the callback of motion.
*/
bool HasMotionCallback() const;
/**
* Start capturing the source.
*/
void Start(const Source &source);
/**
* Stop capturing the source.
*/
void Stop(const Source &source);
/**
* Wait the streams are ready.
*/
void WaitForStreams();
/**
* Enable the data of stream.
* @note must enable the stream if it's a synthetic one. This means the stream
* in not native, the device has the capability to provide this stream, but
* still support this stream.
*/
void EnableStreamData(const Stream &stream);
/**
* Disable the data of stream.
*/
void DisableStreamData(const Stream &stream);
/**
* Get the datas of stream.
* @note default cache 4 datas at most.
*/
api::StreamData GetStreamData(const Stream &stream);
/**
* Get the latest data of stream.
*/
std::vector<api::StreamData> GetStreamDatas(const Stream &stream);
/**
* Enable cache motion datas.
*/
void EnableMotionDatas(
std::size_t max_size = std::numeric_limits<std::size_t>::max());
/**
* Get the motion datas.
*/
std::vector<api::MotionData> GetMotionDatas();
/**
* Enable the plugin.
*/
void EnablePlugin(const std::string &path);
std::shared_ptr<Device> device();

46
src/api/plugin.h
View File

@ -30,27 +30,52 @@ MYNTEYE_BEGIN_NAMESPACE
class API;
class Object;
/**
* The plugin which could implement processing by yourself.
*/
class MYNTEYE_API Plugin {
public:
Plugin() = default;
virtual ~Plugin() = 0;
/**
* Called when plugin created.
* @param api the API instacne.
*/
virtual void OnCreate(API *api) {
api_ = api;
}
/**
* Called when process rectify.
* @param in input object.
* @param out output object.
* @return `true` if you process rectify.
*/
virtual bool OnRectifyProcess(Object *const in, Object *const out) {
UNUSED(in)
UNUSED(out)
return false;
}
/**
* Called when process disparity.
* @param in input object.
* @param out output object.
* @return `true` if you process disparity.
*/
virtual bool OnDisparityProcess(Object *const in, Object *const out) {
UNUSED(in)
UNUSED(out)
return false;
}
/**
* Called when process normalized disparity.
* @param in input object.
* @param out output object.
* @return `true` if you process normalized disparity.
*/
virtual bool OnDisparityNormalizedProcess(
Object *const in, Object *const out) {
UNUSED(in)
@ -58,12 +83,24 @@ class MYNTEYE_API Plugin {
return false;
}
/**
* Called when process points.
* @param in input object.
* @param out output object.
* @return `true` if you process points.
*/
virtual bool OnPointsProcess(Object *const in, Object *const out) {
UNUSED(in)
UNUSED(out)
return false;
}
/**
* Called when process depth.
* @param in input object.
* @param out output object.
* @return `true` if you process depth.
*/
virtual bool OnDepthProcess(Object *const in, Object *const out) {
UNUSED(in)
UNUSED(out)
@ -84,10 +121,19 @@ MYNTEYE_END_NAMESPACE
extern "C" {
/**
* Get the plugin version code.
*/
MYNTEYE_API std::uint32_t plugin_version_code();
/**
* Create the plugin.
*/
MYNTEYE_API mynteye::Plugin *plugin_create();
/**
* Destroy the plugin.
*/
MYNTEYE_API void plugin_destroy(mynteye::Plugin *plugin);
}

12
src/api/processor/object.h
View File

@ -30,21 +30,27 @@ struct MYNTEYE_API Object {
virtual Object *Clone() const = 0;
/** Cast the obj to T pointer */
template <typename T>
static T *Cast(Object *obj) {
return dynamic_cast<T *>(obj);
}
/** Cast the obj to const T pointer */
template <typename T>
static const T *Cast(const Object *obj) {
return dynamic_cast<const T *>(obj);
}
};
/**
* Input & output object of one cv::Mat.
*/
struct MYNTEYE_API ObjMat : public Object {
ObjMat() = default;
explicit ObjMat(const cv::Mat &value) : value(value) {}
/** The value */
cv::Mat value;
Object *Clone() const {
@ -54,12 +60,18 @@ struct MYNTEYE_API ObjMat : public Object {
}
};
/**
* Input & output object of two cv::Mat.
*/
struct MYNTEYE_API ObjMat2 : public Object {
ObjMat2() = default;
ObjMat2(const cv::Mat &first, const cv::Mat &second)
: first(first), second(second) {}
/** The first value */
cv::Mat first;
/** The second value */
cv::Mat second;
Object *Clone() const {

7
src/device/context.h
View File

@ -30,11 +30,18 @@ struct context;
class Device;
/**
* The context about devices.
*/
class MYNTEYE_API Context {
public:
Context();
~Context();
/**
* Get all devices now.
* @return a vector of all devices.
*/
std::vector<std::shared_ptr<Device>> devices() const {
return devices_;
}

111
src/device/device.h
View File

@ -47,9 +47,14 @@ class Channels;
class Motions;
class Streams;
/**
* The Device class to communicate with MYNT® EYE device.
*/
class MYNTEYE_API Device {
public:
/** The device::StreamData callback. */
using stream_callback_t = device::StreamCallback;
/** The device::MotionData callback. */
using motion_callback_t = device::MotionCallback;
using stream_callbacks_t = std::map<Stream, stream_callback_t>;
@ -57,61 +62,167 @@ class MYNTEYE_API Device {
Device(const Model &model, std::shared_ptr<uvc::device> device);
virtual ~Device();
/**
* Create the Device instance.
* @param name the device name.
* @param device the device from uvc.
* @return the Device instance.
*/
static std::shared_ptr<Device> Create(
const std::string &name, std::shared_ptr<uvc::device> device);
/**
* Get the model.
*/
Model GetModel() const {
return model_;
}
/**
* Supports the stream or not.
*/
bool Supports(const Stream &stream) const;
/**
* Supports the capability or not.
*/
bool Supports(const Capabilities &capability) const;
/**
* Supports the option or not.
*/
bool Supports(const Option &option) const;
/**
* Supports the addon or not.
*/
bool Supports(const AddOns &addon) const;
/**
* Get all stream requests of the capability.
*/
const std::vector<StreamRequest> &GetStreamRequests(
const Capabilities &capability) const;
/**
* Config the stream request to the capability.
*/
void ConfigStreamRequest(
const Capabilities &capability, const StreamRequest &request);
/**
* Get the device info.
*/
std::shared_ptr<DeviceInfo> GetInfo() const;
/**
* Get the device info of a field.
*/
std::string GetInfo(const Info &info) const;
/**
* Get the intrinsics of stream.
*/
Intrinsics GetIntrinsics(const Stream &stream) const;
/**
* Get the extrinsics from one stream to another.
*/
Extrinsics GetExtrinsics(const Stream &from, const Stream &to) const;
/**
* Get the intrinsics of motion.
*/
MotionIntrinsics GetMotionIntrinsics() const;
/**
* Get the extrinsics from one stream to motion.
*/
Extrinsics GetMotionExtrinsics(const Stream &from) const;
/**
* Set the intrinsics of stream.
*/
void SetIntrinsics(const Stream &stream, const Intrinsics &in);
/**
* Set the extrinsics from one stream to another.
*/
void SetExtrinsics(
const Stream &from, const Stream &to, const Extrinsics &ex);
/**
* Set the intrinsics of motion.
*/
void SetMotionIntrinsics(const MotionIntrinsics &in);
/**
* Set the extrinsics from one stream to motion.
*/
void SetMotionExtrinsics(const Stream &from, const Extrinsics &ex);
/**
* Log all option infos.
*/
void LogOptionInfos() const;
/**
* Get the option info.
*/
OptionInfo GetOptionInfo(const Option &option) const;
/**
* Get the option value.
*/
std::int32_t GetOptionValue(const Option &option) const;
/**
* Set the option value.
*/
void SetOptionValue(const Option &option, std::int32_t value);
/**
* Run the option action.
*/
bool RunOptionAction(const Option &option) const;
/**
* Set the callback of stream.
*/
void SetStreamCallback(const Stream &stream, stream_callback_t callback);
/**
* Set the callback of motion.
*/
void SetMotionCallback(motion_callback_t callback);
/**
* Has the callback of stream.
*/
bool HasStreamCallback(const Stream &stream) const;
/**
* Has the callback of motion.
*/
bool HasMotionCallback() const;
/**
* Start capturing the source.
*/
virtual void Start(const Source &source);
/**
* Stop capturing the source.
*/
virtual void Stop(const Source &source);
/**
* Wait the streams are ready.
*/
void WaitForStreams();
/**
* Get the datas of stream.
* @note default cache 4 datas at most.
*/
std::vector<device::StreamData> GetStreamDatas(const Stream &stream);
/**
* Get the latest data of stream.
*/
device::StreamData GetLatestStreamData(const Stream &stream);
/**
* Enable cache motion datas.
*/
void EnableMotionDatas(
std::size_t max_size = std::numeric_limits<std::size_t>::max());
/**
* Get the motion datas.
*/
std::vector<device::MotionData> GetMotionDatas();
protected:

1
src/internal/strings.h
View File

@ -24,6 +24,7 @@
MYNTEYE_BEGIN_NAMESPACE
/** The strings error */
class MYNTEYE_API strings_error : public std::runtime_error {
public:
explicit strings_error(const std::string &what_arg) noexcept