<?xml version="1.0"?>
<body>
<CPdocs type="CmdDetails">

<command cmd="act" flags="{p}">
<description>
This makes p (0,1, or 2) the "active" pack. Many actions from
menus or command lines apply to the active pack, so it is
important to be aware of which pack is active: in the panel
with thumbnails of the three packings, the active packing has the
read header.
</description>
</command>

<command cmd="add_bary" flags="{f..}">
<description>
	Given a list of face indices, this adds a trivalent 
	barycentric vertex --- a "ball bearing" circle --- to each 
	face. (Caution: incompatibilites can occur with certain inversive
	distance assignments on the edges.)
</description>
<examples>
<instance text="add_bary a"> One can generate "Apollonian"-type
packings by repeatedly adding barycenters to all interstices
</instance>
</examples>
<seealso>
<see>rm_cir</see>
<see>add_face_triple</see>
</seealso>
</command>


<command cmd="add_cir" flags="{v..}">
<description>	A circle is added to each specified boundary circle v of the
	active pack; the new circle neighbors v and its clockwise 
	boundary neighbor. Its initial radius is that of v.
</description>
</command>


<command cmd="add_edge" flags="{v w..}">
<description>	This adds a vertex to each listed edge. The new vertex is 
	degree 4, being connected to v, w, and to their two common 
	neighbors.
</description>
</command>

<command cmd="add_face_triple" flags="{f..}">
<description>	This adds a triple of new vertices within each of the 
	given faces. (Caution: incompatibilites can occur with 
	certain inversive distance assignments on the edges.)
	One can generate stages of a type of generalized
	"Apollonian" packing by repeating "add_face_triple a". 
	See also 'add_bary'. 
</description>
<seealso>
<see><add_bary</see>
</seealso>
</command>


<command cmd="add_gen" flags="{n} [{d}] [-d] [-b {w..}]">
<description>	n (>0) successive generations of new circles are added to 
	the current boundary, making the current boundary vertices interior
	There are various options for how circles are added.
</description>
	  
<options>
	<opt flag="{n}"> adds n circle-for-circle generations,
	without regard to degree. Note that after the first level
	is added, the remainder will be degree 6 vertices.
	(Deprecated: this was flag -t.)</opt> 
	<opt flag="{n} {d}"> this adds n generations so that at each step
	  the previous boundary vertices are of degree d (>3) (with a
	  message if some are forced to go to larger degree).</opt> 
	<opt flag="{n} -t"> (Deprecated)</opt>
	<opt flag="n -b {w..}"> This allows the user to limit which boundary
      	   components the command applies to (default being
               all). List vertices {w..} on the boundary components
	         you want (e.g., you can get the 'start' vertices from
	   	   the pack "Info" frame).</opt>
	<opt flag="n -d"> Duplicate circles, adding bearing circles to the
resulting quad interstices.</opt>
</options>
<seealso>
<see> add_layer</see>
<seealso>
</command>


<command cmd="add_ideal" flags="{v}">
<description>	Given a boundary vertex v of the active pack, a new vertex is
	added which neighbors all vertices of the boundary component
	containing v. All these and the new vertex become interior
	vertices. Center and radius default to (0,0) and .5 (or PI/2 in
	spherical case).  
</description>
</command>


<command cmd="add_layer" flags="[-dt] [n] v w">
<description>A single layer of new vertices is added to the boundary from
	vertex v to vertex w (these must be on the same boundary
	component; v can equal w to get the whole boundary component). 
	So v, w, and the vertices between them will become interior vertices. 
</description>

<options>
	<opt flag="-t v w"> (default) 'tent' each boundary edge	from v to w,
	  that is, add a circle for each edge and connect ones for neighboring
	  edges to form new boundary edges. If v and w are distinct, they 
	  remain on the boundary as the ends of the new boundary segment.</opt>

	<opt flag="-d v w">	add a chain of circles duplicating those
	  between v and w, putting a bearing circle in each of the
	  resulting interstices. If v and w are distinct, they remain 
	  on the boundary as the ends of the new boundary segment.</opt>

	<opt flag="d v w"> adds circles so that v, w, and the boundary 
	  vertices between end up with degree d (>3); if one or more
	  circles are forced to degree exceeding d, a message is issued.
	  Here v and w become interior vertices.</opt>
</options>
<seealso>
<see>add_gen</see>
</seealso>	  
</command>


<command cmd="adjacency" flags="[-t] {file}">
<description>
For packings of less than 10000 vertices, this stores the adjacency 
matrix for a packing complex in {file} using matlab format. 
</description>
<options>
	<opt flag="-t"> Gives instead the transition matrix for the 
	simple random walk on the graph of the packing, with absorbing 
	boundary. Various other things are added to the matlab file so
	the distribution of exit probabilities can be computed; the
	ordered list of boundary vertices, an initial distibution vector
	with charge at alpha, and computation routine.</opt>
</options>
</command>



<command cmd="adjoin" flags="{p q v w n} [or: {p q v w (v,u)}]">
<description>
	This allows the joining of two packs by an identification 
	of specified boundary circles (and edges). The packs affected are p
	and q, with results put into p. n boundary edges of p are
	identified with n boundary edges of q, starting with circle v of p
	and proceeding clockwise and with circle w of q and proceeding
	counterclockwise (directions are IMPORTANT). If n is negative 
	then that full boundary component  is pasted to q. 
	If 'n' is replaced by '(v,u)', then the edges from v 
	clockwise to u on the boundary of p are pasted to the same number 
	of edges counterclockwise on q, starting with w.

	It is legal to have p=q, resulting in the identification of edges 
	from the same pack. In this case, if v=w, then n edges starting 
	from v=w are identified like a "zipper". 
	
	NOTE: there's an attempt to save 'overlap', 'vlist', and 'elist' 
	info, if set, but face information is corrupted, so 'flist' is 
	discarded.
	
	NOTE: The 'vertexMap' of p should contain pairs {o,m}, where o is
	the original index in q and m is its new index in p.
</description>
</command>


<command cmd="adjust_rad" flags="{f} {v..}">
<description>Adjust the specified radii by factor f greater than 0. 
In euclidean geometry,
	radii are multiplied by f. Also in spherical geometry, though values
	cannot exceed Pi. In hyperbolic	geometry, the 'x-radius' x is 
	replaced by x=1-exp(factor*(log(1-x))). 
</description>	
</command>


<command cmd="alpha" flags="{v}">
<description>
	The "alpha" circle of a pack is an interior circle which is
	treated as a combinatorial origin; e.g., the drawing order is
	started from there. This command sets the alpha circle of the
	active pack to v, assuming v is interior.  It causes the drawing
	order to change and puts circle v at the origin when pack centers
	are computed (or north pole in spherical case).
</description>
<seealso>
<see>beta</see>
<see>gamma</see>
</seealso>
</command>


<command cmd="alt_rect" flags="{v0..v3}">
<description>Pack a combinatorial quadrilateral INSIDE a rectangle (as compared
	to using angle sums to get carrier to be a rectangle). Packing
	must be simply connected and {v0,v1,v2,v3} must be oriented list
	of boundary vertices, each edge {v(i),v(i+1)} should have at
	least three edges. If successful, the packing should be converted
	to euclidean and have radii set. The calling program will need
	to normalize and find the corners of the rectangle. If it fails,
	the packing should be unchanged.
</description>
</command>


<command cmd="aspect" flags="{a b c d}">
<description>For euclidean packings only this finds the extremal length,
	namely, length/height, (aspect ratio) of a rectangle given the 
	corner vertices in counterclockwise order starting with 
	upper-left corner a. (length=left/right, height=top/bottom)
</description>
</command>


<command cmd="bary_refine">
<description>This does a barycentric subdivision of all faces of the
	given packing. The indices and degrees of the origin vertices
	remain unchanged; the face barycenter circles end up with the 
	largest indices. Most auxiliary packing data is lost and if 
	refinement fails, the packing can be corrupt.
</description>
</command>


<command cmd="beta" flags="{v}">
<description>	This is more-or-less defunct designation. Formerly, it was
	required to be a boundary vertex, but now it can be used
	for other purposes, which may be useful since it is stored 
	along with alpha and gamma in the packing files.
</description>
<seealso>
<see> alpha</see>
<see> gamma</see>
</seealso>
</command>

<command cmd="BeurlingFlow" flags="('BF' PackExtender)">
<description>	Sets boundary ratio functions in a discrete version of 
	Beurling's Mapping Theorem using the real-valued function 
	(complex variable 'z') maintained in the "Function"
	tab.
</description>
<seealso>
<see>set_function_text</see>
</seealso>
</command>


<command cmd="blend" flags="-q{qnum} v n">
<description>"Blend" pack q (qnum) with the active pack p. q overlaps p
	-- as when the q is an island of the active pack. Typically
	q has taken its bdry radii from p (though these values may 
	have originate with yet another packing), q has already been
	repacked with these bdry radii, and q has a vertex_map to p.
	
	This call uses a bdry vertex v of q (it's often convenient 
	to indicate 'b' in place of a specific v, so that a boundary 
	vertex will automatically be chosen), generates an antipodal 
	bdry vert, and uses these two to carry q via a Mobius
	transformation into registry with p. The centers are blended 
	to a depth of n. In other words, a bdry annulus of q overlaps 
	part of p and we adjust the centers of these circles using 
	convex combinations of their centers from the two packings: 
	the bdry circles of q take their centers entirely from p, 
	but the centers from q weight more and more heavily as the 
	generations from bdry q grow.

	Notes: If n is negative, the depth is taken as large 
	as possible; n = 1 and q is simply moved to put it in 
	register with p; v = 0 and a boundary vert is chosen 
	automatically.
</description>
</command>


<command cmd="brooks" flags="[OPTIONS] {VH...} ('BQ' pack extension)">
<description>This creates a persistent 'pack extension' class 'BQ'
	which attaches to this packing and handles "Brooks' 
	quadrilateral" constructions. Commands can be directed
	to that class with prefix '|BQ|'
	Brooks quadrilateral packings involve addition
	of 'vertical' and 'horizontal' circles to a quadrilateral
	interstice. After opening the packing, sequences of
	V's and H's direct the construction. Details elsewhere
	(e.g., in my book).
</description>

<options>
	<opt flag="-o">	Create a new Brooks' quadrilateral class in the
			default mode (i.e., Brooks' protocol for adding
			vertical and horizontal circles.</opt>
	<opt flag="-oa">Alternate mode, Use 'alternating' protocol for 
			locating new circles.</opt>
	<opt flag="-x">	Close the Brooks pack extension; the packing
			itself should remain in tact.</opt>
</options>
</command>	


<command cmd="cd" flags="{..}">
<description>Change the working directory. Can use "pwd" to find the
	current directory.
</description>
<examples>
<instance text="cd ~"> change to the user's home directory</instance>
</examples>
<seealso>
<see>pwd</see>
</seealso>
</command>


<command cmd="center_point" flags="{x y}">
<description>Recomputes the centers of the active pack, putting (x,y) at the
	origin. In euclidean case, this is a translation, but in the
	hyperbolic case, a Mobius transformation (automorphism of the
	hyperbolic plane) is applied.  NOTE: This is different than 
	'focus', which just changes the view presented on the canvas.
	See 'set_screen' options also.
</description>
<seealso>
<see>center_vert</see>
</seealso>
</command>


<command cmd="center_vert" flags="{v}">
<description>Same as 'center_point', except that the center (euclidean 
or hyperbolic, as appropriate) of circle v is used in place of (x,y)
</description>
<seealso>
<see>center_point</see>
</seealso>
</command>


<command cmd="cir_aspect" flags="{v}">
<description>For euclidean packings only. For each vertex v this returns the
	"aspect" of its circle; that is, the ratio r/|z| between its
	radius and the distance of its center from the origin 
	(when |z| is non-zero).
</description>
</command>


<command cmd="cir_invert" flags="[-u] {v} {w}">
<description>Apply the Mobius transformation which maps the outside of 
	the circle for v onto the inside of the circle for w.
	This is useful for packing about a circle and then making
	that circle into the outside of the unit disc.
	Cautions: 1) In the hyperbolic case this forces a conversion
	to a euclidean packing. 2) One expects v to be a circle
	enclosing infinity after the mapping.
</description>
<options>
	<opt flag="-u"> Use the unit circle in place of w</opt>
</options>
<seealso>
<see>Mobius</see>
</seealso>	
</command>


<command cmd="cleanse">
<description>This empties a packing, clears its canvas, resets
various options for display and screen control. Caution, there
is no verification and all packing data is lost.
</description>    
</command>


<command cmd="color" flags="[options]">
<description>Color specifications affect the display of filled circles "-c" or
	faces "-f" only. Color is used mainly to illustrate comparisons of
	radii/areas/dilatations.
</description>
<options> (one only)
	<opt flag="bg {i..}"> background color for selected indices 
(faces or circles)</opt>
	<opt flag="fg {i..}"> foreground color</opt>
	<opt flag="{c} c {i..}"> is a color code (in [0,39]), blue 
to red ramp</opt>
	<opt flag="p{p} {i..}"> copies colors from pack p 
(deprecated: '-p')</opt>
	<opt flag="area (all faces)"> blue color ramp based on face 
areas, all faces</opt>
	<opt flag="rad  (all circles)"> blue color ramp based on radii</opt>
	<opt flag="q{p} {v..}"> blue-red color ramp rad/area compared 
to pack p; (deprecated: '-q')</opt>
	<opt flag="q{p} angsum {v..}"> blue-red color ramp comparing angle 
sums to p;</opt>
	<opt flag="d"> color by degree: 6=white, 5=blue, 7=red, 
others various</opt>
 	<opt flag="s {i..}"> 'spread' colors: select cyclically 
from 16 distinct colors</opt>
	<opt flag="S {i..}"> same as 's', except same color is used 
for whole list</opt>
	<opt flag="-k {x}"> (not currently implemented) 
(circles only) blue-red, compare model curvature to x.</opt>
	<opt flag="v {f..}"> (faces only) use vertex colors: majority wins, 
else first vert's color. (deprecated: '-v')</opt>
	<opt flag="qc [options] -m {x} {f..}">  (faces only)
		red color ramp for faces based on quasiconformal 
		dilatation of some map. (Currently, all data must be 
		2D or 3D euclidean data.) -m sets ceiling x on
		dilatations; those above x will be colored dark blue,
		those in [1,x) will be increasingly red, those that 
		can not be computed will be black.
	   options:
		-q{p}  comparison to packing p.
		-[ns] {name} comparison to a file with xyz coords.
		        -n for file, -s for data in the current script file.
		-x      comparison to xyz data stored as part of the 
			packing data.</opt>
</options>
<examples>
<instance text="color -f qc -q1 -m 1.5 a"></instance>
</examples>
</command>
		 
<command cmd="cookie" flags="[option] {v..}">
<description>A portion of the packing is "cookied" out, forming a new packing
	replacing the original, the rest of the original being discarded.
	Caution: This may not do exactly what is expected, since some
	pruning may occur to avoid pathologies: in particular, the 
	new packing must have connected interior and each of its
	boundary vertices must have an interior neighbor.

	The idea is to designate 'poison' vertices. Then the new
	complex is that component of the complement of these poison
	vertices which contains alpha (or a substitute, see -v
	option below). If vertices {v..} are listed in the command,
	then they comprise the poison vertices; otherwise (assuming
	the packing is hyperbolic or euclidean) the poison vertices
	are determined by the current "path", if there is one.

	NOTE: various information is lost, including 'flist', perhaps some
	overlap angles, etc.
</description>
<options>
	<opt flag="-v {v}"> Use v instead of alpha as the 'seed' vertex.</opt>
</options>
<seealso>
<see>set_poison</see>
</seealso>
</command>

<command cmd="copy" flags="{p}">
<description>The active pack is copied into pack p.  CAUTION: No confirmation
	is requested for command-line arguments, so original data in p
	will be lost.
</description>
</command>

<command cmd="count" flags="-[vef] {..}">
<description>Count a list of circles, edges, or faces (specify -v, -e, -f,
	respectively) with usual specification, as in vlist, etc.
	(Note: edge counting doesn't eliminate redundancies, other
	counts do.)
</description>
</command>

<command cmd="create_parent" flags="{filename} N">
<description>This initializes a *.vl type file for an N piece packing 
	decomposition and records the parent packing. The 
	command 'write_vert_list' then adds indices defining the
	N child packings.
</description>
</command>

<command cmd="delaunay" flags="-[cfgs]">
<description>Create the "Delaunay triangulation" for a set
of points on the sphere or euclidean plane and store the
resulting complex in the current packing. The points may
come from the active packing or from a file, which defaults 
to eucl geometry. This call uses C code to call 'qconvex' 
(one of the "QHull" programs) in the spherical setting or
'triangle' (Shewchuk's code). Note: 'qconvex' may not use 
all the points, perhaps	due to identifying some points that 
are very close.
</description>	
<options>
	<opt flag="-c"> use the centers of the active packing</opt>
	<opt flag="-g[se]"> geometry, spherical or euclidean(default)</opt>
	<opt flag="-f {filename}"> read	points from a file</opt>
	<opt flag="-s {filename}"> read points from a script file</opt>
</options>
<seealso>
<see>random_triangulation</see>
<see>random_pack</see>
</seealso>
</command>



	will be printed in the "Messages/Errors" window.
	Current routines are for uncovering combinatorial problems, 
	but additional options will be added. 
</description>
<options>
	<opt flag="-c"> Deep combinatoric check: nghb relationships,
		  orientation of edges, repeats or gaps in petals, etc.</opt>
	<opt flag="-e x"> Find first instance in layout of packing where 
		the two circles used for plotting have error in
		inv_distance relationship of at least x.</opt>
	<opt flag="-E x"> Count edges longer (shorter) by factor of x or more
		than radii and inv distance would imply.</opt>
	<opt flag="-h"> Are there boundary vertices without interior neighbors?</opt>
	<opt flag="-i"> Are the interior vertices of the complex edge connected?</opt>
	<opt flag="-o {v}"> Placement info on vertex v</opt>
	<opt flag="-r"> Check whether red chain of faces is corrupt</opt>
	<opt flag="-R"> Checks red chain layout, return error.</opt>
	<opt flag="-s"> verts with radius less than 2*(smallest radius)</opt>
	<opt flag="-v k"> order verts by average ratio [length/ideal_length]
	        (length versus intended length of edges).
		 k=1: length greater than ideal_length.
		 k=2: length less than ideal_length.
		 k=3: largest ratio either way.
	        Ordered list is in /tmp/diag_list_{pid}.txt.</opt>
</options>
</command>


<command cmd="disp" flags="[options ... ]">
<description>
	This displays the active pack on its canvas. The "Display"
	tab allows one to specify the default drawing options (or a
	user-defined string of commands as described below (see 
	'set_disp_str'). Several specifications can be put in the
	same command if desired. 

	NOTE: When the pack has been laid out using 'layout -l', plot 
	flags are set only for circles/faces which seem properly placed 
	(i.e., consistently with neighbors) and only those are drawn in
	the display. See 'set_plot_flags' to override.
</description>
<options heading="Common Options">
	<opt flag="-w"> clear the canvas</opt>
	<opt flag="-wr"> clear and refresh (i.e., issue 'disp')</opt>
	<opt flag="-c {v..}"> open circles </opt>
	<opt flag="-f {f..}"> open faces </opt>
	<opt flag="-e {v w..}"> edges </opt>
	<opt flag="-ec{n} {e..}"> colored edges with color code 'n'</opt>
	<opt flag="-nc {v..}"> label circles</opt>
	<opt flag="-nf {f..}"> label faces</opt>
	<opt flag="-C"> all circles, recomp'd by drawing order </opt>
	<opt flag="-F {f..}"> ``chained'' faces (see below)</opt>
	<opt flag="-B"> all faces and circles, recomp'd by drawing order</opt>
	<opt flag="-b"> draw all bary-coord defined paths (eucl only)</opt>
	<opt flag="-bc{n}"> ditto, but in color with index n</opt>
	<opt flag="-g"> display current "path" (if available) in thick blue</opt>
	<opt flag="-gc{n}"> ditto, but in color with index n</opt>
	<opt flag="-G"> display current "path" (if available) in normal line</opt>
	<opt flag="-r"> reset screen parameters to defaults </opt>
	<opt flag="-x (-xu)"> turn display of axes on (resp. off)</opt>
	<opt flag="-u"> draw unit circle</opt>
</options>

<options heading="Extended Options">
	('color' refers to stored color info)
	[nfcfgbg] are additional options, you can give one or more:
	n=label, f=fill, c=color border (e.g, color the circle 
	itself, not just the interior),	fg=foreground, bg=background.

      E.g.
	<opt flag="-cc"> all circles in color</opt>
	<opt flag="-cc {v..}"> selected open circles in color</opt>
	<opt flag="-ccf {v..}"> filled circles (color both circle and fill)</opt>
	<opt flag="-cffg {v..}"> filled circles, foreground color</opt>
	<opt flag="-cfbg {v..}"> filled circles, background color</opt>
	<opt flag="-cn {v..}"> open circles, labeled with index</opt>
</options>

<options heading="Specialized Options">

	<opt flag="-d"> this displays the "dual" graph (an edge 
			between the center points of each pair of faces 
			sharing an edge)</opt>
	<opt flag="-D"> this displays the "dual" circles, the inscribed
			circles of the faces</opt> 		
	<opt flag="-ee {v w..}"> extended edges; travel thru up to 16 hex
			vertices from v to w (for hex_refined packs). </opt>
	<opt flag="-gi"> also draw the circles inside the path</opt>
	<opt flag="-nl {v} {st}"> >display string "st" at center of circle v </opt>
	<opt flag="-nz {x y} {st}"> display string "st" at location x+iy</opt>
	<opt flag="-rc"> draw "red" circles using the redfaces data, multiply connected case only.</opt>
	<opt flag="-R {n..}"> display given side-pairings (color coded) in
			the red chain. E.g., "disp -R a" shows all 
			edge-segments, unpaired sides (border segments) 
			are in foreground color</opt>

	<opt flag="-R[o] {n..}"> added option(s): 
				c=draw outer edge circles also
				cn=draw/label circles also
				n=label the sides
				p=draw mated side if side has a matching mate</opt>
	<opt flag="-s {v..}"> closed polygon between centers of listed vertices</opt>
	<opt flag="-sfg {v..}"> </opt>
	<opt flag="-sbg {v..}"> </opt>
	<opt flag="-t* {v..}"> * is a 'trinket': 0=dot (default),1=square,2=triangle,3=plus,4=diamond </opt>
	<opt flag="-tc* {v..}"> ditto, but using circles' colors</opt>
</options>	
     NOTE: Under many options (e.g., c,f,F,cf,e,fn,Ff), no
	indices specified is equivalent to 'all', so -c a and 
	-c have same effect.

     NOTE on the -F option:
	This is like the -f option (and takes the same added
	sub-options), but it will recompute circles as it goes along.
	Suppose "disp -F 3 8 12 2" is the command: it will draw face 3,
	then if face 8 shares an edge with 3 it will use the two circles
	for that edge, but recompute the center of its third circle
	before plotting. Similarly, if 12 shares an edge with 8, its
	third circle will be recomputed. And so forth. 

	A couple of things to note here: 1. Try to pick the first
	face so its circles are mutually tangent; e.g., after "fix",
	start with a face having vertex alpha. 2. In order to
	extend a chain of faces from a former display command,
	repeat its last face as the first in the new list.

     CAUTION: Some objects may be too large to display correctly
	and so may be disregarded or may appear incorrectly. E.g. arcs
	of very large circles.

</command>


<command cmd="double" flags="{b..}">
<description>Doubles a complex across an edge-list of boundary vertices
	or one or more full boundary components. An empty list {b..}
	means to double across all boundary components (producing a
	compact result); otherwise, double across any boundary
	component represented in the list. If {b..} has the form
	'b(u,v)', with u,v on the same boundary component (possibly
	equal), then double across the boundary edges from u to v.
	
	NOTE: The 'vertexMap' of p should contain pairs {o,m}, where 
	o is an original vertex and m gives the name of its double in
	the resulting packing.
</description>
</command>


<command cmd="doyle_annulus" flags="p q n">
<description>Create an annular hex complex whose period is given by a
	closed loop gamma created with p steps along one hex axis 
	followed by q steps along another (the second axis making 
	a left turn by pi/3 from the first). This is followed by 
	adding hex generations to end up with a total of 2n-1 interior 
	copies of gamma. The packing 'vlist' is set to the vertices
	forming the original closed path.
	There are restrictions on (p,q): (0,0), (0,1), (0,2), (1,1) 
	are excluded. (1,2) is excluded temporarily because of some 
	bug that occurs in the combinatorics.

	If you add an ideal vertex to one of the boundary components
	and max_pack, then it appears that with more generations,
	the center of the packing begins to approximate the coherent
	Doyle spiral with related parameters p, q.

	CAUTION: These values of p and q are not always the same ones
	used in defining Doyle spirals (see command "spiral"); e.g., 
	replacing q with q-p is another option. The direction of spiral
	may also be backwards, in which case, use "reorient".

        CAUTION: Adding too many generations can easily lead to radii
	that are so small as to lead to layout errors.
</description>	
</command>

<command cmd="doyle_point" flags="f">
<description>A circle C of radius r, center z whose disc is in the 
	puncture plane has an aspect ratio AR(C)= r/|z|. Any mutually
	tangent triple euclidean circles generates a doyle spiral,
	which is a hexagonal spiral packing which winds around some
	point p in the plane. Given a face f of a euclidean packing,
	this routine computes the point p and the doyle parameters 
	a, b (see "spiral") associated with its circles.
</description>	
</command>


<command cmd="draw_speed" flags="{x}">
<description>	Toggles between two options for how objects are put on screen.
	DEFAULT: show each object as drawn --- this can be very slow for
	big packings, but is often very instructive. 
	ALTERNATIVE: compose canvas in memory and display only when done.
</description>	

<options>
     	<opt flag="f"> fast (i.e. accumulate)</opt>
	<opt flag="s"> slow (i.e. each object)</opt> 
</options>
</command>


<command cmd="elist" flags="[options]">
<description>A utility "edge list" attached to a particular packing; 
	can be read in and stored with packing data. Set with 
	'set_elist'. Can be used whereever a list of edges is 
	called for, e.g., in disp and post calls. 
	NOTE: Elist is the same thing, only it's not attached
	to a packing; it provides a general utility list.

     FORMS: (also apply to Elist)
	elist		produces whole list.
	elist[{i}]	produces the i_th edge in the list, if
			there is one.
	elist[r]	produces the first edge of the list
			and then moves it to the end of the list.
	elist[n] 	produces the "next" edge of the list 
			and then removes it from the list.
</description>
</command>


<command cmd="elist_to_path">
<description>Given an edge-path this resets the active path to follow 
	the edge-path (and close up). If the active pack is 
	spherical, this gives its stereographic projection to 
	the plane.
</description>
</command>


<command cmd="embed" flags="-q{q} a b A B">
<description>Check extent to which active pack can be embedded in pack q, 
	starting by identifying neighbors a and b with A and B in q.
	a and A must be interior vertices and have the same degree.
	The identifications (i.e., a->A, b->B, etc) are (upon some
	success) put in 'vertex_map' for the active pack.
</description>
</command>


<command cmd="encircle" flags="{v..}">
<description>Given a set of vertices, this command attempts to build
	a closed edge-path which encircles them. For example,
	given a closed path, one can mark those inside the path
	with 'mark -cw -c g'. then 'encircle m' will set the
	elist variable of the packing to an edge-path which goes
	(counterclockwise) around the marked vertices. See also
	'path_to_elist', which carries out this precise operation,
	and the reverse operation in 'elist_to_path'.
</description>
</command>


<command cmd="enclose" flags="{-[t] n v..}">
<description>For each boundary circle v of the active pack, add n circles 
as neighbors (or bring total degree to n) and closed up to make v interior.
</description>
<options>
<opt flag="n v.."> add n circles to the flower of each v</opt>
<opt flag="-t n v.."> add enough circles to bring each v to degree n</opt>
</options> 
</command>


<command cmd="erf_ftn" flags="{p1 p2 n}">
<description>Set the boundary radii of packing p2 based on the 
	modulus of the derivative e^{z^n}; n=1 is exponential, 
	n=2 is "error function". There is a domain packing p1 
	and a range p2. Normally the domain is euclidean and 
	univalent; it is copied to p2 and each boundary radius 
	of p2 is set to e^{z^n}*r, where r is its radius, z its 
	center in p1. The calling program them repacks p2 to get
	an analogue of the function F whose derivative is e^{z^n}.

</description>
</command>


<command cmd="eucl_write" flags="{file}">
<description>	The data in the active pack is converted to euclidean (if
	hyperbolic) and the data is stored sequentially in the specified
	file. First, the total node count, then the data in form "x-coord
	y-cood radius".
</description>
</command>

<command cmd="exec" flags="[-n {moniker}] {command}">(NOTE: not yet available in Java version)
<description>Executes a remote process which is hooked to CirclePack via
	pipes; CirclePack continues normal operation while the "child"
	process runs. With -n option can give name to the routine for
	later communications; otherwise, use PID. {command} gives the 
	name of the "child" process and arguments it requires. 
	The child can ask that packs of CirclePack be "locked" to 
	disable commands in CirclePack which might change the data. 
	The lock is indicated by a "padlock" cursor. Locks and other
	effects of child processes should disappear when the child exits
	or dies. 

	See command "msg_remote" for sending commands to running child.

	There are certain protocols for communication:

	-- child sends "lock {n}"; CirclePack responds by locking pack n
		and responding "okaylock {n}", or "nolock".
	-- child sends "unlock {n}"; CirclePack responds by unlocking n
		and responds "unlocked {n}", or "no-unlock".
	-- child, wanting to send pack data to CirclePack, writes "sending";
		CirclePack responds with: "rejected" if pack is locked
		or inappropriate, "failure" is there is some reading
		problem, or "success" if read appears to be okay.
	-- child, wanting to get data from CirclePack, writes "send {n}";
		CirclePack responds with: "failure" if n inappropriate;
		or sends data preceeded by word "sending". If write
		fails, send the word "failure".
	-- child sends "done" when its ready to exit, but waits for
		word "bye" from CirclePack.
	-- child sends commands for CirclePack to execute by preceeding
		them with line containing "command:\n".
	-- child sends messages or error messages to appear in CirclePack's
		message window by preceeding them with "msg:" or "emsg:". 

	NOTE: If a child is giving problems, execute "ps" from the console 
	window to find the child process pid and use "kill" to terminate 
	it; CirclePack itself should be unaffected. Several remote processes
	may be run at the same time.
</description>
</command>


<command cmd="exit">
<description>Close 'CirclePack'. If the script has changed, there is 
an opportunity to save it first.
</description>
</command>	


<command cmd="extender" flags=" -[x] {type}">
<description>'PackExtenders' are Java classes which extend storage and
	functionality for packings. They are recognized via two-letter
	appreviations, as with 'cf' for 'CurvatureFlow'. The commands
	preceeded by "|cf| " will be passed to the extender for
	processing. One of the standard extender commands is 'help',
	which should show a list of the available commands.
</description>	
<options>
   	<opt flag="-x"> {type} close the specified type of extender if the packing has one active.</opt>
	<opt flag="F1 - F10 keyboard 'function' keys"> The user can specify global default actions in '.packrc'
	which are attached to these keys; when the key is pressed, 
	the actions are applied to the pack for the canvas containing 
	the mouse. The action can consist of one line of semi-colon
	separated commands.</opt>
</options>
<examples> 
	<instance text = "Here's what you put in '.packrc'."> F1_KEY: repack;fix;disp -w -c</instance>
</examples>
</command>


<command cmd="face_err" flags="x {f..}">
<description>	Given a threshold x>1.0, this reports the number of faces
	from the given list whose layout's have errors (interpreted
	as [dist between circles)/(intended dist between circles])
	lying outside the interval [1/x,x].
</description>	
</command>

<command cmd="fexec" flags="[-s] {filename}">
<description>Reads and executes commands in {filename}. Can be used as
	method of transferring data from remote routines. 
</description>	

<options>
	<opt flag="-s"> read from open script</opt>
</options>
</command>
	     

<command cmd="f_index" flags="{f j ..}">
<description>Data is a string of pairs: a face index and j = 0, 1, or 2.
	Command tells face f which of its neighbors is first when
	this f is to be drawn. This is to ensure that correct pair
	of neighbors are used when computing the center of the third
	neighbor.
</description>
</command>


<command cmd="f_next" flags="{f g ..}">
<description>Data is a string of face index pairs. Command tells face f 
	that face g is next in drawing order. When f=0, g is set as 
	the first face and gets drawn at the origin. (Default is the 
	alpha vertex.) The last face drawn MUST point to the first
	face in the drawing order.
</description>
</command>

<command cmd="f_red" flags="{f i..}">
<description>	Technical. Sets rwb_flag of faces.
</description>
</command>


<command cmd="f_rnext" flags="{f g..}">
<description>	Technical. Sets next_face index of faces.
</description>
</command>


<command cmd="fix" flags="[options]">
<description>Update data for the active pack. Generally "fix" is needed after
	"repack", since repack changes radii but doesn't compute new
	centers.
</description>
<options> (one of)
	<opt flag="-a"> set "aims" to their defaults</opt>
	<opt flag="-c[cdfs]"> recompute pack centers.
		added options (allow no spaces between):

		c {x}: set decimal number 'x' as threshold for 
		   placement accuracy; e.g., x=.00001 for 5-decimal places.
		d: create /tmp/layout.log diagnostic file for layout
		   errors
		f: plot only circles with placement errors less
		   than assigned threshold, set plot_flag appropriately
		   (like -l option below)
		s: use single face for each new circle (ie straight
		   from drawing-order) (Note: default is now to find
		   center by averaging computations from all available
		   plotted neighbors.</opt>
		
	<opt flag="-d [v]"> comp centers using draw order; report positions of v</opt>
	<opt flag="-e {e..}"> redo drawingorder with given edgelist as desired outer
 boundary. (These edges are declared as 'poison' before
 the drawing order is computed; also see 'set_poison' for
 poison vertices.)</opt>
	<opt flag="-f {f..}"> redo drawingorder with given facelist as a
		   (putative) red chain; the outside edges of the faces
		    are used to set poison edges.</opt>
	<opt flag="-F"> redo everything</opt>
	<opt flag="-K"> update combinatorics, redo drawingorder</opt>
	<opt flag="-l"> verify consistency of plotted centers for circles
		  and faces, set corresponding flags appropriately.</opt>
	<opt flag="-r {f..}"> recompute centers along given chain of faces</opt>
	<opt flag="-s"> recompute angle sums</opt>
	<opt flag="-t"> compute centers from 'tailored' drawing order; marked 
		  vertices will not (to extent possible) be used in drawing 
		  order.</opt>
	<opt flag="-T"> same as -t, but routine will NOT use the marked vertices; 
		it will stop once it has done all it can without them.</opt>	
	<opt flag="default"> recompute angle sums and centers.</opt>

     DETAILS:
	The -cf option sets flags for circles and faces which affects
	whether they are shown in display and postscript operations and
	whether they are used for later placements in the layout process.
	(fix -cc {value} lets you set the threshold for this.)
	For instance, if the radii are not correct, some circles 
	cannot	be placed consistently with all the mandated 
	neighbor relationships; these will not have their flags
	set and will not be drawn in display operations. Similarly,
	if the three circles of a face cannot be placed in a
	proper relationship, then the face will not be drawn in
	display operations. CAUTION: fix -cf is probably not 
	appropriate for nonsimply connected complexes, since 
	placement always leaves some faces incompatibly with neighbors.
	Doing 'fix' without the -l flag will allow display regardless 
	of proper placement.
</options>
</command>


<command cmd="Fix"> 
<description>This does all the updates of "fix". If there are unexplained
	problems cropping up, "Fix" is good thing to try; but remember
	that it resets "aims".
</description>
</command>

<command cmd="flat_hex" flags="{v..}">
<description>Specialized command for flattening jagged edge of eucl hex
	packing by introducing special overlaps. Each v must be
	a boundary vert with 3 neighbors. Introduces 2*pi/3 overlap
	with interior neighbor and pi/3 overlap with each bdry
	neighbor. Results in a flat edge (angle sum pi) at v if
	radii of v and neighbors are all identical.
</description>
</command>

<command cmd="flip" flags="{v w..}">
<description>An interior edge bounds two faces. This command 'flips' 
	the edge; that is, the edge {v w} is removed and a new 
	one created connecting the two common neighbors of v and w.
	This is called a "Whitehead" move.
</description>
<options>
	<opt flag="-cc"> flip counterclockwise edge to each edge in the list (until a flip fails)</opt>
	<opt flag="-cw"> flip clockwise edge to each edge in the list (until a flip fails)</opt>
	<opt flag="-r"> flip one random edge from random interior vertex.
	       (ignore rest of the input string.)</opt>
</options>
</command>

<command cmd="flip_priority" flags="[options]">
<description>This is a specialized routine for putting edges of a
	closed complex in some priority order for consideration
	of flipping them --- aim being to make complex more
	hexagonal. The list is put in the packings 'elist'
	and info is provided on the top few of the list.
</description>
<option>
	<opt flag="1"> lowest degree, then largest avg of contiguous
		  neighbor radii.</opt>
	<opt flag="2"> lowest degree, then largest avg of contiguous
		  neighbor degree.</opt>
</option>
</command>

<command cmd="flist" flags="[options]">
<description>A utility "face list" attached to a particular packing; 
	can be read in and stored with packing data. Set with 
	'set_flist'. Can be used whereever a list of faces is 
	called for, e.g., in disp and post calls. 
	NOTE: Flist is the same thing, only it's not attached
	to a packing; it provides a general utility list.
</description>
<options special="Forms"> (also apply to Flist)
	<opt flag="flist"> produces whole list.</opt>
	<opt flag="flist[{i}]"> produces the i_th face in the list, if there is one.</opt>
	<opt flag="flist[r]"> produces the first face of the list and then moves it to the end of the list.</opt>
	<opt flag="flist[n]"> produces the "next" face of the list and then removes it from the list.</opt>
</options>
</command>

<command cmd="focus" flags="[options] {v}">
<description>Set canvas view to be centered on specified vertex v
	(or xy-coords). For spherical packings, xy is the 
	projection to the screen of the apparent sphere. 
	Defaults to using the center of the active vertex.
</description>

<options>
	<opt flag="-v {v}"> specify a vertex and use it's center.</opt>
	<opt flag="-vs {x} {v}"> also set screen size to 2*x*rad(v). (You can 'zoom' into specified vert.)</opt>
	<opt flag="-z {x y}"> use (x,y) coords</opt>
</options>
</command>

<command cmd="for n:m" flags="{commands}">
<description>Repeat the given command string starting with integer n 
	and ending with integer m. At most 50 iterations are
	allowed; the return value is the number of iterations
	completed. Execution ends on any error. 
	CAUTION: the 'for' command must be the last in any 
	command string: all	remaining commands are taken as part of
	the string subject to iteration.
</description>	
</command>

<command cmd="gamma" flags="{v}">
<description>The "gamma" circle is normalized to be on the positive imaginary
	axis when centers are computed. (This seems most helpful when
	visualizing complexes with mirror symmetry.)
</description>
</command>


<command cmd="gen_cut" flags="{v} {n}">
<description>Cut out the sub-complex of circles of generation at most
n from vertex v. The original complex must be simply connected and
	n must be at least 2; v itself is counted as generation 1. 
	The result is simply connected because the program fills in 
	any "inclusions" of higher generation circles surrounded 
	by those of generation n. 
</description>
</command>


<command cmd="gen_islands" flags="{v..}">
<description>Remove indicated vertices, plug each hole with single
	       circle.
</description>
</command>


<command cmd="gen_mark" flags="[option] {v}">
<description>Set vertex or face with marks according to generations 
	(combinatorial distances) from the list {v} of vertices; 
	if {v} is not given, then use the singleton set {alpha}.
	The '-f' flag to do faces must be first option; it will 
	cause vertices to be marked with their generations.
</description>
<options>
	<opt flag="-f"> (must be first) mark generations of faces: a face is
		generation n if its vertices are all generation n or
		all .le. (n+1).</opt>
	<opt flag="-m n"> mark vertices only up to generation n.</opt>
</options>
</command>


<command cmd="geom_to_[eh]" flags="[option]">
<description>The active pack is converted to indicated geometry: s=spherical,
	e=euclidean, h=hyperbolic. Change to hyperbolic may require scaling 
	to fit properly in the unit disc. (See also "project" for moving
	from hyperbolic to spherical, adding an ideal circle, and
	normalizing.)
</description>
<options>
	<opt flag="-l"> means to reestablish current numerical values of radii 
		after conversion, even though the geometry has changed.</opt>
</options>
</command>

<command cmd="get_data" flags="-q{q} [-t] {flag} {v..}">
<description>Specified, perhaps multiple, types of data for a single list 
	of vertices (or faces) of the active pack is copied from 
	pack q to the active packing. If the -t flag is set and the 
	active packing has a 'vertex_map', then the data for vertices 
	v (or faces f defined by triples of vertices) in the active 
	pack is replaced by that of (legal) image vertices w (or faces)
	in pack q. The flags for the type(s) of data to get are given 
	below; several may be specified, but there is a single list
	of vertices or faces
	E.g. "get_data -q2 -t -z -r a" will get (translated) centers
	and radii from q for all vertices of the active pack.
	Note: some data that transfers may be inappropriate: e.g.
	moving hyperbolic radii to a spherical packing. Minimal
	checking is carried out.

	The -v and -V flags behave differently: these serve to
	transfer or 'compose' vertex maps (or their inverses).
	These are useful as "maps" or "correspondences" between
	the vertex sets of packings. They use the "a" 
	specification for 'all' vertices.
	
	Consider "get_data -q2 -v {v..}". This will transfer 
	entries of the form (v,w) in the vertex map of p2 to 
	(v,w) (when v is legal) in the vertex map of p for 
	the given list {v..}. (Notes: (1) the original vertex 
	map for p will be lost. (2) this will typically be 
	of use only when p shares the complex of p2.) 
	(3) 'put_data' goes other way around, moving the 
	vertex map of p to p2. (4) the usual expectation 
	(not always enforced) is that when (v,w) is an edge 
	of the vertex map of p, then v is a legal vertex 
	for p; on the other hand, w could well refer to some 
	other packing.
	
	The -t in conjunction with -v and -V gives 
	compositions; Consider, e.g., "get_data -q2 -t -v" 
	and assume p2 has a vertex map as well. This command 
	uses (v,w) in the vertex map of p to translate v 
	into w, then looks for (w,u) in the vertex map of p2; 
	if it finds a pair (it takes the first), it adds (v,u) 
	to the new vertex map for p. Thus, if the vertex maps
	for p and p2 represented maps p --> p2 and p2 --> q, resp.,
	then the result is the composition, p --> q. (Likewise,
	"put_data -q2 -t -v", results in a new vertex map for p2
	representing the composition p2 --> p --> q. 
	
	The -V flag is slightly different (and assumes -t). Say 
	the vertex map for p represents a map p --> r and that 
	for p2 a map p2 --> r. Then	"get_data -q2 -V" gives p 
	the vertex map for p --> r --> q, while 
	"put_data -q2 -t -V" gives p2 the vertex map for 
	q --> r --> p. A caveat: the maps may not have full 
	range or domain and results can be non-unique or 
	ambiguous.

     FLAGS: specifying various types of data:
	-r = radii
   	-z = centers
	-a = aims
   	-s = angle sums
   	-c = circle colors
   	-m = vertex 'mark'
   	-f = face colors
   	-fm = face marks
   	-o = inversive distances (for edges)
	-v or -V = vertex_map (see above) 
</description>
</command>


<command cmd="get_xyz" flags="[options]">
<description>For packings with stored 3D (xyz) vertex locations, this
	command allows the user to set various packing data from
	that 3D information. This will expand as more functionality
	is required.
</description>
<options>
	<opt flag="-b"> set boundary radius to the average of 3D-lengths of 
		its two edges (euclidean packing only).</opt>
	<opt flag="-l"> find min/max/ratio of 3D edge lengths.</opt>
</options>
</command>


<command cmd="h_dist" flags="z.re z.re w.re w.im">
<description>Returns the hyperbolic distance between two points of the
	disc. Gives 0 if points are essentially identical; negative
	means one or both points are on or outside the ideal
	boundary (and absolute value of this is the euclidean 
	distance between them).
</description>
</command>

<command cmd="h_g_bar">
<description>Experiments with harmonic functions of form f=h+conj(g).
	Uses packings for h and g in p0 and p1, resp., puts 
	results in p2. The result will have centers reflecting the
	values of the discrete harmonic function, and the result
	can be see by displaying the faces.
</description>
</command>


<command cmd="hex_refine">
<description>This is an edge refinement method which leads to proliferation 
	of hex vertices. It modifies q by adding a barycenter to each 
	edge, breaking each triangle into four and yielding barycenter 
	degree six (on interior edges). The old vertex labels are 
	unchanged and an attempt is made to set estimated new radii/centers 
	from the old ones (both for old and for new vertices). On a
	closed complex, hex_refine precisely doubles the number of vertices.
</description>
</command>


<command cmd="hex_slide" flags="{v..}">
<description>Suppose {v..} is a closed list of vertices which 
determines a simple 
	closed edge-path, all vertices interior and all of degree 6 (to be
	made more general in the future), then this command will "slide"
	the right side of this edge-path forward one edge. It is equivalent
	to splitting the complex along this edge-path, then identifying
	along the path, but with a shift of one edge.
</description>
</command>	
	

<command cmd="hh_path" flags="[options] {e}">
<description>This creates a "half-hex" edgepath and, on success, stores it as
	the active packing's 'elist'. Construction starts with edge e and
	extends depending on the stop options given below and the
	active packing's combinatorics. "Half-hex" means that at each
	vertex v along the edgepath (except the first and last) there are 
	2 edges	to the LEFT of the edgepath as you pass through v. 
	(Terminology: a "hex" edgepath would have 2 to the left AND 2 to the 
	right. This has just two to the left (note the asymmetry).)
	
	The typical use of an half-hex path is to do a sequence of edge 
	flips along its right side; namely, for edge e in the edgepath, the
	clockwise edge ee must be "flipable" (see 'flip'). Additions 
	to the edgepath will stop when this fails, when certain other 
	combinatoric conditions are encountered, or under some other stop 
	conditions options as given below.
	
	The effect of flipping along a path is to shift the vertices to
	the right sides one click back.
</description>	
<options> (default to -b -S -x)
	<opt flag="-a"> append to given edgepath (i.e., {e} is a list {e..})</opt> 
	<opt flag="-b"> stop when the next edge would lie in the boundary</opt>
	<opt flag="-c"> continue as long as possible --- no stop options</opt>
	<opt flag="-N"> {n} add at most n edges (counting e) </opt>
	<opt flag="-S"> stop when edge runs into AND lines up with the original 
		   edge e. (If this flag is set, it overrides -x flag only
		   in this instance.)</opt>
	<opt flag="-x"> stop when encountering vertex already hit by the path</opt>
</options>
<examples>
	<instance text="flip -h elist[n]"> will flip the clockwise edge
	from the next edge in 'elist', if flippable. </instance>
</examples>
</command>


<command cmd="holonomy_trace" flags="{f..} [[-fas] {filename}]">
<description>Given a closed chain of faces (starting/ending with
the same face), this routine finds and computes the tr^2 (trace 
square) of the	Mobius transformation which matches two corners
of the first face in its initial location to the corresponding 
corners of that face in its final position, that is, after the
chain is laid out successively. It sets the current Mobius
transformation. Optional file indicates that the trace and
transformation should be put saved in (or appended to, or put
in script under) "filename".
NOTE: not yet operational in spherical geometry.
</description>
</command>

<command cmd="infile_cmds" flags="{name}">
<description>This reads a stream of lines in the current "script" file; 
	each is taken as a command line (but with no "[]:=" is used).
	These lines can be anywhere in the file, but must immediately 
	follow "name", lines bracketted by CMDS at beginning and END
	at end. This command is mainly for scripts, but can be given 
	on the command-line.
</description>
</command>

<command cmd="infile_path" flags="{name}">
<description>This reads a set of path data in the current "script" file. The
	data can be anywhere, but must immediately follow "name", begin
	with PATH, and end with END. This command is mainly for scripts, 
	but can be given on the command-line.
</description>
</command>
	
<command cmd="infile_read" flags="{name}">
<description>This reads a set of packing data in the current "script" file.
	The data can be anywhere, but must immediately follow "name",
	begin with NODECOUNT, and end with END. This command is for
	scripts, but can be given on command-line.
</description>
</command>

<command cmd="j_ftn" flags="{n0 n1 maxsize}">
<description>This is a very specialized command. It's aim is to build
	the complexes associated with the classical "j-function"
	of function theory (related to the modular function) and
	others with similar structure. These functions are complete
	unlimited branched coverings of the Riemann sphere, 
	punctured at infinity, so that every point over 0 (resp. 1)
	has branch order n0 (resp. n1). These are actually infinite
	complexes, so maxsize puts a cap on the construction. The
	resulting packing (which overwrites the prescribed packing)
	is hyperbolic and the boundary radii are set to infinity.
	
	The classical j-function itself would have n0=2 and n1=1,
	but other values can be specified.
</description>
</command>


<command cmd="layout">
<description>This recomputes the centers of the active pack in euclidean,
	hyperbolic, or spherical geometry, as appropriate. The "alpha" 
	circle is placed at the origin and the "gamma" circle is rotated to be
	on the positive imaginary axis. Note: If the radii have not been
	adjusted to meet the packing condition, then the configuration may
	not be cohesive -- neighbors not contiguous, isolated circles,
	etc. In fact, locations will be dependent on the "drawingorder" 
	which has been chosen for the circles. (Replaces deprecated 'fix')
</description>
</command>

<command cmd="legal" flags="[options] [{e..}]">
<description>A interior edge in a euclidean triangulation is "illegal" 
	by the Delaunay criterion when a circle containing the three 
	vertices of the face on one side encloses the face on the 
	other. (For plane graphs, there is a "Delaunay" triangulation, 
	which is one having no illegal edges.)

 	This command lists "illegal" edges in the utility list 
	'Elist' (previous contents discarded) based on various 
	optional criteria, including Delaunay, and imposes various 
	possible orders on Elist; if list {e..} is specified, it 
	only looks through these edges, otherwise through all 
	interior edges. 
</description>
<options> 
	<opt flag="-c {c}"> Threshhold criterion for inclusion in list: 
		  i    Delaunay criterion (default), 
		  a    look at all edge</opt>
	<opt flag="-f {c}"> What order (default=unspecified)
		  r    by largest ratio of endpoint radii
		  i    most negative imaginary part
		  h {t}  by distance from "hex" ideal (which is
		       -1/2 + sqrt(3)/2 i = -0.5 + i 0.866025),
		       with threshold t>0.</opt>

</options>
<examples>
	<instance text="legal -c i -f i"> will give Elist of interior edges
	illegal by Delaunay criterion (imaginary part .lt. 0) and will 
	order them by most negative imaginary part. </instance>
	<instance text="legal -c a -f h .1"> will list those with d=[(x-ratio)-(hex_ratio)} greater than 0.1 from the
	largest value of d.</instance>
</examples>
</command>

<command cmd="load_pack">
<description>
        Brings up a FileChooser dialog to load and display a
        packing from a file.
</description>
</command>


<command cmd="locate" flags="-[cf] {x y}">
<description> Display labels for circles/faces containing point (x,y). 
</description>
<options> (must have one and only one option)
	<opt flag="-c"> display labels for circles</opt>
	<opt flag="-f"> display labels for faces</opt>
</options>
</command>


<command cmd="Map" flags="[ox] [p q [options]]">
<description> This command is associated with the "Mapping Window",
which displays two packings side-by-side, as in a mapping situation;
by convention, the left is called "domain", the right, "range". Options
-o and -x open and close the Mapping Window (and vice verse for the 
Active Canvas. With the default cursor, the user can click on a 
circle (left mouse button) or face (middle) in one of these packing
and the corresponding object is displayed as filled in both packings.
	
</description>
<options>
	<opt flag="-o"> open Map windows in Java with packs p and q</opt>
	<opt flag="-x"> close Map windows</opt>
	<opt flag="p q -c {v..}"> show circles (default)</opt>
	<opt flag="p q -f {f..}"> show faces</opt>
</options>
</command>
	

<command cmd="map" flags="[options] {v..}">
<description>This translates circle (or face) indices according to the 
	packing's 'vertex_map' (if there is one), storing the 
	resulting list in Vlist (or Flist). By default, index v of 
	the active packing is translated to image index w (as 
	specified in the vertex_map). If the '-r' flag is set,
	this is reversed: w --> v.

	Face numbers depend on packing layout, so translated face 
	indices might be meaningless without some target pack q in 
	mind; the -q option lets the user specify q. (See VERTEX_MAP 
	in data file descriptions.)
</description>

<options> 
	<opt flag="-r"> translate via inverse of vertex_map</opt>
	<opt flag="-v"> circles (the default) (or -c)</opt>
	<opt flag="-f"> faces</opt>
	<opt flag="-t{q}"> vis-a-vis pack number q.</opt>
</options>

<examples> 
	<instance text="map a(1,10)"> This will store the translated indices of circles 1-10 of 
	  the active pack in Vlist.</instance>
	
	<instance text="map -p1 -f -q2 b"> This will store the bdry face indices of p1 into Flist, but
	  will translate them to face indices of pack q (as far as 
	  this is possible).</instance>
</examples>
</command>

<command cmd="mark" flags="[options]">
<description>Circles or faces of a packing may be "marked" for later reference.
	Example: If circles 3, 5, 12 are marked,
	then command "disp -cf m" will display those three filled circles.
	Circles and faces can also be marked with the l-mouse or m-mouse,
	respectively: you must simply hold down the 'shift' key while you
	press the mouse button on the desired circle or face. 
</description>
<options> 
	<opt flag="-w"> clear all marks on all faces and circles</opt>
	<opt flag="-c {v..}"> mark circles</opt>
	<opt flag="-co"> mark each vertex with its position in the current drawing order</opt>
	<opt flag="-cw {v..}"> clear marks of designated circles</opt>
	<opt flag="-f {f..}"> mark faces</opt>
	<opt flag="-fw {f..}"> clear marks of designated faces</opt>
	<opt flag="-g [v]"> mark circles with their generation from v 
		(default: from alpha); v is treated as 
		generation 1. (See gen_mark if you want to 
		replace v by a set of vertices.)</opt>
</options>
</command>

<command cmd="match" flags="-q{q} v w {V W}">
<description>Apply an appropriate Mobius transformation to the active 
	pack to put vertices v and w of active pack in register 
	(as closely as possible) with V and W, resp, of pack q. 
	If V and W are not specified, then use the vertex_map of
	the active pack to find the vertices of q corresponding
	to v and w. Active pack and q must both be hyperbolic
	or euclidean.
</description>
</command>

	
<command cmd="max_pack" flags="[-r{v}] [k]">
<description>Carry out the operations needed to move the packing to its
	"intrinsic" geometry (the one where it's maximal packing
	will live), reset its aims to default, repack, and layout. 
	Note that you have to issue separate commands to display the 
	results.

	Hyperbolic case (most common): Boundary radii are set to 
	5.0 (which is essentially infinity) because setting them
	to infinity (i.e., to any negative value) often results in
	layout errors due to sensitivity of horocycle layouts.

	Euclidean case: This only occurs when the packing's complex
	triangulates a 1-torus.

	Spherical case: Puncture, push down to the hyperbolic 
	setting, repack, layout, then project back to the sphere. 
	The user can specify the puncture (default being the largest 
	index circle); the original indexing is restored after the 
	packing operations. The standard normalization puts the 3D
	centroid of the centers at the origin; alternately, one can
	use 'NSpole' and its options.
	(NOTE: If the packing computation is not completed (e.g., 
	iterations 'cycles' is set too low), then projecting back 
	to sphere largely invalidates the computations and one must
	start over. It is recommended in these cases that puncturing, 
	projection, repacking, layout, projecting back, etc. be 
	carried out separately so the repacking is known to complete.)

	NOTE: Historically, max packings were computing by computing
	the labels first, using Thurston's iterative algorithm, then
	calling 'layout' to compute the centers. (See 'repack'.)
	However, Gerald Orick has developed a routine, and this may
	be called automatically depending on circumstances: 
	In particular, if the C++ library 'HeavyC_lib' is link and
	if the packing is large enough, the Orick's 'CPI' routines
	will be called. These compute radii	and centers simultaneously. 
	Due to use of sparse matrix calls, these routines are very, very 
	fast, and although the radii are not as accurate (as was 
	necessary when they were to	be used in 'layout'), the centers 
	are much better --- avoiding breakups that could occur in large
	packing 'layout's.	
</description>	
<options> 
     <opt flag="-r {v}"> Spherical case, traditional packing method only: 
     		this specifies the vertex to be punctured (and 
     		temporarily adjusts 'alpha' to be a non-neighbor, 
     		if necessary).</opt>
</options>
</command>
     		
<command cmd="mend" flags="{data}">
<description>Routine to fix small gaps/holes in packing layouts. These
	seem to develop from accumulated roundoff error. The idea here 
	is to identify the approximate "center" of such a flaw in p,
	grab the subpacking q of circles within some "radius" of that, 
	pack q on its own using the boundary radii inherited from p,
	put this packing of q in approximate register with p, then 
	"blend" q into p. This last step involves a weighted average
	of radii/centers of circles of q and the corresponding circles
	of p, with the weighting entirely on p on the boundary of q
	but then shifting weight to info in q for about 1/4 of the
	generations into q, at which point the data of q takes over
	entirely. In spherical case, piece is projected to euclidean
	setting to do the packing and registration, then fragment is 
	brought back to the sphere.
	Lot's of things to test and fix in this routine; eg. want to 
	make it automatic: find/mend problems on its own.
	(NOTE: this mend process might actually work in more general
	circumstances to make up for flaws or even inaccuracies in a 
	packing.)
</description>
<data> 
	<opt flag="D v {n} r {r}"> all circles within distance r of </opt>
	<opt flag="D c {x y} r {r}"> center of circle n (or of point (x,y)) </opt>
	<opt flag="l {n}"> number of generations to overlap in the blend
		operation. Default is about 1/4 of the maximal
		number of generations in the mend region complex.</opt>
</data>
</command>

<command cmd="migrate" flags="v w">
<description>This operation is designed for migrating branch points. 
	A branch point is often created geometrically by slitting 
	and pasting two copies of a packing, the tip of the slit 
	becoming the branch circle. This command does a local 
	combinatorial modification mimicking the effect of having
	advanced that slit along one additional edge. So it 
	'migrates' a simple branch point at v to a simple branch 
	point at neighbor w. There are combintoric restrictions:
	* v must have even degree, at least 6
	* w and the neighbor ww opposite across v must have the
	  same degree.
	* v, w, and ww must be interior
	After the migration, the index of the new branch point is
	reset to v as a convenience for further migrations.  
</description>
</command>

<command cmd="Mobius" flags="[s] {v..} (or Mobius_inv [s] {v..})">
<description>Applies the current Mobius transform (or its inverse) to the 
	indicated vertices of the active pack. 
</description>
<options>
	<opt flag="-s"> The transformation is one of the 'side-pairing'
		transformations for this packing. (With this flag,
		the mobius transform will not be applied to the 
		side-pairing transformations, since that would only
		permute them. This flag is used, eg., when the user 
		applies one of the side-pairings from the 'Mobius' 
		panel of the GUI.)</opt>
</options>
<seealso>
<see>pair_mob</see>
</seealso>
</command>

<command cmd="mode_change" flags="{toolname}">
<description>This is mainly for use in scripts: a script
can define active "mode" tools which can be activated (see 
the "Active Cursor" menu) on canvasses. If such a tool
is labeled, then "mode_change {toolname}" will activate
that mode on the active canvas. "mode_change" with no
toolname will activate the default mode on the active
canvas.
</description>
</command>
 		
<command cmd="molify_centers" flags="[option] {v..}">
<description>This routine goes through a packing via its drawing order
	(or through the specified list) and adjusts centers to their 
	average locations based on pairs of plotted neighbors. 
	-i flag indicates n passes through the vertices, treating 
	all as plotted, adjusting centers (except that of alpha) to 
	their average locations as computed over all pairs of 
	contiguous neighbors.

	NOTE: the hope is that these adjustments will help fix
	flaws in the plotting of large packings due to roundoff
	error.
</description>
<options>
	<opt flag="-i n"> n iterative passes through circles via drawing order or specified list.</opt>
</options>
</command>


<command cmd="msg" flags="{msg}">
<description>The message "msg" is sent to the "Messages/Errors" window.  This
	       is useful when running a prepared "script".
</description>
</command>

<command cmd="msg_remote" flags="{pid or moniker} {msg}">
<description>The message "msg" and a line feed are sent to the remote
	process with the give pid (process identification code)
	or the "moniker" it was assigned in the "exec" command
	which started it.
     ALIASES: "m_r" and "mr"
</description>
</command>


<command cmd="nan" flags="{filename}">
<description>Check the active packing to see if any radii, centers, 
	or angle sums are improper; e.g., nan (not-a-number), 
	infinite, illegal in the packing's geometry, etc. 
	Lists of offending vertices are stored in the file 
	/tmp/{filename}_{pid}.txt (default filename is nan.)
</description>
</command>

<command cmd="NSpole" flags="[{N S {E} [t]} (or -a N {E} [t])]">
<description>Spherical geometry only: for normalization. With no
	arguments, default to "centroid" normalization: apply 
	a Mobius transformation so that the centroid of the
	centers in 3-space is at the origin. (still has bugs)
	
	Otherwise, centers of vertices N and S are
	placed at north/south poles, resp. If optional vert E is 
	specified, it ends up centered at 1. Otherwise, using -t 
	flag one can specify a scalar x for dilation; x=1 (default)
	makes circles at the poles have the same spherical radius;
	x>1 would apply a Mobius that dilates and for x.lt.1, one 
	that shrinks. (Note: the north pole corresponds to the origin, 
	the south pole to infinity in the euclidean plane.)
	Optionally, 'NSpole -a N' finds S as the combinatorially 
	antipodal point (furthest from N), then proceeds as before.
</description>

<options>
	<opt flag="-t x"> dilation factor. E takes precedence; x defaults to 1 if E option is absent or if x.le.0.</opt>
	<opt flag="-a N"> Use N as north and find the antipodal point as south</opt>
</options>
</command>


<command cmd="norm_scale" flags="[options]">
<description>
	Normalize a euclidean packing.
	-a x    scale so total euclidean area is x.
	-c v r	scale so vert v gets radius r
	-e q v w  scale so vert v has radius of vert w in pack q
	-u v	scale so eucl center of vert v is on unit circle
	-h v w  rotate so vector w-v is horizontal (left to right)
	-i v    scale/rotate to put vertex v at z=i (asuming v is
		not centered at the origin)
</description>
</command>

<command cmd="outlist"> 
<description>If the packing has a 'redchain' of faces (mainly in multiply
	connected settings), this finds the chain of edges on the
	outside (right-hand side) of the redfaces. The result is
	stored as the packings 'elist' (note: old elist will be lost).
	Generally used in conjunction with 'red_from_elist', which
	converts from the elist to a new redchain. This is a mechanism
	for preventing the wholesale readjustments due to layout that
	occur when redfaces are computed automatically after changes
	in combintorics, such as edge flips or slits.
</description>
</command>
	
<command cmd="output" flags="[format] [-af] {filename}">
<description>To write miscellaneous formated output to files. Filename MUST
	be the last string. If preceeded by '-f', then save to named file,
	if by '-a', then append (if {filename} exists). CAUTION: do not allow 
	character ';' to appear in the text format.

	'format' section structured as follows:

	     {prefix text} :: {datatypes} :: {list} :: {suffix text}

	(MUST have three :: separators, even if only space between.)

	'prefix' and 'suffix' are put at beginning and end of output.

	The {datatypes} (separated by spaces) are one or more of: 
	   - literal strings in " ".
	   - for vertices: VI = circle index, VF = vertex flower, VZ = circle center,
	     VXYZ= circle center XYZ coords,
	     VA = angle sum, VT = angle target, VD = degree,
	     VM = vertex map, VR = radius, VC = color,
	     VSpq = sharp ftn (pack p to q), Varg = arg(center).
	   - for faces: FI = face index, (FZ = corner locations),
	     FC = face color, (FA = face area), FV = face vertices.
	   - for edges: EV = vertices, (EC = color), (EL = actual length), (ER = intended length)
	        (some of these are not yet implemented)
	   - general: Mob = current mobius transformation,
	     tr = trace^2 (complex) for current mobius,
	     Path = current path of x,y coords,
	     #N = nodecount, #F = facecount, 

	The {list} is our usual way of specifying lists of vertices,
	faces, or edges. (Must agree with datatype being requested.)

	control codes: In quoted strings normal control codes work, \n
	for linefeed, \t for tag, "" for single quote, \\ for single \.

     EXAMPLE:
	This command 
	   output %centers\nC=[ :: VZ "\n" :: b :: ] -f dummy.txt
	will create a matlab file with 2 x n matrix C of centers for boundary
	vertices.
</description>	
</command>

<command cmd="Paginate" flags="{filename}">
<description>This renumbers the "Pages" of a postscript file (if there
	are any); needed because pages are created on the fly, so
	they can't be numbered until after the fact.
</description>
</command>

<command cmd="pair_mob" flags="[-1] {n..}">
<description>Multiply-connected complexes are drawn using a computed "red
	chain", a closed list of faces which defines a simply connected 
	fundamental domain for the complex. This involves cuts, so
	certain edge-segments of the red chain are "paired" with 
	other edge-segments. The identified ends determine a mobius
	transformation (in the eucl and hyp settings); these can
	be viewed, with color coding, via the command "disp -R {n..}".
	pair_mob applies this transformation to the packing. For
	example, "pair_mob 5" will apply a Mobius transform which
	pastes a copy of the fundamental region to the edge whose
	initial point is labelled "5".
</description>
<options>
	<opt flag="-1"> indicates the inverse transform (edge-pairing in opposite direction).</opt>
</options>
</command>

<command cmd="path_construct" flags="[options] v1 {v..}">
<description>This is a rather specialized command to construct sequences
	of vertices defining edge paths using alternate descriptions.
	Both options require initial vertex v1, then construct
	sequence of vertices defining additional edges; the resulting
	list is put in Vlist.
</description>
<options> (one of)
	<opt flag="-m"> (default) This is for multi-sheeted packings, where circles
		aren't easily 'picked' with the mouse because they overlap. 
		Feed the sequence of successive possibilities via the list
		{v..}; the routine picks off vertex numbers which 
		extend the existing edge path in Vlist, throwing out those 
		which don't fit.</opt>

	<opt flag="-i"> This describes a path in terms of "turns" in 
		combinatoric direction. First in the list {v..} must
		be a neighbor of v1, then succession of increments.
		E.g., "path_c -i 23 57 2 -4 0 3 -3" will start with edge 
		{23,57}, then {57,x}, where in the flower for 57, 	
		{57,x} is "2" edges counterclockwise from {57,23}, 
		then "4" edges clockwise from {x,57}, then "0" (back up), 
		and so forth. Stop on encountering any illegal increment.
		In a hex packing, "path_c -i 23 57 3 3 3 ..." defines 
		a combinatorially straight path.</opt>
</options>
</command>

<command cmd="path_Mobius">
<description>Applies the current Mobius transformation to the current
	path (if there is one).
</description>
</command>

<command cmd="path_to_elist">
<description>Attempts to find a closed edge-path which approximates the
	current path. See 'elist_to_path' and 'enclose' also.
</description>
</command>


<command cmd="pdata">
<description>	Update various information on the packing.
</description>
</command>

<command cmd="post" flags="[options]">
<description>
A postscript custom output file (default name set in "Config" window) 
	may be opened and specified objects from the active pack may be
	written to it using this command with one or more of the options 
	given below. Note that the information goes into a file and is 
	not printed until requested. Note: when using the mouse actions 
	to prepare this file, you may "pin" the "PostScript Printing" 
	menu so it remains visible while you work. (See the "print" 
	command for direct printing of the pack using its current 
	display mode.)

	NOTE: When the pack has been laid out using 'fix -l', plot 
	flags are set only for circles/faces which seem properly placed 
	(i.e., consistently with neighbors) and only those are drawn in
	the display. 
</description>
<options special="File Management Options">
       (Note: 'name' is optional, default is "Custom print file" 
       in "Config" window. If necessary, custom file is opened 
	(backup {name}+%) or created and initialized.

	<opt flag="-o [name]"> open file - PREVIOUS CONTENTS DISCARDED;</opt>
	<opt flag="-oi [name]">  "str"  begin inserting in custom file at location after first occurance of {str} (or default to end);</opt>
	<opt flag="-oa [name]"> begin appending (as NEW PAGE) to end of custom file;</opt>
	<opt flag="-x"> close the "Custom print file"</opt>
	<opt flag="-xjpg"> close and convert to *.jpg format (75 quality)</opt>
	<opt flag="-xgif"> close and convert to *.gif format</opt>
	<opt flag="...g"> final 'g' on any of above three commands means to launch "ghostview" of the *.ps file</opt>
	<opt flag="-xl"> close and print the "Custom print file" (print command is specified in "Preferences")</opt>
</options>

<options special="Common Options">
	<opt flag="-c {v..}"> open circles</opt>
	<opt flag="-f {f..}"> open faces</opt>
	<opt flag="-e {v w..}"> edges</opt>
	<opt flag="-l {n}"> set linewidth, 0.le.n.le.15, integer multiples of unit linewidth (default=brush size)</opt>
	<opt flag="-nc {v..}"> label circles</opt>
	<opt flag="-nf {f..}"> label faces</opt>
	<opt flag="-C {v..}"> all circles, recomp'd by drawing order </opt>
	<opt flag="-F {f..}"> ``chained'' faces (see below)</opt>
	<opt flag="-B {v..}"> all faces and circles, recomp'd by drawing order</opt>
	<opt flag="-g"> display the current "path", if available.</opt>
	<opt flag="-u"> draw unit circle</opt>
	<opt flag="-T {text}"> text (at most 60 characters) to appear at 
bottom of postscript file.</opt>       
</options>
	
<options special="Extended Options">
	('color' refers to stored color info)
	[nfcfgbg] are additional options, you can give one or more:
	n=label, f=fill, c=color border (e.g, color the circle 
	itself, not just the interior),	fg=foreground, bg=background.

      E.g.
	<opt flag="-cc"> all circles in color</opt>
	<opt flag="-cc {v..}"> selected open circles in color</opt>
	<opt flag="-ccf {v..}"> filled circles (color both circle and fill)</opt>
	<opt flag="-cffg {v..}"> filled circles, foreground color</opt>
	<opt flag="-cfbg {v..}"> filled circles, background color</opt>
	<opt flag="-cn {v..}"> open circles, labeled with index</opt>
</options>
<options special="Specialized Options">

	<opt flag="-d"> this displays the "dual" graph (an edge 
			between the center points of each pair of faces 
			sharing an edge)</opt>
	<opt flag="-D"> this displays the "dual" circles, the inscribed
			circles of the faces</opt> 		
	<opt flag="-ee {v w..}"> extended edges; travel thru up to 16 hex
		      vertices from v to w (for hex_refined packs). </opt>
	<opt flag="-gi"> also draw the circles inside the path</opt>
	<opt flag="-nl {v} {st}"> display string "st" at center of circle v </opt>
	<opt flag="-nz {x y} {st}"> display string "st" at location x+iy</opt>
	<opt flag="-rc"> draw "red" circles using the redfaces data,
			multiply connected case only.</opt>
	<opt flag="-R {n..}"> display given edge-pairing (color coded) in
			the red chain. E.g., "disp -R a" shows all 
			edge-segments, unpaired ones (border segments) 
			are in foreground color</opt>
	<opt flag="-R[o] {n..}"> added options: 
			 c=draw/label circles also
			 n=label the edges
			 p=draw mated pair for each edge</opt>
	<opt flag="-s {v..}"> closed polygon between centers of listed vertices</opt>
	<opt flag="-t {v..}"> display a 'dot' at given centers</opt>
	<opt flag="-tc {v..}"> ditto, but using circles' colors</opt>
	<opt flag="-t? {v..}"> 	Other 'trinkets' in place of dots: 0=dot,1=square,2=triangle,3=plus,4=diamond</opt>
	<opt flag="-t?c {v..}"> ditto, but using circles' colors</opt>
	<opt flag="-T"></opt>
</options>
</command>


<command cmd="pre_cookie">
<description>
	Command 'cookie' cuts out part of a packing based on
	'poison' vertices or edges. It does this by building a
	"red chain" (linked list) of faces defining the core
	to be cut out. This command builds that list and puts
	it in 'flist' so that it can be viewed. (It is recomputed
	if and when 'cookie' is called.)
</description>
</command>
	
<command cmd="print">
<description>The active screen is sent to a PostScript file (named in the
	"Config" window) and then to the printer (using a print command in
	the "Config" window. (NOTE: currently, this just displays the
	output in ghostview, which gives the user the option to print.)

	NOTE: The output depends on the display mode of the canvas, not 
	necessarily on what is currently showing on the computer screen. 
	See the "post" command for more selective printed output.
</description>
</command>

<command cmd="project" flags="[options]">
<description>For simply connected packings in the hyperbolic plane having 
	boundary circles that are horocycles. This command projects the
	packing to the sphere, normalizes (see options), and adds the
	circle for a new ideal boundary vertex.
</description>
<options> (in order of priority)
	<opt flag="-e {v}"> Put vertex v at the point 1.</opt>
	<opt flag="-m"> Choose a vertex to put at the point 1 by picking one a greatest distance from alpha and the boundary.</opt>
	<opt flag="-t {r}"> Normalize so ratio rad(alpha)/rad(S) = r where S is the south pole and these are spherical radii.</opt>
	<opt flag="default"> to -t 1.</opt>
</options>
</command>


<command cmd="puncture" flags="{v}">
<description>Remove an interior vertex v from a complex. Must have two generations
	of neighbors which are also interior; each neighbor must have at least
	5 faces. Any edge data is discarded.
</description>
</command>

<command cmd="put_data" flags="-q{q} [-t] {flag} {v..}">
<description>See "get_data". The same comments apply here, only the data is
	moved FROM the active pack TO pack q. The -t flag means to 
	translate using the vertex_map of the active packing, if it has
	one. (The -v and -V options of get_data do not apply here).

   FlAGS: each {flag} is a single letter specifying a type of data:
	-r = radii
   	-z = centers
	-a = aims
   	-s = angle sums
   	-c = circle colors
   	-m = vertex 'mark'
   	-f = face colors


pwd
	Give the current working directory. Can then use "cd"
	to change it.
</description>
</command>

<command cmd="qc_dil" flags="-q{q} {f..}">
<description>Compute the maximal quasiconformal dilatation between 
	faces of the active packing and another, q, for the 
	given faces. Both must have the same underlying 
	complex, and (currently) both must be euclidean. 
	(See "color" options for coloring faces based on 
	dilatation.)
</description>
</command>

<command cmd="quit">
<description>
	This exits CirclePack; no confirmation requested, all data is lost.
</description>
</command>


<command cmd="random_pack" flags="[options] N">
<description>Instance of 'random_triangulation' below, region being the unit disc.
	The only available option is '-d' for debugging. If N is missing, 
	defaults to N=200.
</description>
</command>

<command cmd="rand_pt_read" flags="filename">
<description>Read a file giving random points. Beginning with key word
UNIT_SQUARE:, the points are xy pairs in [0,1]x[0,1], and their
converted to [0,2pi]x[-pi,pi] to be used on the sphere. A delaunay
triangulation is computed and put in the active packing.
</description>
</command>

<command cmd="random_triangulation" flags="[options]">
<description>Creates a random triangulation. For a region with boundary
	(see options), points are randomly distributed first on the 
	boundary, then on the interior using a poisson point process. 
	Finally, Shewchuk's 'triangle' program computes a CDT (constrained 
	(because it contains boundary edges) Delaunay triangulation). 
	Default radii are assigned, but packing manipulations are left 
	to the user.
</description>
<options>
	<opt flag="-N {n}"> Average number of random interior points (actually number
		   depends on the point process.)</opt>
	<opt flag="-T {x y}"> Randomly triangulate a 1-torus with modulus Tau=x+iy.</opt>
	<opt flag="-g"> Randomly triangulat the interior of a path; default is current path.</opt>
	<opt flag="-g[s] {filename}"> path read from a file (if '-gs', then in the script). </opt>
	<opt flag="-A  {a}"> Randomly triangulate a rectangle of aspect a>0. The four corner vertices, 
			     counterclockwise from upper left, are 1, 2, 3, and 4.</opt>
	<opt flag="-S {n}"> Random triangulation of the sphere (using 'Qhull').</opt>
	<opt flag="-u"> Random triangulation of the unit disc.</opt>
	<opt flag="-d"> debug mode: set seed to (long)1 for reproducability</opt>
	<opt flag="-h {h}"> geometry. Not currently used: in future, if h>0, then
               we want a triangulation of a sphere.</opt>
	NOTE: '-T' takes precedence over '-g' and '-g' over '-A'.
</options>
</command>				   

<command cmd="read" flags="{filename}">
<description>This loads the designated file into the active pack. The
	current default directory name is prepended to the filename. 
	The packing may have been saved in gzip form, so if 'filename' 
	is not found, then there is attempt to read 'filename.gz' instead.

    CAUTION:  No confirmation is requested for command-line arguments,
	so original data in active pack will be lost.
	
	SEE ALSO: see 'delaunay' for reading packings of the sphere as
	lists of triangles.
</description>
</command>


<command cmd="Read" flags="{filename}">
<description>
	Same as "read", except directory path is explicitly given.
</description>
</command>


<command cmd="read_color" flags="[options] {filename}">
<description>Read a colortable from {filename}. Behavior of this command
	depends on whether you're running CirclePack in graphics
	or standalone version.
</description>
<options>
	<opt flag="-n"> {name} designate a name for the color file</opt>
	<opt flag="-l"> (in standalone mode) read the colors locally 
		and send them to the GUI. (Default behavior
		is that the GUI reads the color table and
		uses it for this packing.)</opt>
	<opt flag="-s"> set local colors; in CirclePack these will
		not change the screen colors, but will change
		the colors in postscript output.</opt>
</options>
</command>
	

<command cmd="read_path" flags="{filename}">
<description>A "path" refers to a list (length at least 3) of pairs x y of real
	coordinates specifying a polygonal path. This command reads a path
	from the specified file (with default directory name prepended) into 
	the program's current "path". A path is always closed up when read in.
</description>
</command>
		

<command cmd="Read_path" flags="{filename}">
<description>
	Same as "read_path", except directory path is explicitly given.
</description>
</command>

<command cmd="reorient">
<description>
	This flips the orientation of the active pack; useful, e.g., in
	pasting together surfaces, as done in doubling across a part of
	boundary.
</description>
</command>


<command cmd="rect_orient" flags="{v w}">
<description>
	For euclidean packings only this rotates the packing about the
	origin so that the line from the center of v to the center of w
	is horizontal, pointing left to right. It's useful to orient
	rectangular packings by specifying the left v and right w
	corners of the lower edge to make it horizontal.
</description>
</command>

<command cmd="red_from_elist">
<description>
	Uses 'elist' to create a 'redfaces' chain for the packing,
	with the elist as the edgelist on the outside of the red chain.
	Generally used in conjunction with 'outlist', which goes the
	opposite direction; see notes there.
</description>
</command>


<command cmd="refresh">
<description>
	Have Java repaint the packings.
</description>
</command>	

<command cmd="repack" flags="[options] [k]">
<description>
	This computes radii based on assigned 'aim's. Computations are
	based on Thurston's algorithm; approximate radii by an 
	iterative process. The implementation depends on circumstances.
	The algorithm can be used only in eucl/hyp settings; there is
	no algorithm known directly in spherical geometry, so spherical
	packings are obtained by stereographic projection (e.g., see 'proj').
	Note that to get a packing requires an additional 'layout' call
	after 'repack'.
	
	The computational cycles for this call can be set with 
	the '-k' option (k from 1 to 100,000), or defaults to that 
	set via 'set_cycle'.
</description>

<options> (one of)
	<opt flag="-v {v..}"> repack only specified circles </opt>
	<opt flag="-o">  repack using "old-reliable", but slower, routines. (default if there are nontrivial inversive distances)
			 (Note: options not currently active:</opt>
	<opt flag="-n"> repack using "superstep" routines (even in presence of nontrivial inv distances)</opt>
	<opt flag="-t"> repack using latest experimental routines</opt>
</options>		

	NOTE: There is currently no way to interrupt a repack computation
	(nor is it always easy to tell that one is going on), so moderate
	values of "cycle", e.g. 500, are recommended. 
</command>

<command cmd="RiemHilber" flags="[OPTIONS] ('RH' pack extension)">
<description>
	This creates a persistent 'pack extension' class 'RH'
	which attaches to this packing and handles "Riemann
	Hilbert" experiments. Commands can be directed to this 
	class with prefix '|RH| '. Details elsewhere
</description>

<options>
	<opt flag="-o {name}"> Create a new Riemann-Hilbert class. If 'name' is given, it is read as a packing (if '.p'), as a file of curves (if '.g'), or 		is used as a base in looking for both .p and .g files.</opt>
	<opt flag="-os {name}"> Same only look in the script for the files</opt>
	<opt flag="-x"> Close the ReimHilbert pack extension; the packing itself should remain in tact.</opt>
</options>
</command>


<command cmd="rm_cir" flags="{v..} [-x x y]">
<description>
	Given a list of vertices (or -x flag with xy-coords), this 
	removes any which quality, adjusting the combinatorics 
	appropriately. Qualifying vertices are boundary and trivalent 
	interiors; other conditions are checked so that the remaining 
	complex is legal.
</description>
</command>


<command cmd="rm_edge" flags="[option] {v w..}">
<description>
	This removes one or more edges from the active pack. In 
	the default call, each edge must be a boundary edge and 
	its end vertices will both remain in the packing. 
	
	With the -c "collapse" flag, the edges can be interior 
	or boundary; each edge {v,u} "collapses", that is, the
	ends v, u are fused into one vertex (the lesser of v and 
	u becomes its index) and its flower is a combination of the 
	flowers of v and u. 
	
	NOTE: an edge will not be removed if that would	disconnect the 
	interior or cause some boundary circle to have no interior 
	neighbor.  
	
	NOTE: "overlap angle" information is outdated by this action, 
	and thus is	discarded.
</description>	
<options>
	<opt flag="-c"> collapse edge, interior or bdry</opt>
</options>
</command>


<command cmd="rm_quad" flags="{v w}">
<description>
	This command removes an interior vertex v of degree 4. 
	The resultant quadrangular interstice is broken into two 
	triangles by inserting the edge from w to the opposite vertex.
</description>
</command>


<command cmd="rotate" flags="{a}">
<description>	The active pack (hyp or eucl) is rotated counterclockwise about 
	the origin by a*PI radians.
</description>
</command>


<command cmd="scale" flags="[t]">
<description>
	The active pack is scaled by the map z -> t*z, where t is a
	positive real. Default for t is "eucl incr" as set in the "Config"
	window.  NOTE: In the hyperbolic case, a circle will remain
	unchanged if the scaling would put it outside the unit disc, so
	the pattern will not look right.
</description>
</command>

<command cmd="scale_aims x" flags="{v..}">
<description>
	Reset aims of vertices in list based on their current angle 
	sum, aim, and specified factor x. If aim is positive,
	    aim(v)=angle sum(v) + x*[aim(v)-angle sum(v)].
	(Also see set_aim.)
</description>
</command>


<command cmd="scale_rad" flags="-q{p} x {v..}">
<description>
	Reset radii of vertices in list based on their current radii
	in the active packing, their radii in packing p, and the 
	scale factor x. The current packing and p must be the same 
	size and geometry. Radii in p are reset so
	    rad_p(v)=rad_p(v) + x*[rad_q(v)-rad_p(v)].
	Infinite hyperbolic radii treated as radius 10.0.
</description>	
</command>

<command cmd="screendump" flags="[-mp]">
<description>
	Saves a screen dump of the active packing. See tab 'ScreenShots'
	where thumbnails and their names are displayed.
</description>	
<options>
	<opt flag="-mp"> This dumps the side-by-side canvasses of "Map" frame (not working right, 7/08)  </opt>
</options>
</command>

<command cmd="script" flags="[filename]">
<description>
	This opens the "Script" window and loads the named script. In that
	window's panel are buttons (using left-mouse) to execute and
	select commands, reset to the beginning of the file, or close the
	window. To load, edit, save the files, there is a standard Text
	Editor menu attached to right-mouse when in the edit window.
	Pressing "Execute next command" will carry out the next command
	line starting after the current cursor location. Each command line
	begins with '[*]:=' and ends with a linefeed.  The file may also
	contain pack and path data: see "infile_read" and "infile_path"
	for formating details. CAUTION: execution of script commands can
	modify data already in the packs. CAUTION: Loading a script file
	can inadvertently change the working directory of CirclePack
	itself.
</description>
</command>

<command cmd="seed" flags="[-q] [n]">
<description>
	This replaces the active pack by a single "flower" consisting of a
	central circle and n (>=3) "petals".  The canvas is automatically
	displayed unless flag -q is specified. Default is n=6.  
	CAUTION: No confirmation is requested for command-line arguments, 
	so original data in active pack will be lost.
</description>
</command>

<command cmd="set_accur" flags="{x}">
<description>
	Set the accuracy with which packing computations are done.
	It sets both "toler" and "error", ensuring that the latter is
	smaller. Original setting is x=0.0000001, and highest
	setting allowed is x=0.0000000000000001. Higher settings
	will slow computations.
</description>
</command>

<command cmd="set_active" flags="{v}">
<description>
	Make v the active vertex of the pack -- the vertex that some
	actions apply to when no other vertex is indicated. The active
	vertex can also be set by clicking left mouse on it in the 
	active canvas.
</description>
</command>

<command cmd="set_aim" flags="[options or {a v..}]">
<description>
	The "aim" of a vertex (circle) is the angle sum which it's circle
	attempts to achieve during "repack" computations.  This command
	sets aim to the value a (which must contain a decimal point) times
	PI for the specified circles.  NOTE: A negative aim indicates that
	the radius is not to be adjusted during repacking. Aims of zero
	are allowed in the hyperbolic setting for bdry circles only --
	correspond to horocycles. (Also see scale_aims.)
</description>

<options> (one of)
	<opt flag="-d {v..}"> set to default: 2(*PI),interior; -1, bdry</opt>
	<opt flag="-c {v..}"> set aims to current angle sums</opt>
	<opt flag="-% x {v..}"> add real number x(*PI) to currently set aim </opt>
</options>
</command>


<command cmd="set_brush" flags="{k}">
<description>
	The thickness of lines for display and for PostScript output can
	be set to integer k, 1.le.k.le.15. 
</description>
</command>

<command cmd="set_center" flags="[{x y}] -[m] {v..}">
<description>
	Given {x,y}, set the real and imaginary parts of centers of 
	the given vertices. With the -m (mapping) flag, the current
	center z of the circle for v is replaced by the image of z
	under the current function.
</description>
<options>
	<opt flag="-m"> Transform the current center according to the
	function 'Function Frame' </opt>
</options>	  
<seealso>
<see>set_ftn_text</see>
</seealso>
</command>


<command cmd="set_custom" flags="{name}">
<description>
	Sets custom PostScript file for the active packing; default
	is 'CP_custom.ps'.
</description>
</command>


<command cmd="set_cycle" flags="{n}">
<description>
	Set the default number of iterative angle adjustments to be made
	when "repack" is called. This, the "tolerance", and the geometry
	determine how long it takes to carry out the repack computations.
	The number of cycles used is displayed as a message after each
	repack call.  NOTE: There is currently no way to interrupt a
	repack computation (nor is it always easy to tell that one is
	going on), so moderate values of "cycle", e.g. 5000, are
	recommended.
</description>
</command>


<command cmd="set_dir" flags="{dir_name}">
<description>
	Set the directory from which packings are read/written; typically
	this is 'packings/'. This is typically set by java. 
</description>
</command>


<command cmd="set_disp_flags" flags="{n} {m}"> // deprecated
<description>
	Flags that set the default behavior for display of a packing's
	circles and faces. In each case, the settings are bit encoded 
	in an integer:
		1: display object
		2: filled
		8: boundary color (instead of foreground)
		16: fill in recorded color
		32: with label
</description>
</command>
		
<command cmd="set_disp_str flags"> 
<description>
	Sets the string for the 'DisplayPanel' of this packing and checks
	the checkbox for its use. Unaccompanied commands 'disp', 'disp -wr'
	use this string. 
</description>
</command>

<command cmd="set_elist" flags="{e..}">
<description>
	Store edges in "elist" of active pack. Previous contents
	discarded. NOTE: Currently no check that pairs are actually
	endpoints of edge.
</description>
</command>


<command cmd="set_Elist" flags="{e..}">
<description>
	Same as above, only stores indices in utility "Elist".
	(Validity check against active pack.)
</description>
</command>


<command cmd="set_fill_opacity" flags="{t}">
<description>
	Opacity for 'filling' operations determines brightness/transparency
	of the colors.	t should be in [0,256), the larger the opacity, 
	the brighter the color; default is 125, semitransparent.
</description>
</command>


<command cmd="set_flist" flags="{f..}">
<description>
	Store faces in "flist" of active pack. Previous contents
	discarded. Can also build flist from the canvas: pressing 
	'v' when in any canvas toggles a "list sensitivity" switch.
	When on, clicking the middle button on the canvas adds any
	face containing the cursor to the end of the associated 
	pack's flist.
</description>
</command>


<command cmd="set_Flist" flags="{f..}">
<description>
	Same as above, only stores face indices in utility "Flist".
	(Validity check against active pack.)
</description>
</command>


<command cmd="set_function_text" flags="{text}">
<description>
	CirclePack can store a complex function description in
	the "Function" frame using a complex variable; e.g.,
	1+sin(3*arg(z)), where 'z' (use of this letter is required) 
	specifies a complex variable. This function can then be
	used in various calls in CirclePack or 'PackExtender's.
</description>
<seealso>
<see>set_center -m {v..}</see>
</seealso>
</command>

<command cmd="set_grid" flags="-[cr] -[n]">
<description>
	This sets a global vector of paths represented in
	barycentric coordinates associated with the active packing.
	(Currently, only euclidean packings can be used.)
	Current options allow a grid of spokes and circles for
	the unit circle or a rectangular grid with given corners;
	the number of grid lines is set with a flag, the default
	being 8. The barycentrically coordinated paths may be drawn
	on any packing, though for indexing purposes, this typically
	has the same complex as the packing used to create the grid.
</description>
<options>
	<opt flag="-c"> spoke/circle grid in unit disc.</opt>
	<opt flag="-r [llx lly urx ury]"> rectangular grid, lower
	left corner (llx, lly), upper right corner (urx, ury).
	Default (-1,-1), (1,1).</opt>
	<opt flag="-n"> number of grid lines in each direction.</opt>
</options>
</command>	
    
<command cmd="set_Mobius" flags="{a.re a.im b.re b.im c.re c.im d.re d.im flip}">
<description>
	CirclePack maintains a current Mobius transformation. It defaults
	to the identity, but can be set to any other, whether orientation
	preserving (flip=0) or orientation reversing (flip=1). You read
	in 8 real numbers, real and imaginary parts for the standard four
	complex entries a, b, c, and d, plus an integer 'flip' for 
	orientation (flip is optional, default is 0). 
</description>
<examples>
	<instance text="set_Mobius 0.0 0.0 1.0 0.0 0.0 0.0 1.0 0.0"> specifies reciprocation, z maps to 1/z</instance>
	<instance text="set_Mobius 2.0 0.0 0.0 0.0 1.0 0.0 0.0 0.0"> specifies z maps to 2*z</instance>
	<instance text="set_Mobius 1.0 0.0 0.0 -0.5 0.0 0.5 1.0 0.0"> specifies the disc automorphism (z-i/2)/(z*i/2+1)</instance>  
</examples>
</command>

<command cmd="set_over" flags="[option] {{a} (v w)..}">
<description>
	An "overlap angle" between neighboring circles is the prescribed
	exterior angle they are intended to make where they intersect and
	is limited to [0, PI/2], 0 corresponding to tangency. We also
	allow separated circles with specified "inversive distance".
	The inversive distance must be in [0,infty): In [0,1], this
	is cos(theta), where theta is overlap angle and in [1,infty)
	it is cosh(rho) where rho is the hyerbolic distance (in 3-ball) 
	between the geodesic planes defined by the circles. Here's how
	one specifies a: if it is preceeded by a "*", take it as an
	inversive distance and it must be non-negative; otherwise, it must be
	in [0,0.5] and is multiplied by PI to give the angle. 
	NOTE: that inversive distances and overlap angles
	are independent of the geometry used for the pack.
</description>
<options>
	<opt flag="-d"> set to default, 0 (tangent condition).</opt>
	<opt flag="-c"> set to current values.</opt>
	<opt flag="-t  {x}"> truncate inv_distances at upper value x (x>1.0)</opt>
	<opt flag="-x"> use xyz data, setting based on min of all edgelengths, as though each radius was 1/2 the length of shortest edge.</opt>
	<opt flag="-x {name}"> read in xyz data from this file, then use it </opt> 
	<opt flag="-x -s {name}"> from this file in the current script</opt>
	<opt flag="-h"> use xyz data, setting each overlap based on local edgelengths as though each radius was 1/2 the length of 
			the shortest edge from that vertex.</opt>
	<opt flag="deprecated: -f  {v..}"> set for edges from v; use incidence 'Iv' to get edges</opt>
</options>
<examples>
	<instance text="set_over .3333 5 10"> If {5 10} is an edge, then its overlap 
	angle is set to Pi/3</instance>
	<instance text="set_over *.3333 a"> The inversive distances for all edges are set 
	to acos(.3333)</instance>
	<instance text="set_over *1.25 i"> The inversive distance for all interior 
	edges are set to 1.25</instance>
</examples>
</command>


<command cmd="set_pix_box" flags="lx ly rx ry">
<description>	Resets the pixel box size in lower/upper corner form (integers).
</description>
</command>


<command cmd="set_plot_flags" flags="{flag} {v..}">
<description>
	Vertices have plot flags which indicate whether the circle should
	be drawn in drawing operations -- generally these are set in
	"fix -l" calls and the circles which aren't reliably placed
	have plot_flag=0. However, there may be times when the user 
	wants to set this. Typically call with flag=0 or flag=1 and
	the usual list specifying the vertex indices.
</description>
</command>

<command cmd="set_poison" flags="{v..}">
<description>
	Subcomplexes are cut out from the active packing by using
	'poison' vertices. Eg, by setting a collection V of vertices
	to poison, selecting a 'seed' vert w which is interior and
	not in V, and running 'cookie', one can cut out the
	largest connected complex containing w and stopping at V.
</description>
</command>


<command cmd="set_post_size" flags="{k}">
<description>
	The PostScript output is set to k x k inches, 1.le.k.le.7.  NOTE:
	PostScript output can always be messaged directly after being
	recorded in a file, e.g., using "ghostview". 
	(See "Config" window for names of PostScript files containing the 
	image data.)
</description>
</command>	


<command cmd="set_ps_viewer" flags="{cmd}">
<description>
	The sets the system command to call up the a postscript viewer,
	typically "ghostview", which pops up to show the user a postscript
	file. The user specifies this in his/her ".cpprefrc" file.
</description>
</command>

<command cmd="set_ps" flags="{name}">
<description>
	Sets the screen postscript file (see "Config" window).
</description>
</command>


<command cmd="set_rad" flags="[options] [{r v..}]">
<description>
	Typically without options, setting radius r (which must have 
	a decimal point) for specified vertices of the active pack. Negative 
	r in the hyperbolic setting means radius is infinite (a horocycle).  
	NOTE: In hyperbolic geometry, the euclidean sizes of circles depends on
	their hyperbolic radii and also on their hyperbolic centers; so
	circles may appear to change in size, say when repacking, without
	actually doing so.
</description>
<options>
	<opt flag="-q{p}"> Use along with pack number p according to suboptions:</opt>
	<opt flag="-M"> Use max of active pack and pack p radii</opt>
	<opt flag="-m"> Use min of active pack and pack p radii</opt>
	<opt flag="-a"> Use average of active pack and pack p radii</opt>
</options>
</command>
     
<command cmd="set_ratio" flags="p0 p1">
<description>
	This sets the boundary radii of pack p1 so that the euclidean
	ratio function takes specified values. In particular, the center of
	a boundary circle in p0 is plugged into the function in the
	"Function" window of the java interface. The result is multiplied
	by the euclidean radius of the circle in p0 to set the euclidean
	radius in p1. Packing p0 must be euclidean or hyperbolic, p1
	must be euclidean. Normally, the domain is a maximal packing.
</description>
</command>

<command cmd="set_random" flags="[options] {v..}">
<description>
	Set/modify radii (default) or overlaps using pseudo-random 
	numbers. You may specify the range of the random value generated 
	or the range of a random factor by which the current value 
	will be multiplied. (In the case of the sphere, radii 
	never exceed pi.)
</description>
<options>
	<opt flag="-o"> adjust overlaps instead of radii (must be first option) </opt>
	<opt flag="-r {l h}"> specify range, low to high </opt>
	<opt flag="-f"> means the random quantity will be used as a multiplicative factor for the current value</opt>
	<opt flag="-j {x}"> "jiggle" radii, i.e., adjust by random percentage
	  	   chosen from Gaussian with mean 0, standard deviation of
	  	   x (at most 10) percent. This may help distribute round-off error.</opt>
</options>
<examples>
	<instance text="set_random -r .5 1.2 -f b"> will multiply each boundary radius by a factor uniformly distributed between .5 and 1.2.</instance>
	<instance text="set_random i"> will randomly set all interior radii to random values between (about) 0.005 and 5.0 (the default range).</instance>
	<instance text="set_rand -o -r .1 10 a"> sets overlaps between .1 (overlap)and 10 (inversive distance).</instance>  
</examples>
</command>


<command cmd="set_screen" flags="[options]">
<description>
	This sets the screen center and width (always equal to height)
for a canvas 
</description>
<options> (one of)
	<opt flag="-a"> show all circles by expanding about current center; eucl packings only.</opt>
	<opt flag="-b lx ly ux uy"> set real world canvas box, lowerleft/upperright</opt>
	<opt flag="-d"> set to default size</opt>
	<opt flag="-h {x}"> sets the height </opt>
	<opt flag="-i {dx, dy}"> translate by increment</opt>
	<opt flag="-f {x}"> multiplies height by x > 0. Note: width is 
	determined from height by proportions of the canvas window.</opt>
	<opt flag="-v {v}"> at coords of vertex v</opt>
	<opt flag="-z {x y}"> sets the coords of the point to be centered</opt>
	<opt flag="-c {x y}"> (deprecated version of 'z')</opt>
</options>
</command>


<command cmd="set_sphere view" flags="[options] {a b c} (abbrev: set_sv)">
<description>
	Each canvas has a view it uses for spherical packings. The
	coords used on the sphere are the usual spherical (t,p),
	where t is "theta", measured from positive x-axis, and 
	p is "phi" measured down from north pole. A matrix is stored
	which transforms graphical operations so that the currently
	chosen view is displayed. This command allows you to set or
	change that matrix by giving ratations a*pi,b*pi,c*pi about the
	x,y,z-axes, respectively; note that rotations are applied
	in order z, then y, then x. The default view is the standard
	one, namely, with a slight tilt of the z-axis towards the 
	viewer and a slight rotation of the x-axis to the left. 
</description>

<options> (one of, optional)
	<opt flag="-d"> set to default.</opt>
	<opt flag="-i"> increment current view by additional rotations.</opt>
	<opt flag="-t {m00, m01, .., m22}"> set transformation directly using 3x3 matrix entries. (It is assumed that this is an orthogonal matrix.)</opt>
</options>

<examples> 
	<instance text="set_sphere_view 0.0 0.0 0.0"> will put z-axis vertical, x-axis directly towards the viewer.</instance>
	<instance text="set_sphere_view -i .5 0.0 .5"> will add a rotation by pi/2 about the z-axis, followed by pi/2 about the (new) x-axis,
		   to the current matrix.</instance>
</examples>
</command>


<command cmd="set_sph_opacity" flags="{t}">
<description>
	Opacity determines whether objects on the sphere show 
	through from the back. t should be in [0,256), the larger 
	the less transparency. Default is an opaque sphere, nothing
	shows through.
</description>
</command>


<command cmd="set_sph_pts" flags="{n}">
<description>
	Use n points when drawing arcs/circles/geodesics on the
	sphere. Default is 40. Set higher for final output, lower 
	for draft-quality. Low values save much display time, 
	output space.
</description>
</command>


<command cmd="set_toler" flags="{x}">
<description>
	This determines the accuracy to which repacking computations 
	are carried out. Large packings can accumulate enough error 
	that they do not display correctly; a smaller tolerance will
	generally correct that, at the expense of longer repack delays.
</description>
</command>


<command cmd="set_vlist" flags="{v..}">
<description>
	Store vertices in "vlist" of active pack. Previous contents
	discarded. Can also build vlist from the canvas: pressing 
	'v' when in any canvas toggles a "list sensitivity" switch.
	When on, clicking the left button on the canvas adds any
	circle containing the cursor to the end of the associated
	pack's vlist.
</description>
</command>


<command cmd="set_Vlist" flags="{v..}">
<description>
	Same as above, only stores indices in utility "Vlist".
	(Validity check against active pack.)
</description>
</command>
	

<command cmd="set_xyz">
<description>
	A packing can store a 3D location (x,y,z) for each of its
	vertices. These may be read in, for instance, when the 
	combinatorics originate from a geometric triangular mesh,
	and may subsequently be written to a file with the -x flag 
	of 'write'. The command 'set_xyz' stores the 3D locations 
	of the circle centers; for hyperbolic and euclidean	packings, 
	the points lie in the x,y plane. (More options for this 
	call may be added in the future perhaps.)
</description>
</command>


<command cmd="show_vlist (or 'show_flist' or 'show_elist')">
<description>
	(Standalone only) Returns a string containing the list of
	faces, vertices, or edges currently stored by the packing.
	(See set_vlist, etc.) There is a maximum size put on the
	returned string.
</description>
</command>


<command cmd="show_red">
<description>
	The "red chain" of faces for a complex is the counterclockwise
	list of boundary faces in the simply connected case (empty for
	a triangulation of the sphere) or a counterclockwise list of
	faces defining a fundamental domain in the case of multiply
	connected complexes. It is computed automatically or may be
	provided by a separate routine, as with DesPack.
	This command sends the chain indices to stderr.
</description>
</command>

<command cmd="skeleton" flags="{v..}">
<description>
	Replace the current packing by the packing for a subcomplex
	consisting of the specified vertices and all their immediate 
	neighbors; the new packing inherits the radii and aims (and
	eventually inv distances) of the parent.
	WARNING: This may not be a legitimate complex because of
	combinatorial problems.
	The intended use is to find the subcomplex consisting of
	all vertices along the original edges of a hex-refined 
	complex for use with parallel packing routines.
</description>
</command>


<command cmd="slit" flags="{v..}">
<description>
	Slit a complex open along a string of vertices. The first vertex
	may be boundary or interior, thereafter, must be interior. If the
	first is interior, slit must have at least two edges. This routine 
	has not been tested thoroughly and may damage the complex -- 
	e.g. if	the path crosses itself or essentially disconnects the 
	complex.
</description>
</command>


<command cmd="special{n}" flags="[options]">
<description>
	Special routines where intended to make it easier to write new
	routines without recompiling the whole of CirclePack.  Their code
	is in the file "cp_special.c". The routines there now are
	explained elsewhere. Note that the command is typed as, e.g.,
	"special1" with no space after the word 'special'. Appropriate
	[options] may also be needed, depending on the routine.
</description>
</command>


<command cmd="spiral" flags="[-f] {a b}">
<description>
	"Doyle" spirals are special hexagonal patterns generated with a
	simple procedure. The packing must have hexagonal combinatorics.
	"spiral" sets the (euclidean) radius of the alpha vertex to 1, 
	sets the radii of two contiguous neighbors to a and b, then 
	propogates the rest of the radii using this rule: in each pair 
	of contiguous faces, the product of the radii of the vertices 
	they share is equal to the product of the remaining two radii.
	Some interesting values of a and b are given below. (These spiral
	patterns where first noted by Peter Doyle; for more details, see
	work of Beardon, Dubejko, and Stephenson in Geometria Dedicata.)
	(See also "doyle_annulus".)
</description>

<options> 
	<opt flag="-f"> 
		use a and b as multiplicative factors for modifying 
		the ratio between the radii of the two contiguous 
		neighbors of alpha vis-a-vis vertex alpha itself.
		The radius of vertex alpha is reset to 1, and these
		new ratios set the radii of these two neighbors.</opt>
</options>

<examples text="
	Generate several generations of hexagonal combinatorics,
	using, e.g., the commands 'seed -q;geom_to_e;add_gen 6 6;'
	and then applying 'spiral {a b}' for some of these pairs a b.
	Modify the a and/or b slightly to see de-coherence.
	Note: the p and q have (generically) to do with steps in the hex 
	pattern; check that a^p divided by b^q is approximately 1.">

	<instance text="spiral 1 9.9"> p=q=3</instance>
	<instance text="spiral 1 4.61"> p=q=4</instance>
	<instance text="spiral 1 3.2205"> p=q=5</instance>
	<instance text="spiral 1 2.59"> p=q=6</instance>
	<instance text="spiral 1 2.2365"> p=q=7</instance> 
	<instance text="spiral 1 2.01"> p=q=8</instance>
	<instance text="spiral 4.82374 1.87652"> p=2, q=8</instance>
	<instance text="spiral 3.45903 1.51236"> p=2, q=10</instance>
	<instance text="spiral 2.22209 1.30493"> p=3, q=15</instance>
	<instance text="spiral 3.459050632 1.512350036"> p=4, q=6</instance>
	<instance text="spiral 1.218 .67407066"> p=4, q=8</instance>
	<instance text="spiral 2.222084374 1.304928925"> p=6, q=9</instance>
	<instance text="spiral 1.807161471 1.218051525"> p=8, q=12</instance> 
	<instance text="spiral 2.89 24.137569"> p=2, q=3</instance>

	<instance text="spiral 8.352410036 24.13891302">Coxeter 
		  loxodromic spiral: p=3, q=2: (Here t=g+sqrt(g)=2.890053638, 
		  g is the golden ratio g=1.618033989; a=t^2, b=t^3.)</instance>
	<instance text="spiral 2.890053638   8.352410031">Related neat spiral: 
		  (unknown connection): p=2, q=4: (Here a=g+sqrt(g), b=a^2. 
		  From symmetry, geometric series, and pythagoras, find a 
		  is root of 1-2*a-2*a^2-2*a^3+a^4=0.)</instance>
	<instance text="spiral 1.623 6.939">Brooks' spiral: p=4, q=1: 
		  (Comes from Brooks quad with parameter g. Don't
		  know exact values.)</instance>
</examples>

<examples text="
	Others, unclassified are:(spiral 1.876554  4.82542), 
	(spiral 1.2238  1.2238), (spiral 1.10335 2.19637), and 
	(spiral 1.500527  1.22496).">

</examples>
</command>

<command cmd="sq_fit">
<description>
	This only applies to euclidean packings. The packing will be
	scaled so it just fits into the square with corners at
	(-1,1),(-1,-1),(1,-1),(1,1).
</description>
</command>


<command cmd="sq_grid_layer" flags="[options]">
<description>
	Given vertices v, w on the same boundary component of a
	packing, this command adds a boundary layer of "square 
	grid" type. That is, it adds matching copies tangent to each
	edge vertex counterclockwise from v to w (inclusive)
	and then puts "ball bearing" circles in the resulting
	interstices. If v=w (or if the complex has just one boundary
	and v and w are not specified), then one complete layer is 
	added to that boundary component. 
</description>

<options>
	<opt flag="-n {n}"> add n successive full layers to first boundary component</opt>
	<opt flag="-r {v1..v4}"> add one lay with four "corners"</opt>
	<opt flag="{v,w}"> bdry vertices v,w: one layer from v to w.</opt>
</options>
</command>


<command cmd="sq_grid_overlaps">
<description>
	"Square grid" packings typically have (interior) vertices 
	of degrees 4 and 8, and the "ball bearings", those of 
	degree 4, have inversive distances (overlaps) of angle pi/2 
	with their neighbors. This command simply sets that overlap 
	for all interior circles of degree 4 (whether packing has 
	square grid combinatorics or not). Existing inversive 
	distances are otherwise unchanged.
</description>
</command>


<command cmd="surf_write" flags="[option] {f..}">
<description>
	This writes a triangulated surface in 3D for the specified
	faces (default to 'all') in either xyz data or from the carrier 
	in *.jvx format, which is read and displayed by the software
	package 'JavaView'.
</description>

<options>
	<opt flag="-3D"> Use stored xyz-data</opt>
	<opt flag="-o {name}"> file name, default is 'surf_write.jvx'</opt>
</options>
</command>
	

<command cmd="swap" flags="{v w}">
<description>
	The indices of the circles v and w are swapped in the complex for
	the active pack. This is simply a convenience when it is desirable
	to have circles in a certain order; for instance, when comparing
	two packings' radii. If there is 'vertex_map', it is also adjusted.
</description>
</command>


<command cmd="test_repack" flags="[options]">
<description>
	For testing new repack routines. Options will change.
	Main issue at present concerns incompatibilities for
	overlap/inv. dist. packings.
</description>

<options>
	<opt flag="-d"> adjust compatible vertices as usual, avoiding creation of incompatibilities</opt>
	<opt flag="-c k"> test_cycle limit between status reports, default 1</opt>
	<opt flag="-n k"> total passes, default 200</opt>
</options>
</command>

<command cmd="torus_t">
<description>
 	Computes the modulus of a packing for a 1-torus. It returns
 	an error if the packing is not a combinatorial 1-torus or
 	if no edge-pairings have been computed.
</description>
</command>


<command cmd="transition" flags="{filename}">
<description>
	Prints data (form "v w t(v,w)") in matlab form to create
	matrix of transition probabilities. Currently only in eucl 
	geom, and bdry are automatically absorbing.	
</description>
</command>


<command cmd="tree_pack" flags="[options] {filename}">
<description>
	A tree (meaning a connected graph with no cycles) is read
	in from a file, augmented to become part of a simply connected
	complex, and then max packed. 'elist' contains the edges of the
	tree itself (the current procedure does not	add any vertices, 
	just additional edges). The file format for tree data is the same 
	as that for packing data. (C++ code was initially written by 
	Gerald Orick, summer 2006.)
</description>
	
<options>
	<opt flag="-infile {filename}"> The word 'infile' before the name (which
         must be the last string in the command) means that the
         tree is stored with the CPdata of the script.</opt>
</options>
</command>

<command cmd="unflip" flags="{v w ..}">
<description>
	Reverses the "flip" operation. "flip a b" does a Whitehead 
	move, removing edge {a b} and adding edge {c d} connecting
	the common neighbors of a, b. To undo this, you call 
	"unflip a b" (same as "flip c d").
</description>
</command>


<command cmd="unweld" flags="-q{p} [-o] {e..}">
<description>
	In "conformal welding" theory, there are welding "maps" and 
	associated welding "curves". In this call, the active pack p
	must be a univalent simply connected packing and a simple closed 
	edge-path is to be taken as the welding curve. The portion 
	of the active pack inside or outside (-o flag) the edge-path 
	(including the edge-path itself) is cut out and put in q. 
	(The original contents of q are lost.) 

	In the "outside" case, an ideal vertex is added to the 
	packing, if necessary, before q is determined. The added
	vertex becomes 'alpha' for the new q and the first vertex
	in the edge-path is 'gamma'.

	Normally, once both inside and outside packings have been 
	obtained, their boundary vertices should be identical (vis-a-vis
	the parent p; see their 'vertexMaps'), so these can be max packed 
	and then "weld_map" can show the associated welding "map". For
	convenience the new packing has boundary vert 2 as the 'gamma' 
	--- this is associated with the first vertex in the
	initial edge-path, so it is common to both inside and outside
	extractions.
</description>

<options>
	<opt flag="-o"> extract the outside of edge-path and put it in q; an ideal
	    vertex is added if the active packing has a boundary.</opt>
</options>
</command>

	
<command cmd="vert_map_off">
<description>
	There is an optional 'vertex_map' which can be read in
	and stored with a packing; it translates vertex numbers
	to vertex numbers for some other pack, as would be needed
	for a map between the two. This command destroys this 
	information. (See VERTEX_MAP in data file descriptions for
	more info.)
</description>
</command>


<command cmd="vert_order">
<description>
	Stores information on the order in which circles are drawn
	in the current drawing order. This can be accessed, for
	example, with a 'mark' command: 'mark -co 50' will mark the
	first 50 vertices in the drawing order.
</description>
</command>


<command cmd="vlist" flags="[options]">
<description>
	A utility "vertex list" attached to a particular packing; 
	can be read in and stored with packing data. Set with 
	'set_vlist'. Can be used wherever a list of verts is 
	called for, e.g., in disp and post calls. 
	NOTE: Vlist is the same thing, only it's not attached
	to a packing; it provides a general utility list.
</description>

<forms> (also apply to Vlist)
	<opt flag="vlist"> produces whole list.</opt>
	<opt flag="vlist[{i}]"> produces the i_th vertex in the list, if there is one.</opt>
	<opt flag="vlist[r]"> produces the first vertex of the list and then moves it to the end of the list.</opt>
	<opt flag="vlist[n]"> produces the "next" vertex of the list and then removes it from the list.</opt>
</forms>
</command>


<command cmd="weld" flags="{p} {q} {v} {w} [options]">
<description>
	Prepare to weld pack p to pack q, starting with verts v 
	and w, resp. Results can actually be welded with a call
	to 'adjoin' or with the -w flag here; the result replaces p. 
	The 'welding map' is specified in one of several ways. A 
	typical application involves maximal packings in p and q and 
	a welding map specified in a file. The boundaries of p and 
	q are identified to form a sphere; the identification requires 
	addition of extra boundary vertices and the necessary edges 
	to attach them to interior neighbors; this is the main task 
	of this	routine, to prepare p and q in place.
</description>

<options>
	<opt flag="-a"> use arclength (normalized to total 1) on bdry of each
		packing. (This is default behavior if given packings 
		are euclidean, for now.)</opt>
	<opt flag="-f {filename}"> file containing a real welding map
		(normally orientation preserving homeomorphism
		of [0,1] or [0,2pi], linearly interpolated.)</opt>
	<opt flag="-w"> After preparing p and q, also carry out the welding
		itself (i.e., using 'adjoin') and put the result in p.
		Default behavior is to puncture q at its alpha vert;
		the result can then be max_pack'ed in the hyperbolic
		plane. The user is then responsible for converting to 
		euclidean or projecting to the sphere (see 'proj').</opt>
</options>
</command>

<command cmd="weld_map" flags="{p} {q} {v} {w} {filename} [-gm]">
<description>
	Output the "fingerprint" data for the welding map between 
	packings p and q; both must be hyperbolic maximal packings 
	for combinatorial closed discs and must have the 
	same number of boundary vertices. The boundary 
	identification starts with vertices v and w, respectively.
	The output is matlab formated in {filename} with vector x
	and y of arguments from p and q, respectively to put out
	the fingerprint function h(t): this is (after normalization)
	a monotone increasing real function on [0,2pi]. Normally it 
	will be a bijection (mod 2pi), but if p and/or q is branched, 
	that may not be the case. (Related to the theory of "conformal
	welding". See also "unweld".)
</description>

<options>
	<opt flag="-m"> output in 'matlab' form (default is postscript)</opt>
	<opt flag="-g"> popup ghostviewer for the postscript file</opt>
	<opt flag="-w"> fingerprint output, suitable for input to 'weld'.</opt>
</options>
</command>


<command cmd="write -[AcgirRzZavloftmM]" flags="{filename}">
<description>
	This writes specified data on the active pack to the designated 
	file. It also resets the file name internally and on its canvas. 
	Keys to the stored data are given below; the default is -cgirzv.
	(General info on the data structures has been given elsewhere.)
	The filename must be given; even though the pack has a name in 
	its canvas, there is no automatic save to this name.  
	The -A option allows data to be added to an existing file,
	otherwise, previous contents of {filename} will be lost.
	(CAUTION: No confirmation is requested for command-line calls.)
</description>

<options> 
<comment>Any combination of these:</comment>
	<opt flag="-A"> append specified data to existing file</opt>
	<opt flag="-c"> combinatorics: flowers, a/b/c. </opt>
	<opt flag="-g"> geometry (needed by calls for data r and z) </opt>
	<opt flag="-i"> non-default inv_dist and aims</opt>
	<opt flag="-r"> radii</opt>
	<opt flag="-z"> centers</opt>
	<opt flag="-a"> angle sums</opt>
	<opt flag="-v"> vertex_map</opt>
	<opt flag="-l"> non-default lists: verts/faces/edges</opt>
	<opt flag="-o"> non-default face/circle colors</opt>
	<opt flag="-f"> non-zero plot_flags (Note: this info may immediately
			be overridden if centers are not also included in data)</opt>
	<opt flag="-t"> faces (as triples of vertices)</opt>
	<opt flag="-e"> edge-pairing mobius transformations. (Only for multiply
		  connected packings; be sure to 'layout' to update data.)</opt>
	<opt flag="-m"> minimal: equivalent to cgri</opt>
	<opt flag="-M"> Maximal: equivalent to cgriazsoflv</opt>
	<opt flag="(-S)"> Save data to end of current script file (needs fixing)</opt>
	<opt flag="-x"> 3D xyz data</opt>
	<opt flag="default">-cgirzv</opt>
</options>
</command>

<command cmd="Write" flags="-[AcgirzavloftmM] {filename}">
<description>
	Same as "write", except default path is not prepended to
	filename.
</description>
</command>

<command cmd="write_carrier" flags="[option] {file}">
<description>
	By default this saves OFF (Object File Format) files with 
	carrier of packing in xyz-form (mainly for spherical case, but 
	also xy-form for eucl/hyp cases); only stores data for plotted
	circles, see caution below. 
	Alternately, if the packing has stored "xyzpoint" data, save that.
	OFF/COFF (Object File Format) is for input, e.g., to Geomview.
	CAUTION: You may have to turn off plot_flags for circles
	if their centers are "nan" (not a number); identify
	them with "mark -c nan" and then "set_plot_flags 0 m".
</description>

<options>
	<opt flag="-3D"> Use stored xyzdata (if it exists)</opt>
	<opt flag="-jvx">Use JavaView *.jvx files</opt>
</options>
</command>

<command cmd="write_light(_raw)" flags="{filename}">
<description>
	Writing data for subcomplex to file in "light" packing 
	format;	"_raw" stores data only, no keywords. The 'variable'
	vertices of the light packing are those "marked" in the 
	packing.
</description>
</command>

<command cmd="Write_light(_raw)" flags="{filename}">
<description>
	Same as "write_light", except default path is not prepended
	to filename.
</description>
</command>

<command cmd="write_path" flags="{file}">
<description>
	Writes current path (if there is one) to file as a closed contour.
</description>
</command>

<command cmd="write_select_radii" flags="{file} {v..}">
<description>
	Write file with radii for vertices v..
</description>
</command>

<command cmd="Write_select_radii" flags="{file} {v..}">
<description>
	Same as above, except default path is not prepended to filename.
</description>
</command>

<command cmd="write_select_centers" flags="{file} {v..}">
<description>
	Write file with centers for vertices v..
</description>
</command>

<command cmd="Write_select_centers" flags="{file} {v..}">
<description>
	Same as above, except default path is not prepended to filename.
</description>
</command>

<command cmd="write_vert_list" flags="{filename} {v..}">
<description>
	Adjoin info to *.vl filename:
	   VERT_LIST: v1 v2 ... (done)
</description>
</command>
	
<command cmd="Write_vert_list" flags="{filename} {v..}">
<description>
	Same as "write_vert_list", except default path is not
	prepended to filename.
</description>
</command>

<command cmd="zip v n">
<description>
	Zip together (like a zipper) n pairs of boundary edges starting 
	from the vertex v (must be bdry vert) to form a new complex.
	If n is negative or too large, then as many edges as possible are
	identified. If there is an even number of edges in this bdry
	component, then they all get pasted and there's no bdry left;
	if odd, then a boundary component of three edges remains.
</description>
</command>

<command cmd="!!">
<description>
	This repeats the last command (omitting instances of "!!" itself).
	You can also repeat previous commands in the "History" tab.
</description>
</command>

<command cmd="?{*}">
<description>
	This command prints information of the specified kind in the
	"Messages" tab.
</description>
<options heading="Inquiries">
<comment>(Routine data is available in the "Packing Data" window)</comment>
	     ?overlap {v w..}   inv dist/overlap between neighbors
	     ?alt_rad {v..}     radii in alternate geometries
	     ?kappa {v..}       curvatures
	     ?antip {v}         vertex with maximal combinatoric
	                        distance to v.
        ?screen (data) screen information
	?parameters    program parameter
	Specials:
	     ?pk_status         angle sum error data
	     ?bdry_dist		distance from the bdry in euclidean
	  			packing
	     ?edge_pairing	Gives mobius transformations associated
				with edge-pairings for multiply 
				connected packings
	     ?ratio_ftn {p q}   ratio of (eucl) radii of alpha of
				pack p to that of pack q.
	     ?conductance {v..} transition probabilities for
				markov model of packing algorithm
	     ?remote processes  status of any remote processes open
	     ?bdry_length	comb length of bdry components
	     ?energy -[option]	various measures of point distributions
	     					of centers. 
	     	Options:
	     		-c (default) coulomb energy (L1 norm), 
	     			sum of reciprocals of point pair distances.
	     		-h L2 norm of reciprocals of point pair distances.
	     		-l log energy, sum log(1/dist).
	     		-m minimum distance between pairs.

	     ?script name	Is script file named
	     ?map {v..}		If there is a "vertex_map", what are
				indices (up to 12) associated with list?
	     ?map_rev {v}       same, but return reverse association for
				a single vertex. 
	     ?edge_x_ratio {e..} cross-ratios of interior edges
</options>
</command>

<command cmd="#XY">
<description>
	For use in 'mytools' that can be drag/dropped onto packing 
	canvasses: the drop location is converted to real x y
	coordinates and that pair of real numbers is substituted 
	for #XY before the command is executed:
</description>
	
<examples>
<instance text="flip z #XY">  This executes the 'flip' command using 
the flag 'z' followed by true x y coordinates.
</instance>
</examples>
</command>
	
<command cmd="[{script cmd}]">
<description>
	A line of commands in a "script" file can be given a "name",
	such as 'start' or '5'. From the command line or in a script, 
	the command '[start]' or '[5]' will execute that command.
	Empty brackets [] from the command line or script will execute 
	the next command of the script (if one is loaded). 
</description>
</command>

</CPdocs>
</body>

