2 * ***** BEGIN GPL LICENSE BLOCK *****
4 * This program is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU General Public License
6 * as published by the Free Software Foundation; either version 2
7 * of the License, or (at your option) any later version.
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
14 * You should have received a copy of the GNU General Public License
15 * along with this program; if not, write to the Free Software Foundation,
16 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * The Original Code is Copyright (C) 2012 Blender Foundation.
19 * All rights reserved.
21 * Contributor(s): Campbell Barton
23 * ***** END GPL LICENSE BLOCK *****
26 /** \file blender/python/bmesh/bmesh_py_utils.c
29 * This file defines the 'bmesh.utils' module.
30 * Utility functions for operating on 'bmesh.types'
35 #include "BLI_utildefines.h"
37 #include "MEM_guardedalloc.h"
39 #include "../mathutils/mathutils.h"
43 #include "bmesh_py_types.h"
45 #include "bmesh_py_utils.h" /* own include */
48 PyDoc_STRVAR(bpy_bm_utils_vert_collapse_edge_doc,
49 ".. method:: vert_collapse_edge(vert, edge)\n"
51 " Collapse a vertex into an edge.\n"
53 " :arg vert: The vert that will be collapsed.\n"
54 " :type vert: :class:`bmesh.types.BMVert`\n"
55 " :arg edge: The edge to collapse into.\n"
56 " :type edge: :class:`bmesh.types.BMEdge`\n"
57 " :return: The resulting edge from the collapse operation.\n"
58 " :rtype: :class:`bmesh.types.BMEdge`\n"
60 static PyObject *bpy_bm_utils_vert_collapse_edge(PyObject *UNUSED(self), PyObject *args)
68 if (!PyArg_ParseTuple(args, "O!O!:vert_collapse_edge",
69 &BPy_BMVert_Type, &py_vert,
70 &BPy_BMEdge_Type, &py_edge))
75 BPY_BM_CHECK_OBJ(py_edge);
76 BPY_BM_CHECK_OBJ(py_vert);
78 /* this doubles for checking that the verts are in the same mesh */
79 if (!(py_edge->e->v1 == py_vert->v ||
80 py_edge->e->v2 == py_vert->v))
82 PyErr_SetString(PyExc_ValueError,
83 "vert_collapse_edge(vert, edge): the vertex is not found in the edge");
87 if (BM_vert_edge_count(py_vert->v) > 2) {
88 PyErr_SetString(PyExc_ValueError,
89 "vert_collapse_edge(vert, edge): vert has more then 2 connected edges");
95 e_new = BM_vert_collapse_edge(bm, py_edge->e, py_vert->v, TRUE);
98 return BPy_BMEdge_CreatePyObject(bm, e_new);
101 PyErr_SetString(PyExc_ValueError,
102 "vert_collapse_edge(vert, edge): no new edge created, internal error");
108 PyDoc_STRVAR(bpy_bm_utils_vert_collapse_faces_doc,
109 ".. method:: vert_collapse_faces(vert, edge, fac, join_faces)\n"
111 " Split an edge, return the newly created data.\n"
113 " :arg vert: The vert that will be collapsed.\n"
114 " :type vert: :class:`bmesh.types.BMVert`\n"
115 " :arg edge: The edge to collapse into.\n"
116 " :type edge: :class:`bmesh.types.BMEdge`\n"
117 " :arg fac: The factor to use when merging customdata [0 - 1].\n"
118 " :type fac: float\n"
119 " :return: The resulting edge from the collapse operation.\n"
120 " :rtype: :class:`bmesh.types.BMEdge`\n"
122 static PyObject *bpy_bm_utils_vert_collapse_faces(PyObject *UNUSED(self), PyObject *args)
131 BMEdge *e_new = NULL;
133 if (!PyArg_ParseTuple(args, "O!O!fi:vert_collapse_faces",
134 &BPy_BMVert_Type, &py_vert,
135 &BPy_BMEdge_Type, &py_edge,
136 &fac, &do_join_faces))
141 BPY_BM_CHECK_OBJ(py_edge);
142 BPY_BM_CHECK_OBJ(py_vert);
144 /* this doubles for checking that the verts are in the same mesh */
145 if (!(py_edge->e->v1 == py_vert->v ||
146 py_edge->e->v2 == py_vert->v))
148 PyErr_SetString(PyExc_ValueError,
149 "vert_collapse_faces(vert, edge): the vertex is not found in the edge");
153 if (BM_vert_edge_count(py_vert->v) > 2) {
154 PyErr_SetString(PyExc_ValueError,
155 "vert_collapse_faces(vert, edge): vert has more then 2 connected edges");
161 e_new = BM_vert_collapse_faces(bm, py_edge->e, py_vert->v, CLAMPIS(fac, 0.0f, 1.0f), do_join_faces, TRUE);
164 return BPy_BMEdge_CreatePyObject(bm, e_new);
167 PyErr_SetString(PyExc_ValueError,
168 "vert_collapse_edge(vert, edge): no new edge created, internal error");
174 PyDoc_STRVAR(bpy_bm_utils_vert_dissolve_doc,
175 ".. method:: vert_dissolve(vert)\n"
177 " Dissolve this vertex (will be removed).\n"
179 " :arg vert: The vert to be dissolved.\n"
180 " :type vert: :class:`bmesh.types.BMVert`\n"
181 " :return: True when the vertex dissolve is successful.\n"
184 static PyObject *bpy_bm_utils_vert_dissolve(PyObject *UNUSED(self), PyObject *args)
190 if (!PyArg_ParseTuple(args, "O!:vert_dissolve",
191 &BPy_BMVert_Type, &py_vert))
196 BPY_BM_CHECK_OBJ(py_vert);
200 return PyBool_FromLong((BM_vert_dissolve(bm, py_vert->v)));
203 PyDoc_STRVAR(bpy_bm_utils_vert_separate_doc,
204 ".. method:: vert_separate(vert, edges)\n"
206 " Separate this vertex at every edge.\n"
208 " :arg vert: The vert to be separated.\n"
209 " :type vert: :class:`bmesh.types.BMVert`\n"
210 " :arg edges: The edges to separated.\n"
211 " :type edges: :class:`bmesh.types.BMEdge`\n"
212 " :return: The newly separated verts (including the vertex passed).\n"
213 " :rtype: tuple of :class:`bmesh.types.BMVert`\n"
215 static PyObject *bpy_bm_utils_vert_separate(PyObject *UNUSED(self), PyObject *args)
226 Py_ssize_t edge_array_len;
231 if (!PyArg_ParseTuple(args, "O!O:vert_separate",
232 &BPy_BMVert_Type, &py_vert,
238 BPY_BM_CHECK_OBJ(py_vert);
242 edge_array = BPy_BMElem_PySeq_As_Array(&bm, edge_seq, 0, PY_SSIZE_T_MAX,
243 &edge_array_len, BM_EDGE,
244 TRUE, TRUE, "vert_separate(...)");
246 if (edge_array == NULL) {
250 if (BM_vert_separate(bm, py_vert->v, &elem, &elem_len, edge_array, edge_array_len)) {
251 /* return collected verts */
252 ret = BPy_BMElem_Array_As_Tuple(bm, (BMHeader **)elem, elem_len);
256 ret = PyTuple_New(0);
259 PyMem_FREE(edge_array);
265 PyDoc_STRVAR(bpy_bm_utils_edge_split_doc,
266 ".. method:: edge_split(edge, vert, fac)\n"
268 " Split an edge, return the newly created data.\n"
270 " :arg edge: The edge to split.\n"
271 " :type edge: :class:`bmesh.types.BMEdge`\n"
272 " :arg vert: One of the verts on the edge, defines the split direction.\n"
273 " :type vert: :class:`bmesh.types.BMVert`\n"
274 " :arg fac: The point on the edge where the new vert will be created [0 - 1].\n"
275 " :type fac: float\n"
276 " :return: The newly created (edge, vert) pair.\n"
279 static PyObject *bpy_bm_utils_edge_split(PyObject *UNUSED(self), PyObject *args)
286 BMVert *v_new = NULL;
287 BMEdge *e_new = NULL;
289 if (!PyArg_ParseTuple(args, "O!O!f:edge_split",
290 &BPy_BMEdge_Type, &py_edge,
291 &BPy_BMVert_Type, &py_vert,
297 BPY_BM_CHECK_OBJ(py_edge);
298 BPY_BM_CHECK_OBJ(py_vert);
300 /* this doubles for checking that the verts are in the same mesh */
301 if (!(py_edge->e->v1 == py_vert->v ||
302 py_edge->e->v2 == py_vert->v))
304 PyErr_SetString(PyExc_ValueError,
305 "edge_split(edge, vert): the vertex is not found in the edge");
311 v_new = BM_edge_split(bm, py_edge->e, py_vert->v, &e_new, CLAMPIS(fac, 0.0f, 1.0f));
313 if (v_new && e_new) {
314 PyObject *ret = PyTuple_New(2);
315 PyTuple_SET_ITEM(ret, 0, BPy_BMEdge_CreatePyObject(bm, e_new));
316 PyTuple_SET_ITEM(ret, 1, BPy_BMVert_CreatePyObject(bm, v_new));
320 PyErr_SetString(PyExc_ValueError,
321 "edge_split(edge, vert): couldn't split the edge, internal error");
327 PyDoc_STRVAR(bpy_bm_utils_edge_rotate_doc,
328 ".. method:: edge_rotate(edge, ccw=False)\n"
330 " Rotate the edge and return the newly created edge.\n"
331 " If rotating the edge fails, None will be returned.\n"
333 " :arg edge: The edge to rotate.\n"
334 " :type edge: :class:`bmesh.types.BMEdge`\n"
335 " :arg ccw: When True the edge will be rotated counter clockwise.\n"
336 " :type ccw: boolean\n"
337 " :return: The newly rotated edge.\n"
338 " :rtype: :class:`bmesh.types.BMEdge`\n"
340 static PyObject *bpy_bm_utils_edge_rotate(PyObject *UNUSED(self), PyObject *args)
346 BMEdge *e_new = NULL;
348 if (!PyArg_ParseTuple(args, "O!|i:edge_rotate",
349 &BPy_BMEdge_Type, &py_edge,
355 BPY_BM_CHECK_OBJ(py_edge);
359 e_new = BM_edge_rotate(bm, py_edge->e, do_ccw, 0); /* BMESH_TODO - expose to API */
362 return BPy_BMEdge_CreatePyObject(bm, e_new);
370 PyDoc_STRVAR(bpy_bm_utils_face_split_doc,
371 ".. method:: face_split(face, vert_a, vert_b, coords=(), use_exist=True, example=None)\n"
373 " Face split with optional intermediate points.\n"
375 " :arg face: The face to cut.\n"
376 " :type face: :class:`bmesh.types.BMFace`\n"
377 " :arg vert_a: First vertex to cut in the face (face must contain the vert).\n"
378 " :type vert_a: :class:`bmesh.types.BMVert`\n"
379 " :arg vert_b: Second vertex to cut in the face (face must contain the vert).\n"
380 " :type vert_b: :class:`bmesh.types.BMVert`\n"
381 " :arg coords: Optional argument to define points inbetween *vert_a* and *vert_b*.\n"
382 " :type coords: sequence of float triplets\n"
383 " :arg use_exist: .Use an existing edge if it exists (Only used when *coords* argument is empty or omitted)\n"
384 " :type use_exist: boolean\n"
385 " :arg example: Newly created edge will copy settings from this one.\n"
386 " :type example: :class:`bmesh.types.BMEdge`\n"
387 " :return: The newly created face or None on failure.\n"
388 " :rtype: (:class:`bmesh.types.BMFace`, :class:`bmesh.types.BMLoop`) pair\n"
390 static PyObject *bpy_bm_utils_face_split(PyObject *UNUSED(self), PyObject *args, PyObject *kw)
392 static const char *kwlist[] = {"face", "vert_a", "vert_b",
393 "coords", "use_exist", "example", NULL};
396 BPy_BMVert *py_vert_a;
397 BPy_BMVert *py_vert_b;
400 PyObject *py_coords = NULL;
401 int edge_exists = TRUE;
402 BPy_BMEdge *py_edge_example = NULL;
408 BMFace *f_new = NULL;
409 BMLoop *l_new = NULL;
411 if (!PyArg_ParseTupleAndKeywords(args, kw, "O!O!O!|OiO!:face_split", (char **)kwlist,
412 &BPy_BMFace_Type, &py_face,
413 &BPy_BMVert_Type, &py_vert_a,
414 &BPy_BMVert_Type, &py_vert_b,
417 &BPy_BMEdge_Type, &py_edge_example))
422 BPY_BM_CHECK_OBJ(py_face);
423 BPY_BM_CHECK_OBJ(py_vert_a);
424 BPY_BM_CHECK_OBJ(py_vert_b);
426 if (py_edge_example) {
427 BPY_BM_CHECK_OBJ(py_edge_example);
430 /* this doubles for checking that the verts are in the same mesh */
431 if (BM_vert_in_face(py_face->f, py_vert_a->v) == FALSE ||
432 BM_vert_in_face(py_face->f, py_vert_b->v) == FALSE)
434 PyErr_SetString(PyExc_ValueError,
435 "face_split(...): one of the verts passed is not found in the face");
439 if (py_vert_a->v == py_vert_b->v) {
440 PyErr_SetString(PyExc_ValueError,
441 "face_split(...): vert arguments must differ");
446 ncoords = mathutils_array_parse_alloc_v(&coords, 3, py_coords, "face_split(...): ");
452 /* --- main function body --- */
456 f_new = BM_face_split_n(bm, py_face->f,
457 py_vert_a->v, py_vert_b->v,
458 (float (*)[3])coords, ncoords,
459 &l_new, py_edge_example ? py_edge_example->e : NULL);
462 f_new = BM_face_split(bm, py_face->f,
463 py_vert_a->v, py_vert_b->v,
464 &l_new, py_edge_example ? py_edge_example->e : NULL, edge_exists);
467 if (f_new && l_new) {
468 PyObject *ret = PyTuple_New(2);
469 PyTuple_SET_ITEM(ret, 0, BPy_BMFace_CreatePyObject(bm, f_new));
470 PyTuple_SET_ITEM(ret, 1, BPy_BMLoop_CreatePyObject(bm, l_new));
474 PyErr_SetString(PyExc_ValueError,
475 "face_split(...): couldn't split the face, internal error");
481 PyDoc_STRVAR(bpy_bm_utils_face_join_doc,
482 ".. method:: face_join(faces, remove=True)\n"
484 " Joins a sequence of faces.\n"
486 " :arg faces: Sequence of faces.\n"
487 " :type faces: :class:`bmesh.types.BMFace`\n"
488 " :arg remove: Remove the edges and vertices between the faces.\n"
489 " :type remove: boolean\n"
490 " :return: The newly created face or None on failure.\n"
491 " :rtype: :class:`bmesh.types.BMFace`\n"
493 static PyObject *bpy_bm_utils_face_join(PyObject *UNUSED(self), PyObject *args)
496 PyObject *py_face_array;
498 Py_ssize_t face_seq_len = 0;
500 int do_remove = TRUE;
502 if (!PyArg_ParseTuple(args, "O|i:face_join", &py_face_array, &do_remove)) {
506 face_array = BPy_BMElem_PySeq_As_Array(&bm, py_face_array, 2, PY_SSIZE_T_MAX,
507 &face_seq_len, BM_FACE,
508 TRUE, TRUE, "face_join(...)");
510 if (face_array == NULL) {
511 return NULL; /* error will be set */
514 /* Go ahead and join the face!
515 * --------------------------- */
516 f_new = BM_faces_join(bm, face_array, (int)face_seq_len, do_remove);
518 PyMem_FREE(face_array);
521 return BPy_BMFace_CreatePyObject(bm, f_new);
529 PyDoc_STRVAR(bpy_bm_utils_face_vert_separate_doc,
530 ".. method:: face_vert_separate(face, vert)\n"
532 " Rip a vertex in a face away and add a new vertex.\n"
534 " :arg face: The face to separate.\n"
535 " :type face: :class:`bmesh.types.BMFace`\n"
536 " :arg vert: A vertex in the face to separate.\n"
537 " :type vert: :class:`bmesh.types.BMVert`\n"
538 " :return vert: The newly created vertex or None of failure.\n"
539 " :rtype vert: :class:`bmesh.types.BMVert`\n"
543 " This is the same as loop_separate, and has only been added for convenience.\n"
545 static PyObject *bpy_bm_utils_face_vert_separate(PyObject *UNUSED(self), PyObject *args)
554 if (!PyArg_ParseTuple(args, "O!O!:face_vert_separate",
555 &BPy_BMFace_Type, &py_face,
556 &BPy_BMVert_Type, &py_vert))
561 BPY_BM_CHECK_OBJ(py_face);
562 BPY_BM_CHECK_OBJ(py_vert);
566 if (bm != py_vert->bm) {
567 PyErr_SetString(PyExc_ValueError,
568 "mesh elements are from different meshes");
572 l = BM_face_vert_share_loop(py_face->f, py_vert->v);
575 PyErr_SetString(PyExc_ValueError,
576 "vertex not found in face");
580 v_new = BM_face_loop_separate(bm, l);
583 return BPy_BMVert_CreatePyObject(bm, v_new);
591 PyDoc_STRVAR(bpy_bm_utils_face_flip_doc,
592 ".. method:: face_flip(faces)\n"
594 " Flip the faces direction.\n"
596 " :arg face: Face to flip.\n"
597 " :type face: :class:`bmesh.types.BMFace`\n"
599 static PyObject *bpy_bm_utils_face_flip(PyObject *UNUSED(self), BPy_BMFace *value)
601 if (!BPy_BMFace_Check(value)) {
602 PyErr_Format(PyExc_TypeError,
603 "face_flip(face): BMFace expected, not '%.200s'",
604 Py_TYPE(value)->tp_name);
608 BPY_BM_CHECK_OBJ(value);
610 BM_face_normal_flip(value->bm, value->f);
617 PyDoc_STRVAR(bpy_bm_utils_loop_separate_doc,
618 ".. method:: loop_separate(loop)\n"
620 " Rip a vertex in a face away and add a new vertex.\n"
622 " :arg loop: The to separate.\n"
623 " :type loop: :class:`bmesh.types.BMFace`\n"
624 " :return vert: The newly created vertex or None of failure.\n"
625 " :rtype vert: :class:`bmesh.types.BMVert`\n"
627 static PyObject *bpy_bm_utils_loop_separate(PyObject *UNUSED(self), BPy_BMLoop *value)
632 if (!BPy_BMLoop_Check(value)) {
633 PyErr_Format(PyExc_TypeError,
634 "loop_separate(loop): BMLoop expected, not '%.200s'",
635 Py_TYPE(value)->tp_name);
639 BPY_BM_CHECK_OBJ(value);
643 v_new = BM_face_loop_separate(bm, value->l);
645 if (v_new != value->l->v) {
646 return BPy_BMVert_CreatePyObject(bm, v_new);
654 static struct PyMethodDef BPy_BM_utils_methods[] = {
655 {"vert_collapse_edge", (PyCFunction)bpy_bm_utils_vert_collapse_edge, METH_VARARGS, bpy_bm_utils_vert_collapse_edge_doc},
656 {"vert_collapse_faces", (PyCFunction)bpy_bm_utils_vert_collapse_faces, METH_VARARGS, bpy_bm_utils_vert_collapse_faces_doc},
657 {"vert_dissolve", (PyCFunction)bpy_bm_utils_vert_dissolve, METH_VARARGS, bpy_bm_utils_vert_dissolve_doc}, /* could use METH_O */
658 {"vert_separate", (PyCFunction)bpy_bm_utils_vert_separate, METH_VARARGS, bpy_bm_utils_vert_separate_doc},
659 {"edge_split", (PyCFunction)bpy_bm_utils_edge_split, METH_VARARGS, bpy_bm_utils_edge_split_doc},
660 {"edge_rotate", (PyCFunction)bpy_bm_utils_edge_rotate, METH_VARARGS, bpy_bm_utils_edge_rotate_doc},
661 {"face_split", (PyCFunction)bpy_bm_utils_face_split, METH_VARARGS | METH_KEYWORDS, bpy_bm_utils_face_split_doc},
662 {"face_join", (PyCFunction)bpy_bm_utils_face_join, METH_VARARGS, bpy_bm_utils_face_join_doc},
663 {"face_vert_separate", (PyCFunction)bpy_bm_utils_face_vert_separate, METH_VARARGS, bpy_bm_utils_face_vert_separate_doc},
664 {"face_flip", (PyCFunction)bpy_bm_utils_face_flip, METH_O, bpy_bm_utils_face_flip_doc},
665 {"loop_separate", (PyCFunction)bpy_bm_utils_loop_separate, METH_O, bpy_bm_utils_loop_separate_doc},
666 {NULL, NULL, 0, NULL}
670 PyDoc_STRVAR(BPy_BM_doc,
671 "This module provides access to blenders bmesh data structures."
673 static struct PyModuleDef BPy_BM_types_module_def = {
674 PyModuleDef_HEAD_INIT,
675 "bmesh.utils", /* m_name */
676 BPy_BM_doc, /* m_doc */
678 BPy_BM_utils_methods, /* m_methods */
680 NULL, /* m_traverse */
686 PyObject *BPyInit_bmesh_utils(void)
690 submodule = PyModule_Create(&BPy_BM_types_module_def);