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 typeDY_INTEGER
orDY_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. Forexecute
, vectors are passed asDY_VINT
s orDY_VFLOAT
s. - string
- A string, such as a filename or surface name. Passed to
execute
asDY_STRING
s. - 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 forSETLAYER
. Thelayers
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) orTXUV
(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 theargument
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
orCLEAR
. 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 forSET
and removed from the selection forCLEAR
. 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 beSELECTED
(hide the selected data, the default) orUNSELECTED
. 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
orRADIAL
.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 2n 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 n
font [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'sindex
function) forMAKETEXT2
. The corner type can be eitherSHARP
orBUFFERED
. 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. ForMAKETEXT
, text is always left-aligned with the position argument, while forMAKETEXT2
, the alignment can beLEFT
,CENTER
orRIGHT
.
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
isKNOTS
(the default) orLENGTHS
. ForKNOTS
, an equal number of segments is placed between each knot, or curve vertex, while forLENGTHS
, 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
orSTENCIL
. 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
orADD
. 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 theval[0]
field set to the number of pairs, and theval[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 forALIGNPOLS
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
, orMETAFORM
. 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 thanmaxangle
. 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
andparallel
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.