Commands: Modeler

Modeler Commands

Modeler commands are not case-sensitive. Modeler's native command mechanism is the lookup and execute pair of functions, which translate the command name into a code and use an array of DynaValues to pass the arguments. Commands issued using the evaluate function will be converted into lookup and execute calls. (See the CommandSequence document for definitions of these functions.)

Modeler's evaluate function treats double quote marks as delimiters, not literal characters. Use them when a string argument contains spaces. You can insert a quote mark as a literal character in a string argument by preceeding it with the backslash ( \ ) escape character. If you need a literal backslash, use two in a row. (This can produce some odd-looking code if you're generating evaluate strings using sprintf. To generate a literal quote character that won't be removed by either the C compiler or Modeler's command processor, the sprintf string needs to contain three backslashes, followed by the quote character: \\\".)

Some Modeler command arguments are optional. If they occur at the end of the argument list, they can simply be omitted. If they're in the middle, they can be replaced by placeholders, a DY_NULL DynaValue for execute or an asterisk (*) in an evaluate string. Either way, Modeler will supply default values.

In the command list that follows, optional arguments are placed inside square brackets. The types of the arguments are denoted by the initial letter.

number

A single integer or floating-point number. These are passed to execute as DynaValues of type DY_INTEGER or DY_FLOAT.

vector

A triple of numbers. In evaluate strings, vectors are delimited by angle brackets (< and >). If one or two of the numbers is omitted, the last number present is repeated, so <0> and <0 0 0> are equivalent. For execute, vectors are passed as DY_VINTs or DY_VFLOATs.

string

A string, such as a filename or surface name. Passed to execute as DY_STRINGs.

keyword

A string containing one of several options. Valid keywords are listed in the definition of the command.

flags

A string in which each character represents a toggle.

The commands are divided into six broad categories here, but this is just to get the list under control. The categories don't have any programming significance.

General

CLOSE
CLOSE_ALL

Close the current object workspace, or all object workspaces.

EXIT

Exit Modeler.

NEW

Create a new, empty, unnamed object.

UNDO
REDO

These move back and forth in Modeler's undo buffer.

DELETE
CUT
COPY
PASTE

The delete command removes the selected geometry without placing it in Modeler's clipboard, unlike cutting, but deletes can still be undone.

LOAD sfilename
SAVE sfilename

Load and save object files.

REVERT sfilename

Reload an existing object file.

SETOBJECT sname [nindex]

Set the current object by name, filename or index.

SETLAYER slayers
SETALAYER slayers
SETBLAYER slayers

Set the current foreground (or active) and background layers. SETALAYER is a synonym for SETLAYER. The layers argument is a string containing one or more layer numbers separated by spaces. Layers are numbered sequentially, starting at 1.

SETLAYERNAME sname

Set the name of the current layer.

SETPIVOT vpos

Set the pivot point for the current layer. The pivot point is the origin for rotations in Layout.

SURFACE sname

Set the current default surface. Geometry created after this is called will be assigned this surface.

SELECTVMAP ktype sname

Set the current vertex map of a given type. The type can be MORF (relative morph), SPOT (absolute morph), WGHT (weight), MNVW (subpatch weight) or TXUV (texture UV).

CMDSEQ sname [sarg]

Activate another command sequence plug-in, identified by its internal name, the string in the plug-in's ServerRecord name field. The argument string is placed in the argument field of the LWModCommand structure passed to the plug-in's activation function.

MESHEDIT sname

Activate a MeshDataEdit class plug-in, identified by its internal name.

PLUGIN sfilename [sclass sname susername]

Install the plug-ins contained in a .p file.

Selection

Commands are applied to the current selection, a subset of the geometry data residing in Modeler when a command is issued. The selection is made up of elements from the current layers, and within those layers, is defined by your choice of EltOpSelect mode for each command.

For OPSEL_USER and OPSEL_DIRECT modes, you can change which elements are selected using the SEL_POINT and SEL_POLYGON family of commands. (To individually select points and polygons by ID, you'll need to use a mesh edit with the special OPSEL_MODIFY mode.)

SEL_POINT kaction [condition ...]

Modify point selection. If it isn't already, the Point tab in Modeler's interface will be selected after this command is issued. The action can be either SET or CLEAR. If there is no condition, the action will apply to all points. Otherwise, the points specified by the condition will be added to the selection for SET and removed from the selection for CLEAR. The possible conditions with their additional arguments are:

"VOLUME" vlo vhi

Points within the volume.

"CONNECT"

Points connected to already selected ones. Only works with SET.

"NPEQ" npols

Points belonging to exactly pols polygons.

"NPLT" npols

Points belonging to less than pols polygons.

"NPGT" npols

points belonging to more than npol polygons.

SEL_POLYGON kaction [condition ...]

Modify polygon selection. Like SEL_POINT, with the following conditions:

"VOLEXCL" vlo, vhi

Polygons entirely within the volume.

"VOLINCL" vlo, vhi

Polygons at least partly within the volume.

"CONNECT"

Polygons connected to already selected ones. Only works with SET.

"NVEQ" nverts

Polygons with exactly verts vertices.

"NVLT" nverts

Polygons with less than verts vertices.

"NVGT" nverts

Polygons with more than verts vertices.

"SURFACE" ssurface

Polygons having the given surface.

"FACE"

Face polygons only.

"CURVE"

Curve polygons only.

"NONPLANAR" [nlimit]

Polygons less planar than the given limit. If limit is omitted, the user's default limit is used.

SEL_INVERT

Invert the selection. Selected data becomes unselected and vice versa.

SEL_HIDE kstate

Hide data from view. The state can be SELECTED (hide the selected data, the default) or UNSELECTED.

SEL_UNHIDE

Unhide all hidden data.

INVERT_HIDE

Invert the hiding of data. Hidden data becomes unhidden and vice versa.

Point Transforms

The flex and deform transformations use similar region data to define the scope of their operations. These are set globally and then applied to all transformations of a given type.

FIXEDFLEX kaxis nstart nend [fease]

Set the flex functions to operate on a fixed range along an axis. Ease flags can be "i" (ease-in), "o" (ease-out), or "io".

AUTOFLEX kaxis kpolarity [fease]

Set the flex functions to operate on an automatic range along an axis of the given polarity, which can be "+" or "-".

DEFORMREGION vradius [vcenter kaxis]

Set the area of effect for the deformation tools. If axis is omitted, the effect is bounded in all directions by the given radius. If an axis is specified, the effect is unbounded along that axis.

MOVE voffset
SHEAR voffset
MAGNET voffset

Translate points by the given offset. Shear translates along the flex axis. Magnet translates in the deform region.

ROTATE nangle kaxis [vcenter]
TWIST nangle kaxis [vcenter]
VORTEX nangle kaxis [vcenter]

Rotate points along the given axis by the angle given in degrees. Twist uses the flex axis, and vortex uses the deform region.

SCALE vfactor [vcenter]
TAPER vfactor [vcenter]
POLE vfactor [vcenter]

Scale points by the given factors around the given center. Taper uses the flex axis, and pole uses the deform region.

BEND nangle ndirection [vcenter]
BEND2 nangle ndirection [vcenter]

Bend points by the given bend angle in the direction around the optional center. These commands use the current flex axis. In new code, use BEND2, which always interprets angle values as degrees.

JITTER vradius [ktype vcenter]

Randomly translate points using different displacement functions. The jitter type can be UNIFORM, GAUSSIAN, NORMAL or RADIAL. UNIFORM is the default and moves points randomly along all three axes within a box of the given size. GAUSSIAN distributes the offsets in a bell curve around the start point. NORMAL shifts the points in and out along the local surface normal. RADIAL shifts points toward or away from the center.

SMOOTH [niterations nstrength]

Apply a smoothing function to attempt to remove kinks in polygons connecting affected points.

QUANTIZE vsize

Snap all points to a 3D grid defined by the size vector.

MERGEPOINTS [nmindist]

Merge points lying within a certain minimum distance of each other. If no distance is given, it is computed heuristically.

Object Creation

MAKEBOX vlowcorner vhighcorner [vsegments]

Make a box with the given extent and and number of segments.

MAKEBALL vradius nsides nsegments [vcenter]

Make a globe-style sphere.

MAKETESBALL vradius nlevel [vcenter]
MAKETESBALL2 vradius nsegments [vcenter]

Make a tesselated sphere. A level 0 tesball is an icosahedron. A level n tesball divides the edges of the icosahedron into 2ⁿ segments. The newer MAKETESBALL2 comand allows the number of segments along the edges to be any number, not just powers of 2.

MAKEDISC vradius ntop nbottom kaxis nsides [nsegments vcenter]

Make a disc.

MAKECONE vradius ntop nbottom kaxis nsides [nsegments vcenter]

Make a cone. The top is the pointy end.

MAKETEXT stext nfont [kcornertype nkern nscale kaxis vpos]
MAKETEXT2 stext nfont [kcornertype nkern nscale kaxis vpos kalignment]

Generate text using the given font index. The font index begins at 1 for MAKETEXT and 0 (in agreement with the Font List global's index function) for MAKETEXT2. The corner type can be either SHARP or BUFFERED. The kern is an additional distance to put between characters (normally 0). The scale sets the approximate height of the character cell in meters. The axis defines the plane in which the text will lie. For MAKETEXT, text is always left-aligned with the position argument, while for MAKETEXT2, the alignment can be LEFT, CENTER or RIGHT.

Replication

LATHE kaxis nsides [vcenter nendangle nstartangle noffset]

Spin a template around an axis.

EXTRUDE kaxis nextent [nsegments]

Sweep a template along an axis.

MIRROR kaxis nplane

Copy selected data, flipping it through a plane.

PATHCLONE sfilename [nstep nstart nend]
PATHEXTRUDE sfilename [nstep nstart nend]

Load a motion file and clone or extrude the selected data along the path in the file. Clone creates copies of the selected geometry at intervals along the path, while extrude creates a single continuous object by connecting the copies.

RAILCLONE nsegments [kdivs fflags nstrength]
RAILEXTRUDE nsegments [kdivs fflags nstrength]

Clone or extrude selected data along one or more rails (curves) in background layers. If segments is 0, the number of segments is computed automatically. Otherwise the number of segments is fixed, and the intervals between segments depend on whether divs is KNOTS (the default) or LENGTHS. For KNOTS, an equal number of segments is placed between each knot, or curve vertex, while for LENGTHS, the segments are spaced at equal intervals along the curve. The flags can be "o" (oriented), "s" (scaled) or "os".

Tools

AXISDRILL soperation kaxis [ssurface]
SOLIDDRILL soperation [ssurface]

The drill commands slice the foreground geometry using a 2D template or 3D shape in the background layer. The operation can be CORE, TUNNEL, SLICE or STENCIL.

BOOLEAN soperation

Booleans combine geometry in the foreground and background to create new shapes. The geometry involved must form fully enclosed volumes, which Modeler treats as solids when performing booleans. The operation can be UNION, SUBTRACT, INTERSECT or ADD.

BEVEL ninset nshift

Create a beveled edge around each selected polygon. The polygon's edges are moved inward (toward the polygon's center) by the inset amount, and the polygon is offset in the direction of its normal by the shift amount. The gap between the polygon's new and old vertices is filled by new polygons that form the beveled edge.

SHAPEBEVEL pattern

Perform multiple bevels using a single command. The patten for a shapebevel is either a string containing pairs of inset/shift values, or a DY_CUSTOM DynaValue with the val[0] field set to the number of pairs, and the val[1] field cast to a pointer to an array of doubles holding the pairs.

SMOOTHSHIFT noffset [nmaxangle]

Extrude part of a mesh. Vertices are moved in the average ("smoothed") direction of the shared polygons' normals. The mesh breaks at edges that form angles greater than maxangle, and the shift direction isn't averaged across those edges.

SMSCALE noffset

Move and scale part of a mesh. Vertices are moved as they are with SMOOTHSHIFT, but no new polygons are created.

Polygons

FLIP

Flip the sidedness (reverse the surface normals) of faces and the directions of curves.

TRIPLE

Convert polygons into triangles by subdividing.

FREEZECURVES

Convert curves into polygons.

REMOVEPOLS

Delete polygons, leaving behind their vertices as points.

UNIFYPOLS

Delete duplicate polygons.

ALIGNPOLS

Roughly speaking, flip polygons so that they all face in the "same" direction to form a coherent mesh. Incoherent meshes can result from the use of the UNIFYPOLS command, or when the geometry is created in another program that ignores the sidedness of polygons. It isn't always possible for ALIGNPOLS to infer the correct sidedness for all polygons, however.

CHANGESURFACE ssurface

Set the surface of selected polygons.

CHANGEPART spart

Set the part tag for selected polygons.

SUBDIVIDE kmode [nmaxangle]

Split triangles into four smaller triangles and quads into four smaller quads. The mode can be FLAT, SMOOTH, or METAFORM. With flat subdivision, the new polygons retain the parent's normal. A smooth subdivide creates polygons with normals that interpolate the parent's normal and those of its neighbors. Modeler won't try to interpolate normals across edges that form angles larger than maxangle. Metaform, unlike smooth mode, moves the original vertices to approximate the continuity (roundness) of a higher-order patch.

FRACSUBDIVIDE kmode nfractal [nmaxangle]

Like SUBDIVIDE, but applies a fractal displacement to each new vertex as a function of its position.

TOGGLECCSTART
TOGGLECCEND

These affect the interpretation of the first and last points in curves. When toggled "on," the first (or last) point in a curve becomes a continuity control point. It and the curve segment connected to it are no longer part of the curve, but it can be used to affect the shape of the first (or last) segment that is still part of the curve.

TOGGLEPATCHES

Toggling this "on" converts the selected geometry into a subpatch control cage.

UNWELD

Create multiple copies of the selected points so that none are shared by two polygons at once.

The following eight commands are only valid with EltOpSelect modes of OPSEL_USER or OPSEL_DIRECT. Just as in the user interface, these operations require explicit selection of the elements they will operate on.

MAKE4PATCH nperpendicular nparallel

Create a quad mesh from three or four curves. The perpendicular and parallel values determine the number of segments that will be created in directions perpendicular and parallel to the last-selected curve. The curves must share vertices to form a closed area.

SKINPOLS

Create a triangle mesh that connects two or more polygons and encloses the volume between them. This is sometimes called lofting. The original polygons aren't required to have the same number of vertices.

MORPHPOLS nsegments

Create a triangle mesh that connects exactly two polygons with the same number of vertices. The new mesh is divided into a number of segments along the line connecting the two original polygons.

MERGEPOLS

Merge selected polygons into a single polygon. Each selected polygon must share at least one edge with another.

WELDPOINTS

Merge selected points into a single point. The position of the resulting point is the same as that of the last-selected point before the weld.

WELDAVERAGE

Weld selected points into a single point located at the average position of the welded points.

SPLITPOLS

Divide a polygon into two smaller polygons. The new edge is created between selected points.

SMOOTHCURVES

Smooth a composite of two curves at their join point.