Documentation for new Python thinmesh module

1 files changed, 403 insertions, 0 deletions

diff --git a/source/blender/python/api2_2x/doc/Mesh.py b/source/blender/python/api2_2x/doc/Mesh.py
new file mode 100644
index 00000000000..8fe9c7fa444
--- /dev/null
+++ b/source/blender/python/api2_2x/doc/Mesh.py
@@ -0,0 +1,403 @@
+# Blender.Mesh module and the Mesh PyType object
+
+"""
+The Blender.Mesh submodule.
+
+Mesh Data
+=========
+
+This module provides access to B{Mesh Data} objects in Blender.  It differs
+from the NMesh module by allowing direct access to the actual Blender data, 
+so that changes are done immediately without need to update or put the data
+back into the original mesh.  The result is faster operations with less memory
+usage.
+
+Example::
+
+  import Blender
+  from Blender import Mesh, Material, Window
+
+  editmode = Window.EditMode()    # are we in edit mode?  If so ...
+  if editmode: Window.EditMode(0) # leave edit mode before getting the mesh
+
+  me = Mesh.Get("Plane")          # get the mesh data called "Plane"
+
+  if not me.materials:             # if there are no materials ...
+    newmat = Material.New()        # create one ...
+    me.materials=[newmat]          # and set the mesh's list of mats
+
+  print me.materials               # print the list of materials
+  mat = me.materials[0]            # grab the first material in the list
+  mat.R = 1.0                      # redefine its red component
+  for v in me.verts:               # loop the list of vertices
+    v.co[0] *= 2.5                 # multiply the coordinates
+    v.co[1] *= 5.0
+    v.co[2] *= 2.5
+
+  if editmode: Window.EditMode(1)  # optional, just being nice
+"""
+
+def Get(name=None):
+  """
+  Get the mesh data object called I{name} from Blender.
+  @type name: string
+  @param name: The name of the mesh data object.
+  @rtype: Mesh
+  @return: If a name is given, it returns either the requested mesh or None.
+    If no parameter is given, it returns all the meshs in the current scene.
+  """
+
+class MCol:
+  """
+  The MCol object
+  ===============
+    This object is four ints representing an RGBA color.
+  @ivar r: The Red component in [0, 255].
+  @type r: int
+  @ivar g: The Green component in [0, 255].
+  @type g: int
+  @ivar b: The Blue component in [0, 255].
+  @type b: int
+  @ivar a: The Alpha (transparency) component in [0, 255].
+  @type a: int
+  """
+
+class MVert:
+  """
+  The MVert object
+  ================
+    This object holds mesh vertex data.
+  @ivar co: The vertex coordinates (x, y, z).
+  @type co: vector
+  @ivar no: The vertex's unit normal vector (x, y, z).  Read-only.  B{Note}:
+    if vertex coordinates are changed, it may be necessary to use
+    L{Mesh.calcNormals()} to update the vertex normals.
+  @type no: vector
+  @ivar uvco: The vertex texture "sticky" coordinates (x, y), if present. 
+    Use L{Mesh.vertexUV} to test for presence before trying to access;
+    otherwise an exception will may be thrown.
+    (Sticky coordinates can be set when the object is in the Edit mode;
+    from the Editing Panel (F9), look under the "Mesh" properties for the 
+    "Sticky" button).  
+  @type uvco: vector
+  @ivar index: The vertex's index within the mesh.  Read-only.
+  @type index: int
+  @ivar sel: The vertex's selection state (selected=1).
+   B{Note}: a Mesh will return the selection state of the mesh when EditMode 
+   was last exited. A Python script operating in EditMode must exit EditMode 
+   before getting the current selection state of the mesh.
+  @type sel: int
+  @warn:  There are two kinds of UV texture coordinates in Blender: per vertex
+     ("sticky") and per face vertex (UV in L{MFace}).  In the first, there's
+     only one UV pair of coordinates for each vertex in the mesh.  In the
+     second, for each face it belongs to, a vertex can have different UV
+     coordinates.  This makes the per face option more flexible, since two
+     adjacent faces won't have to be mapped to a continuous region in an image:
+     each face can be independently mapped to any part of its texture.
+  """
+
+class MVertSeq:
+  """
+  The MVertSeq object
+  ===================
+    This object provides sequence and iterator access to the mesh's vertices.
+  """
+
+  def extend(coords):
+    """
+    Append one or more vertices to the mesh.  Unlike L{MEdgeSeq.extend()} and
+    L{MFaceSeq.extend()} no attempt is made to check for duplicate vertices in
+    the parameter list, or for vertices already in the mesh.
+
+    Example::
+      import Blender
+      from Blender import Mesh
+      from Blender.Mathutils import Vector
+
+      me = Mesh.Get("Plane")          # get the mesh data called "Plane"
+      me.verts.extend(1,1,1)          # add one vertex
+      l=[(.1,.1,.1),Vector([2,2,.5])]
+      me.verts.extend(l)              # add multiple vertices
+
+    @type coords: tuple(s) of floats or vectors
+    @param coords: coords can be
+       - a tuple of three floats,
+       - a 3D vector, or
+       - a sequence (list or tuple) of either of the above.
+    """
+
+class MEdge:
+  """
+  The MEdge object
+  ================
+    This object holds mesh edge data.
+  @ivar v1: The first vertex of the edge.
+  @type v1: MVert
+  @ivar v2: The second vertex of the edge.
+  @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}.
+  @type flag: int
+  @ivar index: The edge's index within the mesh.  Read-only.
+  @type index: int
+  """
+
+  def __iter__():
+    """
+    Iterator for MEdge.  It iterates over the MVerts of the edge, returning
+    v1 then v2.
+    @return: one of the edge's vertices
+    @rtype: MVert
+    """
+
+class MEdgeSeq:
+  """
+  The MEdgeSeq object
+  ===================
+    This object provides sequence and iterator access to the mesh's edges.
+  """
+
+  def extend(vertseq):
+    """
+    Add one or more edges to the mesh.  Edges which already exist in the 
+    mesh are ignored.  If three or four verts are specified in any tuple,
+    an edge is also created between the first and last vertices (this is
+    useful when adding faces).
+
+    Example::
+      import Blender
+      from Blender import Mesh
+
+      me = Mesh.Get("Plane")          # get the mesh data called "Plane"
+      v = me.verts                    # get vertices
+      if len(v) >= 6:                 # if there are enough vertices...
+        me.edges.extend(v[0],v[1])    #   add a single edge
+        l=[(v[1],v[2],v[3]),(v[0],v[2],v[4],v[5])]
+        me.edges.extend(l)            #   add multiple edges
+
+    @type vertseq: tuple(s) of MVerts
+    @param vertseq: either two to four MVerts, or sequence (list or tuple) 
+    of tuples each containing two to four MVerts.
+    """
+
+class MFace:
+  """
+  The MFace object
+  ================
+  This object holds mesh face data.
+
+  Example::
+   import Blender
+   from Blender import Mesh, Window
+
+   in_emode = Window.EditMode()
+   if in_emode: Window.EditMode(0)
+
+   me = Mesh.Get("Mesh")
+   faces = me.faces
+
+   ## Example for editmode faces selection:
+   selected_faces = []
+   for f in faces:
+     if f.sel:
+       selected_faces.append(f)
+   # ... unselect selected and select all the others:
+   for f in faces:
+     f.sel = 1 - f.sel # 1 becomes 0, 0 becomes 1
+
+   ## Example for UV textured faces selection:
+   selected_faces = []
+   SEL = NMesh.FaceFlags['SELECT']
+   # get selected faces:
+   for f in faces:
+     if f.flag & SEL:
+       selected_faces.append(f)
+   # ... unselect selected and select all the others:
+   for f in faces:
+     if f.flag & SEL:
+       f.flag &= ~SEL # unselect these
+     else:
+       f.flag |= SEL # and select these
+
+   if in_emode: Window.EditMode(1)
+   Blender.Redraw()
+
+  @ivar verts: The face's vertices.  Each face has 3 or 4 vertices.
+  @type verts: list of MVerts
+  @ivar v: Same as L{verts}.  This attribute is only for compatibility with
+      NMesh scripts and will probably be deprecated in the future.
+  @ivar sel: The face's B{edit mode} selection state (selected=1).
+      This is not the same as the selection state of
+      the textured faces (see L{flag}).
+  @type sel: int
+  @ivar hide: The face's B{edit mode} visibility state (hidden=1).
+      This is not the same as the visibility state of
+      the textured faces (see L{flag}).
+  @type hide: int
+  @ivar smooth: If set, the vertex normals are averaged to make this
+     face look smooth.  (This is the same as choosing "Set Smooth" in the 
+     Editing Panel (F9) under "Link and Material" properties).
+  @type smooth: int
+  @ivar col: The face's vertex colors, if defined.  Each vertex has its own
+     color.
+     Will throw an exception if the mesh does not have UV faces or vertex
+     colors; use L{Mesh.faceUV} and L{Mesh.vertexColors} to test.  B{Note}:
+     if a mesh has i{both} UV faces and vertex colors, the colors stored in
+     the UV faces will be used here. 
+  @type col: list of MCols
+  @ivar mat: The face's index into the mesh's materials
+      list.  It is in the range [0,15].
+  @type mat: int
+  @ivar image: The Image used as a texture for this face.
+      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}).
+      Will throw an exception if the mesh does not have UV faces; use
+      L{Mesh.faceUV} to test.
+  @type mode: int
+  @ivar index: The face's index within the mesh.  Read-only.
+  @type index: int
+
+  @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).
+      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
+      the L{Mesh.activeFace} attribute instead.
+      Will throw an exception if the mesh does not have UV faces; use
+      L{Mesh.faceUV} to test.
+
+  @ivar transp: Transparency mode.  It is one of the values in 
+      L{NMesh.FaceTranspModes}).
+      Will throw an exception if the mesh does not have UV faces; use
+      L{Mesh.faceUV} to test.
+  @type transp: int
+
+  @ivar uv: The face's UV coordinates.  Each vertex has its own UV coordinate.
+      Will throw an exception if the mesh does not have UV faces; use
+      L{Mesh.faceUV} to test.
+  @type uv: list of vectors
+  @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
+    with their own selection and visibility states, due to a mix of old and new
+    code.  To (un)select or (un)hide regular faces (visible in EditMode), use
+    L{MFace.sel} and L{MFace.hide} attributes.  For textured faces (UV Face 
+    Select and Paint modes in Blender) use the L{MFace.flag} attribute.
+    Check the example above and note L{Window.EditMode}.
+  @note: Assigning UV textures to mesh faces in Blender works like this:
+    1. Select your mesh.
+    2. Enter face select mode (press f) and select at least some face(s).
+    3. In the UV/Image Editor window, load / select an image.
+    4. Play in both windows (better split the screen to see both at the same
+       time) until the UV coordinates are where you want them.  Hint: in the
+       3D window, the 'u' key opens a menu of default UV choices and the 'r'
+       key lets you rotate the UV coords.
+    5. Leave face select mode (press f).
+  """
+
+  def __iter__():
+    """
+    Iterator for MVert.  It iterates over the MVerts of the face, returning
+    v1, v2, v3 (and optionally v4);
+    @return: one of the face's vertices
+    @rtype: MVert
+    """
+
+class MFaceSeq:
+  """
+  The MFaceSeq object
+  ===================
+    This object provides sequence and iterator access to the mesh's faces.
+  """
+
+  def extend(vertseq):
+    """
+    Add one or more faces to the mesh.  Faces which already exist in the 
+    mesh are ignored.  Tuples of two vertices are accepted, but no face
+    will be created.
+
+    Example::
+      import Blender
+      from Blender import Mesh
+
+      me = Mesh.Get("Plane")          # get the mesh data called "Plane"
+      v = me.verts                    # get vertices
+      if len(v) >= 6:                 # if there are enough vertices...
+        me.face.extend(v[1],v[2],v[3]) #   add a single edge
+        l=[(v[0],v[1]),(v[0],v[2],v[4],v[5])]
+        me.face.extend(l)            #   add another face
+
+    @type vertseq: tuple(s) of MVerts
+    @param vertseq: either two to four MVerts, or sequence (list or tuple) 
+    of tuples each containing two to four MVerts.
+    """
+
+
+class Mesh:
+  """
+  The Mesh Data object
+  ====================
+    This object gives access to mesh data in Blender.
+  @note: the verts, edges and faces attributes are implemented as sequences.
+  The operator[] and len() are defined for these sequences.  You cannot
+  assign to an item in the sequence, but you can assign to most of the
+  attributes of individual items.
+  @ivar edges: The mesh's edges.
+  @type edges: sequence of MEdges
+  @ivar faces: The mesh's faces.
+  @type faces: sequence of MFaces
+  @ivar verts: The mesh's vertices.
+  @type verts: sequence of MVerts
+
+  @ivar materials: The mesh's materials.  Each mesh can reference up to
+    16 materials.  Empty slots in the mesh's list are represented by B{None}.
+  @type materials: list of Materials
+  @ivar degr: The max angle for auto smoothing in [1,80].  
+  @type degr: int
+  @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}.
+  @type mode: int
+
+  @ivar name: The Mesh name.  It's common to use this field to store extra
+     data about the mesh (to be exported to another program, for example).
+  @type name: str
+  @ivar subDivLevels: The [display, rendering] subdivision levels in [1, 6].
+  @type subDivLevels: list of 2 ints
+  @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.
+  @type faceUV: bool
+  @ivar vertexColors: The mesh contains vertex colors.  Read-only.
+  @type vertexColors: bool
+  @ivar vertexUV: The mesh contains "sticky" per-vertex UV coordinates.  Read-only.
+  @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
+    independent of the selected faces in Face Select and Edit modes.
+    Will throw an exception if the mesh does not have UV faces; use
+    L{faceUV} to test.
+  @type activeFace: int
+  """
+
+  def calcNormals():
+    """
+    Recalculates the vertex normals using face data.
+    """
+
+  def vertexShade(object):
+    """
+    Colors vertices based on the current lighting setup, like when there
+    are no vertex colors and no textured faces and a user enters Vertex Paint
+    Mode in Blender (only lamps in visible layers account).  An exception is
+    thrown if called while in EditMode.
+    @type object: Object
+    @param object: The Blender Object linked to the mesh.
+    """
+