SplineShapes are the general editable versions of all the shape objects, in the same way that Editable Meshes relate to geometry objects. They are the objects that a shape is converted to when you apply an Edit Spline modifier and the result of collapsing a modifier stack on a shape base object. MAXScript lets you construct SplineShapes from scratch, adding individual curves and controls points or you can modify an existing shape by converting it to a SplineShape and using the methods listed below.
See also
Shape Common Properties, Operators, and Methods
Spline Shape Common Properties, Operators, and Methods
Node Common Properties, Operators, and Methods
MAXWrapper Common Properties, Operators, and Methods
Value Common Properties, Operators, and Methods
Class and Object Inspector Functions
Scripting Vertex and Control Point Animation
Notes
You must convert existing shapes to SplineShapes in order to operate on them with the these methods. Use the convertToSplineShape() function to do this.
Only the updateShape() function updates the shape's internal caches and images in 3ds max viewports. This is because updates can be computationally expensive and you don't want them performed on every function call. However, you must make sure you do call the updateShape() function after a series of changes and before the shape is to be worked on in 3ds max or by other functions in MAXScript.
The in and out vectors for Bezier control points are given as vector handle coordinates, not as true vectors as the names suggests.
Coordinates are given in the MAXScript working coordinate system - this is important to note if you are familiar with the corresponding SDK spline functions which always work in object-local coordinates.
If the updateShape() function is called on an object that is selected and currently open in the Modify panel, it will drop the current selection in order to avoid a potential crash in 3ds max, which at the moment, does not support scripted changes to an object open in the Modify panel.
If you are creating or modifying a spline object, and have not yet run updateShape() on the spline, 3ds max will crash if you minimize and then maximize the 3ds max window. This is because an only partially created spline is created, and the internal 3ds max spline structure is left in an unstable state.
Properties
<SplineShape>.angle Float default: 0.0 -- animatable
The rotational position of the cross-section in the renderer.
<SplineShape>.thickness Float default: 1.0 -- animatable
Diameter of the rendered spline.
<SplineShape>.sides Float default: 12.0 -- animatable
Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a square cross section, for example.
<SplineShape>.viewport_thickness Float default: 1.0
Diameter of the viewport spline.
<SplineShape>.viewport_sides Integer default: 12
Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a square cross section, for example.
<SplineShape>.viewport_angle Float default: 0.0
The rotational position of the cross-section in the viewports.
<SplineShape>.DisplayRenderMesh Boolean default: false
When on, displays the mesh generated by the spline in the viewports.
<SplineShape>.UseViewportSettings Boolean default: false
When on, displays the mesh generated by the Viewport settings.
<SplineShape>.DisplayRenderSettings Boolean default: true
When on, displays the mesh generated by the render settings.
<SplineShape>.numSplines Integer, read-only
The number of individual spline curves in the shape.
Up to 3*N vertex and tangent coordinates are available as properties, where N is the number of vertices in the SplineShape. A vertex and its tangents are available as properties once a controller has been assigned to the vertex. Controllers can be assigned to vertices using the animateVertex() method described in Scripting Vertex and Control Point Animation. For example, if a circle object is collapsed to a SplineShape, and some of its vertices are animated, the properties for the vertices and tangents would be similar to:
$Circle01.Spline_1___InVec_1 Point3 value: [-75,33,0] -- animatable
$Circle01.Spline_1___Vertex_1 Point3 value: [-75,33,0] -- animatable
$Circle01.Spline_1___OutVec_1 Point3 value: [-50,0,0] -- animatable
$Circle01.Spline_1___InVec_2 Point3 value: [-20,-33,0] -- animatable
$Circle01.Spline_1___Vertex_2 Point3 value: [7,-66,0] -- animatable
$Circle01.Spline_1___OutVec_2 Point3 value: [32,-95,0] -- animatable
Methods
Shape Methods
Updates the shape's internal caches and viewport display to account for all the changes made by other functions in this kit. This update must be done before 3ds max or any other code tries to work with a modified shape object.
The updateShape() function makes any scripted changes to a base object spline shape propagate into the bottom of any modifier stack that is present. Note that there is no check to warn you that modifications such as topology changes might invalidate modifiers already in the stack. This is equivalent to opening and modifying the base object in a Modify panel, ignoring its warnings about invalidating the object.
Clears all the spline curves out of a shape
Returns the number of spline curves in the shape as an integer. Equivalent to <shape>.numSplines.
setFirstSpline <shape> <spline_index_integer>
Rolls the order of the splines in a shape around so that the numbered spline is the first spline in the shape. This is useful when working with multi-spline shapes in the Lofter and some other modifiers such as Surface Tools which are sensitive to spline order.
Hides the selected splines in the shape.
Hides the selected segments in the shape.
Hides the segments attached to the selected knots in the shape.
Unhides all segments in the shape.
addAndWeld <to_shape> <from_shape> <weldthreshold_float>
Add the splines from one spline shape to the specified bezier shape. The weld threshold will weld the endpoints of the new splines onto endpoints of existing ones if they are within the distance specified.
bindKnot <shape> <isEnd_boolean> <splineId_integer> \
<segIndex_integer> <splineSegId_integer>
Binds the first or end knot of a spline to the midpoint of the specified segment. A bind acts as a constraint, it constrains the first point or the end point of a spline to the mid point of a segment. If <isEnd_boolean> is true the end knot of the spline is bound, otherwise the first knot is bound. <splineId_integer> specifies the index of the spline the first/end knot to bind belongs to, <segIndex_integer> specifies the index of the segment to bind to, and <splineSegId_integer> specifies the index of the spline the bind to segment belongs to.
unBindKnot <shape> <spline_index_integer> <isEnd_boolean>
Unbinds the specified end/first knot of the given spline
Called when the topology changes to update the bind list, for example when knots are deleted from bound spline or the spline bound to.
materialID <shape> <spline_index_integer> <segment_index_integer>
Returns the material id for the given segment of the given shape object.
animateVertex <shape> <vertex_spec>
Applies controllers to the specified vertices and tangents of the splineshape, where <vertex_spec> is one of:
<integer_index>
<integer_index_array>
#all
By assigning controllers to the vertices and tangents, the vertices and tangents are added to the Master subAnim and appear as animatables in the Track View, allowing further scripting of the vertices and tangents. For example,
animateVertex $Circle01 #all
The vertices to be animated are specified by index number or with the keyword #all to animate all vertices.
See also Class and Object Inspector Functions and Scripting Vertex and Control Point Animation for details on accessing the splineshape vertices and tangents. The controller values assigned to the vertices and tangent handles is in object space. See Using Node Transform Properties for information on converting between world space to object space.
Spline Methods
Adds a new spline curve to the spline shape and returns an integer reflecting the spline index of the newly added spline curve. Individual spline curves are given index numbers starting at 1. The addNewSpline() function adds new spline curves to the end of the list of curves in a shape.
Returns the indices of the selected splines in the shape as an array of integers.
setSplineSelection <shape> <spline_index_array> [ keep:<boolean> ]
Selects the splines specified by <spline_index_array> in the specified shape. <spline_index_array> is an array of integers specifying the spline indices. Splines already selected are de-selected unless keep:true is specified.
deleteSpline <shape> <spline_index_integer>
Deletes the indexed spline curve from the shape. The remaining curves are renumbered to account for the deletion.
numSegments <shape> <spline_index_integer>
Returns the number of line segments in the indexed spline as an integer. This is the same as the number of knots for closed splines and 1 less for open splines.
numKnots <shape> [ <spline_index_integer> ]
Returns the number of knots (also known vertices or control points) in the indexed spline as an integer. If the spline index is not specified, returns the number of knots in the entire shape.
isClosed <shape> <spline_index_integer>
returns true if the indexed spline is closed, false if it is open.
close <shape> <spline_index_integer>
closes the indexed spline.
open <shape> <spline_index_integer>
opens the indexed spline between its last and first knots.
reverse <shape> <spline_index_integer>
reverses the order of the knots in the indexed spline.
setFirstKnot <shape> <spline_index_integer> <knot_index_integer>
rolls the order of the knots in the indexed spline around so that the specified knot becomes the first knot in the spline.
getSegLengths <splineShape> <spline_index> [cum:<boolean>] [byVertex:<boolean>] [numArcSteps:<integer>]
Returns array of segment lengths or vertex distances by spline fraction and length, and total spline length. Double precision calculations, very accurate. If cum:true, results are cumulative, otherwise they are relative. If byVertex:true results are per vertex, otherwise per segment.
Defaults: cum:false byVertex:false numArcSteps:100
subdivideSegment <splineShape> <spline_index> <seg_index> <divisions>
Divides the segment into the specified number of divisions. Double precision calculations, very accurate.
interpCurve3D <splineShape> <spline_index> <param_float> [pathParam:<boolean>]
Returns a <point3> coordinate on the indexed curve. If pathParam:false, param is the fraction of the spline length, otherwise it is a segment-based (path) fraction. Default is pathParam:false
tangentCurve3D <splineShape> <spline_index> <param_float> [pathParam:<boolean>]
Returns a <point3> tangent on the indexed curve. If pathParam:false, param is the fraction of the spline length, otherwise it is a segment-based (path) fraction. Default is pathParam:false
Segment Methods
getSegmentType <shape> <spline_index_integer> <seg_index_integer>
Gets the segment type of the indexed segment in the indexed spline
setSegmentType <shape> <spline_index_integer> \
<seg_index_integer> ( #curve | #line )
Sets the segment type of the indexed segment in the indexed spline
refineSegment <shape> <spline_index_integer> \
<seg_index_integer> <seg_interp_param_float>
Adds a new knot to the indexed segment of the indexed curve at a place along the indexed segment corresponding to the given segment interpolation parameter. This value is a float in the range 0.0 to 1.0, specifying a proportion along the segment. The new knot coordinates and in-vector and out-vector are automatically computed to maintain the segment's existing curvature. This is the primitive used by the refine function in the Edit Spline modifier. You can use the MAXScript spline path interpolation functions to derive segment parameters given that a curve's path interpolation parameter is divided evenly among the segments in a curve. (So given a path interpolation parameter u and a target segment n in a spline of m segments, the segment parameter is u - (n-1)/m.) The refineSegment() function returns the index of the newly inserted knot.
getSegSelection <shape> <spline_index_integer>
Returns the indices of the selected segments in the specified shape spline as an array of integers.
setSegSelection <shape> <spline_index_integer> \
<segment_index_array> [ keep: <boolean> ]
Selects the segments specified by <segment_index_array> in the specified shape spline. <segment_index_array> is an array of integers specifying the segment indices. Segments already selected are de-selected unless keep:true is specified.
setMaterialID <splineShape> <spline_index> <seg_index> <matID>
Sets the material ID of the specified spline segment.
getMaterialID <splineShape> <spline_index> <seg_index>
Gets the material ID of the specified spline segment.
Knot Methods
addKnot <shape> <spline_index_integer> \
( #smooth | #corner | #bezier | #bezierCorner ) \
( #curve | #line ) <position_point3> \
[invec_point3 outvec_point3] [where_integer]
Adds a new knot (control point) to the indexed spline and returns an integer reflecting the index of the newly added knot. The 3rd argument specifies the type of the knot, the 4th specifies the type of the segment leaving the knot. The 5th specifies the coordinates for the new point (given in the current working coordinate system). If the knot type is bezier or bezierCorner, you must give the in-vector and out-vector handle coordinates as the 6th and 7th arguments. In the same way as splines are indexed in a shape, knots are indexed in a spline. The optional last argument lets you specify where in the knot order the new knot is to be inserted, defaulting to the end of the spline if you leave this argument off.
deleteKnot <shape> <spline_index_integer> <knot_index_integer>
Deletes the indexed knot in the indexed spline. The remaining knots are renumbered to account for the deletion.
getKnotType <shape> <spline_index_integer> <knot_index_integer>
Returns the knot type of the indexed knot in the indexed spline. The value is one of the names #smooth, #corner, #bezier, or #bezierCorner.
setKnotType <shape> <spline_index_integer> <knot_index_integer> \
(#smooth | #corner | #bezier | #bezierCorner )
Sets the knot type of the indexed knot in the indexed spline. This is equivalent to the right-mouse-button change you can make to spline control-points using the Edit Spline modifier in 3ds max.
getKnotPoint <shape> <spline_index_integer> <knot_index_integer>
Retrieves the coordinates of the indexed knot as a point3 in the current working coordinate system.
setKnotPoint <shape> <spline_index_integer> <knot_index_integer> <point3>
Sets the coordinates of the indexed knot in the indexed spline. Coordinates are given in the current working coordinate system.
getInVec <shape> <spline_index_integer> <knot_index_integer>
Retrieves the coordinates of the in-vector handle for the indexed knot as a point3 in the current working coordinate system.
setInVec <shape> <spline_index_integer> <knot_index_integer> <point3>
Sets the coordinates of the in-vector handle of the indexed knot. Coordinates are given in the current working coordinate system.
getOutVec <shape> <spline_index_integer> <knot_index_integer>
Retrieves the coordinates of the out-vector handle for the indexed knot as a point3 in the current working coordinate system.
setOutVec <shape> <spline_index_integer> <knot_index_integer> <point3>
Sets the coordinates of the out-vector handle of the indexed knot. Coordinates are given in the current working coordinate system.
getKnotSelection <shape> <spline_index_integer>
Returns the indices of the selected knots in the specified shape spline as an array of integers.
setKnotSelection <shape> <spline_index_integer> \
<knot_index_array> [keep: <boolean> ]
Selects the knots specified by <knot_index_array> in the specified shape spline. <knot_index_array> is an array of integers specifying the knot indices. Knots already selected are de-selected unless keep:true is specified.
Editable Spline Modify Panel Command Modes and Operations
A suite of methods provide the ability for a script to invoke Editable Spline, Line, and Edit Spline Modify panel modes and operations, corresponding to buttons available at various shape sub-object levels. These methods reside in the splineOps global structure. These methods effectively "push the button" in the Modify panel. In order to use these methods, the node must be selected and the Modify panel open. In the description of these methods, the first argument <editable_spline_or_line_node_or_modifier> should be interpreted as either an Editable Spline or Line node where the modifier stack level is at the base object, or an Edit Spline modifier where the modifier stack level is at the Edit Spline. In all cases, the following methods work at the current sub-object level, but only if that level is appropriate for the invoked operation.
If you have made scripted changes to the shape you must call the updateShape() method on the mesh before calling these methods. You do not need to call updateShape() after just calling one of these methods, as 3ds max will take care of updating the shape.
The following methods invoke one of the 'user-interaction' button operations in the Editable Spline 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 care should be taken to 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.
splineOps.startUnion <editable_spline_or_line_node_or_modifier>
Enters "Boolean Union" command mode - valid in Spline Sub-Object level. Only 1 closed spline must be selected to enter this command mode.
splineOps.startSubtract <editable_spline_or_line_node_or_modifier>
Enters "Boolean Subtract" command mode - valid in Spline Sub-Object level. Only 1 closed spline must be selected to enter this command mode.
splineOps.intersect <editable_spline_or_line_node_or_modifier>
Enters "Boolean Intersect" command mode - valid in Spline Sub-Object level. Only 1 closed spline must be selected to enter this command mode.
splineOps.startAttach <editable_spline_or_line_node_or_modifier>
Enters "Attach" command mode - valid in all Sub-Object levels, and when not in Sub-Object mode.
splineOps.startBind <editable_spline_or_line_node_or_modifier>
Enters "Bind" command mode - valid in Vertex Sub-Object level.
splineOps.startBreak <editable_spline_or_line_node_or_modifier>
Enters "Break" command mode - valid in Vertex and Segment Sub-Object levels.
splineOps.startChamfer <editable_spline_or_line_node_or_modifier>
Enters "Chamfer" command mode - valid in Vertex Sub-Object level.
splineOps.startConnect <editable_spline_or_line_node_or_modifier>
Enters "Connect" command mode - valid in Vertex Sub-Object level.
splineOps.startCreateLine <editable_spline_or_line_node_or_modifier>
Enters "Create Line" command mode - valid in all Sub-Object levels, and when not in Sub-Object mode.
splineOps.startCrossInsert <editable_spline_or_line_node_or_modifier>
Enters "CrossInsert" command mode - valid in Vertex Sub-Object level.
splineOps.startExtend <editable_spline_or_line_node_or_modifier>
Enters "Extend" command mode - valid in Spline Sub-Object level.
splineOps.startFillet <editable_spline_or_line_node_or_modifier>
Enters "Fillet" command mode - valid in Vertex Sub-Object level.
splineOps.startInsert <editable_spline_or_line_node_or_modifier>
Enters "Insert" command mode - valid in all Sub-Object levels, and when not in Sub-Object mode.
splineOps.startOutline <editable_spline_or_line_node_or_modifier>
Enters "Outline" command mode - valid in Spline Sub-Object level.
splineOps.startRefine <editable_spline_or_line_node_or_modifier>
Enters "Refine" command mode - valid in Vertex and Segment Sub-Object levels. This method does not turn off the Connect checkbox, so it is effectively the same as the startRefineConnect() method.
splineOps.startRefineConnect <editable_spline_or_line_node_or_modifier>
Enters "Refine" command mode - valid in Vertex and Segment Sub-Object levels. This method does not turn on the Connect checkbox, so it is effectively the same as the startRefine() method.
splineOps.startTrim <editable_spline_or_line_node_or_modifier>
Enters "Trim" command mode - valid in Spline Sub-Object level.
The following methods invoke one of the 'instantaneous' button operations in the Editable Shape Modify panel, acting on the currently selected sub-objects:
splineOps.attachMultiple <editable_spline_or_line_node_or_modifier>
Displays Attach Multiple dialog allowing the user to select multiple shapes to attach. Valid in all Sub-Object levels, and when not in Sub-Object mode.
splineOps.close <editable_spline_or_line_node_or_modifier>
Closes the selected splines û valid in Spline Sub-Object level.
splineOps.cycle <editable_spline_or_line_node_or_modifier>
Cycles through the vertices of the spline, selecting each vertex. At least one vertex must be selected before calling this method, or no vertex is selected. If more than one vertex is selected when this method is called, the first vertex of the first shape is selected. Valid in Vertex Sub-Object level.
splineOps.delete <editable_spline_or_line_node_or_modifier>
Deletes the selected sub-objects - valid in all Sub-Object levels.
splineOps.detach <editable_spline_or_line_node_or_modifier>
Displays Detach dialog allowing the user to specify an object name. Valid in all Sub-Object levels.
splineOps.divide <editable_spline_or_line_node_or_modifier>
Divides the selected segments - valid in Segment Sub-Object level.
splineOps.explode <editable_spline_or_line_node_or_modifier>
Explodes the each segment in the selected splines into separate splines or objects. Valid in Spline Sub-Object level.
splineOps.hide <editable_spline_or_line_node_or_modifier>
Hides the selected sub-objects - valid in all Sub-Object levels.
splineOps.makeFirst <editable_spline_or_line_node_or_modifier>
Makes the selected vertices the first vertex in the spline- valid in Vertex Sub-Object level.
splineOps.mirrorBoth <editable_spline_or_line_node_or_modifier>
Mirrors the selected splines horizontally and vertically û valid in Spline Sub-Object level.
splineOps.mirrorHoriz <editable_spline_or_line_node_or_modifier>
Mirrors the selected splines horizontally û valid in Spline Sub-Object level.
splineOps.mirrorVert <editable_spline_or_line_node_or_modifier>
Mirrors the selected splines vertically û valid in Spline Sub-Object level.
splineOps.reverse <editable_spline_or_line_node_or_modifier>
Reverses the order of vertices in the selected splines û valid in Spline Sub-Object level.
splineOps.unbind <editable_spline_or_line_node_or_modifier>
Unbinds the selected vertices - valid in Vertex Sub-Object level.
splineOps.unhideAll <editable_spline_or_line_node_or_modifier>
Unhides all hidden sub-objects -valid in all Sub-Object levels, and when not in Sub-Object mode.
splineOps.weld <editable_spline_or_line_node_or_modifier>
Welds the selected vertices - valid in Vertex Sub-Object level.