pymel.core.modeling.surface

surface(*args, **kwargs)

The cmd creates a NURBS spline surface (rational or non rational). The surface is created by specifying control vertices (CV’s) and knot sequences in the U and V direction. You cannot query the properties of the surface using this command. See examples below.

Maya Bug Fix:

• name parameter only applied to transform. now applies to shape as well

Flags:

Long name (short name)		Argument Types	Properties
degreeU (du)		int
	Degree in surface U direction. Default is degree 3.
degreeV (dv)		int
	Degree in surface V direction. Default is degree 3.
formU (fu)		unicode
	The string for open is “open” , for closed is “closed” or for periodic is “periodic” in U.
formV (fv)		unicode
	The string for open is “open” , for closed is “closed” or for periodic is “periodic” in V.
knotU (ku)		float
	Knot value(s) in U direction. One flag per knot value. There must be (numberOfPointsInU + degreeInU - 1) knots and the knot vector must be non-decreasing.
knotV (kv)		float
	Knot value(s) in V direction. One flag per knot value. There must be (numberOfPointsInV + degreeInV - 1) knots and the knot vector must be non-decreasing.
name (n)		unicode
objectSpace (ob)		bool
point (p)		float, float, float
	To specify non rational CV with (x, y, z) values. “linear” means that this flag can take values with units. Note that you must specify (degree+1) surface points in any direction to create a visible surface span. eg. if the surface is degree 3 in the U direction, you must specify 4 CVs in the U direction. Points are specified in rows of U and columns of V. If you want to incorporate units, add the unit name to the value, eg. “-p 3.3in 5.5ft 6.6yd”
pointWeight (pw)		float, float, float, float
	To specify rational CV with (x, y, z, w) values. “linear” means that this flag can take values with units. Note that you must specify (degree+1) surface points in any direction to create a visible surface span. eg. if the surface is degree 3 in the U direction, you must specify 4 CVs in the U direction. Points are specified in rows of U and columns of V.Flag can appear in Create mode of commandFlag can have multiple arguments, passed either as a tuple or a list.
worldSpace (ws)		bool

Derived from mel command maya.cmds.surface

Example:

import pymel.core as pm

# This following command produces a flat, rectangular surface that is degree 3
# in both directions.  This means that there must be at least 4 x 4
# points to define the surface, since 4 is the (degree + 1).  There
# must be 6 knots in each direction, because the knot vector must
# be (number of points + degree - 1), ie. (4 points + degree 3 - 1).
# The CVs are specified in rows of U and columns of V, as you
# would read a book from left to right, up to down. ie. in this order:
# surface.cv[0][0] surface.cv[0][1] surface.cv[0][2] surface.cv[0][3]
# surface.cv[1][0] surface.cv[1][1] surface.cv[1][2] surface.cv[1][3]
# surface.cv[2][0] surface.cv[2][1] surface.cv[2][2] surface.cv[2][3]
# surface.cv[3][0] surface.cv[3][1] surface.cv[3][2] surface.cv[3][3]

pm.surface( du=3, dv=3, ku=(0, 0, 0, 1, 1, 1), kv=(0, 0, 0, 1, 1, 1), p=((-0.5, 0, 0.5), (-0.5, 0, 0.16), (-0.5, 0, -0.16), (-0.5, 0, -0.5), (-0.16, 0, 0.5), (-0.16, 0, 0.16), (-0.16, 0, -0.16), (-0.16, 0, -0.5), (0.16, 0, 0.5), (0.16, 0, 0.16), (0.16, 0, -0.16), (0.16, 0, -0.5), (0.5, 0, 0.5), (0.5, 0, 0.16), (0.5, 0, -0.16), (0.1, 0, -0.1)) )
# Result: nt.NurbsSurface(u'surfaceShape1') #

# This following command produces a surface that is degree 3 and periodic in
# the U direction, and degree 1 in the V direction.  Notice that
# the first 3 pairs of points match the last 3 pairs of
# points, which is required for a degree 3 periodic surface.

pm.surface( du=3, dv=1, fu='periodic', fv='open', ku=(0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12), kv=(0, 1), pw=((4, -4, 0, 1), (4, -4, -2.5, 1), (5.5, 0, 0, 1), (5.5, 0, -2.5, 1), (4, 4, 0, 1), (4, 4, -2.5, 1), (0, 5.5, 0, 1), (0, 5.5, -2.5, 1), (-4, 4, 0, 1), (-4, 4, -2.5, 1), (-5.5, 0, 0, 1), (-5.5, 0, -2.5, 1), (-4, -4, 0, 1), (-4, -4, -2.5, 1), (0, -5.5, 0, 1), (0, -5.5, -2.5, 1), (4, -4, 0, 1), (4, -4, -2.5, 1), (5.5, 0, 0, 1), (5.5, 0, -2.5, 1), (4, 4, 0, 1), (4, 4, -2.5, 1)) )
# Result: nt.NurbsSurface(u'surfaceShape2') #

# This following command produces a surface that is degree 5 in both directions.

pm.surface( du=5, dv=5, fu='open', fv='open', p=((-7, 0, 1), (-6, 0, 4), (-3, 0, 6), (0, 0, 7), (4, 0, 5), (6, 0, 3), (-7, 2, 1), (-6, 2, 4), (-3, 2, 7), (0, 2, 8), (4, 2, 5), (6, 2, 3), (-7, 3, 1), (-6, 3, 4), (-3, 3, 8), (0, 3, 9), (4, 3, 5), (6, 3, 3), (-7, 4, 1), (-6, 4, 4), (-3, 4, 9), (0, 4, 8), (4, 4, 5), (6, 4, 3), (-7, 5, 1), (-6, 5, 4), (-3, 5, 8), (0, 5, 7.5), (4, 5, 5), (6, 5, 3), (-7, 6, 1), (-6, 6, 4), (-3, 6, 6), (0, 6, 7), (4, 6, 5), (6, 6, 3)), ku=(0, 0, 0, 0, 0, 1, 1, 1, 1, 1), kv=(0, 0, 0, 0, 0, 1, 1, 1, 1, 1) )
# Result: nt.NurbsSurface(u'surfaceShape3') #


# How to query surface properties:

pm.getAttr( 'surface1.degreeU' )
# Result: 3 #
# Returns an integer that is the surface degree in U

pm.getAttr( 'surface1.degreeV' )
# Result: 3 #
# Returns an integer that is the surface degree in V

pm.getAttr( 'surface1.spansU' )
# Result: 1 #
# Returns an integer that is the # spans in U

pm.getAttr( 'surface1.spansV' )
# Result: 1 #
# Returns an integer that is the # spans in V

pm.getAttr( 'surface1.formU' )
# Result: 0 #
# Return 0 = open, 1 = closed, 2 = periodic

pm.getAttr( 'surface1.formV' )
# Result: 0 #
# Returns 0 = open, 1 = closed, 2 = periodic

pm.getAttr( 'surface1.minValueU' )
# Result: 0.0 #
pm.getAttr( 'surface1.maxValueU' )
# Result: 1.0 #
pm.getAttr( 'surface1.minValueV' )
# Result: 0.0 #
pm.getAttr( 'surface1.maxValueV' )
# Result: 1.0 #
# These return the minimum and maximum parameter ranges in each direction.

pm.getAttr( 'surface1.cv[0][0]' )
# Result: dt.Vector([-0.5, 0.0, 0.5]) #
# Returns the position of a CV of surface1 in local space.  If the
# surface is a result of construction history, use a surface info
# node instead to get the CV position.

pm.getAttr( 'surface1.cv[*][0]' )
# Result: (-0.5, 0.0, 0.5) #
# Returns the positions of a row of CVs of surface1 in local space.
# If the surface is a result of construction history, use a surface info
# node instead to get the CV positions.

pm.createNode( 'surfaceInfo' )
# Result: nt.SurfaceInfo(u'surfaceInfo1') #
pm.connectAttr( 'surfaceShape1.worldSpace', 'surfaceInfo1.inputSurface', f=True )
pm.getAttr( 'surfaceInfo1.controlPoints[*]' )
# Result: (-0.5, 0.0, 0.5) #
# Returns the surface CVs in world space.   A surface info node can
# also be used to query the surface knot vectors.