path: root/source/blender/python/api2_2x/doc/Curve.py

# Blender.Curve module and the Curve PyType object

"""
The Blender.Curve submodule.

Curve Data
==========

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

A Blender Curve can consist of multiple curves. Try converting a Text object to a Curve to see an example of this.   Each curve is of
type Bezier or Nurb.  The underlying curves can be accessed with
the [] operator.  Operator [] returns an object of type CurNurb.

The Curve module also supports the Python iterator interface.  This means you can access the curves in a Curve or the control points in a CurNurb using a python for statement.


Add a Curve to a Scene Example::
  from Blender import Curve, Object, Scene
  c = Curve.New()             # create new  curve data
  cur = Scene.getCurrent()    # get current scene
  ob = Object.New('Curve')    # make curve object
  ob.link(c)                  # link curve data with this object
  cur.link(ob)                # link object into scene

Iterator Example::
  ob = Object.GetSelected()[0]
  curve = ob.getData()
  for cur in curve:
    print type( cur ), cur
    for point in cur:
      print type( point ), point


"""

def New ( name = 'CurData'):
    """
  Create a new Curve Data object.
  @type name: string
  @param name: The Curve Data name.
  @rtype: Blender Curve
  @return: The created Curve Data object.
  """

def Get (name = None):
  """
  Get the Curve Data object(s) from Blender.
  @type name: string
  @param name: The name of the Curve Data.
  @rtype: Blender Curve or a list of Blender Curves
  @return: It depends on the 'name' parameter:
        - (name): The Curve Data object with the given name;
        - ():     A list with all Curve Data objects in the current scene.
  """

class Curve:
  """
  The Curve Data object
  =====================
  This object gives access to Curve-specific data in Blender.
  
  @cvar name: The Curve Data name.
  @cvar pathlen: The Curve Data path length.
  @cvar totcol: The Curve Data maximal number of linked materials.
  @cvar flag: The Curve Data flag value; see function getFlag for the semantics.
  @cvar bevresol: The Curve Data bevel resolution.
  @cvar resolu: The Curve Data U-resolution.
  @cvar resolv: The Curve Data V-resolution.
  @cvar width: The Curve Data width.
  @cvar ext1: The Curve Data extent 1(for bevels).
  @cvar ext2: The Curve Data extent2 (for bevels).
  @cvar loc: The Curve Data location(from the center).
  @cvar rot: The Curve Data rotation(from the center).
  @cvar size: The Curve Data size(from the center).
  @cvar bevob: The Curve Bevel Object
  """

  def getName():
    """
    Get the name of this Curve Data object.
    @rtype: string
    """

  def setName(name):
    """
    Set the name of this Curve Data object.
    @rtype: PyNone
    @type name: string
    @param name: The new name.
    """

  def getPathLen():
    """
    Get this Curve's path length.
    @rtype: int
    @return: the path length.
    """

  def setPathLen(len):
    """
    Set this Curve's path length.
    @rtype: PyNone
    @type len: int
    @param len: the new curve's length.
    """

  def getTotcol():
    """
    Get the number of materials linked to the Curve.
    @rtype: int
    @return: number of materials linked.
    """

  def setTotcol(totcol):
    """
    Set the number of materials linked to the Curve.
    @rtype: PyNone
    @type totcol: int
    @param totcol: number of materials linked.
    """

  def getFlag():
    """
    Get the Curve flag value.   
    This item is a bitfield whose value is a combination of the following parameters.
       - Bit 0 :  "3D" is set
       - Bit 1 :  "Front" is set
       - Bit 2 :  "Back" is set
       - Bit 3 :  "CurvePath" is set.
       - Bit 4 :  "CurveFollow" is set.
      
    @rtype: integer bitfield
    """

  def setFlag(val):
    """
    Set the Curve flag value.  The flag corresponds to the Blender settings for 3D, Front, Back, CurvePath and CurveFollow.  This parameter is a bitfield.
    @rtype: PyNone
    @type val: integer bitfield
    @param val : The Curve's flag bits.  See L{getFlag} for the meaning of the individual bits.
    """

  def getBevresol():
    """
    Get the Curve's bevel resolution value.
    @rtype: float
    """

  def setBevresol(bevelresol):
    """
    Set the Curve's bevel resolution value.
    @rtype: PyNone
    @type bevelresol: float
    @param bevelresol: The new Curve's bevel resolution value.
    """

  def getResolu():
    """
    Get the Curve's U-resolution value.
    @rtype: float
    """

  def setResolu(resolu):
    """
    Set the Curve's U-resolution value.
    @rtype: PyNone
    @type resolu: float
    @param resolu: The new Curve's U-resolution value.
    """

  def getResolv():
    """
    Get the Curve's V-resolution value.
    @rtype: float
    """

  def setResolv(resolv):
    """
    Set the Curve's V-resolution value.
    @rtype: PyNone
    @type resolv: float
    @param resolv: The new Curve's V-resolution value.
    """

  def getWidth():
    """
    Get the Curve's width value.
    @rtype: float
    """

  def setWidth(width):
    """
    Set the Curve's width value. 
    @rtype: PyNone
    @type width: float
    @param width: The new Curve's width value. 
    """

  def getExt1():
    """
    Get the Curve's ext1 value.
    @rtype: float
    """

  def setExt1(ext1):
    """
    Set the Curve's ext1 value. 
    @rtype: PyNone
    @type ext1: float
    @param ext1: The new Curve's ext1 value. 
    """

  def getExt2():
    """
    Get the Curve's ext2 value.
    @rtype: float
    """

  def setExt2(ext2):
    """
    Set the Curve's ext2 value.
    @rtype: PyNone 
    @type ext2: float
    @param ext2: The new Curve's ext2 value. 
    """

  def getControlPoint(numcurve,numpoint):
    """
    Get the curve's control point value. The numpoint arg is an index into the list of points and starts with 0.
    @type numcurve: int
    @type numpoint: int
    @rtype: list of floats
    @return: depends upon the curve's type.
      - type Bezier : a list of nine floats.  Values are x, y, z for handle-1, vertex and handle-2 
      - type Nurb : a list of 4 floats.  Values are x, y, z, w.
    """

  def setControlPoint( numcurve, numpoint, controlpoint):
    """
    Set the Curve's controlpoint value.   The numpoint arg is an index into the list of points and starts with 0.
    @rtype: PyNone
    @type numcurve: int
    @type numpoint: int
    @type controlpoint: list
    @param numcurve: index for spline in Curve, starting from 0
    @param numpoint: index for point in spline, starting from 0
    @param controlpoint: The new controlpoint value.
    See L{getControlPoint} for the length of the list.
    """

  def appendPoint( numcurve, new_control_point ):
    """
      add a new control point to the indicated curve.
      @rtype: PyNone
      @type numcurve: int
      @type new_control_point: list xyzw or BezTriple
      @param numcurve:  index for spline in Curve, starting from 0
      @param new_control_point: depends on curve's type.
        - type Bezier: a BezTriple 
	- type Nurb: a list of four floats for the xyzw values
      @raise AttributeError:  throws exception if numcurve is out of range.
    """

  def appendNurb( new_point ):
      """
      add a new curve to this Curve.  The new point is added to the new curve.  Blender does not support a curve with zero points.  The new curve is added to the end of the list of curves in the Curve.
      @rtype: CurNurb
      @return: the newly added spline
      @type new_point: BezTriple or list of xyzw coordinates for a Nurb curve.
      @param new_point: see L{CurNurb.append} for description of parameter.
      """

  def getLoc():
    """
    Get the curve's location value.
    @rtype: a list of 3 floats.
    """

  def setLoc(location):
    """
    Set the curve's location value.
    @rtype: PyNone 
    @type location: list[3]
    @param location: The new Curve's location values. 
    """

  def getRot():
    """
    Get the curve's rotation value.
    @rtype: a list of 3 floats.
    """

  def setRot(rotation):
    """
    Set the Curve's rotation value. 
    @rtype: PyNone
    @type rotation: list[3]
    @param rotation: The new Curve's rotation values. 
    """

  def getSize():
    """
    Get the curve's size value.
    @rtype: a list of 3 floats.
    """

  def setSize(size):
    """
    Set the curve size value.
    @rtype: PyNone 
    @type size: list[3]
    @param size: The new Curve's size values. 
    """

  def getMaterials():
    """
    Returns a list of materials assigned to the Curve.
    @rtype: list of Material Objects
    @return: list of Material Objects assigned to the Curve.
    """

  def getBevOb():
    """
    Returns the Bevel Object (BevOb) assigned to the Curve.
    @rtype: Blender Object or PyNone
    @return: Bevel Object (BevOb) assigned to the Curve.
    """

  def setBevOb( object ):
    """
    Assign a Bevel Object (BevOb) to the Curve.  Passing None as the object parameter removes the bevel.
    @rtype: PyNone
    @return: PyNone
    @type object: Curve type Blender Object
    @param object: Blender Object to assign as Bevel Object (BevOb)
    @raise TypeError: throws exception if the parameter is not a Curve type Blender Object or PyNone
    """

  def update():
    """
    Updates display list for a Curve.
    Used after making changes to control points.
    
    You B{must} use this if you want to see your changes!
    @rtype: PyNone
    @return: PyNone
    """

  def isNurb( curve_num ):
      """
      method used to determine whether a CurNurb is of type Bezier or of type Nurb.
      @rtype: integer
      @return:  Zero if curve is type Bezier, One if curve is of type Nurb.
      @type curve_num: integer
      @param curve_num: zero-based index into list of curves in this Curve.
      @raise AttributeError:  throws exception if curve_num is out of range.
      """

  def isCyclic( curve_num ):
      """
      Boolean method checks whether the curve is cyclic (closed) or not.

      @rtype: boolean
      @return: True if is cyclic, False if not
      @type curve_num: integer
      @param curve_num: zero-based index into list of curves in this Curve
      @raise AttributeError:  throws exception if curve_num is out of range.
      """

  def getNumCurves():
      """
      Get the number of curves in this Curve Data object.
      @rtype: integer
      """

  def getNumPoints( curve_num ):
      """
      Get the number of control points in the curve.
      @type curve_num: integer
      @param curve_num: zero-based index into list of curves in this Curve
      @rtype: integer
      """

class CurNurb:
    """
    The CurNurb Object
    ==================
    This object provides access to the control points of the curves that make up a Blender Curve.

    The CurNurb supports the python iterator protocol which means you can use a python for statement to access the points in a curve.

    The CurNurb also supports the sequence protocol which means you can access the control points of a CurNurb using the [] operator.

    @cvar flagU: The CurNurb knot flag U (0: uniform, 1: endpoints, 2: bezier)
    @cvar flagV: The CurNurb knot flag V (0: uniform, 1: endpoints, 2: bezier)
    @cvar type: The type of the curve (Poly: 0, Bezier: 1, NURBS: 4)
    """
	
    def __setitem__( n, point ):
      """
	  Replace the Nth point in the curve. The type of the argument must match the type of the curve. List of 4 floats (optional 5th float is the tilt value in radians) for Nurbs or BezTriple for Bezier.
      @rtype: PyNone
      @return: PyNone
      @type n: integer
      @param n: the index of the element to replace
      @type point: BezTriple or list of 4 floats (optional 5th float is the tilt value in radians)
      @param point: the point that will replace the one in the curve.  The point can be either a BezTriple type or a list of 4 floats in x,y,z,w (optionally tilt in radians as 5th value) format for a Nurb curve.
      """

    def __getitem__( n ):
      """
	  Get the Nth element in the curve. For Bezier curves, that element is a BezTriple. For the rest (Poly and Nurbs), it is a list of 5 floats: x, y, z, weight, tilt (in radians). NOTE 1: This element element is independant on the curve, modifying it will not affect the curve. NOTE 2: Each successive call returns a new object.
      @rtype: BezTriple (Bezier Curve) or List of 5 floats [x, y, z, w, t] for Poly or Nurbs
      @return: The Nth element in the curve
      @type n: integer
      @param n: the index of the element to return
      """

    def append( new_point ):
      """
      Appends a new point to a curve.  This method appends points to both Bezier and Nurb curves. The type of the argument must match the type of the curve. List of 4 floats (optional 5th float is the tilt value in radians) for Nurbs or BezTriple for Bezier.
      @rtype: PyNone
      @return: PyNone
      @type new_point: BezTriple or list of 4 floats (optional 5th float is the tilt value in radians)
      @param new_point: the new point to be appended to the curve.  The new point can be either a BezTriple type or a list of 4 floats in x,y,z,w (optionally tilt in radians as 5th value) format for a Nurb curve.
      """

    def setMatIndex( index ):
      """
      Sets the Material index for this CurNurb.
      @rtype: PyNone
      @return: PyNone
      @type index:  integer
      @param index: the new value for the Material number of this CurNurb.  No range checking is done.
      """

    def getMatIndex():
      """
      Returns the Material index for this CurNurb.
      @rtype: integer
      @return: integer
      """

    def isNurb():
      """
      Boolean method used to determine whether a CurNurb is of type Bezier or of type Nurb.
      @rtype: boolean
      @return:  True or False
      """

    def isCyclic():
      """
      Boolean method checks whether a CurNurb is cyclic (a closed curve) or not.
      @rtype: boolean
      @return: True or False
	  """

    def getFlagU():
      """
      Get the CurNurb knot flag U 
      @rtype: integer
      @return: 0 - uniform, 1 - endpoints, 2 - bezier
      """

    def setFlagU( value ):
      """
      Set the CurNurb knot flag U (knots are recalculated automatically)
      @type value: integer
      @param value: CurNurb knot flag (0 - uniform, 1 - endpoints, 2 - bezier)
      @rtype: PyNone
      @return: PyNone
      """

    def getFlagV():
      """
      Get the CurNurb knot flag V 
      @rtype: integer
      @return: 0 - uniform, 1 - endpoints, 2 - bezier
      """

    def setFlagV( value ):
      """
      Set the CurNurb knot flag V (knots are recalculated automatically)
      @type value: integer
      @param value: CurNurb knot flag (0 - uniform, 1 - endpoints, 2 - bezier)
      @rtype: PyNone
      @return: PyNone
      """

    def getType():
      """
      Get the type of the curve 
      @rtype: integer
      @return:  0 - Poly, 1 - Bezier, 4 - NURBS
      """

    def getType( value ):
      """
      Set the type of the curve and converts the curve to its new type if needed
      @type value: integer
      @param value: CurNurb type flag (0 - Poly, 1 - Bezier, 4 - NURBS)
      @rtype: PyNone
      @return: PyNone
      """