diff options
author | Ken Hughes <khughes@pacific.edu> | 2005-10-27 23:37:37 +0400 |
---|---|---|
committer | Ken Hughes <khughes@pacific.edu> | 2005-10-27 23:37:37 +0400 |
commit | a9a545d7848c06dbc5792e6cebcb53364c6a35a9 (patch) | |
tree | 97701c4e9b386f0f42182f58a4d625187658e02c /source/blender/python/api2_2x/doc/Mesh.py | |
parent | 637895d29d4077b4e1980ad0d5bd537e28c1ca91 (diff) |
Lots of BPy Mesh additions:
- added faces.uvSel attribute: can get/set selection status of UV vertices in
UV Editor window
- make mesh.faceUV, mesh.vertexUV and mesh.vertexColor writable: users
can now enable/disable UV faces, vertex colors, "sticky" vertices
- fixed bug with mesh tool methods: before it would only work if an object
linked to the mesh was selected
- added mesh.quadToTriangle() and mesh.triangleToQuad() methods
- added selected() method to verts, edges, faces; returns list of indices
of selected items
- mesh.getFromObject() now gets derived mesh data
- ported vertex group methods from NMesh (required change to Object.c)
- ported module dictionaries from NMesh
Diffstat (limited to 'source/blender/python/api2_2x/doc/Mesh.py')
-rw-r--r-- | source/blender/python/api2_2x/doc/Mesh.py | 268 |
1 files changed, 244 insertions, 24 deletions
diff --git a/source/blender/python/api2_2x/doc/Mesh.py b/source/blender/python/api2_2x/doc/Mesh.py index 41b10179e11..a20cb2ae993 100644 --- a/source/blender/python/api2_2x/doc/Mesh.py +++ b/source/blender/python/api2_2x/doc/Mesh.py @@ -12,13 +12,16 @@ B{New}: - delete methods for L{verts<MVertSeq.delete>}, L{edges<MEdgeSeq.delete>} and L{faces<MFaceSeq.delete>} - new experimental mesh tools: - L{fill()<Mesh.Mesh.fill>}, - L{flipNormals()<Mesh.Mesh.flipNormals>}, - L{recalcNormals()<Mesh.Mesh.recalcNormals>}, - L{remDoubles()<Mesh.Mesh.remDoubles>}, - L{smooth()<Mesh.Mesh.smooth>}, - L{subdivide()<Mesh.Mesh.subdivide>} and - L{toSphere()<Mesh.Mesh.toSphere>} + L{mesh.fill()<Mesh.Mesh.fill>}, + L{mesh.flipNormals()<Mesh.Mesh.flipNormals>}, + L{mesh.recalcNormals()<Mesh.Mesh.recalcNormals>}, + L{mesh.remDoubles()<Mesh.Mesh.remDoubles>}, + L{mesh.smooth()<Mesh.Mesh.smooth>}, + L{mesh.subdivide()<Mesh.Mesh.subdivide>}, + L{mesh.toSphere()<Mesh.Mesh.toSphere>}, + L{mesh.quadToTriangle()<Mesh.Mesh.quadToTriangle>}, + L{mesh.triangleToQuad()<Mesh.Mesh.triangleToQuad>} + - methods for accessing and modifying vertex groups - and if you're never used Mesh before, everything! Mesh Data @@ -53,8 +56,59 @@ Example:: v.co[2] *= 2.5 if editmode: Window.EditMode(1) # optional, just being nice + +@type Modes: readonly dictionary +@type FaceFlags: readonly dictionary +@type FaceModes: readonly dictionary +@type FaceTranspModes: readonly dictionary +@var Modes: The available mesh modes. + - NOVNORMALSFLIP - no flipping of vertex normals during render. + - TWOSIDED - double sided mesh. + - AUTOSMOOTH - turn auto smoothing of faces "on". + - SUBSURF - turn Catmull-Clark subdivision of surfaces "on". + - OPTIMAL - optimal drawing of edges when "SubSurf" is "on". +@var FaceFlags: The available *texture face* (uv face select mode) selection + flags. Note: these refer to TexFace faces, available if nmesh.hasFaceUV() + returns true. + - SELECT - selected. + - HIDE - hidden. + - ACTIVE - the active face. +@var FaceModes: The available *texture face* modes. Note: these are only + meaningful if nmesh.hasFaceUV() returns true, since in Blender this info is + stored at the TexFace (TexFace button in Edit Mesh buttons) structure. + - ALL - set all modes at once. + - BILLBOARD - always orient after camera. + - HALO - halo face, always point to camera. + - DYNAMIC - respond to collisions. + - INVISIBLE - invisible face. + - LIGHT - dynamic lighting. + - OBCOL - use object color instead of vertex colors. + - SHADOW - shadow type. + - SHAREDVERT - apparently unused in Blender. + - SHAREDCOL - shared vertex colors (per vertex). + - TEX - has texture image. + - TILES - uses tiled image. + - TWOSIDE - two-sided face. +@var FaceTranspModes: The available face transparency modes. Note: these are + enumerated values (enums), they can't be combined (and'ed, or'ed, etc) like a bit vector. + - SOLID - draw solid. + - ADD - add to background (halo). + - ALPHA - draw with transparency. + - SUB - subtract from background. +@var EdgeFlags: The available edge flags. + - SELECT - selected. + - EDGEDRAW - edge is drawn out of edition mode. + - SEAM - edge is a seam for LSCM UV unwrapping + - FGON - edge is part of a F-Gon. +@type AssignModes: readonly dictionary. +@var AssignModes: blah blah fix me. + - REPLACE - selected. + - ADD - edge is drawn out of edition mode. + - SUBTRACT - edge is a seam for LSCM UV unwrapping """ +AssignModes = {'REPLACE':1} + def Get(name=None): """ Get the mesh data object called I{name} from Blender. @@ -220,6 +274,13 @@ class MVertSeq: the above. """ + def selected(): + """ + Get selected vertices. + @return: a list of the indices for all vertices selected in edit mode. + @rtype: list of ints + """ + class MEdge: """ The MEdge object @@ -231,7 +292,7 @@ class MEdge: @type v2: MVert @ivar crease: The crease value of the edge. It is in the range [0,255]. @type crease: int - @ivar flag: The bitfield describing edge properties. See L{NMesh.EdgeFlags}. + @ivar flag: The bitfield describing edge properties. See L{EdgeFlags}. @type flag: int @ivar index: The edge's index within the mesh. Read-only. @type index: int @@ -289,6 +350,14 @@ class MEdgeSeq: the above. """ + def selected(): + """ + Get selected edges. + Selected edges are those for which both vertices are selected. + @return: a list of the indices for all edges selected in edit mode. + @rtype: list of ints + """ + class MFace: """ The MFace object @@ -316,7 +385,7 @@ class MFace: ## Example for UV textured faces selection: selected_faces = [] - SEL = NMesh.FaceFlags['SELECT'] + SEL = Mesh.FaceFlags['SELECT'] # get selected faces: for f in faces: if f.flag & SEL: @@ -361,7 +430,7 @@ class MFace: Will throw an exception if the mesh does not have UV faces; use L{Mesh.faceUV} to test. @type image: Image - @ivar mode: The texture mode bitfield (see L{NMesh.FaceModes}). + @ivar mode: The texture mode bitfield (see L{FaceModes}). Will throw an exception if the mesh does not have UV faces; use L{Mesh.faceUV} to test. @type mode: int @@ -370,7 +439,7 @@ class MFace: @ivar flag: The face's B{texture mode} flags; indicates the selection, active , and visibility states of a textured face (see - L{NMesh.FaceFlags} for values). + L{FaceFlags} for values). This is not the same as the selection or visibility states of the faces in edit mode (see L{sel} and L{hide}). To set the active face, use @@ -379,7 +448,7 @@ class MFace: L{Mesh.faceUV} to test. @ivar transp: Transparency mode. It is one of the values in - L{NMesh.FaceTranspModes}). + L{FaceTranspModes}). Will throw an exception if the mesh does not have UV faces; use L{Mesh.faceUV} to test. @type transp: int @@ -388,6 +457,12 @@ class MFace: Will throw an exception if the mesh does not have UV faces; use L{Mesh.faceUV} to test. @type uv: list of vectors + @ivar uvSel: The face's UV coordinates seletion state; a 1 indicates the + vertex is selected. Each vertex has its own UV coordinate select state + (this is not the same as the vertex's edit mode selection state). + Will throw an exception if the mesh does not have UV faces; use + L{Mesh.faceUV} to test. + @type uvSel: list of ints @ivar no: The face's normal vector (x, y, z). Read-only. @type no: vector @note: there are regular faces and textured faces in Blender, both currently @@ -459,6 +534,14 @@ class MFaceSeq: - a integer, specifying an index into the mesh's face list """ + def selected(): + """ + Get selected faces. + mode. + @return: a list of the indices for all faces selected in edit mode. + @rtype: list of ints + """ + class Mesh: """ The Mesh Data object @@ -486,7 +569,7 @@ class Mesh: @ivar maxSmoothAngle: Same as L{degr}. This attribute is only for compatibility with NMesh scripts and will probably be deprecated in the future. - @ivar mode: The mesh's mode bitfield. See L{NMesh.Modes}. + @ivar mode: The mesh's mode bitfield. See L{Modes}. @type mode: int @ivar name: The Mesh name. It's common to use this field to store extra @@ -497,11 +580,17 @@ class Mesh: @ivar users: The number of Objects using (linked to) this mesh. @type users: int - @ivar faceUV: The mesh contains UV-mapped textured faces. Read-only. + @ivar faceUV: The mesh contains UV-mapped textured faces. Enabling faceUV + does not initialize the face colors like the Blender UI does; this must + be done in the script. B{Note}: if faceUV is set, L{vertexColors} cannot + be set. Furthermore, if vertexColors is already set when faceUV is set, + vertexColors is cleared. This is because the vertex color information + is stored with UV faces, so enabling faceUV implies enabling vertexColors. @type faceUV: bool - @ivar vertexColors: The mesh contains vertex colors. Read-only. + @ivar vertexColors: The mesh contains vertex colors. See L{faceUV} for the + use of vertex colors when UV-mapped texture faces are enabled. @type vertexColors: bool - @ivar vertexUV: The mesh contains "sticky" per-vertex UV coordinates. Read-only. + @ivar vertexUV: The mesh contains "sticky" per-vertex UV coordinates. @type vertexUV: bool @ivar activeFace: Index of the mesh's active face in UV Face Select and Paint modes. Only one face can be active at a time. Note that this is @@ -514,8 +603,9 @@ class Mesh: def getFromObject(name): """ Replace the mesh's existing data with the raw mesh data from a Blender - Object. This method support all the geometry based objects (mesh, text, - curve, surface, and meta). + Object. This method supports all the geometry based objects (mesh, text, + curve, surface, and meta). If the object has modifiers, they will be + applied before to the object before extracting the vertex data. @note: The mesh coordinates are in i{local space}, not the world space of its object. For world space vertex coordinates, each vertex location must be multiplied by the object's 4x4 transform matrix (see L{transform}). @@ -598,6 +688,124 @@ class Mesh: returned. If a sequence of edges is passed, a list is returned. """ + def addVertGroup(group): + """ + Add a named and empty vertex (deform) group to the object this nmesh is + linked to. The mesh must first be linked to an object (with object.link() + or object.getData() ) so the method knows which object to update. + This is because vertex groups in Blender are stored in I{the object} -- + not in the mesh, which may be linked to more than one object. + @type group: string + @param group: the name for the new group. + """ + + def removeVertGroup(group): + """ + Remove a named vertex (deform) group from the object linked to this mesh. + All vertices assigned to the group will be removed (just from the group, + not deleted from the mesh), if any. If this mesh was newly created, it + must first be linked to an object (read the comment in L{addVertGroup} for + more info). + @type group: string + @param group: the name of a vertex group. + """ + + + def assignVertsToGroup(group, vertList, weight, assignmode = AssignModes['REPLACE']): + """ + Adds an array (a Python list) of vertex points to a named vertex group + associated with a mesh. The vertex list is a list of vertex indices from + the mesh. You should assign vertex points to groups only when the mesh has + all its vertex points added to it and is already linked to an object. + + I{B{Example:}} + The example here adds a new set of vertex indices to a sphere primitive:: + import Blender + sphere = Blender.Object.Get('Sphere') + replace = Blender.Mesh.AssignModes.REPLACE + mesh = sphere.getData(mesh=True) + mesh.addVertGroup('firstGroup') + vertList = [] + for x in range(300): + if x % 3 == 0: + vertList.append(x) + mesh.assignVertsToGroup('firstGroup', vertList, 0.5, replace) + + @type group: string + @param group: the name of the group. + @type vertList: list of ints + @param vertList: a list of vertex indices. + @type weight: float + @param weight: the deform weight for (which means: the amount of influence + the group has over) the given vertices. It should be in the range + [0.0, 1.0]. If weight <= 0, the given vertices are removed from the + group. If weight > 1, it is clamped. + @type assignmode: module constant + @param assignmode: Three choices: + - ADD: if the vertex in the list is not assigned to the group + already, this creates a new association between this vertex and the + group with the weight specified, otherwise the weight given is added to + the current weight of an existing association between the vertex and + group. + - SUBTRACT: will attempt to subtract the weight passed from a vertex + already associated with a group, else it does nothing.\n + - REPLACE: attempts to replace a weight with the new weight value + for an already associated vertex/group, else it does nothing. + """ + + def removeVertsFromGroup(group, vertList = None): + """ + Remove a list of vertices from the given group. If this nmesh was newly + created, it must first be linked to an object (check L{addVertGroup}). + @type group: string + @param group: the name of a vertex group + @type vertList: list of ints + @param vertList: a list of vertex indices to be removed from I{group}. + If None, all vertices are removed -- the group is emptied. + """ + + def getVertsFromGroup(group, weightsFlag = 0, vertList = None): + """ + Return a list of vertex indices associated with the passed group. This + method can be used to test whether a vertex index is part of a group and + if so, what its weight is. + + I{B{Example:}} + Append this to the example from L{assignVertsToGroup}:: + # ... + print "Vertex indices from group %s :" % groupName + print mesh.getVertsFromGroup('firstGroup') + print "Again, with weights:" + print mesh.getVertsFromGroup('firstGroup',1) + print "Again, with weights and restricted to the given indices:" + print mesh.getVertsFromGroup('firstGroup',1,[1,2,3,4,5,6]) + + @type group: string + @param group: the group name. + @type weightsFlag: bool + @param weightsFlag: if 1, the weight is returned along with the index. + @type vertList: list of ints + @param vertList: if given, only those vertex points that are both in the + list and group passed in are returned. + """ + + def renameVertGroup(groupName, newName): + """ + Renames a vertex group. + @type groupName: string + @param groupName: the vertex group name to be renamed. + @type newName: string + @param newName: the name to replace the old name. + """ + + def getVertGroupNames(): + """ + Return a list of all vertex group names. + @rtype: list of strings + @return: returns a list of strings representing all vertex group + associated with the mesh's object + """ + def smooth(): """ Flattens angle of selected faces. Experimental mesh tool. @@ -617,6 +825,24 @@ class Mesh: An exception is thrown if called while in EditMode. """ + def fill(): + """ + Scan fill a closed selected edge loop. Experimental mesh tool. + An exception is thrown if called while in EditMode. + """ + + def triangleToQuad(): + """ + Convert selected triangles to quads. Experimental mesh tool. + An exception is thrown if called while in EditMode. + """ + + def quadToTriangle(): + """ + Convert selected quads to triangles. Experimental mesh tool. + An exception is thrown if called while in EditMode. + """ + def subdivide(beauty=0): """ Subdivide selected edges in a mesh. Experimental mesh tool. @@ -637,12 +863,6 @@ class Mesh: @return: the number of vertices deleted """ - def fill(): - """ - Scan fill a closed selected edge loop. Experimental mesh tool. - An exception is thrown if called while in EditMode. - """ - def recalcNormals(direction=0): """ Recalculates inside or outside normals for selected faces. Experimental |