patch [#25027] formatting mathutils.geometry module docs for sphinx
[blender.git] / source / blender / python / generic / mathutils_geometry.c
index e57eb4ce83d481879117afb73c2a561b1e105684..673ce87d9cec7eb6ec699c897f954e014c00a317 100644 (file)
 
 /*-------------------------DOC STRINGS ---------------------------*/
 static char M_Geometry_doc[] = "The Blender geometry module\n\n";
-static char M_Geometry_Intersect_doc[] = "(v1, v2, v3, ray, orig, clip=1) - returns the intersection between a ray and a triangle, if possible, returns None otherwise";
-static char M_Geometry_TriangleArea_doc[] = "(v1, v2, v3) - returns the area size of the 2D or 3D triangle defined";
-static char M_Geometry_TriangleNormal_doc[] = "(v1, v2, v3) - returns the normal of the 3D triangle defined";
-static char M_Geometry_QuadNormal_doc[] = "(v1, v2, v3, v4) - returns the normal of the 3D quad defined";
-static char M_Geometry_LineIntersect_doc[] = "(v1, v2, v3, v4) - returns a tuple with the points on each line respectively closest to the other";
-static char M_Geometry_PolyFill_doc[] = "(veclist_list) - takes a list of polylines (each point a vector) and returns the point indicies for a polyline filled with triangles";
-static char M_Geometry_LineIntersect2D_doc[] = "(lineA_p1, lineA_p2, lineB_p1, lineB_p2) - takes 2 lines (as 4 vectors) and returns a vector for their point of intersection or None";
-static char M_Geometry_ClosestPointOnLine_doc[] = "(pt, line_p1, line_p2) - takes a point and a line and returns a (Vector, float) for the point on the line, and the bool so you can know if the point was between the 2 points";
-static char M_Geometry_PointInTriangle2D_doc[] = "(pt, tri_p1, tri_p2, tri_p3) - takes 4 vectors, one is the point and the next 3 define the triangle, only the x and y are used from the vectors";
-static char M_Geometry_PointInQuad2D_doc[] = "(pt, quad_p1, quad_p2, quad_p3, quad_p4) - takes 5 vectors, one is the point and the next 4 define the quad, only the x and y are used from the vectors";
+static char M_Geometry_Intersect_doc[] =
+".. function:: Intersect(v1, v2, v3, ray, orig, clip=True)\n"
+"\n"
+"   Returns the intersection between a ray and a triangle, if possible, returns None otherwise.\n"
+"\n"
+"   :rtype: boolean\n"
+"   :arg v1: Point1\n"
+"   :type v1: :class:`mathutils.Vector`\n"
+"   :arg v2: Point2\n"
+"   :type v2: :class:`mathutils.Vector`\n"
+"   :arg v3: Point3\n"
+"   :type v3: :class:`mathutils.Vector`\n"
+"   :arg ray: Direction of the projection\n"
+"   :type ray: :class:`mathutils.Vector`\n"
+"   :arg orig: Origin\n"
+"   :type orig: :class:`mathutils.Vector`\n"
+"   :arg clip: Clip by the ray length\n"
+"   :type clip: boolean\n";
+
+static char M_Geometry_TriangleArea_doc[] =
+".. function:: TriangleArea(v1, v2, v3)\n"
+"\n"
+"   Returns the area size of the 2D or 3D triangle defined.\n"
+"\n"
+"   :rtype: float\n"
+"   :arg v1: Point1\n"
+"   :type v1: :class:`mathutils.Vector`\n"
+"   :arg v2: Point2\n"
+"   :type v2: :class:`mathutils.Vector`\n"
+"   :arg v3: Point3\n"
+"   :type v3: :class:`mathutils.Vector`\n";
+
+static char M_Geometry_TriangleNormal_doc[] = 
+".. function:: TriangleNormal(v1, v2, v3)\n"
+"\n"
+"   Returns the normal of the 3D triangle defined.\n"
+"\n"
+"   :rtype: :class:`mathutils.Vector`\n"
+"   :arg v1: Point1\n"
+"   :type v1: :class:`mathutils.Vector`\n"
+"   :arg v2: Point2\n"
+"   :type v2: :class:`mathutils.Vector`\n"
+"   :arg v3: Point3\n"
+"   :type v3: :class:`mathutils.Vector`\n";
+
+static char M_Geometry_QuadNormal_doc[] = 
+".. function:: QuadNormal(v1, v2, v3, v4)\n"
+"\n"
+"   Returns the normal of the 3D quad defined.\n"
+"\n"
+"   :rtype: :class:`mathutils.Vector`\n"
+"   :arg v1: Point1\n"
+"   :type v1: :class:`mathutils.Vector`\n"
+"   :arg v2: Point2\n"
+"   :type v2: :class:`mathutils.Vector`\n"
+"   :arg v3: Point3\n"
+"   :type v3: :class:`mathutils.Vector`\n"
+"   :arg v4: Point4\n"
+"   :type v4: :class:`mathutils.Vector`\n";
+
+static char M_Geometry_LineIntersect_doc[] = 
+".. function:: LineIntersect(v1, v2, v3, v4)\n"
+"\n"
+"   Returns a tuple with the points on each line respectively closest to the other.\n"
+"\n"
+"   :rtype: tuple with elements being of type :class:`mathutils.Vector`\n"
+"   :arg v1: First point of the first line\n"
+"   :type v1: :class:`mathutils.Vector`\n"
+"   :arg v2: Second point of the first line\n"
+"   :type v2: :class:`mathutils.Vector`\n"
+"   :arg v3: First point of the second line\n"
+"   :type v3: :class:`mathutils.Vector`\n"
+"   :arg v4: Second point of the second line\n"
+"   :type v4: :class:`mathutils.Vector`\n";
+
+static char M_Geometry_PolyFill_doc[] = 
+".. function:: PolyFill(veclist_list)\n"
+"\n"
+"   Takes a list of polylines (each point a vector) and returns the point indicies for a polyline filled with triangles.\n"
+"\n"
+"   :rtype: list\n"
+"   :arg veclist_list: list of polylines\n";
+
+static char M_Geometry_LineIntersect2D_doc[] = 
+".. function:: LineIntersect2D(lineA_p1, lineA_p2, lineB_p1, lineB_p2)\n"
+"\n"
+"   Takes 2 lines (as 4 vectors) and returns a vector for their point of intersection or None.\n"
+"\n"
+"   :rtype: :class:`mathutils.Vector`\n"
+"   :arg lineA_p1: First point of the first line\n"
+"   :type lineA_p1: :class:`mathutils.Vector`\n"
+"   :arg lineA_p2: Second point of the first line\n"
+"   :type lineA_p2: :class:`mathutils.Vector`\n"
+"   :arg lineB_p1: First point of the second line\n"
+"   :type lineB_p1: :class:`mathutils.Vector`\n"
+"   :arg lineB_p2: Second point of the second line\n"
+"   :type lineB_p2: :class:`mathutils.Vector`\n";
+
+static char M_Geometry_ClosestPointOnLine_doc[] =
+".. function:: ClosestPointOnLine(pt, line_p1, line_p2)\n"
+"\n"
+"   Takes a point and a line and returns a tuple with the closest point on the line and its distance from the first point of the line as a percentage of the length of the line.\n"
+"\n"
+"   :rtype: (:class:`mathutils.Vector`, float)\n"
+"   :arg pt: Point\n"
+"   :type pt: :class:`mathutils.Vector`\n"
+"   :arg line_p1: First point of the line\n"
+"   :type line_p1: :class:`mathutils.Vector`\n"
+"   :arg line_p1: Second point of the line\n"
+"   :type line_p1: :class:`mathutils.Vector`\n";
+
+static char M_Geometry_PointInTriangle2D_doc[] = 
+".. function:: PointInTriangle2D(pt, tri_p1, tri_p2, tri_p3)\n"
+"\n"
+"   Takes 4 vectors (using only the x and y coordinates): one is the point and the next 3 define the triangle. Returns 1 if the point is within the triangle, otherwise 0.\n"
+"\n"
+"   :rtype: int\n"
+"   :arg pt: Point\n"
+"   :type v1: :class:`mathutils.Vector`\n"
+"   :arg tri_p1: First point of the triangle\n"
+"   :type tri_p1: :class:`mathutils.Vector`\n"
+"   :arg tri_p2: Second point of the triangle\n"
+"   :type tri_p2: :class:`mathutils.Vector`\n"
+"   :arg tri_p3: Third point of the triangle\n"
+"   :type tri_p3: :class:`mathutils.Vector`\n";
+
+static char M_Geometry_PointInQuad2D_doc[] =
+".. function:: PointInQuad2D(pt, quad_p1, quad_p2, quad_p3, quad_p4)\n"
+"\n"
+"   Takes 5 vectors (using only the x and y coordinates): one is the point and the next 4 define the quad, only the x and y are used from the vectors. Returns 1 if the point is within the quad, otherwise 0.\n"
+"\n"
+"   :rtype: int\n"
+"   :arg pt: Point\n"
+"   :type v1: :class:`mathutils.Vector`\n"
+"   :arg quad_p1: First point of the quad\n"
+"   :type quad_p1: :class:`mathutils.Vector`\n"
+"   :arg quad_p2: Second point of the quad\n"
+"   :type quad_p2: :class:`mathutils.Vector`\n"
+"   :arg quad_p3: Third point of the quad\n"
+"   :type quad_p3: :class:`mathutils.Vector`\n"
+"   :arg quad_p4: Forth point of the quad\n"
+"   :type quad_p4: :class:`mathutils.Vector`\n";
+
 static char M_Geometry_BoxPack2D_doc[] = "";
 static char M_Geometry_BezierInterp_doc[] = "";
+static char M_Geometry_BarycentricTransform_doc[] = "";
 
 //---------------------------------INTERSECTION FUNCTIONS--------------------
 //----------------------------------geometry.Intersect() -------------------
@@ -68,11 +202,11 @@ static PyObject *M_Geometry_Intersect(PyObject *UNUSED(self), PyObject* args)
        int clip = 1;
 
        if(!PyArg_ParseTuple(args, "O!O!O!O!O!|i", &vector_Type, &vec1, &vector_Type, &vec2, &vector_Type, &vec3, &vector_Type, &ray, &vector_Type, &ray_off , &clip)) {
-               PyErr_SetString( PyExc_TypeError, "expected 5 vector types\n" );
+               PyErr_SetString(PyExc_TypeError, "expected 5 vector types" );
                return NULL;
        }
        if(vec1->size != 3 || vec2->size != 3 || vec3->size != 3 || ray->size != 3 || ray_off->size != 3) {
-               PyErr_SetString( PyExc_TypeError, "only 3D vectors for all parameters\n");
+               PyErr_SetString(PyExc_TypeError, "only 3D vectors for all parameters");
                return NULL;
        }
 
@@ -140,11 +274,11 @@ static PyObject *M_Geometry_LineIntersect(PyObject *UNUSED(self), PyObject* args
        float v1[3], v2[3], v3[3], v4[3], i1[3], i2[3];
 
        if( !PyArg_ParseTuple( args, "O!O!O!O!", &vector_Type, &vec1, &vector_Type, &vec2, &vector_Type, &vec3, &vector_Type, &vec4 ) ) {
-               PyErr_SetString( PyExc_TypeError, "expected 4 vector types\n" );
+               PyErr_SetString(PyExc_TypeError, "expected 4 vector types" );
                return NULL;
        }
        if( vec1->size != vec2->size || vec1->size != vec3->size || vec3->size != vec2->size) {
-               PyErr_SetString( PyExc_TypeError,"vectors must be of the same size\n" );
+               PyErr_SetString(PyExc_TypeError,"vectors must be of the same size" );
                return NULL;
        }
 
@@ -192,7 +326,7 @@ static PyObject *M_Geometry_LineIntersect(PyObject *UNUSED(self), PyObject* args
                }
        }
        else {
-               PyErr_SetString( PyExc_TypeError, "2D/3D vectors only\n" );
+               PyErr_SetString(PyExc_TypeError, "2D/3D vectors only" );
                return NULL;
        }
 }
@@ -210,15 +344,15 @@ static PyObject *M_Geometry_QuadNormal(PyObject *UNUSED(self), PyObject* args)
        float v1[3], v2[3], v3[3], v4[3], e1[3], e2[3], n1[3], n2[3];
 
        if( !PyArg_ParseTuple( args, "O!O!O!O!", &vector_Type, &vec1, &vector_Type, &vec2, &vector_Type, &vec3, &vector_Type, &vec4 ) ) {
-               PyErr_SetString( PyExc_TypeError, "expected 4 vector types\n" );
+               PyErr_SetString(PyExc_TypeError, "expected 4 vector types" );
                return NULL;
        }
        if( vec1->size != vec2->size || vec1->size != vec3->size || vec1->size != vec4->size) {
-               PyErr_SetString( PyExc_TypeError,"vectors must be of the same size\n" );
+               PyErr_SetString(PyExc_TypeError,"vectors must be of the same size" );
                return NULL;
        }
        if( vec1->size != 3 ) {
-               PyErr_SetString( PyExc_TypeError, "only 3D vectors\n" );
+               PyErr_SetString(PyExc_TypeError, "only 3D vectors" );
                return NULL;
        }
 
@@ -258,15 +392,15 @@ static PyObject *M_Geometry_TriangleNormal(PyObject *UNUSED(self), PyObject* arg
        float v1[3], v2[3], v3[3], e1[3], e2[3], n[3];
 
        if( !PyArg_ParseTuple( args, "O!O!O!", &vector_Type, &vec1, &vector_Type, &vec2, &vector_Type, &vec3 ) ) {
-               PyErr_SetString( PyExc_TypeError, "expected 3 vector types\n" );
+               PyErr_SetString(PyExc_TypeError, "expected 3 vector types" );
                return NULL;
        }
        if( vec1->size != vec2->size || vec1->size != vec3->size ) {
-               PyErr_SetString( PyExc_TypeError, "vectors must be of the same size\n" );
+               PyErr_SetString(PyExc_TypeError, "vectors must be of the same size" );
                return NULL;
        }
        if( vec1->size != 3 ) {
-               PyErr_SetString( PyExc_TypeError, "only 3D vectors\n" );
+               PyErr_SetString(PyExc_TypeError, "only 3D vectors" );
                return NULL;
        }
 
@@ -297,11 +431,11 @@ static PyObject *M_Geometry_TriangleArea(PyObject *UNUSED(self), PyObject* args)
        if( !PyArg_ParseTuple
                ( args, "O!O!O!", &vector_Type, &vec1, &vector_Type, &vec2
                , &vector_Type, &vec3 ) ) {
-               PyErr_SetString( PyExc_TypeError, "expected 3 vector types\n");
+               PyErr_SetString(PyExc_TypeError, "expected 3 vector types");
                return NULL;
        }
        if( vec1->size != vec2->size || vec1->size != vec3->size ) {
-               PyErr_SetString( PyExc_TypeError, "vectors must be of the same size\n" );
+               PyErr_SetString(PyExc_TypeError, "vectors must be of the same size" );
                return NULL;
        }
 
@@ -328,7 +462,7 @@ static PyObject *M_Geometry_TriangleArea(PyObject *UNUSED(self), PyObject* args)
                return PyFloat_FromDouble( area_tri_v2(v1, v2, v3) );
        }
        else {
-               PyErr_SetString( PyExc_TypeError, "only 2D,3D vectors are supported\n" );
+               PyErr_SetString(PyExc_TypeError, "only 2D,3D vectors are supported" );
                return NULL;
        }
 }
@@ -352,7 +486,7 @@ static PyObject *M_Geometry_PolyFill(PyObject *UNUSED(self), PyObject * polyLine
        
        
        if(!PySequence_Check(polyLineSeq)) {
-               PyErr_SetString( PyExc_TypeError, "expected a sequence of poly lines" );
+               PyErr_SetString(PyExc_TypeError, "expected a sequence of poly lines" );
                return NULL;
        }
        
@@ -363,7 +497,7 @@ static PyObject *M_Geometry_PolyFill(PyObject *UNUSED(self), PyObject * polyLine
                if (!PySequence_Check(polyLine)) {
                        freedisplist(&dispbase);
                        Py_XDECREF(polyLine); /* may be null so use Py_XDECREF*/
-                       PyErr_SetString( PyExc_TypeError, "One or more of the polylines is not a sequence of mathutils.Vector's" );
+                       PyErr_SetString(PyExc_TypeError, "One or more of the polylines is not a sequence of mathutils.Vector's" );
                        return NULL;
                }
                
@@ -373,7 +507,7 @@ static PyObject *M_Geometry_PolyFill(PyObject *UNUSED(self), PyObject * polyLine
                        if (EXPP_check_sequence_consistency( polyLine, &vector_Type ) != 1) {
                                freedisplist(&dispbase);
                                Py_DECREF(polyLine);
-                               PyErr_SetString( PyExc_TypeError, "A point in one of the polylines is not a mathutils.Vector type" );
+                               PyErr_SetString(PyExc_TypeError, "A point in one of the polylines is not a mathutils.Vector type" );
                                return NULL;
                        }
 #endif
@@ -414,7 +548,7 @@ static PyObject *M_Geometry_PolyFill(PyObject *UNUSED(self), PyObject * polyLine
        
        if(ls_error) {
                freedisplist(&dispbase); /* possible some dl was allocated */
-               PyErr_SetString( PyExc_TypeError, "A point in one of the polylines is not a mathutils.Vector type" );
+               PyErr_SetString(PyExc_TypeError, "A point in one of the polylines is not a mathutils.Vector type" );
                return NULL;
        }
        else if (totpoints) {
@@ -428,14 +562,14 @@ static PyObject *M_Geometry_PolyFill(PyObject *UNUSED(self), PyObject * polyLine
                tri_list= PyList_New(dl->parts);
                if( !tri_list ) {
                        freedisplist(&dispbase);
-                       PyErr_SetString( PyExc_RuntimeError, "geometry.PolyFill failed to make a new list" );
+                       PyErr_SetString(PyExc_RuntimeError, "geometry.PolyFill failed to make a new list" );
                        return NULL;
                }
                
                index= 0;
                dl_face= dl->index;
                while(index < dl->parts) {
-                       PyList_SetItem(tri_list, index, Py_BuildValue("iii", dl_face[0], dl_face[1], dl_face[2]) );
+                       PyList_SET_ITEM(tri_list, index, Py_BuildValue("iii", dl_face[0], dl_face[1], dl_face[2]) );
                        dl_face+= 3;
                        index++;
                }
@@ -460,7 +594,7 @@ static PyObject *M_Geometry_LineIntersect2D(PyObject *UNUSED(self), PyObject* ar
          &vector_Type, &line_b1,
          &vector_Type, &line_b2)
        ) {
-               PyErr_SetString( PyExc_TypeError, "expected 4 vector types\n" );
+               PyErr_SetString(PyExc_TypeError, "expected 4 vector types" );
                return NULL;
        }
        
@@ -560,7 +694,7 @@ static PyObject *M_Geometry_ClosestPointOnLine(PyObject *UNUSED(self), PyObject*
        &vector_Type, &line_1,
        &vector_Type, &line_2)
          ) {
-               PyErr_SetString( PyExc_TypeError, "expected 3 vector types\n" );
+               PyErr_SetString(PyExc_TypeError, "expected 3 vector types" );
                return NULL;
        }
        
@@ -596,7 +730,7 @@ static PyObject *M_Geometry_PointInTriangle2D(PyObject *UNUSED(self), PyObject*
          &vector_Type, &tri_p2,
          &vector_Type, &tri_p3)
        ) {
-               PyErr_SetString( PyExc_TypeError, "expected 4 vector types\n" );
+               PyErr_SetString(PyExc_TypeError, "expected 4 vector types" );
                return NULL;
        }
        
@@ -617,7 +751,7 @@ static PyObject *M_Geometry_PointInQuad2D(PyObject *UNUSED(self), PyObject* args
          &vector_Type, &quad_p3,
          &vector_Type, &quad_p4)
        ) {
-               PyErr_SetString( PyExc_TypeError, "expected 5 vector types\n" );
+               PyErr_SetString(PyExc_TypeError, "expected 5 vector types" );
                return NULL;
        }
        
@@ -636,7 +770,7 @@ static int boxPack_FromPyObject(PyObject * value, boxPack **boxarray )
        
        /* Error checking must already be done */
        if( !PyList_Check( value ) ) {
-               PyErr_SetString( PyExc_TypeError, "can only back a list of [x,y,x,w]" );
+               PyErr_SetString(PyExc_TypeError, "can only back a list of [x,y,x,w]" );
                return -1;
        }
        
@@ -649,7 +783,7 @@ static int boxPack_FromPyObject(PyObject * value, boxPack **boxarray )
                list_item = PyList_GET_ITEM( value, i );
                if( !PyList_Check( list_item ) || PyList_Size( list_item ) < 4 ) {
                        MEM_freeN(*boxarray);
-                       PyErr_SetString( PyExc_TypeError, "can only back a list of [x,y,x,w]" );
+                       PyErr_SetString(PyExc_TypeError, "can only back a list of [x,y,x,w]" );
                        return -1;
                }
                
@@ -660,7 +794,7 @@ static int boxPack_FromPyObject(PyObject * value, boxPack **boxarray )
                
                if (!PyNumber_Check(item_1) || !PyNumber_Check(item_2)) {
                        MEM_freeN(*boxarray);
-                       PyErr_SetString( PyExc_TypeError, "can only back a list of 2d boxes [x,y,x,w]" );
+                       PyErr_SetString(PyExc_TypeError, "can only back a list of 2d boxes [x,y,x,w]" );
                        return -1;
                }
                
@@ -698,7 +832,7 @@ static PyObject *M_Geometry_BoxPack2D(PyObject *UNUSED(self), PyObject * boxlist
        int error;
        
        if(!PyList_Check(boxlist)) {
-               PyErr_SetString( PyExc_TypeError, "expected a sequence of boxes [[x,y,w,h], ... ]" );
+               PyErr_SetString(PyExc_TypeError, "expected a sequence of boxes [[x,y,w,h], ... ]" );
                return NULL;
        }
        
@@ -739,7 +873,7 @@ static PyObject *M_Geometry_BezierInterp(PyObject *UNUSED(self), PyObject* args)
          &vector_Type, &vec_h2,
          &vector_Type, &vec_k2, &resolu) || (resolu<=1)
        ) {
-               PyErr_SetString( PyExc_TypeError, "expected 4 vector types and an int greater then 1\n" );
+               PyErr_SetString(PyExc_TypeError, "expected 4 vector types and an int greater then 1" );
                return NULL;
        }
        
@@ -789,7 +923,7 @@ static PyObject *M_Geometry_BarycentricTransform(PyObject *UNUSED(self), PyObjec
                                                                                vec_t2_tar->size != 3 ||
                                                                                vec_t3_tar->size != 3)
        ) {
-               PyErr_SetString( PyExc_TypeError, "expected 7, 3D vector types\n" );
+               PyErr_SetString(PyExc_TypeError, "expected 7, 3D vector types" );
                return NULL;
        }
 
@@ -813,7 +947,7 @@ struct PyMethodDef M_Geometry_methods[] = {
        {"PointInQuad2D", ( PyCFunction ) M_Geometry_PointInQuad2D, METH_VARARGS, M_Geometry_PointInQuad2D_doc},
        {"BoxPack2D", ( PyCFunction ) M_Geometry_BoxPack2D, METH_O, M_Geometry_BoxPack2D_doc},
        {"BezierInterp", ( PyCFunction ) M_Geometry_BezierInterp, METH_VARARGS, M_Geometry_BezierInterp_doc},
-       {"BarycentricTransform", ( PyCFunction ) M_Geometry_BarycentricTransform, METH_VARARGS, NULL},
+       {"BarycentricTransform", ( PyCFunction ) M_Geometry_BarycentricTransform, METH_VARARGS, M_Geometry_BarycentricTransform_doc},
        {NULL, NULL, 0, NULL}
 };