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 ../../../_images/create.gif
 
Degree in surface U direction. Default is degree 3.
degreeV (dv) int ../../../_images/create.gif
 
Degree in surface V direction. Default is degree 3.
formU (fu) unicode ../../../_images/create.gif
 
The string for open is “open” , for closed is “closed” or for periodic is “periodic” in U.
formV (fv) unicode ../../../_images/create.gif
 
The string for open is “open” , for closed is “closed” or for periodic is “periodic” in V.
knotU (ku) float ../../../_images/create.gif
 
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 ../../../_images/create.gif
 
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 ../../../_images/create.gif
 

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 ../../../_images/create.gif
 

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.

Previous topic

pymel.core.modeling.subdivDisplaySmoothness

Next topic

pymel.core.modeling.textCurves

Core

Core Modules

Other Modules

This Page