MODELER AREXX INTERFACE
=======================
Updated 6/5/93


Modeler operates as a function host for function calls only.
"LWModelerARexx.port" is the function host address.


FUNCTION ARGUMENTS

Function arguments and return values are generally one of the fixed 
set of types whose formats are listed below, although values may be
formatted in a specific way for some functions.  The standard formats
are shown here:

	number	-- a floating point or integer number.

			examples:	12  -99   0  1.23  -.5601  1.667e-3

	bool	-- a number where 0 is false and anything else is true
		   (usually 1).

	vector	-- a triple of floating point numbers separated by spaces, 
		   or a single number.  A single number is interpreted as
		   a vector with all three components the same.

			examples:	1 1 -1      .5 -12.6 0      0 -15 -13
			example:	2 and 2 2 2 give the same vector

	string	-- raw argument text

	keyword	-- one of several possible keywords, shown as <a|b|c...>
		   Only enough of a keyword need be specified to 
		   distinguish it from the other possibilities.

			example:	axis <X|Y|Z>

	flags	-- a string that can contain any of a set of characters,
		   shown as <a;b;c>.  If the character is present in the
		   string, the flag it represents is set.  Likewise, if
		   the character is not present the flag is clear.

			example:	ease <i;o>

	layers	-- a list of one or more layer numbers in the range 1-8.


INTERFACE MODES and STATES

The client ARexx interface has modes and states in which it operates. 
Some commands are only valid in some modes, and some are valid in any
mode.  An attempt to use a command when the interface is in the wrong mode 
will generate an error.

	NORMAL mode.  This is the default mode, and the one the interface 
	starts in.  Most single-function commands are valid in this mode.

	ADD mode.  Started with ADD_BEGIN and exited with ADD_END.  Only
	the "add" data creation commands are allowed in this mode.

	TRANSFORM mode.  Started with XFRM_BEGIN and ended with XFRM_END.
	Only "xfrm" coordinate trasform commands are allowed in this mode.

	REPLICATE mode.  Started with REPL_BEGIN and ended with REPL_END.
	Only replication step commands are allowed in this mode.

Any of the above modes will also be terminated with a BEGIN command for
another of the modes, or the END_ALL command.

In addition to these mutually-exclusive modes, there is the REQUESTER
state, which is used to build and display a requester to the user for 
input.  This additional mode is entered and exited with REQ_BEGIN and 
REQ_END commands.  The "req" requester commands are only valid in 
REQUESTER state, but other commands, including the mode change commands 
above are valid regardless of REQUESTER state.

Certain selection functions are only valid in USER selection mode.  See
the section on selection below.


FUNCTION SUMMARY

Parameter types are shown in <>'s.  Trailing arguments which are 
optional are shown in [], where any number of tailing arguments can
be omitted.

General:

	NEW()
	     -- Clear all data.

	EXIT()
	     -- Return to LightWave layout.  There can be no commands after
		this one.

	UNDO()
	     -- Restore data from last change.

	CUT()
	     -- Cut current layers to paste buffer.

	COPY()
	     -- Copy current layers to paste buffer.

	PASTE()
	     -- Copy paste buffer to current layer.


File I/O:

	LOAD(filename<string>)
	     -- Load data from LightWave file into current layer.

	SAVE(filename<string>)
	     -- Store data from current layers into LightWave file.


State:

	SETLAYER(<layers>)
	SETBLAYER(<layers>)
	     -- Switch active or background layers to show given list.

	SURFACE(name<string>)
	     -- Set current surface to given name.  If it does not
		exist it will be created.

	END_ALL()
	     -- Set mode to NORMAL regardless of current mode, and
		terminate REQUESTER state, if active.  This is done
		automatically when a script initiated from Modeler
		completes.


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 trasformations of a given type.

	FIXEDFLEX(axis<X|Y|Z>, start<number>, end<number>, [ease<i;o>])
	     -- Set the flex functions to operate on a fixed range
		along an axis.  Ease flags are 'i' for ease-in and 'o'
		for ease-out.

	AUTOFLEX(axis<X|Y|Z>, direction<+|->, [ease<i;o>])
	     -- Set the flex functions to operate on an automatic range 
		along an axis of the given polarity.

	DEFORMREGION(radius<vector>, [center<vector>, axis<X|Y|Z>])
	     -- 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  (offset<vector>)
	SHEAR (offset<vector>)
	MAGNET(offset<vector>)
	     -- Translate points by the given offset.  Shear translates
		along the flex axis.  Magnet translates in the deform
		region.

	ROTATE(angle<number>, axis<X|Y|Z>, [center<vector>])
	TWIST (angle<number>, axis<X|Y|Z>, [center<vector>])
	VORTEX(angle<number>, axis<X|Y|Z>, [center<vector>])
	     -- Rotate points along the given axis by the angle given
		in degrees.  Twist uses the flex axis, and vortex uses
		the deform region.

	SCALE(factor<vector>, [center<vector>])
	TAPER(factor<vector>, [center<vector>])
	POLE (factor<vector>, [center<vector>])
	     -- Scale points by the given factors around the given
		center.  Taper uses the flex axis, and pole uses the
		deform region.

	BEND(angle<number>, direction<number>, [center<vector>])
	     -- Bend points by the given bend angle in the direction
		around the optional center.  This function uses the 
		current flex axis.

	JITTER(radius<vector>)
	     -- Randomly translate points within a given radius.

	SMOOTH([iterations<number>, strength<number>])
	     -- Apply smoothing function to attempt to remove kinks in
		polygons connecting affected points.

	QUANTIZE(size<vector>)
	     -- Snap all points to a 3D grid defined by the size vector.

	MERGEPOINTS([mindist<number>])
	     -- Merge points lying within a certain minimum distance of
		each other.  If no distance is given, it is computed
		automatically.


Object Creation:

	MAKEBOX(lowcorner<vector>, highcorner<vector>, [nsegments<vector>])
	     -- Make a box with the given extent and divisions.

	MAKEBALL(radius<vector>, nsides<int>, nsegments<int>, [center<vector>])
	     -- Make a globe-style sphere.

	MAKETESBALL(radius<vector>, level<int>, [center<vector>])
	     -- Make a tesselated sphere.

	MAKEDISC(radius<vector>, top<number>, bottom<number>, axis<X|Y|Z>,
		 nsides<int>, [nsegments<int>, center<vector>])
	     -- Make a disc.

	MAKECONE {same as disc}
	     -- Make a cone.  Top is the pointy end.


Text:

	index<number> = FONTLOAD(filename<string>)
	     -- Load the given font file into the font list.  Returns 
		the font index in the table if loaded sucessfully, zero 
		otherwise.

	count<number> = FONTCOUNT()
	     -- Get number of fonts loaded.

	index<number> = FONTINDEX(name<string>)
	     -- Get index for name.

	name<string> = FONTNAME(index<number>)
	     -- Get name for index.

	width<number> = MAKETEXT(text<string>, index<number>,
				 [cornertype<SHARP|BUFFERED>, spacing<number>,
				  scale<number>, axis<X|Y|Z>, pos<vector>])
	     -- Generate text using the given font index.  Returns width
		as computed from the font metrics.  Spacing is an additional 
		distance to put between characters (normally 0).  Scale is
		a scale factor (or approximate size in meters).  Axis and
		pos define the position of the first character and the plane
		in which the text will lie.


Query Functions:

	active<layers> = CURLAYER()
	     -- Returns current active layer numbers.

	background<layers> = CURBLAYER()
	     -- Returns current background layer numbers.

	empty<layers> = EMPTYLAYERS()
	     -- Returns numbers of empty layers.

	name<string> = CURSURFACE()
	     -- Returns current surface name.

	boxdata = BOUNDINGBOX([test<layers>])
	     -- Returns bounding box information for the given layers or the
		current layers if none given.  Bounding box is a string:

			num x0 x1 y0 y1 z0 z1

		num is number of points tested.  If 0, the remaining values
		are also zero.  The remaining values are the low and high
		in the three axes -- 0 is low, 1 is high.


Additional:

	LATHE(axis<X|Y|Z>, nsides<int>,
	      [center<vector>, endangle<number>, startangle<number>])
	     --	Spin template around axis.

	EXTRUDE(axis<X|Y|Z>, extent<number>, [nsegments<int>])
	     --	Sweep template along axis.

	MIRROR(axis<X|Y|Z>, plane<number>)
	     -- Copy selected data, fliping it through a plane.

	PATHCLONE(...)
	PATHEXTRUDE(filename<string>, [step<number>,
			start<number>, end<number>])
	     -- Load the motion file and extrude or clone selected data
		according to path interval settings.

	RAILCLONE(...)
	RAILEXTRUDE(segments<number>, [divs<KNOTS|LENGTHS>, flags<o;s>,
			strength<number>])
	     -- Clone or extrude selected data using rails in background
		layers.  If segments is zero, they are computed automatically,
		otherwise it is a fixed division.  Flags are 'o' for 
		oriented and 's' for scaled.

	AXISDRILL(operation<CORE|TUNNEL|SLICE|STENCIL>, axis<X|Y|Z>,
		  [surface<string>])
	     -- Use background layers as template to operate on foreground 
		layers.  Surface is used for STENCIL operation.

	SOLIDDRILL(operation<CORE|TUNNEL|SLICE|STENCIL>, [surface<string>])
	     -- Use background object to operate on foreground.

	BOOLEAN(operation<UNION|SUBTRACT|INTERSECT|ADD>)
	     -- Combine background object with foreground data.

	BEVEL(inset<number>, shift<number>)
	     -- Perform bevel operation on selected polygons.

	SHAPEBEVEL(pattern)
	     --	Bevel with a shape defined by a series of insets and
		shifts.  The pattern is a blank-separated list of 
		inset/shift pairs, each relative to the original polygon.  
		The same effect can be achieved using iterative bevels, 
		but the results are not always correct because of self-
		crossing.

	SMOOTHSHIFT(offset<number>, [maxangle<number>])
	     -- Shift selected polygons by given offset.  Any angles 
		greater than maxangle will cause the surface to break.

	FLIP()
	     -- Flip sidedness of faces, direction of curves.

	TRIPLE()
	     -- Convert all polygons into triangles.

	REMOVEPOLS()
	     -- Remove polygons leaving points.

	ALIGNPOLS()
	     -- Flip polygons so all are facing the same direction (as
		much as is possible).

	UNIFYPOLS()
	     -- Delete any duplicate polygons.

	CHANGESURFACE(surface<string>)
	     -- Set the surface of all selected polygons.

	SUBDIVIDE(mode<FLAT|SMOOTH>, [maxangle<number>])
	     -- Split all triangles into four smaller triangles.

	FREEZECURVES()
	     -- Convert all selected curves directly into polygons.


Data Creation (ADD mode):

	ADD_BEGIN()
	     -- Enter data creation (ADD) mode.  Points and polygons
		can be added.  Other operations are illegal except 
		for the SURFACE command which sets surface for new 
		polygons.

	index<int> = ADD_POINT(position<vector>)
	     -- Points are numbered in creation order starting at 1.
		The index of the new point is returned.

	ADD_POLYGON(<point number list>)
	     -- Takes a variable number of point numbers as argument.
		Polygon is created using current default surface.

	ADD_QUAD(<point number list>)
	     -- Takes a variable number of point numbers, up to four.
		Polygon is created using current default surface and
		will have 2 sides or be made with triangles if those
		flags are set.

	ADD_CURVE(<point number list>, [ccstate])
	     -- Takes a variable number of point numbers as argument.
		Curve is assigned current default surface.  Ccstate
		gives the condition of the continuity control points
		at the start and end.  If the ccstate argument 
		contains 's', the first point in the list is a CC 
		point.  If the string contains 'e', the same for the 
		last point in list.

	ADD_END()
	     -- Exit data creation mode.  New data will appear in the
		layer at this time and the whole operation can be
		undone as an atomic command.


Point Transform (TRANSFORM mode):

	n<number> = XFRM_BEGIN()
	     -- Start a point transformation.  Returns number of points in
		the current layer.  If the number returned is zero, there
		are no points to process and TRANSFORM mode is not entered.

	pos<vector> = XFRM_GETPOS(index<number>)
	     -- Get position of indexed point.  Index is from 1 to N. 

	XFRM_SETPOS(index<number>, position<vector>)
	     -- Move the indexed point to a new position.

	XFRM_END()
	     -- Complete the transform and move all the points to their
		new positions.  END_ALL aborts the transform.


Sweep and Copy (REPLICATE mode):

	REPL_BEGIN(mode<COPY|SWEEP>)
	     -- Start replication.  This is a copy or sweep, given by
		the argument.

	REPL_STEP(offset<vector>, scale<vector>, rotation<vector>,
		  [center<vector>])
	     -- Set the next step of the replication.  Offset is a shift.
		Rotation is a vector of (H,P,B) which is rotation around
		the Y, X and Z axes, respectively.  Rotation and scaling
		will occur around optional center.  To get a first step 
		that is the same as the start pattern, REPL_STEP(0,1,0) 
		must be included in the sequence.

	REPL_END()
	     -- Complete the replication creating new data.  END_ALL can be
		used to abort the operation.


Selection:

Selection can be in two modes.  In the GLOBAL mode, all points and polygons
in active layers are selected for operation.  This is the default selection 
mode.  In USER mode, the selection set in the main window is honored by
rexx functions.  This selection can also be altered.

	SEL_MODE(newmode<GLOBAL|USER>)
	     --	Set the selection mode.  END_ALL or script termination 
		will reset this mode to GLOBAL.

	SEL_POINT(action<SET|CLEAR>, [condition ...])
	     --	Modify point selection.  Only valid in USER mode, and
		the user's selection mode will be changed to point if
		it is not already.  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 
		arguements are:

		VOLUME, lo<vector>, hi<vector>
		     -- points within the volume.

		CONNECT
		     -- points connected to already selected ones.  Only
			works with SET.

		NPEQ, npol<number>
		     --	points belonging to exactly npol polygons.

		NPLT, npol<number>
		     --	points belonging to less than npol polygons.

		NPGT, npol<number>
		     --	points belonging to more than npol polygons.

	SEL_POLYGON(action<SET|CLEAR>, [condition ...])
	     --	Modify polygon selection.  Like SEL_POINT, with the
		following conditions:

		VOLEXCL, lo<vector>, hi<vector>
		     -- polygons entirely within the volume.

		VOLINCL, lo<vector>, hi<vector>
		     -- polygons at least partly within the volume.

		CONNECT
		     -- polygons connected to already selected ones.  Only
			works with SET.

		NVEQ, nvert<number>
		     --	polygons with exactly nvert vertices.

		NVLT, nvert<number>
		     --	polygons with less than nvert vertices.

		NVGT, nvert<number>
		     --	polygons with greater than nvert vertices.

		SURFACE, surface<string>
		     -- polygons having the given surface.

		FACE
		     -- face polygons only.

		CURVE
		     -- curve polygons only.

		NONPLANAR, [limit<number>]
		     -- polygons less planar than the given limit.  If
			limit is omitted, it is the user's default limit.


User Interface:

	ok<bool> = NOTIFY(type<number>, line1<string>, [line2, ...])
	     -- Puts up a simple notification requester and returns user
		choice if one given.  Type is 1 for simple OK only
		notification and the function always returns 1.  Type 2
		is OK/Cancel request and function returns 1 for OK, 0
		for Cancel.  Type 3 is Yes/No request and the function
		returns 1 for Yes.  The remaining arguments are text 
		lines, which will be in the default color unless preceded 
		by '@' or '!' for increasingly strong emphasis colors.

	fnam<string> = GETFILENAME(title<string>, dir<string>, [nam<string>])
	     -- Get a filename from the user.  Title is the title text
		for the file requester.  Dir is the start directory and
		nam is the optional name to start with in that directory.
		The return value is a name plus a path which clients will
		have to parse themselves if they want parts of the name.
		The string "(none)" is returned if the user cancels.

A client ARexx macro can put up a requester to get input from the user.
The interface is a set of functions to set up the request and get the 
user's responses.

	REQ_BEGIN(header<string>)
	     -- Start a requester box interaction.  The requester box will
		have the given header string at the top.

	id = REQ_ADDCONTROL(label<string>, type<string>, [opts, ...])
	     -- Add a user input control with the given label text and
		description.  The type is a code for the type of control
		to create, and subsequent arguments are provided 
		depending on type.

		type	       code   other args
		----	       ----   ----------
		string		S     width (number of characters)
		number		N     units (flag for meters(1) or unitless(0))
		vector		V     units
		v-choice	CV    text1 text2 text3 ...
		h-choice	CH    ...
		boolean		B
		text-line	T     line1, line2, ...
		surface		R
		font		F

		Controls must be all added before any attempt to set or
		get values, or to post.

	REQ_SETVAL(id, value ...)
	     -- Set the value of the control.  Interpretation of value
		argument(s) depends on control type.  Text-line controls
		have no value.

		type	  value args
		----	  ----------
		string	  text<string>
		number	  value<number>, [default<number>]
		vector	  value<vector>, [default<number>]
		choice	  index<number 1..N>
		boolean	  state<bool>
		surface	  name<string>
		font	  index<number 1..fontcount()>

	ok<bool> = REQ_POST()
	     -- Posts request box and returns 1 for Ok, 0 for Cancel.

	value = REQ_GETVAL(id)
	     -- Get the value of the control.  Interpretation of the
		value string depends on the type of the control.  Values
		are as they are in SETVAL, with vectors always returned 
		as a triple.

	REQ_END()
	     -- Complete requester interaction.  Each request must be
		complete before the next begins.

A client ARexx macro can configure the custom ARexx commands available
to the interactive user.

	ok<bool> = RXCMD_ADD(name<string>, cmd<string>)
	     -- Add the given command string to the interface with the
		given descriptive name.  Returns true if item could
		be added.

	RXCMD_REMOVE(name<string>)
	     -- Remove the command from interface given its descriptive
		name.

	cmd<string> = RXFUN_GET(n<number>)
	     -- Get the command string for function key n (1..10).

	RXFUN_SET(n<number>, cmd<string>)
	     -- Set the command string for function key n (1..10).  Since
		any change made here will be saved in the config file, 
		scripts that do this should probably restore the old 
		command before exiting.


A macro can show how it is progressing through the stages of an operation
with the progress meter.  Metering is a state that can co-exist with any
mode or with a requester.

	METER_BEGIN(count<int>, header<string>, [footer<string>])
	     -- Initiate progress meter with the given main header and
		optional footer.  The count is the number of times
		METER_STEP() will be called before operation is done.

	METER_STEP()
	     -- Step the progress meter one step closer to completion.
		Will return an error if the initial count is exceeded,
		or if the user requests an abort.

	METER_END()
	     -- Deactivate meter.  Can be called before process final
		count is reached.