========
= CELL =
========

--------------
CELL COMMANDS:
--------------

cell create <label>
	- creates a new cell instance named <label>.  <label> will also be the
	  name of the procedure that you use to access the cell instance.

cell list
	- lists existing cells.

cell types
	- list available model types.

-----------------------
CELL INSTANCE COMMANDS:
-----------------------

bbox <model>
	- returns model's bounding box, in global coordinates.
	  If the box is empty, an empty list is returned; otherwise a list of
	  six numbers is returned, with the first three specifying one corner
	  of the box and the second three the opposite corner.

cget option
	- returns cell's option value.

children <model>
	- returns a list of model's immediate children.

configure ?options?
	- configures cell options.

convert <model> <{x y z}>
	- converts vector {x y z} from <model>'s local coordinate system to
	  that of <model>'s parent's coordinate system.

create <model> type ?options?
	- creates a model. valid types are line, point, polygon, cylinder,
	  disk, and sphere.  Note that model types cylinder, disk, and sphere
	  are actually approximated internally by OpenGL with polygons.

delete <model>
	- deletes a model from cell.

destroy
	- destroys the cell and frees up all data structures associated with
	  it.

extent <model>
	- returns the smallest box that encloses model and its descendants, in
	  global coordinates. If the box is empty, an empty list is returned;
	  otherwise a list of six numbers is returned, with the first three
	  specifying one corner of the box and the second three the opposite
	  corner.
 
list
	- lists existing models in cell.

modelcget <model> option
	- returns model's option value.

modelconfigure <model> ?options?
	- configures model options.

setv <model> <mode> <{index x y z} ...>
	- changes the coordinates of one or more of <model>'s vertices. <mode>
	  can be either 'absolute' or 'offset'. <index> is the index of the
	  vertex to be changed. If mode is 'absolute', {x y z} replaces the
	  current coordinate values; otherwise {x y z} are added to the
	  current values.
	  If x, y, or z is null, then the corresponding coordinate is not
	  modified.

type <model>
	- returns model's type.


------------
CELL OPTIONS
------------

-epsilon
	used in normalizing vectors. A vector will be considered a null
	vector (0, 0, 0) if its magnitude is less than epsilon.


--------------------
COMMON MODEL OPTIONS
--------------------

-ambient
	ambient reflectance coefficients of polygon's front faces.  Specify
	one component (between 0 and 1) each for red, green and blue.

-color
	color of the model (or its front faces.)  This color will be modulated
	by the emissive and reflectance coefficients and the color of the light
	sources to determine the final color.

-diffuse
	diffuse reflectance coefficients of the model (or its front faces.)
	Specify one component (between 0 and 1) each for red, green and blue.

-emissive
	emissive coefficients of the model (or its front faces.)  Specify one
	component (between 0 and 1) each for red, green and blue.

-fwd
	model's forward direction vector.  The forward vector and the up
	vector together define the orientation of the model with respect to
	its parent (or relative to the global coordinates with no parent.)

-parent
	model's parent.

-position
	model's position relative to its parent.  When the model has no
	parent, its position is in global coordinates.

-shading
	shading model: none, flat, or smooth.

-specular
	specular color and shininess of the model (or its front faces.)
	Specify one component (between 0 and 1) each for red, green and blue,
	and a non-negative number for shininess.

-up
	model's up direction vector.  The forward vector and the up vector
	together define the orientation of the model with respect to its
	parent (or relative to the global coordinates with no parent.)

-visible
	boolean flag indicating whether the model should be drawn.  When off,
	model and all its descendents will not be drawn.


-------
POLYGON
-------

-average
	flag indicating whether vertex normals should be generated by
	averaging adjacent surface normals.

-backmode
	how the polygon's back faces should be drawn: fill, line, or point.

-bfambient
	ambient reflectance coefficients of the polygon's back faces.  Specify
	one component (between 0 and 1) each for red, green and blue.

-bfcolor
	color of the polygon's back faces.  This color will be modulated by
	the emissive and reflectance coefficients and the color of the light
	sources to determine the final color.

-bfdiffuse
	diffuse reflectance coefficients of the polygon's back faces.  Specify
	one component (between 0 and 1) each for red, green and blue.

-bfemissive
	emissive coefficients of the polygon's back faces.  Specify one
	component (between 0 and 1) each for red, green and blue.

-bfspecular
	specular color and shininess of the polygon's back faces.  Specify a 
	one component (between 0 and 1) each for red, green and blue, and a
	non-negative number for shininess.

-ccw
	controls how front and back-faces for the polygon are determined.
	When on, faces that have their vertices specified in counter-clockwise
	orientation are front-facing.

-cull
	which polygon faces are culled: none, front, back, or both.

-frontmode
	how the polygon's front faces should be drawn: fill, line, or point.

-materials
	vertex materials.  The value of this option should be a list, with
	each element of the list consisting of a surface index (starting
	at 1) and a list of material properties.  The number of material
	properties must be the same as the number of vertices in the surface.
	Each material property has the form:

	{ambient diffuse specular emissive shininess}

	ambient, diffuse, specular, and emissive coefficients each should be
	a list of three numbers (the red, green, and blue components.)
	shininess should be a positive number.

-normals
	vertex normals.  The value of this option should be a list, with
	each element of the list consisting of a surface index (starting
	at 1) and a list of normal vectors.  The number of normal vectors
	must be the same as the number of vertices in the surface.

-surfaces
	list of polygonal surfaces.  Each surface consists of a list of
	vertex indices (starting at 1).

-textures
	list of texture map entries.  Each entry is a list of 9 elements:

		index
		textureID
		components
		function
		s mode
		t mode
		magnification filter
		minification filter
		border color
		texture coordinates

	<index> indicates which surface to apply the texture map to.  Only
	front faces will be affected.  The first surface has an index of 1.

	<textureID> is the ID of the texture map created with the "texture"
	command.  See the file "texture" for information about creating
	texture maps.

	<components> indicates which of the RGB components will be used in the
	texturing process.  Valid values depend on the function selected.

	<function> is one of: 'decal', 'modulate', and 'blend'.

	<s mode>: whether the texture should be repeated or clamped ('repeat'
	or 'clamp') in the s-direction.

	<t mode>: whether the texture should be repeated or clamped ('repeat'
	or 'clamp') in the t-direction.

	<magnification filter> is either 'nearest' or 'linear'.

	<minification filter> is either 'nearest' or 'linear'.

	<border color> has the form {r g b}, where 0.0 <= r, g, b <= 1.0.

	<texture coordinates> is a list of {s t} coordinates that are assigned
	to the surface vertices.  The length of the list must equal the number
	of vertices.

	Please refer to the OpeGL Programming Guide for explanations of each
	field.

-usetexture
	boolean flag indicating whether texture maps should be applied to
	the model.

-vertices
	list of vertices, in the form {{x y z} ... }.


-----
POINT
-----

-pointsize
	size of the point vertices.  Setting -pointsize will clear the
	previous -sizes setting.

-materials
	vertex materials.  The value of this option should be a list, with
	each element of the list consisting of a list of material properties.
	The number of material properties must be the same as the number of
	vertices in the model. Each material property has the form:

	{ambient diffuse specular emissive shininess}

	ambient, diffuse, specular, and emissive coefficients each should be
	a list of three numbers (the red, green, and blue components.)
	shininess should be a positive number.

-normals
	vertex normals.  The value of this option should be a list of normal
	vectors.  The number of normal vectors must be the same as the number
	of vertices in the model.

-sizes
	vertex sizes.  The value of this option should be a list of numbers
	representing the vertex sizes.  The sizes are assigned in order to
	model vertices.  The length of the list must equal the number of
	vertices in the model.

-textures
	list of texture map entries.  Each entry is a list of elements:

		textureID
		components
		function
		s mode
		t mode
		magnification filter
		minification filter
		border color
		texture coordinates

	<textureID> is the ID of the texture map created with the "texture"
	command.  See the file "texture" for information about creating
	texture maps.

	<components> indicates which of the RGB components will be used in the
	texturing process.  Valid values depend on the function selected.

	<function> is one of: 'decal', 'modulate', and 'blend'.

	<s mode>: whether the texture should be repeated or clamped ('repeat'
	or 'clamp') in the s-direction.

	<t mode>: whether the texture should be repeated or clamped ('repeat'
	or 'clamp') in the t-direction.

	<magnification filter> is either 'nearest' or 'linear'.

	<minification filter> is either 'nearest' or 'linear'.

	<border color> has the form {r g b}, where 0.0 <= r, g, b <= 1.0.

	<texture coordinates> is a list of {s t} coordinates that are assigned
	to the vertices.  The length of the list must equal the number of
	vertices.

	Please refer to the OpeGL Programming Guide for explanations of each
	field.

-usetexture
	boolean flag indicating whether texture maps should be applied to
	the model.

-vertices
	list of vertices, in the form {{x y z} ... }.


----
LINE
----

-lines
	list of line segments.  Each segment consists of a list of vertex
	indices (starting at 1).

-linestipple
	specifies the stippling pattern for the line segments in the model.
	The value of this option is interpreted as a 16-bit series of 0's
	and 1's.  Setting -linestipple will clear the previous -stipples
	setting.

-linestipplefactor
	specifies the factor by which line stipples are stretched.  Setting
	-linestipplefactor will clear the previous -stipples setting.

-linewidth
	specifies the width of the line segments.  Setting -linewidth will
	clear the previous -widths setting.

-materials
	vertex materials.  The value of this option should be a list, with
	each element of the list consisting of a segment index (starting
	at 1) and a list of material properties.  The number of material
	properties must be the same as the number of vertices in the segment.
	Each material property has the form:

	{ambient diffuse specular emissive shininess}

	ambient, diffuse, specular, and emissive coefficients each should be
	a list of three numbers (the red, green, and blue components.)
	shininess should be a positive number.

-normals
	vertex normals.  The value of this option should be a list, with
	each element of the list consisting of a segment index (starting
	at 1) and a list of normal vectors.  The number of normal vectors
	must be the same as the number of vertices in the segment.

-stipples
	line stipples.  The value of this option should be a list, with
	each element of the list consisting of a segment index (starting
	at 1), a stippling pattern (an 16-bit integer), and a scaling factor
	(an integer).

-textures
	list of texture map entries.  Each entry is a list of 9 elements:

		index
		textureID
		components
		function
		s mode
		t mode
		magnification filter
		minification filter
		border color
		texture coordinates

	<index> indicates which segment to apply the texture map to.  The
	first segment has an index of 1.

	<textureID> is the ID of the texture map created with the "texture"
	command.  See the file "texture" for information about creating
	texture maps.

	<components> indicates which of the RGB components will be used in the
	texturing process.  Valid values depend on the function selected.

	<function> is one of: 'decal', 'modulate', and 'blend'.

	<s mode>: whether the texture should be repeated or clamped ('repeat'
	or 'clamp') in the s-direction.

	<t mode>: whether the texture should be repeated or clamped ('repeat'
	or 'clamp') in the t-direction.

	<magnification filter> is either 'nearest' or 'linear'.

	<minification filter> is either 'nearest' or 'linear'.

	<border color> has the form {r g b}, where 0.0 <= r, g, b <= 1.0.

	<texture coordinates> is a list of {s t} coordinates that are assigned
	to vertices of the line segment.  The length of the list must equal
	the number of vertices in the segment.

	Please refer to the OpeGL Programming Guide for explanations of each
	field.

-usetexture
	boolean flag indicating whether texture maps should be applied to
	the model.

-vertices
	list of vertices, in the form {{x y z} ... }.

-widths
	line segment widths.  The value of this option should be a list, with
	each element of the list consisting of a line segment index (starting
	at 1), and a segment width.


--------
CYLINDER
--------

-baseradius
	radius of the cylinder base.

-backmode
	how the cylinder's back faces should be drawn: fill, line, or point.

-bfambient
	ambient reflectance coefficients of the cylinder's back faces.
	Specify one component (between 0 and 1) each for red, green and blue.

-bfcolor
	color of the cylinder's back faces.  This color will be modulated by
	the emissive and reflectance coefficients and the color of the light
	sources to determine the final color.

-bfdiffuse
	diffuse reflectance coefficients of the cylinder's back faces.
	Specify one component (between 0 and 1) each for red, green and blue.

-bfemissive
	emissive coefficients of the cylinder's back faces.  Specify one
	component (between 0 and 1) each for red, green and blue.

-bfspecular
	specular color and shininess of the cylinder's back faces.  Specify a 
	one component (between 0 and 1) each for red, green and blue, and a
	non-negative number for shininess.

-ccw
	controls how front and back-faces of the cylinder are determined.
	When on, faces that have their vertices specified in counter-clockwise
	orientation are front-facing.

-cull
	which cylinder faces are culled: none, front, back, or both.

-drawstyle
	how the cylinder should be drawn: fill, line, or point.

-frontmode
	how the cylinder's front faces should be drawn: fill, line, or point.

-height
	height of the cylinder.

-normals
	specifies the type of normals desired for the cylinder: none, flat, or
	smooth.

-orientation
	specifies the desired surface orientation of the cylinder: inside or
	outside.

-slices
	number of subdivisions around the z axis.

-stacks
	number of subdivisions along the z axis.

-topradius
	radius of the cylinder top.


----
DISK
----

-backmode
	how the disk's back faces should be drawn: fill, line, or point.

-bfambient
	ambient reflectance coefficients of the disk's back faces.  Specify
	one component (between 0 and 1) each for red, green and blue.

-bfcolor
	color of the disk's back faces.  This color will be modulated by
	the emissive and reflectance coefficients and the color of the light
	sources to determine the final color.

-bfdiffuse
	diffuse reflectance coefficients of the disk's back faces.  Specify
	one component (between 0 and 1) each for red, green and blue.

-bfemissive
	emissive coefficients of the disk's back faces.  Specify one component
	(between 0 and 1) each for red, green and blue.

-bfspecular
	specular color and shininess of the disk's back faces.  Specify a 
	one component (between 0 and 1) each for red, green and blue, and a
	non-negative number for shininess.

-ccw
	controls how front and back-faces of the disk are determined.  When
	on, faces that have their vertices specified in counter-clockwise
	orientation are front-facing.

-cull
	which disk faces are culled: none, front, back, or both.

-drawstyle
	how the disk should be drawn: fill, line, or point.

-frontmode
	how the disk's front faces should be drawn: fill, line, or point.

-innerradius
	inner radius of the disk.

-loops
	number of concentric rings about the origin into which the disk
	is subdivided.

-normals
	specify the type of normals desired for the disk: none, flat, or
	smooth.

-orientation
	specify the desired surface orientation of the disk: inside or
	outside.

-outerradius
	outer radius of the disk.

-slices
	number of subdivisions around the z axis.


------
SPHERE
------

-backmode
	how the sphere's back faces should be drawn: fill, line, or point.

-bfambient
	ambient reflectance coefficients of the sphere's back faces.  Specify
	one component (between 0 and 1) each for red, green and blue.

-bfcolor
	color of the sphere's back faces.  This color will be modulated by
	the emissive and reflectance coefficients and the color of the light
	sources to determine the final color.

-bfdiffuse
	diffuse reflectance coefficients of the sphere's back faces.  Specify
	one component (between 0 and 1) each for red, green and blue.

-bfemissive
	emissive coefficients of the sphere's back faces.  Specify one
	component (between 0 and 1) each for red, green and blue.

-bfspecular
	specular color and shininess of the sphere's back faces.  Specify a 
	one component (between 0 and 1) each for red, green and blue, and a
	non-negative number for shininess.

-ccw
	controls how front and back-faces of the sphere are determined.  When
	on, faces that have their vertices specified in counter-clockwise
	orientation are front-facing.

-cull
	which sphere faces are culled: none, front, back, or both.

-drawstyle
	how the sphere should be drawn: fill, line, or point.

-frontmode
	how the sphere's front faces should be drawn: fill, line, or point.

-normals
	specifies the type of normals desired for the sphere: none, flat, or
	smooth.

-orientation
	specifies the desired surface orientation of the sphere: inside or
	outside.

-radius
	radius of the sphere.

-slices
	number of subdivisions around the z axis (similar to lines of
	longitude.

-stacks
	number of subdivisions along the z axis (similar to lines of
	latitude).
