# Blender.NMesh module and the NMesh PyType object

"""
The Blender.NMesh submodule.

B{New}:
 - edges class (L{NMEdge}) and nmesh methods (L{NMesh.addEdge},
L{NMesh.addEdgesData}, etc.);
 - new optional arguments to L{NMesh.update};
 - L{NMesh.transform};
 - L{GetNames}.

Mesh Data
=========

This module provides access to B{Mesh Data} objects in Blender.

Example::

  import Blender
  from Blender import NMesh, 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 = NMesh.GetRaw("Plane")       # get the mesh data called "Plane"

  if not me.materials:             # if there are no materials ...
    newmat = Material.New()        # create one ...
    me.materials.append(newmat)    # and append it to 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
  me.update()                      # update the real mesh in Blender

  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
  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.
"""

def Col(col = [255, 255, 255, 255]):
  """
  Get a new mesh rgba color.
  @type col: list
  @param col: A list [red, green, blue, alpha] of integer values in [0, 255].
  @rtype: NMCol
  @return:  A new NMCol (mesh rgba color) object.
  """

def Vert(x = 0, y = 0, z = 0):
  """
  Get a new vertex object.
  @type x: float
  @type y: float
  @type z: float
  @param x: The x coordinate of the vertex.
  @param y: The y coordinate of the vertex.
  @param z: The z coordinate of the vertex.
  @rtype: NMVert
  @return: A new NMVert object.
  """

def Face(vertexList = None):
  """
  Get a new face object.
  @type vertexList: list
  @param vertexList: A list of B{up to 4} NMVerts (mesh vertex
      objects).
  @rtype: NMFace
  @return: A new NMFace object.
  """

def New(name = 'Mesh'):
  """
  Create a new mesh object.
  @type name: string
  @param name: An optional name for the created mesh.
  rtype: NMesh
  @return: A new (B{empty}) NMesh object.
  """

def GetRaw(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: NMesh
  @return: It depends on the 'name' parameter:
      - (name) - The NMesh wrapper of the mesh called I{name},
        None if not found.
      - () - A new (empty) NMesh object.
  """

def GetNames():
  """
  Get a list with the names of all available meshes in Blender.
  @rtype: list of strings
  @return: a list of mesh names.
  @note: to get actual mesh data, pass a mesh name to L{GetRaw}.
  """

def GetRawFromObject(name):
  """
  Get the raw mesh data object from the Object in Blender called I{name}.\n
  Note: The mesh coordinates are in local space, not the world space of its Object.\n
  For world space vertex coordinates, each vertex location must be multiplied by the object's 4x4 matrix.
  @type name: string
  @param name: The name of an Object of type "Mesh".
  @rtype: NMesh
  @return: The NMesh wrapper of the mesh data from the Object called I{name}.
  @note: For "subsurfed" meshes, it's the B{display} level of subdivision that
      matters, the rendering one is only processed at the rendering pre-stage
      and is not available for scripts.  This is not a problem at all, since
      you can get and set the subdivision levels via scripting, too (see
      L{NMesh.getSubDivLevels}, L{NMesh.setSubDivLevels}).
  @warn: This function gets I{deformed} mesh data, already modified for
      displaying (think "display list").  It also doesn't let you overwrite the
      original mesh in Blender, so if you try to update it, a new mesh will
      be created.
  """

def PutRaw(nmesh, name = None, recalc_normals = 1, store_edges = 0):
  """
  Put a BPython NMesh object as a mesh data object in Blender.
  @note: if there is already a mesh with the given 'name', its contents are
  freed and the new data is put in it.  Also, if this mesh is not linked to any
  object, a new object for it is created.  Reminder: in Blender an object is
  composed of the base object and linked object data (mesh, metaball, camera,
  etc. etc).
  @type nmesh: NMesh
  @type name: string
  @type recalc_normals: int
  @type store_edges: int
  @param name: The name of the mesh data object in Blender which will receive
     this nmesh data.  It can be an existing mesh data object or a new one.
  @param recalc_normals: If non-zero, the vertex normals for the mesh will
     be recalculated.
  @param store_edges: if non-zero, the edges data are stored
  @rtype: None or Object
  @return: It depends on the 'name' parameter:
      - I{name} refers to an existing mesh data obj already linked to an
           object: return None.
      - I{name} refers to a new mesh data obj or an unlinked (no users) one:
           return the created Blender Object wrapper.
  """

class NMCol:
  """
  The NMCol object
  ================
    This object is a list of ints: [r, g, b, a] representing an
    rgba color.
  @ivar r: The Red component in [0, 255].
  @ivar g: The Green component in [0, 255].
  @ivar b: The Blue component in [0, 255].
  @ivar a: The Alpha (transparency) component in [0, 255].
  """

class NMVert:
  """
  The NMVert object
  =================
    This object holds mesh vertex data.
  @type co: 3D Vector object.
  @ivar co: The vertex coordinates (x, y, z).
  @type no: 3D Vector object. (unit length)
  @ivar no: The vertex normal vector (x, y, z).
  @type uvco: 3D Vector object.
  @ivar uvco: The vertex texture "sticky" coordinates. The Z value of the Vector is ignored.
  @type index: int
  @ivar index: The vertex index, if owned by a mesh.
  @type sel: int
  @ivar sel: The selection state (selected:1, unselected:0) of this vertex.\n
  Note: An NMesh will return the selection state of the mesh when EditMod was last exited. A python script operating in EditMode must exit edit mode, before getting the current selection state of the mesh.
  @warn:  There are two kinds of uv texture coordinates in Blender: per vertex
     ("sticky") and per face vertex (uv in L{NMFace}).  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 NMEdge:
  """
  The NMEdge object
  =================
    This object holds mesh edge data.
  @type v1: NMVert
  @ivar v1: The first vertex of the edge.
  @type v2: NMVert
  @ivar v2: The second vertex of the edge.
  @type crease: int
  @ivar crease: The crease value of the edge. It is in the range [0,255].
  @type flag: int
  @ivar flag: The bitmask describing edge properties. See L{NMesh.EdgeFlags<EdgeFlags>}.
  """

class NMFace:
  """
  The NMFace object
  =================
  This object holds mesh face data.

  Example::
   import Blender
   from Blender import NMesh, Window

   in_emode = Window.EditMode()
   if in_emode: Window.EditMode(0)

   me = NMesh.GetRaw("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

   me.update()
   if in_emode: Window.EditMode(1)
   Blender.Redraw()

  @type v: list
  @ivar v: The list of face vertices (B{up to 4}).
  @type sel: bool
  @ivar sel: The selection state (1: selected, 0: unselected) of this NMesh's
      faces *in edit mode*.  This is not the same as the selection state of
      the textured faces (see L{NMesh.NMFace.flag}).
  @type hide: bool
  @ivar hide: The visibility state (1: hidden, 0: visible) of this NMesh's
      faces *in edit mode*.  This is not the same as the visibility state of
      the textured faces (see L{NMesh.NMFace.flag}).
  @ivar col: The list of vertex colours.
  @ivar mat: Same as I{materialIndex} below.
  @ivar materialIndex: The index of this face's material in its NMesh materials
      list.
  @ivar smooth: If non-zero, the vertex normals are averaged to make this
     face look smooth.
  @ivar image: The Image used as a texture for this face.
  @ivar mode: The display mode (see L{Mesh.FaceModes<FaceModes>})
  @ivar flag: Bit vector specifying selection / visibility flags for uv
     textured faces (visible in Face Select mode, see
     L{NMesh.FaceFlags<FaceFlags>}).
  @ivar transp: Transparency mode bit vector
     (see L{NMesh.FaceTranspModes<FaceTranspModes>}).
  @ivar uv: List of per-face UV coordinates: [(u0, v0), (u1, v1), ...].
  @ivar normal: (or just B{no}) The normal vector for this face: [x,y,z].
  @note: there are normal 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 normal faces (visible in editmode), use
    L{NMFace.sel} and L{NMFace.hide} vars.  For textured faces (Face Select
    mode in Blender) use the old L{NMFace.flag} bitflag.  Also 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 append(vertex):
    """
    Append a vertex to this face's vertex list.
    @type vertex: NMVert
    @param vertex: An NMVert object.
    """

class NMesh:
  """
  The NMesh Data object
  =====================
    This object gives access to mesh data in Blender.  We refer to mesh as the
    object in Blender and NMesh as its Python counterpart.
  @ivar name: The NMesh name.  It's common to use this field to store extra
     data about the mesh (to be exported to another program, for example).
  @ivar materials: The list of materials used by this NMesh.  See
     L{NMesh.getMaterials} for important details.
  @ivar verts: The list of NMesh vertices (NMVerts).
  @ivar users: The number of Objects using (linked to) this mesh.
  @ivar faces: The list of NMesh faces (NMFaces).
  @ivar edges: None if mesh has no edge data, else a list of L{NMEdge} edges. Use L{addEdgesData} to create edge data if it do not exist.
  @ivar mode:  The mode flags for this mesh.  See L{setMode}.
  @ivar subDivLevels: The [display, rendering] subdivision levels in [1, 6].
  @ivar maxSmoothAngle: The max angle for auto smoothing.  See L{setMode}.
  """

  def addEdge(v1, v2):
    """
    Create an edge between two vertices.
    If an edge already exists between those vertices, it is returned.
    Created edge is automatically added to edges list.
    You can only call this method if mesh has edge data.
    @note: In Blender only zero or one edge can link two vertices.
    @type v1: NMVert
    @param v1: the first vertex of the edge.
    @type v2: NMVert
    @param v2: the second vertex of the edge.
    @rtype: NMEdge
    @return: The created or already existing edge.
    """

  def findEdge(v1, v2):
    """
    Try to find an edge between two vertices.
    If no edge exists between v1 and v2, None is returned.
    You can only call this method if mesh has edge data.
    @type v1: NMVert
    @param v1: the first vertex of the edge.
    @type v2: NMVert
    @param v2: the second vertex of the edge.
    @rtype: NMEdge
    @return: The found edge. None if no edge was found.
    """

  def removeEdge(v1, v2):
    """
    Remove an edge between two vertices.
    All faces using this edge are removed from faces list.
    You can only call this method if mesh has edge data.
    @type v1: NMVert
    @param v1: the first vertex of the edge.
    @type v2: NMVert
    @param v2: the second vertex of the edge.
    """

  def addFace(face):
    """
    Add a face to face list and add to edge list (if edge data exists) necessary edges.
    @type face: NMFace
    @param face: the face to add to the mesh.
    @rtype: list of NMEdge
    @return: If mesh has edge data, return the list of face edges.
    """

  def removeFace(face):
    """
    Remove a face for face list and remove edges no more used by any other face (if edge data exists).
    @type face: NMFace
    @param face: the face to add to the mesh.
    """

  def addEdgesData():
    """
    If edge data does not exist for the mesh (ie L{edges}==None), then create them.
    """
    
  def addMaterial(material):
    """
    Add a new material to this NMesh's list of materials.  This method is the
    slower but safer way to add materials, since it checks if the argument
    given is really a material, imposes a limit of 16 materials and only adds
    the material if it wasn't already in the list.
    @type material: Blender Material
    @param material: A Blender Material.
    """

  def getMaterials(what = -1):
    """
    Get this NMesh's list of materials.
    @type what: int
    @param what: determines the list's contents:
        - -1: return the current nmesh's list;
        -  0: retrieve a fresh list from the Blender mesh -- eventual
              modifications made by the script not included, unless
              L{NMesh.update}d is called before this method;
        -  1: like 0, but empty slots are not ignored, they are returned as
              None's.
    @note: what >= 0 also updates nmesh.materials attribute.
    @rtype: list of materials
    @return: the requested list of materials.
    @note: if a user goes to the material buttons window and removes some
        mesh's link to a material, that material slot becomes empty.
        Previously such materials were ignored.
    """

  def setMaterials(matlist):
    """
    Set this NMesh's list of materials.  This method checks the consistency of
    the passed list: must only have materials or None's and can't contain more
    than 16 entries.
    @type matlist: list of materials
    @param matlist: a list with materials, None's also accepted (they become
        empty material slots in Blender.
    """

  def hasVertexColours(flag = None):
    """
    Get (and optionally set) if this NMesh has vertex colours.
    @type flag: int
    @param flag: If given and non-zero, the "vertex colour" flag for this NMesh
        is turned I{on}.
    @rtype: bool
    @return: The current value of the "vertex colour" flag.
    @warn: If a mesh has both vertex colours and textured faces, this function
       will return False.  This is due to the way Blender deals internally with
       the vertex colours array (if there are textured faces, it is copied to
       the textured face structure and the original array is freed/deleted).
       If you want to know if a mesh has both textured faces and vertex
       colours, set *in Blender* the "VCol Paint" flag for each material that
       covers an area that was also vertex painted and then check in your
       Python script if that material flag is set.  Of course also tell others
       who use your script to do the same.  The "VCol Paint" material mode flag
       is the way to tell Blender itself to render with vertex colours, too, so
       it's a natural solution.
    """

  def hasFaceUV(flag = None):
    """
    Get (and optionally set) if this NMesh has UV-mapped textured faces.
    @type flag: int
    @param flag: If given and non-zero, the "textured faces" flag for this
        NMesh is turned I{on}.
    @rtype: bool
    @return: The current value of the "textured faces" flag.
    """

  def hasVertexUV(flag = None):
    """
    Get (and optionally set) the "sticky" flag that controls if a mesh has
    per vertex UV coordinates.
    @type flag: int
    @param flag: If given and non-zero, the "sticky" flag for this NMesh is
        turned I{on}.
    @rtype: bool
    @return: The current value of the "sticky" flag.
    """

  def getActiveFace():
    """
    Get the index of the active face.
    @rtype: int
    @return: The index of the active face.
    """

  def getSelectedFaces(flag = None):
    """
    Get list of selected faces.
    @type flag: int
    @param flag: If given and non-zero, the list will have indices instead of
        the NMFace objects themselves.
    @rtype: list
    @return:  It depends on the I{flag} parameter:
        - if None or zero: List of NMFace objects.
        - if non-zero: List of indices to NMFace objects.
    @warn: this method exists to speed up retrieving of selected faces from
       the actual mesh in Blender.  So, if you make changes to the nmesh, you
       need to L{update} it before using this method.
    """

  def getVertexInfluences(index):
    """
    Get influences of bones in a specific vertex.
    @type index: int
    @param index: The index of a vertex.
    @rtype: list of lists
    @return: List of pairs (name, weight), where name is the bone name (string)
        and its weight is a float value.
    """

  def insertKey(frame = None, type = 'relative'):
    """
    Insert a mesh key at the given frame.  Remember to L{update} the nmesh
    before doing this, or changes in the vertices won't be updated in the
    Blender mesh.
    @type frame: int
    @type type: string
    @param frame: The Scene frame where the mesh key should be inserted.  If
        None, the current frame is used.
    @param type: The mesh key type: 'relative' or 'absolute'.  This is only
        relevant on the first call to insertKey for each nmesh (and after all
        keys were removed with L{removeAllKeys}, of course).
    @warn: This and L{removeAllKeys} were included in this release only to
        make accessing vertex keys possible, but may not be a proper solution
        and may be substituted by something better later.  For example, it
        seems that 'frame' should be kept in the range [1, 100]
        (the curves can be manually tweaked in the Ipo Curve Editor window in
        Blender itself later).
    """

  def removeAllKeys():
    """
    Remove all mesh keys stored in this mesh.
    @rtype: bool
    @return: True if successful or False if this NMesh wasn't linked to a real
       Blender Mesh yet (or was, but the Mesh had no keys).
    @warn: Currently the mesh keys from meshes that are grabbed with
       NMesh.GetRaw() or .GetRawFromObject() are preserved, so if you want to
       clear them or don't want them at all, remember to call this method.  Of
       course NMeshes created with NMesh.New() don't have mesh keys until you
       add them.
    """

  def update(recalc_normals = 0, store_edges = 0, vertex_shade = 0):
    """
    Update the mesh in Blender.  The changes made are put back to the mesh in
    Blender, if available, or put in a newly created mesh if this NMesh wasn't
    already linked to one.
    @type recalc_normals: int (bool)
    @param recalc_normals: if nonzero the vertex normals are recalculated.
    @type store_edges: int (bool)
    @param store_edges: if nonzero, then edge data is stored.
    @type vertex_shade: int (bool)
    @param vertex_shade: if nonzero vertices are colored 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).  To use this functionality, be out of
        edit mode or else an error will be returned.
    @warn: edit mesh and normal mesh are two different structures in Blender,
        synchronized upon leaving or entering edit mode.  Always remember to
        leave edit mode (L{Window.EditMode}) before calling this update
        method, or your changes will be lost.  Even better: for the same reason
        programmers should leave EditMode B{before} getting a mesh, or changes
        made to the editmesh in Blender may not be visible to your script
        (check the example at the top of NMesh module doc).
    @warn: unlike the L{PutRaw} function, this method doesn't check validity of
        vertex, face and material lists, because it is meant to be as fast as
        possible (and already performs many tasks).  So programmers should make
        sure they only feed proper data to the nmesh -- a good general
        recommendation, of course.  It's also trivial to write code to check
        all data before updating, for example by comparing each item's type
        with the actual L{Types}, if you need to.
    @note: this method also redraws the 3d view and -- if 'vertex_shade' is
        nonzero -- the edit buttons window.
    @note: if your mesh disappears after it's updated, try
        L{Object.Object.makeDisplayList}.  'Subsurf' meshes (see L{getMode},
        L{setMode}) need their display lists updated, too.
    """

  def transform(matrix, recalc_normals = False):
    """
    Transforms the mesh by the specified 4x4 matrix, as returned by
    L{Object.Object.getMatrix}, though this will work with any invertible 4x4
    matrix type.  Ideal usage for this is exporting to an external file where
    global vertex locations are required for each object.
    Sometimes external renderers or file formats do not use vertex normals.
    In this case, you can skip transforming the vertex normals by leaving
    the optional parameter recalc_normals as False or 0 ( the default value ).
    
    Example::
     # This script outputs deformed meshes worldspace vertex locations
     # for a selected object
     import Blender
     from Blender import NMesh, Object
     
     ob = Object.GetSelected()[0] # Get the first selected object
     me = NMesh.GetRawFromObject(ob.name) # Get the objects deformed mesh data
     me.transform(ob.matrix)
   
     for v in me.verts:
       print 'worldspace vert', v.co
    
    @type matrix: Py_Matrix
    @param matrix: 4x4 Matrix which can contain location, scale and rotation. 
    @type recalc_normals: int (bool)
    @param recalc_normals: if True or 1, transform normals as well as vertex coordinates.
    @warn: if you call this method and later L{update} the mesh, the new
        vertex positions will be passed back to Blender, but the object
        matrix of each object linked to this mesh won't be automatically
        updated.  You need to set the object transformations (rotation,
        translation and scaling) to identities, then, or the mesh data will
        be changed ("transformed twice").
    """

  def getMode():
    """
    Get this mesh's mode flags.
    @rtype: int
    @return: Or'ed value.  See L{Modes}.
    """

  def setMode(m = None, m1=None, m2=None, m3=None):
    """
    Set the mode flags for this mesh.  Given mode strings turn the mode "on".
    Modes not passed in are turned "off", so setMode() (without arguments)
    unsets all mode flags.
    @type m: string or int (bitflag)
    @param m: mode string or int.  An int (see L{Modes}) or from none to 5
      strings can be given:
       - "NoVNormalsFlip"
       - "TwoSided"
       - "AutoSmooth"
       - "SubSurf"
       - "Optimal"
    """

  def addVertGroup(group):
    """
    Add a named and empty vertex (deform) group to the object this nmesh is
    linked to. If this nmesh was newly created or accessed with GetRaw, it must
    first be linked to an object (with object.link or NMesh.PutRaw) so the
    method knows which object to update.\n
    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. For this
    reason, it's better to use "mesh = object.getData()" than
    "mesh = NMesh.GetRaw(meshName)" to access an existing mesh.
    @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 nmesh.
    All vertices assigned to the group will be removed (just from the group,
    not deleted from the mesh), if any. If this nmesh 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 = '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')
     mesh = sphere.getData()
     mesh.addVertGroup('firstGroup')
     vertList = []
     for x in range(300):
         if x % 3 == 0:
             vertList.append(x)
     mesh.assignVertsToGroup('firstGroup', vertList, 0.5, 'add')

    @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: string
    @param assignmode: Three choices:
        - 'add'
        - 'substract'
        - 'replace'\n
	
        'B{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.\n
        'B{subtract}' will attempt to subtract the weight passed from a vertex
        already associated with a group, else it does nothing.\n
        'B{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 the given
        '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 getMaxSmoothAngle():
    """
    Get the max angle for auto smoothing.
    Note: This will only affect smoothing generated at render time.
    Smoothing can also be set per face which is visible in Blenders 3D View.
    @return: The value in degrees.
    """

  def setMaxSmoothAngle(angle):
    """
    Set the max angle for auto smoothing.
    @type angle: int
    @param angle: The new value in degrees -- it's clamped to [1, 80].
    """

  def getSubDivLevels():
    """
    Get the mesh subdivision levels for realtime display and rendering.
    @return: list of ints: [display, render].
    """

  def setSubDivLevels(subdiv):
    """
    Set the mesh subdivision levels for realtime display and rendering.
    @type subdiv: list of 2 ints
    @param subdiv: new subdiv levels: [display, render].  Both are clamped to
        lie in the range [1, 6].
    """