Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add comprehensive documentation to Python via sphinx #3993

Merged
merged 16 commits into from
May 19, 2019
Merged

Add comprehensive documentation to Python via sphinx #3993

Show file tree
Hide file tree
Changes from 12 commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
3183f19
[python] add docstrings to enums
Mar 28, 2019
8cedaa0
[docs] lots of work on python docs, some edits in C++ docs too. Minor…
Apr 18, 2019
35c0247
More python doc work
Apr 21, 2019
e270d4d
[python] Move away from deprecated placement-new style init functions
Jan 30, 2019
0ccb2c9
More updates to python docs
Apr 21, 2019
d8d2fe6
More updates to python docs
Apr 21, 2019
28d3f76
pydocs: up to sensor.hpp
Apr 22, 2019
73cd903
[python] Restore gil release on sensor::stop
Apr 22, 2019
58195df
Pydocs: up to pipeline.hpp
Apr 22, 2019
0d50c03
Complete updating python documentation
May 16, 2019
31c18a3
replace backslash with forward slash in python documentation
May 16, 2019
f25f93c
Make python html doc generation work
May 16, 2019
4cbd27e
Update sphinx generation because github pages doesn't like directorie…
May 16, 2019
4b489cf
Correct way to make sphinx documentation work is add .nojekyll file t…
May 19, 2019
24516b3
Fix grammar per @bfulkers-i's instructions
May 19, 2019
0ce699e
Add additional changes clarified by #ev-mp
May 19, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion include/librealsense2/h/rs_frame.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ typedef enum rs2_timestamp_domain
} rs2_timestamp_domain;
const char* rs2_timestamp_domain_to_string(rs2_timestamp_domain info);

/** \brief Per-Frame-Metadata are set of read-only properties that might be exposed for each individual frame */
/** \brief Per-Frame-Metadata is the set of read-only properties that might be exposed for each individual frame. */
typedef enum rs2_frame_metadata_value
{
RS2_FRAME_METADATA_FRAME_COUNTER , /**< A sequential index managed per-stream. Integer value*/
Expand Down
6 changes: 3 additions & 3 deletions include/librealsense2/h/rs_sensor.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ typedef enum rs2_camera_info {
} rs2_camera_info;
const char* rs2_camera_info_to_string(rs2_camera_info info);

/** \brief Streams are different types of data provided by RealSense devices */
/** \brief Streams are different types of data provided by RealSense devices. */
typedef enum rs2_stream
{
RS2_STREAM_ANY,
Expand All @@ -51,7 +51,7 @@ typedef enum rs2_stream
} rs2_stream;
const char* rs2_stream_to_string(rs2_stream stream);

/** \brief Format identifies how binary data is encoded within a frame */
/** \brief A stream's format identifies how binary data is encoded within a frame. */
typedef enum rs2_format
{
RS2_FORMAT_ANY , /**< When passed to enable stream, librealsense will try to provide best suited format */
Expand Down Expand Up @@ -79,7 +79,7 @@ typedef enum rs2_format
} rs2_format;
const char* rs2_format_to_string(rs2_format format);

/** \brief Cross-stream extrinsics: encode the topology describing how the different devices are connected. */
/** \brief Cross-stream extrinsics: encodes the topology describing how the different devices are oriented. */
typedef struct rs2_extrinsics
{
float rotation[9]; /**< Column-major 3x3 rotation matrix */
Expand Down
16 changes: 8 additions & 8 deletions include/librealsense2/h/rs_types.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
extern "C" {
#endif

/** \brief Category of the librealsense notifications */
/** \brief Category of the librealsense notification. */
typedef enum rs2_notification_category{
RS2_NOTIFICATION_CATEGORY_FRAMES_TIMEOUT, /**< Frames didn't arrived within 5 seconds */
RS2_NOTIFICATION_CATEGORY_FRAME_CORRUPTED, /**< Received partial/incomplete frame */
Expand All @@ -25,7 +25,7 @@ typedef enum rs2_notification_category{
} rs2_notification_category;
const char* rs2_notification_category_to_string(rs2_notification_category category);

/** \brief Exception types are the different categories of errors that RealSense API might return */
/** \brief Exception types are the different categories of errors that RealSense API might return. */
typedef enum rs2_exception_type
{
RS2_EXCEPTION_TYPE_UNKNOWN,
Expand Down Expand Up @@ -53,7 +53,7 @@ typedef enum rs2_distortion
} rs2_distortion;
const char* rs2_distortion_to_string(rs2_distortion distortion);

/** \brief Video stream intrinsics */
/** \brief Video stream intrinsics. */
typedef struct rs2_intrinsics
{
int width; /**< Width of the image in pixels */
Expand All @@ -66,7 +66,7 @@ typedef struct rs2_intrinsics
float coeffs[5]; /**< Distortion coefficients, order: k1, k2, p1, p2, k3 */
} rs2_intrinsics;

/** \brief Motion device intrinsics: scale, bias, and variances */
/** \brief Motion device intrinsics: scale, bias, and variances. */
typedef struct rs2_motion_device_intrinsic
{
/* \internal
Expand Down Expand Up @@ -112,11 +112,11 @@ typedef struct rs2_pose
rs2_quaternion rotation; /**< Qi, Qj, Qk, Qr components of rotation as represented in quaternion rotation (relative to initial position) */
rs2_vector angular_velocity; /**< X, Y, Z values of angular velocity, in radians/sec */
rs2_vector angular_acceleration; /**< X, Y, Z values of angular acceleration, in radians/sec^2 */
unsigned int tracker_confidence; /**< pose data confidence 0x0 - Failed, 0x1 - Low, 0x2 - Medium, 0x3 - High */
unsigned int mapper_confidence; /**< pose data confidence 0x0 - Failed, 0x1 - Low, 0x2 - Medium, 0x3 - High */
unsigned int tracker_confidence; /**< Pose data confidence 0x0 - Failed, 0x1 - Low, 0x2 - Medium, 0x3 - High */
lramati marked this conversation as resolved.
Show resolved Hide resolved
unsigned int mapper_confidence; /**< Pose data confidence 0x0 - Failed, 0x1 - Low, 0x2 - Medium, 0x3 - High */
lramati marked this conversation as resolved.
Show resolved Hide resolved
} rs2_pose;

/** \brief Severity of the librealsense logger */
/** \brief Severity of the librealsense logger. */
typedef enum rs2_log_severity {
RS2_LOG_SEVERITY_DEBUG, /**< Detailed information about ordinary operations */
RS2_LOG_SEVERITY_INFO , /**< Terse information about ordinary operations */
Expand All @@ -128,7 +128,7 @@ typedef enum rs2_log_severity {
} rs2_log_severity;
const char* rs2_log_severity_to_string(rs2_log_severity info);

/** \brief Specifies advanced interfaces (capabilities) objects may implement */
/** \brief Specifies advanced interfaces (capabilities) objects may implement. */
typedef enum rs2_extension
{
RS2_EXTENSION_UNKNOWN,
Expand Down
4 changes: 2 additions & 2 deletions include/librealsense2/hpp/rs_context.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ namespace rs2
:_removed(removed), _added(added) {}

/**
* check if specific device was disconnected
* check if a specific device was disconnected
* \return true if device disconnected, false if device connected
*/
bool was_removed(const rs2::device& dev) const
Expand All @@ -34,7 +34,7 @@ namespace rs2
}

/**
* check if specific device was added
* check if a specific device was added
* \return true if device added, false otherwise
*/
bool was_added(const rs2::device& dev) const
Expand Down
64 changes: 32 additions & 32 deletions include/librealsense2/hpp/rs_frame.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ namespace rs2
*/
int stream_index() const { return _index; }
/**
* Return the stream format
* Return the stream type
* \return rs2_stream - stream type
*/
rs2_stream stream_type() const { return _type; }
Expand All @@ -53,7 +53,7 @@ namespace rs2
int unique_id() const { return _uid; }

/**
* Clone current profile and change the type, index and format to input parameters
* Clone the current profile and change the type, index and format to input parameters
* \param[in] type - will change the stream type from the cloned profile.
* \param[in] index - will change the stream index from the cloned profile.
* \param[in] format - will change the stream format from the cloned profile.
Expand Down Expand Up @@ -118,7 +118,7 @@ namespace rs2
}

/**
* Checking if stream profile is marked/assigned as default, the meaning is that the profile will be selected when the user will request stream configuration using wildcards (RS2_DEPTH, -1,-1,...
* Checking if stream profile is marked/assigned as default, meaning that the profile will be selected when the user requests stream configuration using wildcards (RS2_DEPTH, -1,-1,...
lramati marked this conversation as resolved.
Show resolved Hide resolved
* \return bool - true or false.
*/
bool is_default() const { return _default; }
Expand Down Expand Up @@ -153,8 +153,8 @@ namespace rs2
return res;
}
/**
* Assign extrinsic transformation parameters to a specific profile (sensor). The extrinsic information is generally available as part of the camera calibration, and librealsense is responsible to retrieve and assign these parameters where appropriate.
* The specific function is intended for synthetic/mock-up (software) devices for which the parameters are produced and injected by the user.
* Assign extrinsic transformation parameters to a specific profile (sensor). The extrinsic information is generally available as part of the camera calibration, and librealsense is responsible for retrieving and assigning these parameters where appropriate.
* This specific function is intended for synthetic/mock-up (software) devices for which the parameters are produced and injected by the user.
* \param[in] stream_profile to - which stream profile to be registered with the extrinsic.
* \param[in] rs2_extrinsics extrinsics - the extrinsics to be registered.
*/
Expand Down Expand Up @@ -201,7 +201,7 @@ namespace rs2
{
public:
/**
* Video stream profile instance which contans additional video attributes
* Stream profile instance which contains additional video attributes
* \param[in] stream_profile sp - assign exisiting stream_profile to this instance.
*/
explicit video_stream_profile(const stream_profile& sp)
Expand Down Expand Up @@ -231,7 +231,7 @@ namespace rs2
return _height;
}
/**
* Get stream profile instrinsics attribute
* Get stream profile instrinsics attributes
* \return rs2_intrinsics - stream intrinsics.
*/
rs2_intrinsics get_intrinsics() const
Expand All @@ -253,7 +253,7 @@ namespace rs2
{
public:
/**
* Motion stream profile instance which contans IMU-specific intrinsic
* Stream profile instance which contains IMU-specific intrinsics.
* \param[in] stream_profile sp - assign exisiting stream_profile to this instance.
*/
explicit motion_stream_profile(const stream_profile& sp)
Expand Down Expand Up @@ -407,7 +407,7 @@ namespace rs2
void keep() { rs2_keep_frame(frame_ref); }

/**
* Parenthesis operator check internal frame handle is valid.
* Parenthesis operator check if internal frame handle is valid.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The parenthesis operator checks if the

* \return bool - true or false.
*/
operator bool() const { return frame_ref != nullptr; }
Expand Down Expand Up @@ -570,7 +570,7 @@ namespace rs2
{
public:
/**
* Inherit frame class with additional video related attributs/functions
* Extend frame class with additional video related attributes and functions
lramati marked this conversation as resolved.
Show resolved Hide resolved
* \param[in] frame - existing frame instance
*/
video_frame(const frame& f)
Expand Down Expand Up @@ -653,12 +653,12 @@ namespace rs2
{
public:
/**
* Inherit frame class with additional point cloud related attributs/functions
* Extend frame class with additional point cloud related attributes and functions
lramati marked this conversation as resolved.
Show resolved Hide resolved
*/
points() : frame(), _size(0) {}

/**
* Inherit frame class with additional point cloud related attributs/functions
* Extend frame class with additional point cloud related attributes and functions
lramati marked this conversation as resolved.
Show resolved Hide resolved
* \param[in] frame - existing frame instance
*/
points(const frame& f)
Expand All @@ -678,7 +678,7 @@ namespace rs2
}
}
/**
* Retrieve back the vertices
* Retrieve the vertices for the point cloud
lramati marked this conversation as resolved.
Show resolved Hide resolved
* \param[in] vertex* - pointer of vertex sturcture
*/
const vertex* get_vertices() const
Expand All @@ -690,7 +690,7 @@ namespace rs2
}

/**
* Export current point cloud to PLY file
* Export the point cloud to PLY file
lramati marked this conversation as resolved.
Show resolved Hide resolved
* \param[in] string fname - file name of the PLY to be saved
* \param[in] video_frame texture - the texture for the PLY.
*/
Expand All @@ -703,7 +703,7 @@ namespace rs2
error::handle(e);
}
/**
* return the texture coordinate(uv map) for the point cloud
* Retrieve the texture coordinates (uv map) for the point cloud
* \return texture_coordinate* - pointer of texture coordinates.
*/
const texture_coordinate* get_texture_coordinates() const
Expand All @@ -727,7 +727,7 @@ namespace rs2
{
public:
/**
* Inherit video_frame class with additional depth related attributs/functions
* Extend video_frame class with additional depth related attributes and functions
lramati marked this conversation as resolved.
Show resolved Hide resolved
* \param[in] frame - existing frame instance
*/
depth_frame(const frame& f)
Expand All @@ -742,10 +742,10 @@ namespace rs2
}

/**
* Return the distance between two depth pixels
* \param[in] int x - first pixel position.
* \param[in] int y - second pixel position.
* \return float - distance between to points.
* Provide the depth in metric units at the given pixel
* \param[in] int x - pixel's x coordinate.
* \param[in] int y - pixel's y coordinate.
* \return float - depth in metric units at given pixel
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are metric units here meters? millimeters? Say which.
Also might be useful to define depth. I believe it is defined to be the Z distance along the optical axis of the camera.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ev-mp Do you know which the case is here?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Depth is given in metric units, i.e 1.f==1meter;
The depth is defined as Z in Euclidean space.

*/
float get_distance(int x, int y) const
{
Expand Down Expand Up @@ -790,7 +790,7 @@ namespace rs2
{
public:
/**
* Inherit frame class with additional motion related attributs/functions
* Extends frame class with additional motion related attributes and functions
* \param[in] frame - existing frame instance
*/
motion_frame(const frame& f)
Expand All @@ -804,7 +804,7 @@ namespace rs2
error::handle(e);
}
/**
* Retrieve back the motion data from IMU sensor
* Retrieve the motion data from IMU sensor
* \return rs2_vector - 3D vector in Euclidean coordinate space.
*/
rs2_vector get_motion_data() const
Expand All @@ -818,7 +818,7 @@ namespace rs2
{
public:
/**
* Inherit frame class with additional pose related attributs/functions
* Extends frame class with additional pose related attributes and functions
lramati marked this conversation as resolved.
Show resolved Hide resolved
* \param[in] frame - existing frame instance
*/
pose_frame(const frame& f)
Expand All @@ -832,7 +832,7 @@ namespace rs2
error::handle(e);
}
/**
* Retrieve back the pose data from T2xx position tracking sensor
* Retrieve the pose data from T2xx position tracking sensor
* \return rs2_pose - orientation and velocity data.
*/
rs2_pose get_pose_data() const
Expand All @@ -849,11 +849,11 @@ namespace rs2
{
public:
/**
* Inherit frame class with additional frameset related attributs/functions
* Extend frame class with additional frameset related attributes and functions
lramati marked this conversation as resolved.
Show resolved Hide resolved
*/
frameset() :_size(0) {};
/**
* Inherit frame class with additional frameset related attributs/functions
* Extend frame class with additional frameset related attributes and functions
lramati marked this conversation as resolved.
Show resolved Hide resolved
* \param[in] frame - existing frame instance
*/
frameset(const frame& f)
Expand All @@ -875,7 +875,7 @@ namespace rs2
}

/**
* Retrieve back the first frame of specific stream and format types, if no frame found, return the default one(frame instance)
* Retrieve the first frame of specific stream and format types, if no frame found, return the default one (frame instance)
lramati marked this conversation as resolved.
Show resolved Hide resolved
* \param[in] rs2_stream s - frame to be retrieved from this stream type.
* \param[in] rs2_format f - frame to be retrieved from this format type.
* \return frame - first found frame with s stream type.
Expand All @@ -892,7 +892,7 @@ namespace rs2
return result;
}
/**
* Retrieve back the first frame of specific stream type, if no frame found, error will be thrown
* Retrieve the first frame of specific stream type, if no frame found, an error will be thrown
lramati marked this conversation as resolved.
Show resolved Hide resolved
* \param[in] rs2_stream s - frame to be retrieved from this stream type.
* \param[in] rs2_format f - frame to be retrieved from this format type.
* \return frame - first found frame with s stream type.
Expand All @@ -905,7 +905,7 @@ namespace rs2
}

/**
* Retrieve back the first depth frame, if no frame found, return the default one(frame instance)
* Retrieve the first depth frame, if no frame found, return the default one (frame instance)
lramati marked this conversation as resolved.
Show resolved Hide resolved
* \return depth_frame - first found depth frame.
*/
depth_frame get_depth_frame() const
Expand All @@ -914,7 +914,7 @@ namespace rs2
return f.as<depth_frame>();
}
/**
* Retrieve back the first color frame, if no frame found, search the color frame from IR stream. If still can't find, return the default one(frame instance)
* Retrieve the first color frame, if no frame found, search the color frame from IR stream. If one still can't be found, return the default one (frame instance)
lramati marked this conversation as resolved.
Show resolved Hide resolved
* \return video_frame - first found color frame.
*/
video_frame get_color_frame() const
Expand All @@ -930,7 +930,7 @@ namespace rs2
return f;
}
/**
* Retrieve back the first infrared frame, return the default one(frame instance)
* Retrieve the first infrared frame, if no frame found, return the default one (frame instance)
lramati marked this conversation as resolved.
Show resolved Hide resolved
* \param[in] size_t index
* \return video_frame - first found infrared frame.
*/
Expand Down Expand Up @@ -1005,7 +1005,7 @@ namespace rs2
}

/**
* Template function, extract internal frame handle from the frameset and invoke the action function
* Template function, extract internal frame handles from the frameset and invoke the action function
* \param[in] action - instance with () operator implemented will be invoke after frame extraction.
*/
template<class T>
Expand Down
Loading