🐍 refreshed wrapper for Circle Arc

refreshed wrapper for CircleArc class 

 - added build method
 - copy method is more pythonic, and returns a copy instead of copying another target on the self instance
 - docs for all methods
 - ray renamed radius
 - removed abstract BaseClass methods

src_py/src/python-CircleArc.cc

@@ -12,114 +12,218 @@
 namespace G2lib {
   namespace python {
     void wrap_CircleArc(py::module & m) {
-      py::class_<CircleArc, BaseCurve>(m, "CircleArc")
-        .def(py::init<BaseCurve const &>())
-        .def(py::init<LineSegment const &>())
-        .def(py::init<CircleArc const &>())
-        .def(py::init<real_type, real_type, real_type, real_type, real_type>())
-        .def("copy", &CircleArc::copy)
-        .def("build_G1", &CircleArc::build_G1)
-        .def("build_3P", &CircleArc::build_3P)
-        //.def("bbTriangle", [](CircleArc * self) {
-        //  real_type x0, y0, x1, y1, x2, y2;
-        //  self->bbTriangle(x0, y0, x1, y1, x2, y2);
-        //  return std::make_tuple(
-        //    std::make_tuple(x0, y0), 
-        //    std::make_tuple(x1, y1), 
-        //    std::make_tuple(x2, y2));
-        //})
-        .def("bbTriangle", [](CircleArc * self, real_type ss0 = 0, 
-                                    real_type ss1 = 0, int_type icurve = 0) {
-          Triangle2D t;
-          bool v = self->bbTriangle(t, ss0, ss1, icurve);
-          return std::make_tuple(v, t);
-        }, py::arg("ss0") = 0, py::arg("ss1") = 0, py::arg("icurve") = 0)
-        .def("bbTriangle_ISO", [](CircleArc * self, real_type offs, real_type ss0 = 0, 
-                                  real_type ss1 = 0, int_type icurve = 0) {
-          Triangle2D t;
-          bool v = self->bbTriangle_ISO(offs, t, ss0, ss1, icurve);
-          return std::make_tuple(v, t);
-        }, py::arg("offs"), py::arg("ss0") = 0, py::arg("ss1") = 0, py::arg("icurve") = 0)
-        .def("bbTriangle_SAE", [](CircleArc * self, real_type offs, real_type ss0 = 0, 
-                                  real_type ss1 = 0, int_type icurve = 0) {
-          Triangle2D t;
-          bool v = self->bbTriangle_SAE(offs, t, ss0, ss1, icurve);
-          return std::make_tuple(v, t);
-        }, py::arg("offs"), py::arg("ss0") = 0, py::arg("ss1") = 0, py::arg("icurve") = 0)
-        .def("bbTriangles", [](CircleArc * self, real_type max_angle = Utils::m_pi/18, 
-                                    real_type max_size  = 1e100, int_type icurve = 0) {
-          std::vector<Triangle2D> tvec;
-          self->bbTriangles(tvec, max_angle, max_size, icurve);
-          return tvec;
-        }, py::arg("max_angle") = Utils::m_pi/18, py::arg("max_size") = 1e100, py::arg("icurve") = 0)
-        .def("bbTriangles_ISO", [](CircleArc * self, real_type offs, real_type max_angle, 
-                                    real_type max_size, int_type icurve) {
-          std::vector<Triangle2D> tvec;
-          self->bbTriangles_ISO(offs, tvec, max_angle, max_size, icurve);
-          return tvec;
-        })
-        .def("bbTriangles_SAE", [](CircleArc * self, real_type offs, real_type max_angle, 
-                                    real_type max_size, int_type icurve) {
-          std::vector<Triangle2D> tvec;
-          self->bbTriangles_SAE(offs, tvec, max_angle, max_size, icurve);
-          return tvec;
-        })
-        .def("collision", &CircleArc::collision)
-        .def("intersect", [](CircleArc * self, CircleArc const & C, bool swap_s_vals) {
-          IntersectList ilist;
-          self->intersect(C, ilist, swap_s_vals);
-          return ilist;
-        })
-        .def("collision_ISO", &CircleArc::collision_ISO)
-        .def("intersect_ISO", [](CircleArc * self, real_type offs, CircleArc const & C, real_type Coffs, bool swap_s_vals) {
-          IntersectList ilist;
-          self->intersect_ISO(offs, C, Coffs, ilist, swap_s_vals);
-          return ilist;
-        })
-        .def("sinTheta0", &CircleArc::sinTheta0)
-        .def("cosTheta0", &CircleArc::cosTheta0)
-        .def("curvature", &CircleArc::curvature)
-        .def("lenTolerance", &CircleArc::lenTolerance)
-        .def("delta_theta", &CircleArc::delta_theta)
-        .def("thetaTotalVariation", &CircleArc::thetaTotalVariation)
-        .def("thetaMinMax", [](CircleArc * self) {
-          real_type th_min, th_max;
-          self->thetaMinMax(th_min, th_max);
-          return std::make_tuple(th_min, th_max);
-        })
-        .def("changeCurvilinearOrigin", &CircleArc::changeCurvilinearOrigin)
-        .def("center", [](CircleArc * self) {
-          real_type x, y;
-          self->center(x, y);
-          return std::make_tuple(x, y);
-        })
-        .def("ray", &CircleArc::ray)
-        .def("paramNURBS", [](CircleArc * self) {
-          int_type n_pnts, n_knots;
-          self->paramNURBS(n_knots, n_pnts);
-          return std::make_tuple(n_knots, n_pnts);
-        })
-        .def("toNURBS", [](CircleArc * self){
-          using Point = real_type[3];
-          int_type n_pnts, n_knots;
-          self->paramNURBS(n_knots, n_pnts);
-          real_type * knots = new real_type[n_knots];
-          Point * Poly = new Point[n_pnts];
-          self->toNURBS(knots, Poly);
-
-          std::vector<std::tuple<real_type, real_type, real_type>> Poly_vec;
-          for (int_type i = 0; i < n_pnts; i++) {
-            Poly_vec.push_back(std::make_tuple(Poly[i][0], Poly[i][1], Poly[i][2]));
-          }
-          std::vector<real_type> knots_vec;
-          for (int_type i = 0; i < n_knots; i++) {
-            knots_vec.push_back(knots[i]);
-          }
-          auto ret = std::make_tuple(knots_vec, Poly_vec);
-          delete[] Poly;
-          delete[] knots;
-          return ret;
+      py::class_<CircleArc, BaseCurve>(m, "CircleArc",
+      R"S(
+        Class that menages a circle arc. There are several possible
+        constructor for this class
+
+         * constructor from a Base Curve
+         * constructor from a Line Segment
+         * constructor from a Circle Arc
+         * constructor from raw data
+
+        for this last constructor:
+
+        :param float x0: starting position **x** coordinate
+        :param float y0: starting position **y** coordinate
+        :param float theta0: initial angle
+        :param k: curvature
+        :param l: length
+      )S")
+
+      .def(py::init<BaseCurve const &>(), py::arg("c"))
+      .def(py::init<LineSegment const &>(), py::arg("c"))
+      .def(py::init<CircleArc const &>(), py::arg("c"))
+      .def(py::init<real_type, real_type, real_type, real_type, real_type>(),
+        py::arg("x0"), py::arg("y0"), py::arg("theta0"), py::arg("k"), py::arg("l"))
+
+      .def("copy", [](const CircleArc & self) {
+        CircleArc other;
+        other.copy(self);
+        return other;
+      },
+      R"S(
+        Create a copy of the current circle arc curve
+
+        :return: a new copy of the current circle arc
+        :rtype: CircleArc
+      )S")
+
+      .def("build", &CircleArc::build, 
+        py::arg("x0"), py::arg("y0"), py::arg("theta0"), py::arg("k"), py::arg("l"),
+      R"S(
+        Builds a circle arc with the standard parameters
+
+        :param float x0: starting position **x** coordinate
+        :param float y0: starting position **y** coordinate
+        :param float theta0: initial angle
+        :param float k: curvature
+        :param float l: length
+        :return: nothing, works in place
+        :rtype: NoneType
+      )S")
+
+      .def("build_G1", &CircleArc::build_G1, 
+        py::arg("x0"), py::arg("y0"), py::arg("theta0"), py::arg("x1"), py::arg("y1"),
+      R"S(
+        Builds a circle arc with the standard parameters
+
+        :param float x0: starting position **x** coordinate
+        :param float y0: starting position **y** coordinate
+        :param float theta0: initial angle
+        :param float x1: final position **x** coordinate
+        :param float l: final position **y** coordinate
+        :return: true if build succeeds
+        :rtype: bool
+      )S")
+
+      .def("build_3P", &CircleArc::build_3P,
+        py::arg("x0"), py::arg("y0"), py::arg("x1"), py::arg("y1"), py::arg("x2"), py::arg("y2"),
+      R"S(
+        Builds a circle arc with the standard parameters
+
+        :param float x0: first point **x** coordinate
+        :param float y0: first point **y** coordinate
+        :param float x1: second point **x** coordinate
+        :param float y1: second point **y** coordinate
+        :param float x2: third point **x** coordinate
+        :param float y2: third point **y** coordinate
+        :return: true if build succeeds
+        :rtype: bool
+      )S")
+
+      .def("sinTheta0", &CircleArc::sinTheta0,
+      R"S(
+        Returns the :math:`\sin(\theta_0)` (sine of initial angle)
+
+        :return: sine of initial angle
+        :rtype: float
+      )S")
+
+      .def("cosTheta0", &CircleArc::cosTheta0,
+      R"S(
+        Returns the :math:`\cos(\theta_0)` (cosine of initial angle)
+
+        :return: cosine of initial angle
+        :rtype: float
+      )S")
+
+      .def("curvature", &CircleArc::curvature,
+      R"S(
+        Curvature of the circle arc
+
+        :return: curvature of the circle arc
+        :rtype: float
+      )S")
+
+      .def("lenTolerance", &CircleArc::lenTolerance, py::arg("tol"),
+      R"S(
+        Return the arc length to evaluate length with the requested
+        tolerance
+
+        :param float tol: tolerance
+        :return: arc length
+        :rtype: float
+      )S")
+
+      .def("delta_theta", &CircleArc::delta_theta, 
+      R"S(
+        Return the tangent angle variation in the circle arc
+
+        :return: tangent angle variation
+        :rtype: float
+      )S")
+
+      .def("thetaTotalVariation", &CircleArc::thetaTotalVariation,
+      R"S(
+        Return the absolute value of the tangent angle variation in the circle arc.
+
+        :return: absolute value of the tangent angle variation
+        :rtype: float
+      )S")
+
+      .def("thetaMinMax", [](const CircleArc & self) {
+        real_type th_min, th_max;
+        self.thetaMinMax(th_min, th_max);
+        return std::make_tuple(th_min, th_max);
+      }, 
+      R"S(
+        Minimum and maximum tangent angle
+
+        :return: the minimum and maximum tangent angle
+        :rtype: Tuple[float, float]
+      )S")
+
+      .def("changeCurvilinearOrigin", &CircleArc::changeCurvilinearOrigin,
+        py::arg("s0"), py::arg("newL"),
+      R"S(
+        Change the origin of the curvilinear abscissa of the circle arc
+        and the length of the arc
+
+        :param float s0: new curvilinear abscissa origin
+        :param float newL: new length of the curve
+        :return: nothing, works in place
+        :rtype: NoneType
+      )S")
+
+      .def("center", [](const CircleArc & self) {
+        real_type x, y;
+        self.center(x, y);
+        return std::make_tuple(x, y);
+      },
+      R"S(
+        Get the center of the arc
+
+        :return: center of the arc
+        :rtype: Tuple[float, float]
+      )S")
+
+      .def("radius", &CircleArc::ray,
+      R"S(
+        Returns the radius of the circle arc
+
+        :return: radius of the circle
+        :rtype: float
+      )S")
+
+      .def("paramNURBS", [](const CircleArc & self) {
+        int_type n_pnts, n_knots;
+        self.paramNURBS(n_knots, n_pnts);
+        return std::make_tuple(n_knots, n_pnts);
+      },
+      R"S(
+        Return the number of knots and points for the nurbs of the circle
+
+        :return: knots count and point count
+        :rtype: Tuple[int, int]
+      )S")
+
+      .def("toNURBS", [](const CircleArc & self){
+        using Point = real_type[3];
+        using TPoint = std::tuple<float, float, float>;
+
+        int_type n_pnts, n_knots;
+        self.paramNURBS(n_knots, n_pnts);
+
+        std::vector<real_type> knots(n_knots);
+        std::vector<Point> poly(n_pnts);
+        std::vector<TPoint> tpoly;
+        tpoly.reserve(n_pnts);
+
+        self.toNURBS(knots.data(), poly.data());
+        std::for_each(poly.cbegin(), poly.cend(), [&](const Point & p) {
+          tpoly.push_back(std::make_tuple(p[0], p[1], p[2]));
         });
+
+        return std::make_tuple(knots, tpoly);
+      },
+      R"S(
+        Returns the nurbs parameters of the circle arc, as a tuple with
+        knots and point list (as a tuple of 3 value)
+
+        :return: nurbs parameters
+        :rtype: Tuple[List[float], List[Tuple[float, float, float]]]
+      )S");
     }
   }
 }