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.
layernameinstancingenable- Enables layer name instancing.
layernameinstancingdisable- Disables layer name instancing.
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 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 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.
|
