PolyToolsModeling : GlobalUtilityPlugin

The PolyToolsModeling Global Utility Plugin introduced in 3ds Max 2011 exposes an interface that provides MAXScript access to the Graphite Modeling tools.

The functionality was first implemented in 3ds Max 2010 using different functions that were not officially supported as MAXScript tools. This interface consolidates all relevant properties and methods, and lets MAXScript users apply them in their own tools.

PolyToolsModeling interfaces:

Constructor:

Class instances not creatable by MAXScript

PolyToolsModeling interfaces:

Interface:  PolyToolsModeling

Methods:

Loops Panel

<boolean>PolyToolsModeling.DistanceConnect ()

Creates connections between sub-object elements across distance and other topology.

Sub-Object Level	Function
Polygon	Not supported.
Edge	Select two edges and apply to make a connection between them that goes across the mesh between them.
Vertex	Select two end vertices and apply to make a connection between them that goes across the mesh between them.

EXAMPLE

Connecting the two selected edges over a distance:

   --Step 1:
   p = plane lengthsegs:10 widthsegs:10 wirecolor:blue
   convertTo p Editable_Poly
   select p
   max modify mode
   subObjectLevel = 2
   polyOp.setEdgeSelection p #{76,92}
   --Step 2:
   PolyToolsModeling.DistanceConnect ()

<boolean>PolyToolsModeling.RemoveLoop ()

Removes a loop in the current sub-object level and automatically removes any left over vertices.

Sub-Object Level	Function
Polygon	Select two or more polygons and apply to remove whole rows of polygons.
Edge	Select one or more edges and apply to remove the loops which the selected edges is on.
Vertex	Select two or more vertices and apply to remove loops of vertices.

EXAMPLE

Removing Edge Loops using two Polygons, one Edge and two Vertices:

   --Step 1:
   p = plane lengthsegs:10 widthsegs:10 wirecolor:blue --create a plane
   convertTo p Editable_Poly --convert the plane to Editable_Poly
   select p --select the plane to be able to see the results
   max modify mode --switch Command Panel to Modify mode
   subObjectLevel = 4 --switch topolygonsub-object level
   polyOp.setFaceSelection p #{22,23} --select two polygons to define the loops
   --Step 2:
   PolyToolsModeling.RemoveLoop () --remove the loops defined by the two polygons

   --Step 3:
   subObjectLevel = 2 --switch to edge sub-object level
   polyOp.setEdgeSelection p #{101} --select one edge
   --Step 4:
   PolyToolsModeling.RemoveLoop() --remove the loop defined by the one edge

   --Step 5:
   subObjectLevel =1 --switch to vertex sub-object level
   polyOp.setVertSelection p #{101} --select two vertices
   --Step 6:
   PolyToolsModeling.RemoveLoop () --remove the loop defined by the two vertices

<boolean>PolyToolsModeling.SetFlow <boolean>autoLoop

Automatically fits selected edges or vertices to the surrounding flow of the mesh.

If autoLoop is supplied as true, a full edge loop will be created in the Edge sub-object level.

Sub-Object Level	Function
Polygon	Not supported.
Edge	Select one or more edges and apply to fit to surrounding topology.
Vertex	Select one or more vertices and apply to fit to surrounding topology.

<boolean>PolyToolsModeling.SetFlowVertex ()

Automatically fits the selected vertex to the surrounding flow of the mesh.

<boolean>PolyToolsModeling.BuildEnd ()

Inserts two loops and builds a quad ending on both endings.

Sub-Object Level	Function
Polygon	Not supported.
Edge	Select edges in a row (edge ring) and call this method to insert two loops connecting the selected edges and build quad endings.
Vertex	Select two vertices at the ends of two parallel loops and apply to build quad end.

<boolean>PolyToolsModeling.BuildCorner ()

Builds a quad corner based on vertex selection to make an edge loop turn.

Sub-Object Level	Function
Polygon	Not supported.
Edges	Select one or more edges at the corner of an edge loop and apply to build quad corner.
Vertex	Select two vertices and apply to build quad corner.

<boolean>PolyToolsModeling.RandomConnect <float>jitter <boolean>autoLoop

Connects edges and randomizes the position of the newly created vertex within each edge.

Returns true on success, false on failure (for example, if called while not in Edge Sub-Object Level).

The first argument controls the Random Jitter factor.

A jitter value of 0 produces a connection through the centers of the selected edges without any randomness.
A value of 0.5 jitters the position of the new vertices within the length of the edge (between its two vertices).
Values above 0.5 will produce vertices outside the selected edge, potentially causing polygon overlaps and z-fighting geometry.

The second argument controls whether the initial selection needs to be expanded to neighbor edge loops to facilitate connecting when the initial selection is not enough to produce any.

If set to false, connections will be produced only within the initial selection.
If set to true, the initial selection will be expanded first by selecting edge rings from the existing selected edge loops, then the resulting selection will be used to create the random connections.

EXAMPLE

Random Connecting Within a 10x10 Grid using autoLoop passed as true:
   --Step 1:
   p = plane lengthsegs:10 widthsegs:10 wirecolor:blue --create a plane
   convertTo p Editable_Poly --convert the plane to Editable_Poly
   select p --select the plane to be able to see the results
   max modify mode --switch Command Panel to Modify mode
   subObjectLevel =2 --switch to polygonsub-object level
   polyOp.setEdgeSelection p #{82} --select one edge to define a loop
   --Step 2:
   PolyToolsModeling.RandomConnect 0.3 true --create loops and connect randomly
Note that although there was just a single edge selected, the AutoLoop second argument set to true produced an edge ring from the selected edge, then performed the random connect over the new selection. With autoLoop false, no connection edges are created.
   --Step 3:
   PolyToolsModeling.RandomConnect 0.3 true --create loops and connect randomly
   --Step 4:
   PolyToolsModeling.RandomConnect 0.3 true --create loops and connect randomly
In the third step, we start once again from a single edge loop which, if used with autoLoop set to false, would not produce any connections. Now we produce a large number of parallel random loops, but they are "blocked" by unselected straight edgeloops which would once again produce no connections if autoLoop would be passed as false in the fourth step.

EXAMPLE

Random Connecting Within a 10x10 Grid using autoLoop passed as false:
   --Step 1:
   p = plane lengthsegs:10 widthsegs:10 wirecolor:blue --create a plane
   convertTo p Editable_Poly --convert the plane to Editable_Poly
   select p --select the plane to be able to see the results
   max modify mode --switch Command Panel to Modify mode
   subObjectLevel =2 --switch to polygon sub-object level
   polyOp.setEdgeSelection p #{80,82,84,86,88} --select edges to define a ring
   --Step 2:
   PolyToolsModeling.RandomConnect 0.5 false --connect selected only
In this case, our initial selection already contains enough edges in a ring to create a valid random connection. We do not want the selected edge ring to be expanded further, so we pass false as the second argument, producing a random connection only within the existing selection.

Edges Panel

<boolean>PolyToolsModeling.SpinEdge <boolean>alternativeDir

Spins the selected edge/edges in the polygon, changing their direction.

Returns true on success, false on failure.

Sub-Object Level	alternativeDir = false	alternativeDir = true
Polygon	Not supported.	Not supported.
Edge	Select edge/edges and apply to spin edges clockwise.	Select edge/edges and apply to spin edges counter-clockwise.
Vertex	Not supported.	Not supported.

<boolean>PolyToolsModeling.InsertVertex <integer>number

Inserts the specified number of vertices in the selected edges. The inserted vertices are evenly spaced along the edge.

Returns true on success, false on failure.

Sub-Object Level	Function
Polygon	Not supported.
Edge	Select an edge and apply to insert vertices on the selected edge/edges.
Vertex	Not supported.

Geometry (All) Panel

<boolean>PolyToolsModeling.Quadrify <boolean>withinSel <boolean>selectOnly

Remove triangulation from the model to achieve mainly four sided polygons.

When withinSel is set to true, applies to the current sub-object selection only.

When selectOnly is set to true, does not remove, but only selects the edges to be removed.

Returns true on success, false on failure.

Polygons Panel

<boolean>PolyToolsModeling.GeoPoly ()

Untangles a polygon and organizes the vertices to form a perfect geometric shape.

Sub-Object Level	Function
Polygon	Select polygons and apply to make geometric shape. If several adjacent polygons are selected, the result will be averaged between the polygons.
Edge	Not supported.
Vertex	Not supported.

Loop Tools

<boolean>PolyToolsModeling.CenterLoop <boolean>autoLoop

Centers edges or edgeloops on the edgerings they are on and places the vertices in the middle of the edges.

Select an edge or more edges and apply.

If the autoLoop argument is true , the selection will be automatically looped.

<boolean>PolyToolsModeling.SpaceLoop <boolean>autoLoop

Spaces the vertices evenly along the selected edges/edgeloops so that the distances between the vertices become equal.

If the autoLoop argument is true, the selection will be automatically looped.

If the SHIFT key is pressed while this method is being executed, it will also space loops on the top and bottom of a cylinder.

<boolean>PolyToolsModeling.CurveLoop <boolean>autoLoop <boolean>spaceLoop

Adjusts each set of selected edges/edgeloops into smooth curves.

The curvature of each loop is determined by the position of the selected vertices along the loop. Think of the curve that you can create as a spline going from the endpoints of the edges/loop with a smoothly interpolated spline knot at each selected vertex.

If the autoLoop argument is true , the initial selection will be automatically looped before the tool is applied.

If the spaceLoop argument is true , all vertices will be evenly spaced along the loop.

If the spaceLoop argument is false , the initial relationship between vertices on the loop will be kept.

Note:

The edgeloop selection must not be closed (like a circle) for this tool to work because there needs to be a start and end-point for a curve.

The actual edgeloop can be closed, but not the selected edgeloop.

<boolean>PolyToolsModeling.StraightLoop <boolean>autoLoop <boolean>spaceLoop

Straightens each set of selected edges/edgeloops into straight lines.

If any of the vertex "endpoints" of the set of edges/edgeloop are selected, the line will go from the first edge that the selected vertex is on and straight out from that edge. If no vertices are selected, the line will go between the two endpoints of the edges/edgeloop.

If the autoLoop argument is true , the initial selection will be automatically looped before the tool is applied.

If the spaceLoops argument is true , all vertices will be evenly spaced along the loop.

If the spaceLoops argument is false , the initial relationship between vertices on the loop will be kept.

If the SHIFT key is pressed while this method is being executed, it will also straighten loops on the top and bottom of a cylinder.

<boolean>PolyToolsModeling.CircleLoop <boolean>autoLoop

Turns each set of selected edges/edgeloops into the form of a circle.

The selected vertex along each loop determines the beginning point for the circle.

For open loops one of the "endpoints" of the edges/loop must be selected.

For closed loops (like around a cylinder), the vertex you want to least have change position must be selected.

If the autoLoop argument is true , the initial selection will be automatically looped before the tool is applied.

If the SHIFT key is pressed while this method is being executed, it will also circle loops on the top and bottom of a cylinder.

Tip: Make sure that the vertex next after the first on the loop goes in the general direction of the intended circle so that the circle is not "inverted".

<boolean>PolyToolsModeling.RelaxLoop <boolean>autoLoop

Relaxes/smooths out the curvature of each set of selected edges/edgeloops.

Call multiple times to relax more.

If the autoLoop argument is true, checked the initial selection will be automatically looped before the tool is applied.

If the SHIFT key is pressed while this method is being executed, it will also relax loops on the top and bottom of a cylinder.

Symmetry

<boolean>PolyToolsModeling.SymmetryGather <node>node <value>axis <float>threshold

Collects symmetry data from the node specified as the first argument.

The second argument defines the symmetry axis as name- #x, #y, or #z.

The third argument defines the position variation threshold to use when searching for symmetry vertices.

<boolean>PolyToolsModeling.SymmetryPosToNeg <value>axis

Copies the vertex positions from the positive side of the symmetry axis to the negative side.

The axis argument can be either #x, #y, or #z.

Corresponds to the "+To-" button in the Symmetry Tools floating dialog.

<boolean>PolyToolsModeling.SymmetryNegToPos <value>axis

Copies the vertex positions from the negative side of the symmetry axis to the positive side.

The axis argument can be either #x, #y, or #z.

Corresponds to the "-To+" button in the Symmetry Tools floating dialog.

<boolean>PolyToolsModeling.SymmetryFlip <value>axis

Swaps the symmetry data about the specified axis.

<boolean>PolyToolsModeling.SymmetryCopy ()

Copies the vertex positions of the currently selected vertices into an internal "clipboard".

<boolean>PolyToolsModeling.SymmetryPaste ()

Pastes the vertex positions back onto the same vertices, even if not selected.

EXAMPLES

Using the Symmetry methods:

   --Step 1:
   s = sphere radius:12 segs:32 wirecolor:blue
   convertTo s Editable_Poly
   select s
   max modify mode
   subObjectLevel = 1
   PolyToolsModeling.SymmetryGather s #x 0.01

   --Step 2:
   PolyOp.moveVert s #{122} [5,0,5]
   --Step 3:
   PolyToolsModeling.SymmetryPosToNeg #x

   --Step 4:
   PolyOp.moveVert s # {170} [-5,0,0]
   --Step 5:
   PolyToolsModeling.SymmetryNegToPos #x

   --Step 6:
   PolyOp.moveVert s #{58} [3,0,5]
   --Step 7:
   PolyToolsModeling.SymmetryFlip #x

   --Step 8:
   PolyOp.setVertSelection s #{122,170}
   PolyToolsModeling.SymmetryCopy()
   PolyOp.moveVert s #{122,170} [5,0,-20]
   --Step 9:
   PolyToolsModeling.SymmetryPaste()

Other Modeling Methods

<boolean>PolyToolsModeling.MultiHide ()

Hides either selected polygons or selected vertices based on the current sub-object level.

Sub-Object Level	Function
Polygon	Select polygons and apply to hide them.
Edge	Not supported.
Vertex	Select vertices and apply to hide them.

<boolean>PolyToolsModeling.RotateSelection <float>degree <integer>coordsys <point3>viewDirection

Rotates the current sub-selection at the specified degree in the coordinate system defined by the second argument counter-clockwise relative to the view direction specified by the third argument.

Returns true on success, false on failure. For example, if not in a sub-object level.

EXAMPLE

Rotating a Polygon Selection at 30 degrees CCW:

   --Step 1:
   p = plane lengthsegs:10 widthsegs:10 wirecolor:blue --create a plane
   convertTo p Editable_Poly --convert the plane to Editable_Poly
   select p --select the plane to be able to see the results
   max modify mode --switchCommand PaneltoModify mode
   subObjectLevel = 4 --switch topolygonsub-object level
   polyOp.setFaceSelection p #{22,23} --select two polygons to define the loops
   --Step 2:
   PolyToolsModeling.RotateSelection 30 1 -(viewport.getTM()).row3

<boolean>PolyToolsModeling.MirrorElement <value>axis <boolean>clone

Mirror the selected element about the specified axis.

If the clone argument is passed as true, the element will be duplicated.

If the clone argument is false, the original element will be mirrored.

Returns true on success, false on failure.

<integer>PolyToolsModeling.CreateFace <bitArray>bitarray

Creates a Polygon from the vertex indices provided by the bitarray argument.

Returns the index of the new polygon.

PolyToolsModeling : GlobalUtilityPlugin

PolyToolsModeling interfaces:

Loops Panel

Edges Panel

Geometry (All) Panel

Polygons Panel

Loop Tools

Symmetry

Other Modeling Methods

Related pages