ruby-opencv 0.0.11 → 0.0.12.pre

data/ext/opencv/cvconnectedcomp.h

@@ -20,7 +20,7 @@ __NAMESPACE_BEGIN_CVCONNECTEDCOMP
 
 VALUE rb_class();
 
-void define_ruby_class();
+void init_ruby_class();
 
 VALUE rb_allocate(VALUE klass);
 

data/ext/opencv/cvcontour.cpp

@@ -11,8 +11,9 @@
 /*
  * Document-class: OpenCV::CvContour
  *
- * Contour.
- * CvMat#find_contours
+ * Contour
+ *
+ * @see CvMat#find_contours
  */
 __NAMESPACE_BEGIN_OPENCV
 __NAMESPACE_BEGIN_CVCONTOUR
@@ -33,56 +34,19 @@ rb_class()
   return rb_klass;
 }
 
-void
-define_ruby_class()
-{
-  if (rb_klass)
-    return;
-  /* 
-   * opencv = rb_define_module("OpenCV");
-   * cvseq = rb_define_class_under(opencv, "CvSeq");
-   * curve = rb_define_module_under(opencv, "Curve");
-   * pointset = rb_define_module_under(opencv, "PointSet");
-   *
-   * note: this comment is used by rdoc.
-   */
-  VALUE opencv = rb_module_opencv();
-  VALUE cvseq = cCvSeq::rb_class();
-  VALUE curve = mCurve::rb_module();
-  VALUE pointset = mPointSet::rb_module();
-
-  rb_klass = rb_define_class_under(opencv, "CvContour", cvseq);
-  rb_include_module(rb_klass, curve);
-  rb_include_module(rb_klass, pointset);
-
-  rb_define_alloc_func(rb_klass, rb_allocate);
-
-  VALUE approx_option = rb_hash_new();
-  rb_define_const(rb_klass, "APPROX_OPTION", approx_option);
-  rb_hash_aset(approx_option, ID2SYM(rb_intern("method")), INT2FIX(CV_POLY_APPROX_DP));
-  rb_hash_aset(approx_option, ID2SYM(rb_intern("accuracy")), rb_float_new(1.0));
-  rb_hash_aset(approx_option, ID2SYM(rb_intern("recursive")), Qfalse);
-  
-  rb_define_private_method(rb_klass, "initialize", RUBY_METHOD_FUNC(rb_initialize), -1);
-  rb_define_method(rb_klass, "rect", RUBY_METHOD_FUNC(rb_rect), 0);
-  rb_define_method(rb_klass, "color", RUBY_METHOD_FUNC(rb_color), 0);
-  rb_define_method(rb_klass, "color=", RUBY_METHOD_FUNC(rb_set_color), 1);
-  rb_define_method(rb_klass, "reserved", RUBY_METHOD_FUNC(rb_reserved), 0);
-  rb_define_method(rb_klass, "approx_poly", RUBY_METHOD_FUNC(rb_approx_poly), -1);
-  rb_define_alias(rb_klass, "approx", "approx_poly");
-  rb_define_method(rb_klass, "bounding_rect", RUBY_METHOD_FUNC(rb_bounding_rect), 0);
-  rb_define_method(rb_klass, "create_tree", RUBY_METHOD_FUNC(rb_create_tree), -1);
-  rb_define_method(rb_klass, "in?", RUBY_METHOD_FUNC(rb_in_q), 1);
-  rb_define_method(rb_klass, "measure_distance", RUBY_METHOD_FUNC(rb_measure_distance), 1);
-  rb_define_method(rb_klass, "point_polygon_test", RUBY_METHOD_FUNC(rb_point_polygon_test), 2);
-}
-
 VALUE
 rb_allocate(VALUE klass)
 {
   return Data_Wrap_Struct(klass, mark_root_object, unregister_object, NULL);
 }
 
+/*
+ * Constructor
+ * @overload new(storage = nil)
+ *   @param [CvMemStorage] storage Sequence location
+ * @return [CvContour] self
+ * @opencv_func cvCreateSeq
+ */
 VALUE
 rb_initialize(int argc, VALUE *argv, VALUE self)
 {
@@ -107,18 +71,33 @@ rb_initialize(int argc, VALUE *argv, VALUE self)
   return self;
 }
 
+/*
+ * Returns bounding box of the contour
+ * @overload rect
+ * @return [CvRect] Bounding box of the contour
+ */
 VALUE
 rb_rect(VALUE self)
 {
   return cCvRect::new_object(CVCONTOUR(self)->rect);
 }
 
+/*
+ * Returns color of the contour
+ * @overload color
+ * @return [Number] Color of the contour
+ */
 VALUE
 rb_color(VALUE self)
 {
   return INT2NUM(CVCONTOUR(self)->color);
 }
 
+/*
+ * Set color of the contour
+ * @overload color=value
+ *   @param value [Number] Color of the contour
+ */
 VALUE
 rb_set_color(VALUE self, VALUE color)
 {
@@ -126,6 +105,11 @@ rb_set_color(VALUE self, VALUE color)
   return self;
 }
 
+/*
+ * Returns reserved region values of the contour
+ * @overload reserved
+ * @return [Array<Number>] Reserved region values of the contour
+ */
 VALUE
 rb_reserved(VALUE self)
 {
@@ -136,17 +120,18 @@ rb_reserved(VALUE self)
 }
 
 /*
- * call-seq:
- *   approx_poly(<i>approx_poly_option</i>) -> cvcontour
- *
- * Approximates polygonal curve(s) with desired precision.
- * <i>approx_poly_option</i> should be Hash include these keys.
- *   :method - Approximation method.
- *     :dp - corresponds to Douglas-Peucker algorithm.
- *   :accuracy - approximation accuracy. (high-accuracy will create more simple contours)
- *   :recursive - (default false)
- *      If not nil or false, the function approximates all chains that access can be obtained to
- *      from self by h_next or v_next links. If 0, approximated this one.
+ * Approximates polygonal curves with desired precision
+ * @overload approx_poly(options)
+ *   @param options [Hash] Parameters
+ *   @option options [Symbol] :method Approximation method (default :dp)
+ *     * :dp - Douglas-Peucker algorithm.
+ *   @option options [Number] :accuracy Parameter specifying the approximation accuracy.
+ *     This is the maximum distance between the original curve and its approximation.
+ *   @option options [Boolean] :recursive Recursion flag. If true, the function approximates
+ *     all the contours accessible from curve by h_next and v_next links.
+ * @return [CvContour] Result of the approximation
+ * @return [nil] Approximation faied
+ * @opencv_func cvApproxPoly
  */
 VALUE
 rb_approx_poly(int argc, VALUE *argv, VALUE self)
@@ -167,11 +152,10 @@ rb_approx_poly(int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * call-seq:
- *   bounding_rect -> rect
- *
  * Calculates up-right bounding rectangle of point set.
- * 
+ * @overload bounding_rect
+ * @return [CvRect] Bounding rectangle
+ * @opencv_func cvBoundingRect
  */
 VALUE
 rb_bounding_rect(VALUE self)
@@ -187,14 +171,12 @@ rb_bounding_rect(VALUE self)
 }
 
 /*
- * call-seq:
- *   create_tree([threshold = 0.0]) -> cvcontourtree
- *
- * Creates hierarchical representation of contour.
- * If the parameter <i>threshold</i> is less than or equal to 0,
- * the method creates full binary tree representation.
- * If the threshold is greater than 0, the function creates
- * representation with the precision threshold: 
+ * Creates hierarchical representation of contour
+ * @overload create_tree(threshold = 0.0)
+ *   @param threshold [Number] If <= 0, the method creates full binary tree representation.
+ *     If > 0, the method creates representation with the precision threshold.
+ * @return [CvContourTree] Hierarchical representation of the contour
+ * @opencv_func cvCreateContourTree
  */
 VALUE
 rb_create_tree(int argc, VALUE *argv, VALUE self)
@@ -213,10 +195,14 @@ rb_create_tree(int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * call-seq:
- *    in?(<i>point</i>) -> true or nil or false
- *
- * Determines whether the <i>point</i> is inside contour(true), outside(false) or lies on an edge(nil).
+ * Performs a point-in-contour test.
+ * The method determines whether the point is inside a contour, outside,
+ * or lies on an edge (or coincides with a vertex).
+ * @overload in?(point)
+ *   @param point [CvPoint2D32f] Point tested against the contour
+ * @return [Boolean] If the point is inside, returns true. If outside, returns false.
+ *   If lies on an edge, returns nil.
+ * @opencv_func cvPointPolygonTest
  */
 VALUE
 rb_in_q(VALUE self, VALUE point)
@@ -232,10 +218,11 @@ rb_in_q(VALUE self, VALUE point)
 }
 
 /*
- * call-seq:
- *    measure_distance(<i>point</i>) -> float
- *
- * Return distance between the point and the nearest contour edge.
+ * Calculates distance between a point and the nearest contour edgex
+ * @overload measure_distance(point)
+ *   @param point [CvPoint2D32f] Point tested against the contour
+ * @return Signed distance between the point and the nearest contour edge
+ * @opencv_func cvPointPolygonTest
  */
 VALUE
 rb_measure_distance(VALUE self, VALUE point)
@@ -251,11 +238,14 @@ rb_measure_distance(VALUE self, VALUE point)
 }
 
 /*
- * call-seq:
- *    point_polygon_test(<i>point, measure_dist</i>) -> float
- *
  * Determines whether the point is inside a contour, outside, or lies on an edge (or coinsides with a vertex).
- * It returns positive, negative or zero value, correspondingly. When measure_dist = false or 0, the return value is +1, -1 and 0, respectively. When measure_dist = true or 1, it is a signed distance between the point and the nearest contour edge.
+ * @overload point_polygon_test(point, measure_dist)
+ *   @param point [CvPoint2D32f] Point tested against the contour
+ *   @param measure_dist [Boolean] If true, the method estimates the signed distance from the point to
+ *      the nearest contour edge. Otherwise, the function only checks if the point is inside a contour or not.
+ * @return [Number] When measure_dist = false, the return value is +1, -1 and 0, respectively.
+ *   When measure_dist = true, it is a signed distance between the point and the nearest contour edge.
+ * @opencv_func cvPointPolygonTest
  */
 VALUE
 rb_point_polygon_test(VALUE self, VALUE point, VALUE measure_dist)
@@ -291,6 +281,52 @@ VALUE new_object()
   return object;
 }
 
+
+void
+init_ruby_class()
+{
+#if 0
+  // For documentation using YARD
+  VALUE opencv = rb_define_module("OpenCV");
+  VALUE cvseq = rb_define_class_under(opencv, "CvSeq");
+  VALUE curve = rb_define_module_under(opencv, "Curve");
+  VALUE pointset = rb_define_module_under(opencv, "PointSet");
+#endif
+
+  if (rb_klass)
+    return;
+
+  VALUE opencv = rb_module_opencv();
+  VALUE cvseq = cCvSeq::rb_class();
+  VALUE curve = mCurve::rb_module();
+  VALUE pointset = mPointSet::rb_module();
+
+  rb_klass = rb_define_class_under(opencv, "CvContour", cvseq);
+  rb_include_module(rb_klass, curve);
+  rb_include_module(rb_klass, pointset);
+
+  rb_define_alloc_func(rb_klass, rb_allocate);
+
+  VALUE approx_option = rb_hash_new();
+  rb_define_const(rb_klass, "APPROX_OPTION", approx_option);
+  rb_hash_aset(approx_option, ID2SYM(rb_intern("method")), INT2FIX(CV_POLY_APPROX_DP));
+  rb_hash_aset(approx_option, ID2SYM(rb_intern("accuracy")), rb_float_new(1.0));
+  rb_hash_aset(approx_option, ID2SYM(rb_intern("recursive")), Qfalse);
+  
+  rb_define_method(rb_klass, "initialize", RUBY_METHOD_FUNC(rb_initialize), -1);
+  rb_define_method(rb_klass, "rect", RUBY_METHOD_FUNC(rb_rect), 0);
+  rb_define_method(rb_klass, "color", RUBY_METHOD_FUNC(rb_color), 0);
+  rb_define_method(rb_klass, "color=", RUBY_METHOD_FUNC(rb_set_color), 1);
+  rb_define_method(rb_klass, "reserved", RUBY_METHOD_FUNC(rb_reserved), 0);
+  rb_define_method(rb_klass, "approx_poly", RUBY_METHOD_FUNC(rb_approx_poly), -1);
+  rb_define_alias(rb_klass, "approx", "approx_poly");
+  rb_define_method(rb_klass, "bounding_rect", RUBY_METHOD_FUNC(rb_bounding_rect), 0);
+  rb_define_method(rb_klass, "create_tree", RUBY_METHOD_FUNC(rb_create_tree), -1);
+  rb_define_method(rb_klass, "in?", RUBY_METHOD_FUNC(rb_in_q), 1);
+  rb_define_method(rb_klass, "measure_distance", RUBY_METHOD_FUNC(rb_measure_distance), 1);
+  rb_define_method(rb_klass, "point_polygon_test", RUBY_METHOD_FUNC(rb_point_polygon_test), 2);
+}
+
 __NAMESPACE_END_CVCONTOUR
 __NAMESPACE_END_OPENCV
 

data/ext/opencv/cvcontour.h

@@ -19,7 +19,7 @@ __NAMESPACE_BEGIN_CVCONTOUR
 
 VALUE rb_class();
 
-void define_ruby_class();
+void init_ruby_class();
 
 VALUE rb_initialize(int argc, VALUE *argv, VALUE self);
 VALUE rb_rect(VALUE self);

data/ext/opencv/cvcontourtree.cpp

@@ -11,15 +11,9 @@
 /*
  * Document-class: OpenCV::CvContourTree
  *
- * Contour tree. CvContour#create_tree
+ * Contour tree
  *
- * C structure is here.
- *  typedef struct CvContourTree {
- *    CV_SEQUENCE_FIELDS()
- *    CvPoint p1;
- *    CvPoint p2;
- *  } CvContourTree;
- * 
+ * @see CvContour#create_tree
  */
 __NAMESPACE_BEGIN_OPENCV
 __NAMESPACE_BEGIN_CVCONTOURTREE
@@ -32,32 +26,22 @@ rb_class()
   return rb_klass;
 }
 
-void
-define_ruby_class()
-{
-  if (rb_klass)
-    return;
-  /* 
-   * opencv = rb_define_module("OpenCV");
-   * cvseq = rb_define_class_under(opencv, "CvSeq");
-   *
-   * note: this comment is used by rdoc.
-   */
-  VALUE opencv = rb_module_opencv();
-  VALUE cvseq = cCvSeq::rb_class();
-  
-  rb_klass = rb_define_class_under(opencv, "CvContourTree", cvseq);
-  rb_define_method(rb_klass, "p1", RUBY_METHOD_FUNC(rb_p1), 0);
-  rb_define_method(rb_klass, "p2", RUBY_METHOD_FUNC(rb_p2), 0);
-  rb_define_method(rb_klass, "contour", RUBY_METHOD_FUNC(rb_contour), 1);
-}
-
+/*
+ * Returns the first point of the binary tree root segment
+ * @overload p1
+ * @return [CvPoint] First point of the binary tree root segment
+ */
 VALUE
 rb_p1(VALUE self)
 {
   return REFER_OBJECT(cCvPoint::rb_class(), &CVCONTOURTREE(self)->p1, self);
 }
 
+/*
+ * Returns the last point of the binary tree root segment
+ * @overload p2
+ * @return [CvPoint] Last point of the binary tree root segment
+ */
 VALUE
 rb_p2(VALUE self)
 {
@@ -65,12 +49,14 @@ rb_p2(VALUE self)
 }
 
 /*
- * call-seq:
- *   contour(<i>[criteria = 0]</i>) -> cvcontour
- *
  * Restores the contour from its binary tree representation.
- * The parameter criteria determines the accuracy and/or the number of tree levels
+ *
+ * The parameter +criteria+ determines the accuracy and/or the number of tree levels
  * used for reconstruction, so it is possible to build approximated contour.
+ * @overload contour(criteria = 0)
+ *   @param criteria [Integer] Criteria, where to stop reconstruction
+ * @return [CvContour] Contour tree
+ * @opencv_func cvContourFromContourTree
  */
 VALUE
 rb_contour(VALUE self, VALUE criteria)
@@ -87,5 +73,24 @@ rb_contour(VALUE self, VALUE criteria)
   return cCvSeq::new_sequence(cCvContour::rb_class(), contour, cCvPoint::rb_class(), storage);
 }
 
+void
+init_ruby_class()
+{
+#if 0
+  // For documentation using YARD
+  VALUE opencv = rb_define_module("OpenCV");
+  VALUE cvseq = rb_define_class_under(opencv, "CvSeq");
+#endif
+  if (rb_klass)
+    return;
+  VALUE opencv = rb_module_opencv();
+  VALUE cvseq = cCvSeq::rb_class();
+
+  rb_klass = rb_define_class_under(opencv, "CvContourTree", cvseq);
+  rb_define_method(rb_klass, "p1", RUBY_METHOD_FUNC(rb_p1), 0);
+  rb_define_method(rb_klass, "p2", RUBY_METHOD_FUNC(rb_p2), 0);
+  rb_define_method(rb_klass, "contour", RUBY_METHOD_FUNC(rb_contour), 1);
+}
+
 __NAMESPACE_END_CVCONTOURTREE
 __NAMESPACE_END_OPENCV

data/ext/opencv/cvcontourtree.h

@@ -19,7 +19,7 @@ __NAMESPACE_BEGIN_CVCONTOURTREE
 
 VALUE rb_class();
 
-void define_ruby_class();
+void init_ruby_class();
 
 VALUE rb_p1(VALUE self);
 VALUE rb_p2(VALUE self);

data/ext/opencv/cvconvexitydefect.cpp

@@ -11,15 +11,7 @@
 /*
  * Document-class: OpenCV::CvConvexityDefect
  *
- * Convexity.
- * C structure is here.
- *   typedef struct CvConvexityDefect {
- *     CvPoint* start;
- *     CvPoint* end;
- *     CvPoint* depth_point;
- *     float depth;
- *   } CvConvexityDefect;
- *
+ * Convexity defect
  */
 __NAMESPACE_BEGIN_OPENCV
 __NAMESPACE_BEGIN_CVCONVEXITYDEFECT
@@ -32,30 +24,10 @@ rb_class()
   return rb_klass;
 }
 
-void
-define_ruby_class()
-{
-  if (rb_klass)
-    return;
-  /* 
-   * opencv = rb_define_module("OpenCV");
-   * 
-   * note: this comment is used by rdoc.
-   */
-  VALUE opencv = rb_module_opencv();
-  
-  rb_klass = rb_define_class_under(opencv, "CvConvexityDefect", rb_cObject);
-  rb_define_method(rb_klass, "start", RUBY_METHOD_FUNC(rb_start), 0);
-  rb_define_method(rb_klass, "end", RUBY_METHOD_FUNC(rb_end), 0);
-  rb_define_method(rb_klass, "depth_point", RUBY_METHOD_FUNC(rb_depth_point), 0);
-  rb_define_method(rb_klass, "depth", RUBY_METHOD_FUNC(rb_depth), 0);
-}
-
 /*
- * call-seq:
- *   start -> cvpoint
- *
- * Return start point as CvPoint.
+ * Returns the point of the contour where the defect begins
+ * @overload start
+ * @return [CvPoint] Start point of the contour
  */
 VALUE
 rb_start(VALUE self)
@@ -64,10 +36,9 @@ rb_start(VALUE self)
 }
 
 /*
- * call-seq:
- *   end -> cvpoint
- *
- * Return end point as CvPoint.
+ * Returns the point of the contour where the defect ends
+ * @overload end
+ * @return [CvPoint] End point of the contour
  */
 VALUE
 rb_end(VALUE self)
@@ -76,10 +47,9 @@ rb_end(VALUE self)
 }
 
 /*
- * call-seq:
- *   depth_point -> cvpoint
- *
- * Return depth point as CvPoint.
+ * Returns the farthest from the convex hull point within the defect
+ * @overload depth_point
+ * @return [CvPoint] The farthest from the convex hull point within the defect
  */
 VALUE
 rb_depth_point(VALUE self)
@@ -88,10 +58,9 @@ rb_depth_point(VALUE self)
 }
 
 /*
- * call-seq:
- *   depth -> float
- *
- * Return depth.
+ * Returns distance between the farthest point and the convex hull
+ * @overload depth
+ * @return [Number] Distance between the farthest point and the convex hull
  */
 VALUE
 rb_depth(VALUE self)
@@ -99,5 +68,25 @@ rb_depth(VALUE self)
   return rb_float_new(CVCONVEXITYDEFECT(self)->depth);
 }
 
+void
+init_ruby_class()
+{
+#if 0
+  // For documentation using YARD
+  VALUE opencv = rb_define_module("OpenCV");
+#endif
+
+  if (rb_klass)
+    return;
+
+  VALUE opencv = rb_module_opencv();
+
+  rb_klass = rb_define_class_under(opencv, "CvConvexityDefect", rb_cObject);
+  rb_define_method(rb_klass, "start", RUBY_METHOD_FUNC(rb_start), 0);
+  rb_define_method(rb_klass, "end", RUBY_METHOD_FUNC(rb_end), 0);
+  rb_define_method(rb_klass, "depth_point", RUBY_METHOD_FUNC(rb_depth_point), 0);
+  rb_define_method(rb_klass, "depth", RUBY_METHOD_FUNC(rb_depth), 0);
+}
+
 __NAMESPACE_END_CVCONVEXITYDEFECT
 __NAMESPACE_END_OPENCV