Patch Objects

Patches are the general editable versions of all the patch objects, in the same way that Editable Meshes relate to geometry objects. They are the objects that a patch is converted to when you apply an Edit Patch modifier and the result of collapsing a modifier stack on a patch base object. While MAXScript lets you construct patches, there are no properties or methods for accessing or modifying the sub-objects (vertices, edges, and patches) within the patch object.

Constructor

Quadpatch...
Tripatch...

To create a Patch scene object from scratch, you can call the Patch constructor function,

FOR EXAMPLE

Quadpatch pos:[10,10,10] name:"foo"

This creates an empty patch.

convertTo <node> Editable_Patch -- mapped

Converts the given scene node to a Patch object. If the object cannot be converted (typically, if it is not a geometry object), the function returns undefined . Any modifiers present will be collapsed. The collapseStack() function can also be used as well as the collapse button in the modifier stack dialog in 3ds Max; both generate a Patch, but will only do so if there is at least one modifier present.

Properties

A control vertex and its tangents are available as properties once a controller has been assigned to the control vertex. The number of tangents for a control vertex is the number of edges associated with the control vertex. Controllers can not be assigned to the control vertices using MAXScript. If a TriPatch object is collapsed to Editable_Patch and some of its control vertices are animated, the properties for the control vertices and tangents will be similar to:

$TriPatch01.Vertex_1 Point3value:[-21.5,-6.4,0] -- animatable
$TriPatch01.Vertex_1_Vector_1 Point3value:[-21.5,-2.1,0] -- animatable
$TriPatch01.Vertex_1_Vector_2 Point3value:[-7.1,-6.4,0 ]-- animatable
$TriPatch01.Vertex_2 Point3value:[21.5,-6.4,0] -- animatable
$TriPatch01.Vertex_2_Vector_1 Point3value:[7.1,-6.4,0] -- animatable
$TriPatch01.Vertex_2_Vector_2 Point3value:[7.1,-2.1,0] -- animatable

See also Class and Object Inspector Functions for details on accessing the patch vertices and tangents. The controller values assigned to the vertices and tangent handles is in the object space. See Using Node Transform Properties for information on converting between world space to object space.

Methods

getPatchSteps <editable_patch_node>

Returns the number of steps the patch uses in the viewports, and reflects the View Steps spinner in the Modify panel.

setPatchSteps <editable_patch_node> <integer>

Sets the number of View Steps used by the editable patch object to the specified value.

Editable Patch Modify Panel Command Modes and Operations

A suite of methods provide the ability for a script to invoke Editable Patch and Edit Mesh Modify panel modes and operations, corresponding to buttons available at various mesh sub-object levels. These methods reside in the patchOps global structure. These methods effectively "push the button" in the Modify panel. To use these methods, the node must be selected and the Modify panel must be open. In the description of these methods, the first argument <editable_patch_node_or_modifier> can be interpreted as either an Editable Patch node where the modifier stack level is at the base object, or an Edit Patch modifier where the modifier stack level is at the Edit Patch. In all cases, the following methods work at the current sub-object level, but only if that level is appropriate for the invoked operation.

The follow methods invoke one of the 'user-interaction' button operations in the Editable Patch Modify panel, acting on the currently selected sub-objects. These methods highlight the corresponding button in the Geometry rollout and start the operation, at which point the user interactively completes the operation. These methods return after starting the operation and before the user completes the operation, so ensure that your script does not interfere with the operation. Invoking any of these methods is the same as clicking on the associated button in the Modify panel. Calling a method when the operation is already in effect (either due to a user action or a MAXScript command) causes the operation to be terminated and the highlight is removed from the button.

patchOps.startAttach <editable_patch_node_or_modifier>

Enters the "Attach" command mode - valid in all Sub-Object levels, and when not in the Sub-Object mode.

patchOps.startBevel <editable_patch_node_or_modifier>

Enters the "Bevel" command mode - valid in the Patch Sub-Object level.

patchOps.startBind <editable_patch_node_or_modifier>

Enters the "Bind" command mode - valid in the Vertex Sub-Object level.

patchOps.startCreate <editable_patch_node_or_modifier>

Enters the "Create" command mode - valid in the Vertex, Patch, and Element Sub-Object levels.

patchOps.startExtrude <editable_patch_node_or_modifier>

Enters the "Extrude" command mode - valid in the Patch Sub-Object level.

patchOps.startFlipNormalMode <editable_patch_node_or_modifier>

Enters the "Flip Normal" command mode - valid in the Patch and Element Sub-Object levels.

patchOps.startWeldTarget <editable_patch_node_or_modifier>

Enters the "Weld Target" command mode - valid in the Vertex Sub-Object level.

The following methods invoke one of the 'instantaneous' button operations in the Editable Patch Modify panel, acting on the currently selected sub-objects:

patchOps.addTri <editable_patch_node_or_modifier>

Adds a TriPatch to the selected edge - valid in the Edge Sub-Object level.

patchOps.addQuad <editable_patch_node_or_modifier>

Adds a QuadPatch to the selected edge - valid in the Edge Sub-Object level.

patchOps.break <editable_patch_node_or_modifier>

Creates a new vertex for each patch attached to the selected sub-objects - valid in the Vertex and Edge Sub-Object levels.

patchOps.clearAllSG <editable_patch_node_or_modifier>

Clears the smoothing groups on the currently selected patches - valid in the Face, Polygon, and Element Sub-Object levels.

patchOps.createShapeFromEdges <editable_patch_node_or_modifier>

Displays the Create Shape dialog allowing the user to specify an object name for the shape to create from the selected edges. Valid in the Edge Sub-Object level.

patchOps.delete <editable_patch_node_or_modifier>

Deletes the selected sub-objects - valid in all the Sub-Object levels.

patchOps.detach <editable_patch_node_or_modifier>

Displays the Detach dialog allowing the user to specify an object name. Valid in the Patch Sub-Object level.

patchOps.flipNormal <editable_patch_node_or_modifier>

Flips the normal of the selected patches - valid in the Patch and Element Sub-Object levels.

patchOps.hide <editable_patch_node_or_modifier>

Hides the selected sub-objects - valid in all the Sub-Object levels.

patchOps.selectByID <editable_patch_node_or_modifier>

Displays a Select By Material ID dialog and choose patches with the specified material ID. - valid in the Patch and Element Sub-Object levels.

patchOps.selectBySG <editable_patch_node_or_modifier>

Displays a Select By Smooth Groups dialog and choose patches with the specified smoothing groupd IDs - valid in the Patch and Element Sub-Object levels.

patchOps.selectOpenEdges <editable_patch_node_or_modifier>

Selects all edges with only one patch. Valid in the Edge Sub-Object level.

patchOps.subdivide <editable_patch_node_or_modifier>

Divides the selected sub-objects - valid in the Edge and Patch Sub-Object levels.

patchOps.unbind <editable_patch_node_or_modifier>

Unbinds the selected vertices - valid in the Vertex Sub-Object level.

patchOps.unifyNormal <editable_patch_node_or_modifier>

Unifies the normals of the selected patches - valid in the Patch and Element Sub-Object levels.

patchOps.unhideAll <editable_patch_node_or_modifier>

Unhides all hidden sub-objects -valid in all Sub-Object levels, and when not in Sub-Object mode.

patchOps.weld <editable_patch_node_or_modifier>

Welds the selected vertices - valid in the Vertex Sub-Object level.

The following methods are available in 3ds Max 6 and higher:

patchOps.growSelection <editable_patch_node_or_modifier>

Grows the selection - valid in all the Sub-Object levels except for Handle.

patchOps.shrinkSelection <editable_patch_node_or_modifier>

Shrinks the selection - valid in all the Sub-Object levels except for Handle.

patchOps.selectEdgeRing <editable_patch_node_or_modifier>

Selects a ring of edges - valid in the Edge Sub-Object level.

patchOps.selectEdgeLoop <editable_patch_node_or_modifier>

Selects a loop of edges - valid in the Edge Sub-Object level.

patchOps.patchSmooth <editable_patch_node_or_modifier>

Smooths the patch by avergaing the Handles.

patchOps.toggleShadedFaces <editable_patch_node_or_modifier>

Toggles the shaded faces.

There is also a patch structure containing a large number of functions for creating, modifying, and accessing patch objects.

The following function is used to get the type of the patch.

patch.getPatchType < patch_object >

Returns #triPatch, #quadPatch, #undefPatch, or 'undefined'. A value of #undefPatch might be returned by third-party-defined patch object. A value of 'undefined' will be returned if the internal patch type is not in the list of defined values.

Get and set the overall geometry of the patch

Set keep:true to the setNumXXX functions for them to retain existing vertex/vector/patch/edge data. This value defaults to false, which cleans out the geometry.

patch.getNumVerts <obj>

Returns the number of vertices as integer value.

patch.setNumVerts <obj> <num> [keep:<boolean>]

Sets the number of vertices to the integer value.

patch.getNumVecs <obj>

Returns the number of vectors as integer value.

patch.setNumVecs <obj> <num> [keep:<boolean>]

Sets the number of vectors to the integer value.

patch.getNumPatches <obj>

Returns the number of patches as integer value.

patch.setNumPatches <obj> <num> [keep:<boolean>]

Sets the number of patches to the integer value.

patch.getNumEdges <obj>

Returns the number of edges as integer value.

patch.setNumEdges <obj> <num> [keep:<boolean>]

Sets the number of edges to the integer value.

Get and set individual vertex and vector handle locations

The vertex and vector coordinates are interpreted in MAXScript's current working coordinate context. Consistent with the rest of MAXScript, all vertex/patch/vector/edge indexes start numbering at 1.

patch.getVert <obj> <index>

Returns the indexed vertex as the Point3 value.

patch.setVert <obj> <index> <point3>

Sets the indexed vertex to the Point3 value

patch.getVec <obj> <index>

Returns the indexed vector as the Point3 value

patch.setVec <obj> <index> <point3>

Sets the indexed vector to the Point3 value

Creating individual patches in the patch mesh

patch.makeQuadPatch <obj> <index> <va> <vab> <vba> <vb> <vbc> <vcb> <vc> <vcd> <vdc> <vd> <vda> <vad> <i1> <i2> <i3> <i4> <sm>

Where:

index = The index of the patch to create (0> = index < numPatches).
va = The first vertex.
vab = Vector ab.
vba = Vector ba.
vb = The second vertex.
vbc = Vector bc.
vcb = Vector cb.
vc = The third vertex.
vcd = Vector cd.
vdc = Vector dc.
vd = The fourth vertex.
vda = Vector da.
vad = Vector ad.
i1 = Interior 1.
i2 = Interior 2.
i3 = Interior 3.
i4 = Interior 4.
sm = The smoothing group mask

patch.makeTriPatch <obj> <index> <va> <vab> <vba> <vb> <vbc> <vcb> <vc> <vca> <vac> <i1> <i2> <i3> <sm>

Where:

index = The index of the patch to create (0> = index < numPatches).
va = The first vertex.
vab = Vector ab.
vba = Vector ba.
vb = The second vertex.
vbc = Vector bc.
vcb = Vector cb.
vc = The third vertex.
vca = Vector ca.
vac = Vector ac.
i1 = Interior 1.
i2 = Interior 2.
i3 = Interior 3.
sm = The smoothing group mask

Update a Patch object:

patch.update <obj>

Forces all geometry and topology caches to be rebuilt, change notifications to be sent, and a screen redraw request to be flagged.

You must call this function after making any changes to a path object, before exiting the script. If you make the changes otherwise, an invalid patch might be passed to MAX, possibly causing a crash. The patch.update() function is similar in function and purpose to the update() function in mesh object scripting.

Accessing the topology of an existing patch object:

They return either indexes or arrays of indexes of the sub-objects requested. For example, getVertVecs() returns an array of the vectors coming out of the specified vertex.

patch.getVertVecs <obj> <index> -> integer_array
patch.getVertPatches <obj> <index> -> integer_array
patch.getVertEdges <obj> <index> -> integer_array
patch.getVecVert <obj> <index> -> integer
patch.getVecPatches <obj> <index> -> integer_array
patch.getEdgeVert1 <obj> <index> -> integer
patch.getEdgeVert2 <obj> <index> -> integer
patch.getEdgeVec12 <obj> <index> -> integer
patch.getEdgeVec21 <obj> <index> -> integer

Accessing and manipulating the texture mapping information

patch.setNumMaps <obj> <num> [keep:<bool>]
patch.getNumMaps <obj> -> integer
patch.setMapSupport <obj> <map_chan> [init:<boolean>]
patch.getMapSupport <obj> <map_chan> -> boolean
patch.maxMapChannels <obj>
patch.setNumMapVerts <obj> <map_chan> <num> [keep:<boolean>]
patch.getNumMapVerts <obj> <map_index>
patch.setNumMapPatches <obj> <map_chan> <num> [keep:<boolean>]
patch.getMapVert <obj> <map_chan> <index>
patch.setMapVert <obj> <map_chan> <index> <point3>
patch.getMapPatch <obj> <map_chan> <index>
patch.setMapPatch <obj> <map_chan> <index> <index_array>

Getting and setting the material ID of the whole object or individual patches

patch.getPatchMtlID <obj> <index> -> integer
patch.setPatchMtlID <obj> <patch_index> <mtl_id>

NOTE:The material ID value returned by patch.getPatchMtlID and set by patch.setPatchMtlID are now 1-based. The material ID value was 0-based in 3ds Max 4.

Accessing and controlling viewport and renderer tesselation and visibility

patch.setMeshSteps <obj> <steps>
patch.getMeshSteps <obj>
patch.setMeshStepsRender <obj> <steps>
patch.getMeshStepsRender <obj>
patch.setShowInterior <obj> <bool>
patch.getShowInterior <obj>
patch.setAdaptive <obj> <bool>
patch.getAdaptive <obj>

Accessing topology info for the specified sub-object

patch.getEdges <obj> <v1> [<v2>] -> integer_array
patch.getPatches <obj> <v1> [<v2>] -> integer_array
patch.getVectors <obj> <vert> -> integer_array

Transforming all vertices and vectors in the patch object by the given matrix

patch.transform <obj> <matrix3>

This transform happens in object local space.

Performing various high-level operations on a patch object

patch.weldVerts <obj> <threshold> <weldIdentical_bool> <startVert>
patch.weld2Verts <obj> <v1> <v2>
patch.weldEdges <obj>
patch.deletePatchParts <obj> <del_vert_bitarray> <del_patches_bitarray>
patch.clonePatchParts <obj> <patch_bit_array>
patch.subdivideEdges <obj> <propogate>
patch.subdividePatches <obj> <propogate>
patch.addTriPatch <obj>
patch.addQuadPatch <obj>

Getting and manipulating surface normal information

patch.patchNormal <obj> <patch>
patch.edgeNormal <obj> <edge>
patch.updatePatchNormals <obj>
patch.flipPatchNormal <obj> <patch>
patch.unifyNormals <obj>
patch.autoSmooth <obj> <angle> <useSel_bool> <preventIndirectSmoothing_bool>

Normal vectors are given in MAXScript's current working coordinate context.

Accessing and changing the vertex and interior vertex types

patch.changeVertType <obj> <vert> #corner|#coplanar patch.getVertType <obj> <vert> -> #corner or #coplanar
patch.changePatchInteriorType <obj> <patch> #automatic|#manual patch.getPatchInteriorType <obj> <patch> -> #automatic or #manual

Accessingthe current mesh tesselation for thepatch object

patch.getMesh <obj> -> mesh value

Interpolating individual patch surfaces

patch.interpTriPatch <obj> <patch> <u> <v> <w> -> point3
patch.interpQuadPatch <obj> <patch> <u> <v> -> point3

A tri-patch interpolation takes u,v,w barycentric coordinates. A quad-patch takes u and c parameters. In both cases, the point returns is given in the current MAXScript working coordinate context.