UVs¶
Uv Functions¶
- uvLists(componentSelection)¶
From any maya selection return the UVs as two lists, u space and v space:
uList = [12, 23.0, 34.5] vList = [12.34, 23.23, 3.5]
- Parameters:
componentSelection (str(lists)) – Maya selection
- Returns:
- Return type:
- uvEdgeVerticalOrHorizontal(componentSelection, mode='tube')¶
Returns whether the uv edge selection is in horizontal or vertical space, assumes perfectly horizontal/vertical Usually used with gridify and unfold on a single axis.
Automatically figures if unwrap should be vertical or horizontal.
If mode is “tube” then assumes the edge selection is on a UV border (has been gridified), otherwise “grid” is a single edge-loop. “tube” mode needs more than one edge selected or it will fail.
- The selection will have 2 rows or columns in a perfectly straight UV line, return whether:
Columns = should unwrap “horizontal” Rows = should unwrap “vertical” Unknown not detected = “”
mode is the method to figure:
“tube”: is two uv edge loops (only in uvs) sharing a shell border “grid”: one edge loop
- uvBoundingBoxSize(componentSelection)¶
returns the bounding box size of the component selection in uvs
- Example:
componentSelection = [“object.f[0:123]”, “object.f[333]”] return uWidth: 0.751, return vHeight: 0.221
- Parameters:
componentSelection (list(str)) – Maya object or component selection
- Return uWidth:
the width of the uv bounding box
- Rtype uWidth:
float
- Return vHeight:
the height of the uv bounding box
- Rtype vHeight:
float
- boundingBoxHorizontalOrVertical(selComponents)¶
Tests to see if the UV bounding box of any maya selection is more vertical or horizontal.
returns “” if the uv bounding box is identical in width and height
- Parameters:
selComponents (list(str)) – Maya object or component selection
- Return horizontalOrVertical:
Can be “horizontal”, “vertical” or “” if identical
- Rtype horizontalOrVertical:
str
- openUVEditor(displayStyle='')¶
Opens Mayas UV editor and optionally sets the newly opened UV editor’s display settings
- Parameters:
displayStyle (str) – The preset name as defined in the globals
- uvDisplayModePresets(displayStyle='Display Checker 100%')¶
Presets for various UV editor display modes
- Parameters:
displayStyle (str) – The preset name as defined in the globals
- uvDisplayMode(checker=True, textureImage=False, shaded=False, distortion=False, coloredShells=False, textureTransparency=1.0)¶
Sets the UV display settings of the UV editor
Note this code can be a little flakey, seems to be due to Maya code doing weird things, works in most cases.
- Parameters:
checker (bool) – Sets the checker texture visibility, must also have textureImage on. checker False is maya texture
textureImage (bool) – Sets the texture image on or off. Can be the texture or the objects texture see “checker”
shaded (bool) – Sets the shaded mode on needed for distortion and coloredShells, otherwise is blue shells
distortion (bool) – Sets the distortion to be on, must have “shaded” on, coloredShells off
coloredShells (bool) – Sets each UV shell to be a different color, must have “shaded” on, distortion off
textureTransparency (bool) – Sets the texture dimming level 1.0 is full texture, 0.0 is black
- uvBorderSize(borderSize=2)¶
Sets the UV border display width
- Parameters:
borderSize (int) – Border width in pixels
- checkerTextureSize(checkerDensity=128)¶
Sets the check size if visible, above 256 is a lot of squares and can alias badly
- Parameters:
checkerDensity (int) – The amount of squares horizontally or vertically
- uvProjection(selList, type='planar', mapDirection='c')¶
Standard Maya UV projection, “planar”, “cylindrical”, “spherical”
Must use selection in this function due to converting to faces with selection.convertSelection(type=”faces”)
- uvProjectionSelection(type='planar', mapDirection='c', message=True)¶
Standard Maya UV projection, “planar”, “cylindrical”, “spherical” uses selection
- Parameters:
- Return success:
Operation was successful True or not False
- Rtype success:
bool
- symmetryBrush(auto=True, UVAxisOffset=0.5, UVAxis=0, UVAxisIncrement=0.1, useMayaOptions=False)¶
Activates the symmetry brush with automatic setting of the UVAxisOffset and UVAxis
Select a center edge (if auto=True)
Run the script
Select the same center edge
Pivot and axis are set automatically
- Parameters:
auto (bool) – When True will take the selection if a edge, uv or vert selection
UVAxisOffset (float) – The pivot of the symmetry, is overriden by auto=True
UVAxis (int) – 0 is horizontal, 1 is vertical
UVAxisIncrement (float) – For the ctrl MMB set axis manually, amount to increment that line
useMayaOptions (bool) – If True will use Maya’s default options, instead of our kwargs, “auto” must be False
- cutUvs(edgeSelection, constructionHistory=False)¶
Cuts UV edge based on selList list with edge selection
- Parameters:
edgeSelection (list(str)) – Maya selection list
- cutUvsSelection(message=True, constructionHistory=True)¶
Cuts UV edge based on selection with edge check and warning message
Supports multiple object selection.
- Parameters:
message (bool) – Report the message to the user?
- Return success:
Operation was successful True or not False
- Rtype success:
bool
- cutPerimeterUVs(componentSelection, constructionHistory=True)¶
Cuts a perimeter edge of UVs while maintaining the current selection and component mode
- cutPerimeterUVsSelection(constructionHistory=True)¶
Cuts a perimeter edge of UVs based on selection, while maintaining the current selection and component mode
- Parameters:
constructionHistory (bool) – keep construction history?
- sewUvs(edgeSelection, constructionHistory=False)¶
Cuts UV edges based on selList list with edge selection
- Parameters:
edgeSelection (list(str)) – Maya selection list
- sewUvsSelection(constructionHistory=False, message=True)¶
Sews UV edges based on selection with edge check and warning message
- Parameters:
message (bool) – Report the message to the user?
- Return success:
Operation was successful True or not False
- Rtype success:
bool
- moveAndSew(selList)¶
Move and sew uvs with default settings
- Parameters:
selList (list(str)) – Maya selection
- moveAndSewSelection(message=True)¶
Unitize UV faces (old normalize), each quad is zero to one space
- Parameters:
message (bool) – Report the message to the user?
- Return success:
Operation was successful True or not False
- Rtype success:
bool
- cutAndSewTool3d()¶
Enters Maya’s 3d Cut and Sew tool
- autoSeamsSelection(splitShells=0.0, cutPipes=1)¶
Maya’s auto seam tool
- Parameters:
splitShells (float) – The slider for more or less edges in the automatic seam selection (0.0 -1.0)
cutPipes –
- orientEdge()¶
Orients the whole shell by straightening to the selected edge
- orientShell()¶
Orients the whole shell automatically, select an object or shell, no component selected will work on object
- alignUvSelection(straightenType='avgV')¶
Align Straighten UVs to the center, max or min on either horizontal (U) or vertical (V)
- straightenType is a str, the average minimum or maximum value, and on either vertical or horizontal:
“minV”, “maxV”, “avgV”, “minU”, “maxU”, “avgU”
- straightenUv(components, angle=30, dirType='all')¶
Mel straighten UV command with options, this function passes in a component selection
- type:
“all” is all edges are straightened mel “UV” “horizontal” restricts to only horizontal edges or “U” “vertical” restricts to only vertical edges or “V”
- angle:
The angle threshold where the straighten occurs
- straightenUvSelection(angle=30, dirType='all')¶
Mel straighten UV command with options, works off current selection
- type:
“all” is all edges are straightened mel “UV” “horizontal” restricts to only horizontal edges or “U” “vertical” restricts to only vertical edges or “V”
- angle:
The angle threshold where the straighten occurs
- autoSeamsUnfoldSelection(splitShells=0.0, cutPipes=1, select=1, mapSize=1024)¶
Maya’s autoseam tool with unfold
- Parameters:
splitShells –
cutPipes –
select –
mapSize –
- Returns:
- Return type:
- regularUnfoldSelection(iterations=1, pack=0, borderintersection=1, triangleflip=1, mapsize=1024, roomspace=0)¶
The default newer plugin Unfold3D algorithm, not legacy unfold. Works on selection.
- Parameters:
iterations (int) – Number of times the calculations are performed
pack (int) – Pack the UVs after unfolding? Note must be 1 or 0 as it’s mel
borderintersection (int) – prevents self-intersections on the border of the unfolded UV shells, must be 0 or 1
triangleflip (int) – prevents degenerate UV maps. Degeneracy can occur when a UV is moved so a face overlaps itself
mapsize (int) – The texture map size in pixels to account for shell spacing
roomspace (int) – Space between UVs on own shells see Maya documentation, recommended don’t go past 2
- regularUnfoldSelectionPackOption(iterations=1, borderintersection=1, triangleflip=1, mapsize=1024, roomspace=0)¶
Same as regularUnfoldSelection but will auto pack if an object selection and not pack if component
Depreciated as the Unfold layout isn’t great, could use regular unfold after?
See regularUnfoldSelection() for documentation
- legacyUnfold(selList, dirType='')¶
Legacy unfold UVs with options, usually for directional unfolding as is not in the new plugin
Mostly used for unfolding on one axis If using both axis then better to use regularUnfoldSelection()
- legacyUnfoldSelection(dirType='', message=True)¶
Unitize UV faces (old normalize), each quad is zero to one space
- Parameters:
message (bool) – Report the message to the user?
- Return success:
Operation was successful True or not False
- Rtype success:
bool
- layoutUvs(selObjs='', resolution=1024, preScaleMode=1, preRotateMode=0, shellSpacing=2, tileMargin=2, packBox='0 1 0 1')¶
Works on the selection if selection is “”
- Parameters:
selObjs –
resolution –
preScaleMode –
preRotateMode –
shellSpacing –
tileMargin –
packBox –
- Returns:
- Return type:
- normalize(selList, preserveAspectRatio=True)¶
Normalizes UVs into 0-1 space. Preserve aspect ratio does not stretch UVs
- normalizeSelection(selList, preserveAspectRatio=True, message=True)¶
Normalizes UVs into 0-1 space based on selection. Preserve aspect ratio does not stretch UVs
Uv Macros¶
Macro Functions for UVs Unfold/Gridify/Straighten Functions. this module also includes functions with repeat/undo decorators for hitting the “g” hotkey.
- unfoldGridifyMesh(unfold, dirType, uvShellSelection, recordAutomatic, straightenLoops, faceSelection, straightenAngle, edgeSelection, deleteHistory, directionWarning, mode)¶
The second half of the functions unwrapGridShellSelection() and unwrapTubeSelection() see those for documentation
Assumes that a uvs have been gridified and proceeds with the unfold
- unwrapGridShellSelection(dirType='automatic', straightenLoops=True, unfold=True, straightenAngle=80, deleteHistory=True, faceLimit=1500, message=True)¶
Gridifies a UV shell, must be a quad grid, then optionally unfolds on a single axis, or other options.
Works from a single edge loop selection on the interior of the quad grid UV shell.
Helpful for straightening road like UVs and other windy planes or UV shells.
Similar to unwrapTubeSelection()
Warning: This function can get slow over about 1500 faces while straightening. See times here. Set a limit with the kwarg faceLimit:
1000 faces = 7 seconds 1500 faces = 20 sec 2500 faces = 1 min 3500 faces = 2 mins 6500 face = 7 mins
- Parameters:
dirType (str) – “automatic”, “vertical” or “horizontal” use the legacy unfold, “regular” uses Unfold3d plugin
straightenLoops (bool) – straighten all edge loops, if off the opposite direction may not be straight
unfold (bool) – straighten all edge loops, if off the opposite direction may not be straight
straightenAngle (float) – The angle that Maya’s straighten algorithm uses
deleteHistory (float) – After completing delete the objects history?
message (bool) – Report the message to the user?
- Return faceCount:
The number of faces potentially unwrapped due to the faceLimit and for UI
- Rtype faceCount:
int
- unwrapTubeSelection(dirType='automatic', straightenLoops=True, unfold=True, straightenAngle=80.0, deleteHistory=True, faceLimit=1500, message=True)¶
Unwraps a tube with a macro that uses the Maya unitize method of tube unwrapping, sometimes known as “gridify”
Can optionally unfold with various options, and straighten all edges.
- type:
“vertical” the unfold is restricted to unfold vertically “horizontal” the unfold is restricted to unfold vertically “automatic” the unfold is automatically figured out, recommended as it’s accurate in most cases “regular” unfolds with the new Maya unfold in both directions
Note: A lot of unavoidable selection in this function short of using other methods such as om2
Warning: This function can get slow over about 1500 faces while straightening. See times here. Set a limit with the kwarg faceLimit:
1000 faces = 7 seconds 1500 faces = 20 sec 2500 faces = 1 min 3500 faces = 2 mins 6500 face = 7 mins
- Parameters:
dirType (str) – “automatic”, “vertical” or “horizontal” use the legacy unfold, “regular” uses Unfold3d plugin
straightenLoops (bool) – straighten all edge loops, if off the opposite direction may not be straight
unfold (bool) – straighten all edge loops, if off the opposite direction may not be straight
straightenAngle (float) – The angle that Maya’s straighten algorithm uses
deleteHistory (float) – After completing delete the objects history?
faceLimit (float) – Counts the faces trying to unwrap, if over limit bail as it may take to long and appear to hang.
message (bool) – Report the message to the user?
- Return faceCount:
The number of faces potentially unwrapped due to the faceLimit and for UI
- Rtype faceCount:
int
- edgeLoopVerticalHorizontal(edgeUvSelection)¶
Calculates whether a line of uvs is more horizontal or vertical
- Parameters:
edgeUvSelection (list(str)) – a list of UVs in a line
- Return directionResult:
“horizontal” U is longer “vertical” v is longer, or “equal” is the same length
- Rtype directionResult:
str
- walkRecordEdgeLoops(edgeSelection, walkSteps=30)¶
Walks 20 (walkSteps) left and records the edge loops, then walks the other way.
Returns the loops left as a list of selections and the loops right.
This function is needed since changing selection while walking will randomly changes its direction, avoids feedback/infinite loops
- walkEdgeLoopsStraightenSelection(walkSteps=30, message=True)¶
Will walk (arrow keys) the edges of a gridded uv shell and straighten all edge loops within its borders
Select an edgeloop and run on a shell that is made up of gridded quads, is fairly stable In some circumstances the border edges will not be straightened.
Is generally faster than Maya’s mel “texStraightenUVs” (uvFunctions.straightenUvSelection) and more reliable
There are a number of issues regarding this function which make it messy:
1. Pick walk is random in the direction it chooses so must pre cache the loops “walkSteps” is the count in each direction, so 30 means max 60 loops are potentially straightened by default. 2. It’s difficult to tell the edge loops that are on the shell border, the whole border is selected instead There are a number of checks to test the correct loop on a border but it can fail in some circumstances. 3. Maya is doing a loads of selection as the converting unfortunately requires it :/