docstrings for all python classes (isl-org#877)

docs/conf.py

@@ -23,6 +23,7 @@
 import sphinx_rtd_theme
 import sys
 import os
+import re
 
 # Import open3d raw python package with the highest priority
 # This is a trick to show open3d.open3d as open3d in the docs
@@ -176,5 +177,45 @@
      'Miscellaneous'),
 ]
 
-# added by Jaesik to list Python members using the source order
-autodoc_member_order = 'bysource'
+# Version 0: Added by Jaesik to list Python members using the source order
+# Version 1: Changed to 'groupwise': __init__ first, then methods, then
+#            properties. Within each, sorted alphabetically.
+autodoc_member_order = 'groupwise'
+
+
+def is_enum_class(func, func_name):
+    def import_from_str(class_name):
+        components = class_name.split('.')
+        mod = __import__(components[0])
+        for comp in components[1:]:
+            mod = getattr(mod, comp)
+        return mod
+
+    is_enum = False
+    try:
+        if func_name == "name" and "self: handle" in func.__doc__:
+            is_enum = True
+        else:
+            pattern = re.escape(func_name) + r"\(self: ([a-zA-Z0-9_\.]*).*\)"
+            m = re.match(pattern, func.__doc__)
+            if m:
+                c_name = m.groups()[0]
+                c = import_from_str(c_name)
+                if hasattr(c, "__entries"):
+                    is_enum = True
+    except:
+        pass
+    return is_enum
+
+
+# Keep the __init__ function doc
+def skip(app, what, name, obj, would_skip, options):
+    if name in {"__init__", "name"}:
+        if is_enum_class(obj, name):
+            return True
+        else:
+            return False
+    return would_skip
+
+def setup(app):
+    app.connect("autodoc-skip-member", skip)

docs/python_api/camera.rst

@@ -9,3 +9,4 @@ open3d.camera
 .. automodule:: open3d.camera
     :members:
     :undoc-members:
+

src/Open3D/ColorMap/ColorMapOptimization.h

@@ -49,6 +49,8 @@ namespace color_map {
 class ColorMapOptimizationOption {
 public:
     ColorMapOptimizationOption(
+            // Attention: when you update the defaults, update the docstrings in
+            // Python/color_map/color_map.cpp
             bool non_rigid_camera_coordinate = false,
             int number_of_vertical_anchors = 16,
             double non_rigid_anchor_point_weight = 0.316,

src/Open3D/Geometry/HalfEdgeTriangleMesh.h

@@ -68,7 +68,7 @@ class HalfEdgeTriangleMesh : public TriangleMesh {
     /// True if half-edges have already been computed
     bool HasHalfEdges() const;
 
-    /// Query manifold boundary half edges
+    /// Query manifold boundary half edges from a starting vertex
     /// If query vertex is not on boundary, empty vector will be returned
     std::vector<int> BoundaryHalfEdgesFromVertex(int vertex_index) const;
 

src/Open3D/Geometry/LineSet.h

@@ -62,8 +62,9 @@ class LineSet : public Geometry3D {
     }
 
     std::pair<Eigen::Vector3d, Eigen::Vector3d> GetLineCoordinate(
-            size_t i) const {
-        return std::make_pair(points_[lines_[i][0]], points_[lines_[i][1]]);
+            size_t line_index) const {
+        return std::make_pair(points_[lines_[line_index][0]],
+                              points_[lines_[line_index][1]]);
     }
 
 public:

src/Open3D/Odometry/RGBDOdometryJacobian.h

@@ -73,7 +73,7 @@ class RGBDOdometryJacobian {
             const CorrespondenceSetPixelWise &corresps) const = 0;
 };
 
-/// Function to Compute Jacobian using color term
+/// Class to compute Jacobian using color term
 /// Energy: (I_p-I_q)^2
 /// reference:
 /// F. Steinbrucker, J. Sturm, and D. Cremers.
@@ -99,7 +99,7 @@ class RGBDOdometryJacobianFromColorTerm : public RGBDOdometryJacobian {
             const CorrespondenceSetPixelWise &corresps) const override;
 };
 
-/// Function to Compute Jacobian using hybrid term
+/// Class to compute Jacobian using hybrid term
 /// Energy: (I_p-I_q)^2 + lambda(D_p-(D_q)')^2
 /// reference:
 /// J. Park, Q.-Y. Zhou, and V. Koltun

src/Open3D/Registration/FastGlobalRegistration.h

@@ -70,7 +70,7 @@ class FastGlobalRegistrationOption {
     bool decrease_mu_;
     // Maximum correspondence distance (also see comment of USE_ABSOLUTE_SCALE)
     double maximum_correspondence_distance_;
-    // Maximum number of iteration
+    // Maximum number of iterations
     int iteration_number_;
     // Similarity measure used for tuples of feature points.
     double tuple_scale_;

src/Open3D/Registration/Registration.h

@@ -81,7 +81,7 @@ class RANSACConvergenceCriteria {
     int max_validation_;
 };
 
-/// Class that contains the registration result
+/// Class that contains the registration results
 class RegistrationResult {
 public:
     RegistrationResult(

src/Python/camera/camera.cpp

@@ -27,13 +27,17 @@
 #include <Open3D/Camera/PinholeCameraIntrinsic.h>
 #include <Open3D/Camera/PinholeCameraTrajectory.h>
 
+#include "Python/docstring.h"
 #include "Python/camera/camera.h"
 
 using namespace open3d;
 
 void pybind_camera_classes(py::module &m) {
+    // open3d.camera.PinholeCameraIntrinsic
     py::class_<camera::PinholeCameraIntrinsic> pinhole_intr(
-            m, "PinholeCameraIntrinsic", "PinholeCameraIntrinsic");
+            m, "PinholeCameraIntrinsic",
+            "PinholeCameraIntrinsic class stores intrinsic camera matrix, and "
+            "image height and width.");
     py::detail::bind_default_constructor<camera::PinholeCameraIntrinsic>(
             pinhole_intr);
     py::detail::bind_copy_functions<camera::PinholeCameraIntrinsic>(
@@ -48,20 +52,32 @@ void pybind_camera_classes(py::module &m) {
             .def(py::init([](camera::PinholeCameraIntrinsicParameters param) {
                      return new camera::PinholeCameraIntrinsic(param);
                  }),
-                 "param"_a)
+                 "param"_a);
+    pinhole_intr
             .def("set_intrinsics",
                  &camera::PinholeCameraIntrinsic::SetIntrinsics, "width"_a,
-                 "height"_a, "fx"_a, "fy"_a, "cx"_a, "cy"_a)
+                 "height"_a, "fx"_a, "fy"_a, "cx"_a, "cy"_a,
+                 "Set camera intrinsic parmeters.")
             .def("get_focal_length",
-                 &camera::PinholeCameraIntrinsic::GetFocalLength)
+                 &camera::PinholeCameraIntrinsic::GetFocalLength,
+                 "Returns the focal length.")
             .def("get_principal_point",
-                 &camera::PinholeCameraIntrinsic::GetPrincipalPoint)
-            .def("get_skew", &camera::PinholeCameraIntrinsic::GetSkew)
-            .def("is_valid", &camera::PinholeCameraIntrinsic::IsValid)
-            .def_readwrite("width", &camera::PinholeCameraIntrinsic::width_)
-            .def_readwrite("height", &camera::PinholeCameraIntrinsic::height_)
+                 &camera::PinholeCameraIntrinsic::GetPrincipalPoint,
+                 "Returns the principle point.")
+            .def("get_skew", &camera::PinholeCameraIntrinsic::GetSkew,
+                 "Returns the skew.")
+            .def("is_valid", &camera::PinholeCameraIntrinsic::IsValid,
+                 "Returns True iff both the width and height are greater than "
+                 "0.")
+            .def_readwrite("width", &camera::PinholeCameraIntrinsic::width_,
+                           "int: Width of the image.")
+            .def_readwrite("height", &camera::PinholeCameraIntrinsic::height_,
+                           "int: Height of the image.")
             .def_readwrite("intrinsic_matrix",
-                           &camera::PinholeCameraIntrinsic::intrinsic_matrix_)
+                           &camera::PinholeCameraIntrinsic::intrinsic_matrix_,
+                           "3x3 numpy array: Intrinsic camera matrix ``[[fx, "
+                           "0, cx], [0, fy, "
+                           "cy], [0, 0, 1]]``")
             .def("__repr__", [](const camera::PinholeCameraIntrinsic &c) {
                 return std::string(
                                "camera::PinholeCameraIntrinsic with width = ") +
@@ -71,45 +87,83 @@ void pybind_camera_classes(py::module &m) {
                        std::string(
                                ".\nAccess intrinsics with intrinsic_matrix.");
             });
-    py::enum_<camera::PinholeCameraIntrinsicParameters>(
+    docstring::ClassMethodDocInject(m, "PinholeCameraIntrinsic", "__init__");
+    docstring::ClassMethodDocInject(m, "PinholeCameraIntrinsic",
+                                    "set_intrinsics",
+                                    {{"width", "Width of the image."},
+                                     {"height", "Height of the image."},
+                                     {"fx", "X-axis focal length"},
+                                     {"fy", "Y-axis focal length."},
+                                     {"cx", "X-axis principle point."},
+                                     {"cy", "Y-axis principle point."}});
+    docstring::ClassMethodDocInject(m, "PinholeCameraIntrinsic",
+                                    "get_focal_length");
+    docstring::ClassMethodDocInject(m, "PinholeCameraIntrinsic",
+                                    "get_principal_point");
+    docstring::ClassMethodDocInject(m, "PinholeCameraIntrinsic", "get_skew");
+    docstring::ClassMethodDocInject(m, "PinholeCameraIntrinsic", "is_valid");
+
+    // open3d.camera.PinholeCameraIntrinsicParameters
+    py::enum_<camera::PinholeCameraIntrinsicParameters> pinhole_intr_params(
             m, "PinholeCameraIntrinsicParameters", py::arithmetic(),
-            "PinholeCameraIntrinsicParameters")
+            "PinholeCameraIntrinsicParameters");
+    pinhole_intr_params
             .value("PrimeSenseDefault",
-                   camera::PinholeCameraIntrinsicParameters::PrimeSenseDefault)
+                   camera::PinholeCameraIntrinsicParameters::PrimeSenseDefault,
+                   "Default camera intrinsic parameter for PrimeSense.")
             .value("Kinect2DepthCameraDefault",
                    camera::PinholeCameraIntrinsicParameters::
-                           Kinect2DepthCameraDefault)
+                           Kinect2DepthCameraDefault,
+                   "Default camera intrinsic parameter for Kinect2 depth "
+                   "camera.")
             .value("Kinect2ColorCameraDefault",
                    camera::PinholeCameraIntrinsicParameters::
-                           Kinect2ColorCameraDefault)
+                           Kinect2ColorCameraDefault,
+                   "Default camera intrinsic parameter for Kinect2 color "
+                   "camera.")
             .export_values();
+    pinhole_intr_params.attr("__doc__") = docstring::static_property(
+            py::cpp_function(
+                    [](py::handle arg) -> std::string { return "Enum class"; }),
+            py::none(), py::none(), "");
 
+    // open3d.camera.PinholeCameraParameters
     py::class_<camera::PinholeCameraParameters> pinhole_param(
-            m, "PinholeCameraParameters", "PinholeCameraParameters");
+            m, "PinholeCameraParameters",
+            "Contains both intrinsic and extrinsic pinhole camera parameters.");
     py::detail::bind_default_constructor<camera::PinholeCameraParameters>(
             pinhole_param);
     py::detail::bind_copy_functions<camera::PinholeCameraParameters>(
             pinhole_param);
     pinhole_param
             .def_readwrite("intrinsic",
-                           &camera::PinholeCameraParameters::intrinsic_)
+                           &camera::PinholeCameraParameters::intrinsic_,
+                           "``open3d.camera.PinholeCameraIntrinsic``: "
+                           "PinholeCameraIntrinsic "
+                           "object.")
             .def_readwrite("extrinsic",
-                           &camera::PinholeCameraParameters::extrinsic_)
+                           &camera::PinholeCameraParameters::extrinsic_,
+                           "4x4 numpy array: Camera extrinsic parameters.")
             .def("__repr__", [](const camera::PinholeCameraParameters &c) {
                 return std::string("camera::PinholeCameraParameters class.\n") +
                        std::string(
                                "Access its data via intrinsic and extrinsic.");
             });
 
+    // open3d.camera.PinholeCameraTrajectory
     py::class_<camera::PinholeCameraTrajectory> pinhole_traj(
-            m, "PinholeCameraTrajectory", "PinholeCameraTrajectory");
+            m, "PinholeCameraTrajectory",
+            "Contains a list of ``PinholeCameraParameters``, useful to storing "
+            "trajectories.");
     py::detail::bind_default_constructor<camera::PinholeCameraTrajectory>(
             pinhole_traj);
     py::detail::bind_copy_functions<camera::PinholeCameraTrajectory>(
             pinhole_traj);
     pinhole_traj
             .def_readwrite("parameters",
-                           &camera::PinholeCameraTrajectory::parameters_)
+                           &camera::PinholeCameraTrajectory::parameters_,
+                           "``List(open3d.camera.PinholeCameraIntrinsic)``: "
+                           "List of PinholeCameraIntrinsic objects.")
             .def("__repr__", [](const camera::PinholeCameraTrajectory &c) {
                 return std::string("camera::PinholeCameraTrajectory class.\n") +
                        std::string("Access its data via camera_parameters.");