<?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 title box.
</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>
<see>split_edge</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="{v1 w2  v2 w2 ..}">
<description> Given a list of vertices, we pick off successive pairs
	{v,w}. We stop unless v and w are bdry vertices sharing one 
	(resp. two) common neighbor(s). In this case we create a new edge {v w}
	and one (resp. two) new faces. Note that successive pairs may 
	become eligible as earlier edges are added. If two faces are 
	added, this means the vertices were part of a 4-edge bdry component;
	this bdry disappears, as the two new faces formed will be interior.
	See also "enclose 0 u ", where u is the common neighbor.
</description>
<seealso>
<see> enclose</see>
<see> split_edge</see>
<see> meld_edge</see>
</seealso>
</command>

<command cmd="add_face_triple" flags="{f..}">
<description> This command is associated with a generalization
	of "Apollonian" packing: instead of adding one 'ball bearing'
	to an interstice (see 'add_bary'), this adds a triple of circles. 
	The command	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". 

</description>
<examples>
<instance text="add_face_triple a">Repeating this will generate stages of
this generalized 'Apollonian' packing</instance> 
</examples>
<seealso>
<see>add_bary</see>
</seealso>
</command>


<command cmd="add_gen" flags="{n} [{d}] [-dt] [-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 'tent' generations,	without regard to degree. 
	Note that after the first level
	is added, the remainder will be degree 6 vertices.
	(Deprecated: "{n} -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>
<examples>
<instance text="add_gen 4"> adds 4 generations, circle-for-circle, 
to every boundary component; those after the first generation will 
be degree 6.</instance>
<instance text="add_gen 2 -d -b 65"> adds two "duplicate" generations
to the boundary component containing vertex 65</instance>
</examples>
</command>


<command cmd="add_ideal" flags="[-fs] {v..}">
<description>Given one or more boundary vertices v, add an ideal
    vertex or ideal face to v. An ideal vertex is a new vertex neighboring
    v and all vertices of the boundary component containing v (or optionally, 
    a portion of the boundary component). Center and radius of the new 
    vertex default to (0,0) and .5 (or PI/2 in spherical case). 
    An ideal face is a new face; this works if and only if v's bdry component 
    has precisely three vertices, in which case, they form a new face -- no 
    new vertices are required.   
</description>
<options>
<opt text="{v..}"> default: add ideal vertices to each bdry component 
containing one of vertices v.</opt>
<opt text="-f {v..}">  add ideal face to each bdry component containing one a v</opt>
<opt text="-s {v w}">  add ideal vertices neighboring boundary segment from v to w.</opt>
</options>
<examples>
<instance text="add_ideal"> add an ideal vertex for every boundary 
component</instance>
<instance text="add_ideal 8"> add an ideal vertex for the boundary 
component containing vertex 8</instance>
<instance text="add_ideal -f v"> add an ideal face to the bdry component containing v if it
has 3 vertices</instance>
<instance text="add_ideal -s 4 23"> if 4 and 23 are in the same bdry component, add a new vertex 
neighboring the segment of bdry vertices from 4 to 23, inclusive</instance>
</examples>
<seealso>
<see>puncture</see>
</seealso>
</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 the vertices between v and w will become interior vertices (as 
	will v if it is equal to w). 
</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="n v w"> adds circles so that v, w, and the boundary 
	  vertices between end up with degree n (>3); if one or more
	  circles are forced to degree exceeding n, a message is issued.
	  Here v and w become interior vertices.</opt>
</options>
<seealso>
<see>add_gen</see>
</seealso>
<examples>
<instance text="add_layer 6 340 340"> add a layer to convert to degree
6 on the full boundary component containing vert 340</instance>
<instance test="add_layer -d 26 39"> add a duplicate layer between 
boundary vertices 26 and 39</instance>
</examples>
</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>	
<seealso>
<see>set_rad</see>
<see>set_random</see>
</seealso>
</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 at north pole in spherical case).
</description>
<seealso>
<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 side {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 rectangular packings with corner vertices 
{a b c d} in counterclockwise order starting with upper-left corner a,
give the extremal length, namely, length/height, (aspect ratio).
</description>
<seealso>
<see> polypack</see>
</seealso>
</command>


<command cmd="bary_refine">
<description>This carries out a barycentric subdivision of all faces of the
	given packing: that is, each face becomes a hex flower, with an added 
	center vertex and an added vertex in each edge. 
	The indices and degrees of the original vertices
	remain unchanged; the face centers end up with the 
	largest indices. Most auxiliary packing data is lost and if 
	refinement fails, the packing will likely 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>(Not maintained robustly) "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>
<seealso>
<see>blend</see>
</seealso>
</command>


<command cmd="break">
<description> In a command string, this stops execute of the 
    remaining commands. It is built to prepare for "if-then"
    structures (6/2015).
</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 distinct than 
	'focus', which just changes the view presented on the canvas.
</description>
<seealso>
<see>center_vert</see>
<see>set_screen</see>
<see>focus</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>
<see>focus</see>
</seealso>
</command>

<command cmd="chgP" flags="{n}">
<description>Change the paired canvasses to size n-by-n, with
	n in range [200,800].
</description>
<seealso>
<see>set_display</see>
<see>chgS {n}</see>
</seealso>
</command>

<command cmd="chgS" flags="{n}">
<description>Change the active canvas to size n-by-n, with
	n in range [200,1200].
</description>
<seealso>
<see>set_display</see>
<see>chgP {n}</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 applies 'cleanse' to all packings. 
</description>
<seealso>
<see>cleanse</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>
<seealso>
<see>Cleanse</see>
</seealso>
</command>

<command cmd="close" flags="[window list]">
<description>
    The various windows and frames of CirclePack's GUI are normally 
    opened/closed via mouse and buttons actions. This command (and
    'open') allows these from command line or script, which is 
    particularly useful in demonstrating features of CirclePack. 
</description>
<options>
<opt flag="Active"> Frame displaying the 'active' packing, the main single-canvas window</opt>
<opt flag="Paired"> Frame displaying side-by-side packings (perhaps neither the active pack)</opt>
<opt flag="Advanced"> Control frame, droppable icons and small views of all three packings</opt>
<opt flag="Script"> Frame with current 'Script' for running CirclePack</opt>
<opt flag="www"> Browser window, good for loading scripts from the web or files</opt>
<opt flag="Message"> Frame with Messages, Scratch area, Command line</opt>
<opt flag="Help"> Help frame</opt>
<opt flag="Mobius"> Frame for managing Mobius transformations</opt>
<opt flag="Function"> Frame for setting a function and parameterized path</opt>
<opt flag="Save"> Frame with save operations</opt>
<opt flag="Screen"> Frame with screen snapshots, display settings</opt>
<opt flag="Information"> Frame with pack information</opt> 
<opt flag="Configure"> Frame with Configuration settings</opt> 
<opt flag="About"> Frame showing 'About Script' info (if a script is loaded)</opt>
</options>
<examples>
<instance text="close Script Save"> Close the Script frame and the frame for Save operations</instance>
</examples> 
<seealso>
<see>open</see>
<see>Map</see>
</seealso>
</command>

<command cmd="color" flags="-[cfe] [options]">
<description>Color specifications affect the display of filled 
	circles, faces, edges, or tiles only -- "-T" "-D" "-Q" for 
	tiles, dual tiles, quad tiles.
</description>
<options> (one only)
	<opt flag="bg {i..}"> background color for selected objects</opt>
	<opt flag="fg {i..}"> foreground color</opt>
	<opt flag="{c} c {i..}"> c 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 
among 16 distinct colors starting at random point</opt>
	<opt flag="S {i..}"> same as 's', except same color for the full list</opt>
	<opt flag="s0 {i..}"> same as 's', but start at 0 point</opt> 
	<opt flag="S0 {i..}"> same as 'S', but start at 0 point</opt> 
	<opt flag="-k {x}"> (not currently implemented) 
         (circles only) blue-red, compare model curvature to x.</opt>
	<opt flag="x {f..}"> (faces) compare 3D/2D eucl area (if 'xyz' data exists).</opt>
	<opt flag="v {f..}"> (faces) use vertex colors: majority wins, 
		 else first vert's color. (deprecated: '-v')</opt>
	<opt flag="v {t..}"> (tiles) use color assigned to baryVert vertex</opt>
	<opt flag="qc [options] -m {x} {f..}">  (faces only)
		 red color ramp for faces based on quasiconformal 
		 dilatation of some map. (All computations are done using
		 euclidean data.) -m {x} sets ceiling x on
		 dilatations; those above x will be dark blue,
		 those in [1,x) will be increasingly red, those that 
		 cannot be computed for some reason 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>
	<opt flag="a {v..}"> (circles/faces) 'ArgWheel'; based on complex 
	      argument of center or incenter.</opt>
	<opt flag="z {v w ...}"> (edges only) based on schwarzian</opt>
	<opt flag="r"> (edge only) reset all to foreground</opt>
</options>
<examples>
<instance text="color -f qc q1 -m 1.5 a">color by 
quasiconformal dilatation, compared to p1</instance>
<instance text="color -D d a">color 
dual tiles based on number of edges (if dual tiling exists).</instance> 
<instance text="color -e z a">color all interior edges base on their 
schwarzians</instance> 
</examples>
</command>
		 
<command cmd="cookie" flags="[option] {v..}">
<description>A portion of the packing is "cookied" out, giving a 
	new packing that replaces 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 'vertexMap' of the new packing contains pairs {m,n},
	where n is the new index for the circle having original
	index m.

	The cookie strategy based on designate 'poison' vertices; 
	the new	complex is that component of the complement of these poison
	vertices which contains the alpha vertex (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.
	
	DCEL version: based on list of 'forbidden' halfedges. This does
	not (yet) guarantee that every vertex has an interior neighbor.
	 
</description>
<options>
	<opt flag="-v {v}"> Use v instead of alpha as the 'seed' vertex.</opt>
	<opt flag="-e {v u ...}"> (DCEL) - list of forbidden edges </opt>
	<opt flag="-n {v ..}"> (DCEL) - 'non-keeper' vertices: edges with
	          both ends non-keepers are added to forbidden edges. </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.
The result appears in the "Message" window.	(Note: edge counting 
does not eliminate redundancies, as other counts do.)
</description>
<examples>
	<instance text="count -v b"> will count the boundary vertices
	</instance>
</examples>
</command>

<command cmd="create" flags="{type} [options]">
<description>This command allows you to create various types of
    packings from scratch. Generally, parameters are specified,
    e.g., the number of petals for "seed", or the number of 
    generations, as with "hex" or "tri_group". Depending on 
    the type, there may be special numbering or marking of 
    vertices and/or edges.
    
    The "hex_torus" construction builds a regular parallelogram-like
    hex torus with given w/h for width/height.
    
	The "tri_group" construction involves parameters (a b c) for 
	triangle angles	pi/a, pi/b, pi/c; a, b, c can be (at worst) half 
	integers, and if one is a half integer, then the other two must be 
	equal to make combinatoric sense. The geometry for the packing is 
	determined by the angles.
	
	The "j_ftn" is associated with a triangle group (0 a b). It
	is similar to a dessin d'enfants with branch multiplicities
	a and b over 0 and 1, respectively, but logarithmic branching
	over infinity. Default to a=2 and b=3, the classical 
	j-function associated with the modular group. 
	
	The "Kagome" construction builds the packing for a tiling in
	the famous Kagome latttice pattern.
	
	The Fibonacci tilings are "fusion" type of Frank and Sadun.
	Parameters W H X determine combinatorial edge lengths, 
	defaulting to 1 1 1.
	
	A regular "tetrahedron" on there sphere; 4 circles, each of radius
	arcsin(sqrt(2/3)).
	
	Additional types can be anticipated, potentially with further
	required options.
</description>
<examples>
	<instance text="hex_torus 3 6"> 
	build 3-by-6 hex torus</instance>
	<instance text="create hex 23"> 
	hexagonal packing of 23 generations</instance>
	<instance text="create sq_grid 4"> 
	'square grid' pattern from 4 quadruplings of a 4-flower</instance>
	<instance text="create tri_group 8 2 3 5"> 
	8 generations of the (2 3 5) triangle group on
	the sphere.</instance>
	<instance text="create j_ftn 8"> 
	8 generations of the classical j-function.</instance>
	<instance text="create Kag 4"> 
	4 layers of Kagome lattice about a central hexagon</instance>
	<instance text="create pent 5">
	5 generations of regular pentagonal tiling</instance>
	<instance text="create pent3 3"> 
	3 generations of pent tiling centered on triple point</instance>
	<instance text="create pent4 3"> 
	3 generations of pent tiling centered on quad point</instance>
	<instance text="create dyadic 6"> 
	6 generations of Penrose's hyperbolic tiling (Carleson squares in the limit)</instance>
	<instance text="create fib 5 6 3 2"> 
	5 generations of Fibonnacci-related tiling, W=6,H=3,X=2.</instance>
	<instance text="tetra"> 
	regular tetrahedron on the sphere</instance>
</examples>
<seealso>
<see>seed</see>
<see>pave</see>
</seealso>
</command>

<command cmd="DCEL" flags="[options]">
<description> DCEL is a halfedge based model for storing 
graph combinatorics. Starting in June 2016 I have begun testing
this approach as a possible replacement for current methods. 
Current commands are temporary; look in 'CommandStrParser.java'
for details. 
</description>
<options>
<opt> dcel	Create the dcel structure for the active pack</opt>
</options>
</command> 


<command cmd="debug" flags="[drsex]">
<description>Various debug helpers. Some put results in a file in the
default temporary directory (see 'Messages'), others print something.
</description>
<options>
<opt flag="-d"> (default) generates tmp file 'faceOrder_xxxx_log'</opt>  
<opt flag="-r"> generates file 'RedList_xxxxx_log' of the 'red' faces</opt>
<opt flag="-s"> prints size/location info on 'StackBox's in the script</opt>
<opt flag="-e"> print commands to stderr to debug threads and lock ups</opt>
<opt flag="-x"> turn off -e option</opt>
</options>
</command>

<command cmd="delaunay" flags="-[cfgs]">
<description>Create the "Delaunay triangulation" for a set
    of points and store the resulting complex in the current packing. 
    The points may come from the active packing centers or from a file
    (see mutually exclusive options). 

    If the points are read from a file, an attempt is made to read some
    standard formats giving 2D or 3D points. A euclidean 
    or spherical packing is generated with a C library call to 'qconvex' 
    (one of the "QHull" programs) or to Shewchuk's 'triangle' code, respectively. 

    There is one special case: if the file of points begins with keyword
    "UNIT_SQUARE:", then its points (x,y) lie in [0,1]x[0,1]. If the user
    chooses spherical geometry via the "-g s" flag, then these points are
    interpreted as being on the sphere: namely, (x,y) converts to the point
    (theta, phi) where theta=2pi*x and phi=arccos(2*(y-.5)). This is a
    convenience for generating random points on the sphere, for if (x,y) 
    are, say, Poisson random in the unit square, then (theta,phi) are Poisson
    random on the sphere. 

    CAUTION: This call will not work if the C++ library is not operational.
</description>	
<options>
	<opt flag="-c"> use the centers of the active packing</opt>
	<opt flag="-f {filename}"> read	points from a file</opt>
	<opt flag="-s {filename}"> read points from a script file</opt>
	<opt flag="-g {hes}"> geometry, hyp, eucl, or spherical</opt>
</options>
<seealso>
<see>random_triangulation</see>
<see>random_pack</see>
</seealso>
</command>

<command cmd="Disp" flags="[options ...] (see 'disp')">
<description>"Disp" (with upper case 'D') calls "disp" with the given
	options, but also stores those options with this canvas (as in
	"set_disp_flags"). This is extremely useful: mouse and menu actions
	that cause the screen to redisplay, or calls to "disp -wr",
	will repeat these display options.
</description>
<seealso>
<see>disp</see>
<see>set_disp_flags</see>
</seealso>
</command>	

<command cmd="disp" flags="[options ... ] (also 'Disp')">
<description>
	This is the command for actually displaying the active packing and 
	associated objects on its canvas (or canvasses). There are numerous
	options as described below, but the key ones are '-c', '-f', and
	'-e' for circles, faces, and edges, respectively. The commands have
	default color, fill, and thickness options, but these can be modified.
	See the "'disp' options" tab in the Help Window for full details.

    The "Screen, Display Options" panel allows one to specify the default 
	drawing options or give a user-defined string of commands as described 
	below (see 'set_disp_flags'). 
	
	"Disp" (with upper case 'D') will both display the indicated objects
	and store that specification as in 'set_disp_flags'. This is very
	useful: these display options will be used when mouse and menu actions
	cause the screen to redisplay or when "disp -wr" is called.

	CAUTION: 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="-a {f..}"> sector arcs (eucl); based on edgelength</opt>
    <opt flag="-h {v..}"> hull, meaning convex hull of tangency 
points with nghbs</opt>
	<opt flag="-nc {v..}"> label circles</opt>
	<opt flag="-nf {f..}"> label faces</opt>
	<opt flag="-B"> all faces and circles, recomp'd by drawing order</opt>
	<opt flag="-C"> all circles, recomp'd by drawing order </opt>
	<opt flag="-D"> all dual faces, recomputed by drawing order (eucl only)</opt>
    <opt flag="-F {f..}"> ``chained'' faces, recompute centers in order</opt>
	<opt flag="-Bs"> all faces and circles, recomp'd by drawing order using schwarzians</opt>
	<opt flag="-Cs"> all circles, recompute center by drawing order using schwarzians </opt>
    <opt flag="-Fs {f..}"> ``chained'' faces, recompute centers in 
    	order using schwarzians</opt>
	<opt flag="-P {v..}"> 'pavers' (polygon formed by face flower) recomp'd by drawing order 
	(eucl only)</opt>
    <opt flag="-b"> draw bary-coord defined paths, generally grid lines (eucl only)</opt>
    <opt flag="-bs"> draw bary-coord defined paths, generally stream lines (eucl only)</opt>
	<opt flag="-bc{n}"> ditto, but in color with index n</opt>
	<opt flag="-g"> display current "path" (if available) in 
		thicker blue</opt>
	<opt flag="-gc{n}"> ditto, but in color with index n</opt>
	<opt flag="-q{p}"> display on pack p' canvas (may be geometry conflict)</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>
	<opt flag="-y {f..}"> display circumcircles of given faces 
	(useful for Delaunay triangulations)</opt>
</options>

<options heading="Dual Object Options">
	<opt flag="-dc"> dual circles (associated with packing interstices)</opt>
	<opt flag="-de"> dual edges</opt>
	<opt flag="-df"> dual faces</opt>
	<opt flag="-dh"> dual face hull (polygon of tangency point)</opt>
	<opt flag="-dg"> dual edges given, else those in pack's 'dualGraph'</opt>
	<opt flag="-dp"> dual circle tangency points</opt>
	<opt flag="-dt"> trinkets at dual centers</opt>
	<opt flag="-D?"> (layout as needed, e.g. multiply connected cases)</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="-ee {v w..}"> extended edges; travel thru up to 16 hex
			vertices from v to w (for hex_refined packs). </opt>
	<opt flag="-gi"> draw path and the circles inside it</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 (no interpolation of vertices between)</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>
	<opt flag="-T {t..}"> closed polygonal tiles (if the packing has tiling data)</opt>
</options>	
     NOTE: Under many options (e.g., c,f,F,cf,e,fn,Ff,T), 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 "layout",
	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.

<seealso>
<see>set_disp_flags</see>
<see>set_plot_flags</see>
</seealso>
</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>
<seealso>
<see>reorient</see>
</seealso>
</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>	
<seealso>
<see>spiral</see>
</seealso>
</command>

<command cmd="doyle_point" flags="f">
<description>A circle C of radius r, center z whose disc is in the 
	punctured 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>
<seealso>
<see>spiral</see>
</seealso>
</command>


<command cmd="dual_layout" flags="-[c{flags}] -[f{flags}] [{f1 g1 ...}]">
<description>
	This is for laying out a circle packing using schwarzians of
	its edges (if they are set). The layout order is associated
	with the given list of dual edges specified by pairs (f,g) of
	contiguous faces --- often a directed tree and by default,
	a dual spanning tree. We assume f is in place and use the 
	real schwarzian for the	common edge to place the opposite 
	circle of g. This is used only in spherical or euclidean 
	geometry. See 'Schwarzian.java' for details. Also, all vertex 
	angle sums (ie. 'curv')	are set to and new angles accumulate
	at vertices as successive faces are laid out.
	
	If the first pair has form (0,f) (as when created as a dual 
	spanning tree), then f is designated as base face to be laid
	out first. This face is our 'base equilateral' face, meaning
	it is an equilateral triangle formed by three circles of (eucl)
	radius sqrt(3) with barycenter at the origin, and tangency 
	points in the direction of the cube roots of unity.  
	OBE: original command's name was 'sch_layout'
</description>
<options>
<opt flag="f"> draw each new face as laid out with usual display options</opt>
<opt flag="c"> draw each new circle with usual display options</opt>
</options>
<seealso>
<see>sch_report</see>
<see>set_schwarzian</see>
</seealso>
</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 packing's
	elist 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>
<seealso>
<see>path_to_elist</see>
<see>elist_to_path</see>
</seealso>
</command>


<command cmd="enclose" flags="-[t] n {v..}">
<description>For each circle v, if on the boundary, add n circles 
as neighbors (or bring degree to n) and closed up to make v interior.
The -t option does not always succeed due to combinatorial influences.
</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>
<seealso>
<see>quit</see>
</seealso>
</command>	


<command cmd="extender" flags=" -[xr] {type}">
<description>'PackExtenders' are Java classes which can be launched
for particular packings, extending storage and functionality for them.
The intention is that users can write extenders tailored to their
purposes but without the need to delve into 'CirclePack' core 
operations. Extenders process commands directed to them via 
two-letter abbreviations, as with 'cf' for the 'CurvatureFlow' extender. 
When a extender is started for a packing, the "Pack Extender" tab of
the Help Frame displays help information.
</description>	
<options>
<opt flag="{type}"> Where {type} is two letter abbreviation for the
extender. (Currently, 'CirclePack' must already know of the associated
class.)</opt> 
   	<opt flag="-x [{typ}]"> close extenders of the specified type, or
all extenders if the type is omitted.</opt>
    <opt flag="-r {typ}"> close any extenders of type 'typ' and then 
    start an extender of this type.</opt>
</options>
<examples> 
<instance text="extender cf"> would start a "CurvatureFlow" pack
extender.</instance>
<instance text="extender -x"> would close all extenders for this packing.</instance>
<instance text="extender -r ct"> would close any current 'ConformalTiling' extenders 
for this packing and start a new one.</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>(Technical) 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>(Technical) 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>(Deprecated: preferred command is "layout"). 
</description>
<seealso>
<see>layout</see>
</seealso>
</command>


<command cmd="Fix"> 
<description>(Deprecated: replaced by "layout -F".)
</description>
<seealso>
<see>layout</see>
</seealso>
</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>
<seealso>
<see>unflip</see>
</seealso>
</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>
<seealso>
<see>flip</see>
<see>unflip</see>
</seealso>
</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>
<seealso>
<see>center_vert</see>
<see>center_point</see>
</seealso>
</command>

<command cmd="for" flags="(...) -d {x} {cmd;cmd;..}">
<description>Repeat the given sequence of commands based on iteration
	specification (..). Its preferred form is 'for (s,e,d)' where iteration
	starts with real number s, ends with real number e, with real (non-zero)
	increment d. Deprecated form is 'for n,m' (or 'for n:m') where
	iteration starts at integer n and ends with integer m. 
	As safety measure, limit is 10 iterations unless command 'FOR' is used.
	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 subsequent commands are taken as part of
	the string subject to iteration.
</description>	
<options>
	<opt flag="FOR"> Remove the 10 iteration limit.</opt>
	<opt flag="-d {x}"> impose a x second delay between iterations</opt>
</options>
<examples>
<instance text="for 12:20 disp -F flist[n]"> layout and display 9 faces 
from the current flist.</instance>
<instance text="FOR (v:=1,40,2) disp -p1 -c _v"> this displays odd-indexed 
circles from 1 to 39.</instance>
</examples>
</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>
<seealso>
<see>alpha</see>
</seealso>
</command>


<command cmd="frack" flags="{v..}">
<description>This is a local refinement method for combinatorics.
    A list of vertices must be provided. A barycenter is added to each
	face neighboring one of these vertices, then the new barycenter 
	vertices about any of the given vertices v are connected to form a 
	flower around v, while any former edges from v are remove. 
	Caution: adjustment for neighboring vertices in the list will
	interfer with one another, and results are difficult to predict.
	The user will typically repack, layout, and display.
</description>
<seealso>
<see>hex_refine</see>
<see>add_bary</see>
</seealso>
</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 the 'mark' data for vertices (default) or faces 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 as well.
</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>
<examples>
<instance text="gen_mark A">mark vertices with their combinatorial distance
from the alpha vertex</instance>
<instance text="F:={gen_mark -f b}"> will set variable 'F' to the index of
the face furthest from the boundary faces</instance>
</examples>
<seealso>
<see>mark</see>
</seealso>
</command>


<command cmd="geom_to_[ehs]" 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. 
</description>
<options>
	<opt flag="-l"> means to reestablish current numerical values of radii 
		after conversion, even though the geometry has changed.</opt>
</options>
<seealso>
<see>project</see>
</seealso>
</command>

<command cmd="get_data" flags="-q{q} [-t] {flag} {..}">
<description>Copy data from pack q to the active packing. 
    There are (perhaps multiple) specifications, each 
    with a list of vertices/faces/edges. 
    
	If the -t flag is set it must be first and the active 
	packing must have a 'vertex_map'; then the data for 
	verts/faces/edges in the active	pack is replaced by 
	that of (legal) image vertices w (or faces) in pack q. 
	(Note: faces are associated with triples of vertices.)
	The flags for the type(s) of data to get are given 
	below; several may be specified, each with a list of
	objects. E.g. "get_data -q2 -t -z b -r a" will get 
	(translated) centers for bdry vertices and radii all
	vertices of the active pack, the data taken from q.
	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 default to 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 encountered), 
	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.
</description>
<options heading="Data specification flags">
<opt flag="-t"> translate (see above); must occur first after '-q2'</opt>
<opt flag="-r"> radii (same as '-cr')</opt>
<opt flag="-z"> centers (same as '-cz')</opt>
<opt flag="-a"> aims (same as '-ca')</opt>
<opt flag="-cc"> circle colors</opt>
<opt flag="-cm"> circle 'mark's</opt>
<opt flag="-c[rzmca]"> multiple specifications (same vertex list)</opt>
<opt flag="-fc"> face colors</opt>
<opt flag="-fm"> face 'mark's</opt>
<opt flag="-f[mc]"> mutilple specifications (same face list)</opt>
<opt flag="-em"> edge 'mark's</opt>
<opt flag="-ec"> edge color</opt>
<opt flag="-es"> schwarzians (for edges)</opt>
<opt flag="-ei"> inversive distances (for edges)</opt>
<opt flag="-e[mcsi]"> multiple specifications (same edge list)</opt>
<opt flag="-v -V"> vertex_map (see above); these occur alone</opt>
</options> 

<examples>
<instance text="get_data -q2 -t -crz b">Copy (translated) centers
	and radii from p2 for all bdry vertices of the active pack.</instance>
<instance text="get_data -q2 -ems">Copy all edge marks and schwarzians
    from p2 to the active packing for all edges.</instance>
<instance text="get_data -q2 -fm {f...} -cz {v...}"> Combined call with
	lists specified for each flag.</instance> 
<instance text="get_data -q2 -ca {c:a.gt.3.0}"> Aims for circles with
    aim greater than 3.0*Pi.</instance>	 	
</examples>
<seealso>
<see>put_data</see>
</seealso>
</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="GOpack" flags="[-v {v..}] -[ghqrsx] -[b{f}] -[c{n}]">
<description> For packing computations using Gerald Orick's methods,
    which involve computation of centers and radii at the same time.
    These use sparse matrices and so rely (as of 6/2015) on C libraries.
    Calls to 'max_pack' will use GOpack routines behind the scenes
    for larger packings. However, these calls use default settings,
    and for cases requiring more care, 'GOpack' can be started and
    allowed to persist through multiple calls. One use of GOpack is
    to adjust locations of some subpatch of centers: use the -v flag
    to identify the vertices to be adjusted, then the -h flag to fix
    all other locations.
</description>
<options>
    <opt flag="-v {v..}"> special premptive flag, other flags ignored:
        {v..} specifies subcomplex of vertices to be considered 'interior'.</opt>
    <opt flag="-s"> set all radii to 1, but do no riffles</opt>
    <opt flag="-m {n}"> do the usual max packing (sph or disc), 'n' passes</opt>
    <opt flag="-c {n}"> continue packing 'n' passes with the current 
        local data</opt>
    <opt flag="-r"> (eucl case only) restart the existing 'GOpacker' 
        by getting eucl radii and centers from the parent packing</opt>
    <opt flag="-b{n} v1..vn [a1..an]"> Specifies a polygonal packing, v1..vn as 
        cclw corners, optional a1..an as corresponding interior angles/pi. (default
        to equal angles) </opt> 
    <opt flag="-h"> 'harmonic' layout, i.e. solve for 'interior' with 
        fixed boundary centers/radii (eucl only).</opt>        
    <opt flag="-l"> debugging: layout the bdry only, depending on mode</opt>
    <opt flag="-n {n}"> set the number of passes (iterations), used in
        conjunction with other commands</opt>
    <opt flag="-q"> return a value showing packing quality</opt>
    <opt flag="-x"> kill the 'GOpacker'</opt>
    <opt flag="-?"> print current GOpack status</opt>
</options>
<seealso>
    <see> max_pack</see>  
    <see> repack</see>
    <see> polypack</see>
    <see> perp_pack</see>  
</seealso>
<examples>
    <instance text="GOpack -m"> computes the max packing with default number
    of iterations</instance>
    <instance text="GOpack -b4 2 3 7 33 .25 .75 .25 .75"> Using bdry radii, 
    form a parallelogram with given corner vertices, and corner angles/pi 
    (default values would be 1/4).
    </instance>
</examples>     
</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 then 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 seen 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 saved under "filename".
NOTE: not yet operational in spherical geometry.
</description>
<options>
<opt flag="-f"> Save to given file</opt>
<opt flag="-a"> Append to given file</opt>
<opt flag="-s"> Save to given file in the script</opt>
</options>
</command>

<command cmd="IF" flags=".. THEN .. (ELSE ..)">
<description>IF 'condition' THEN 'cmds1' ELSE 'cmds2' is a usual type of
    if-then-else construction. The 'condition' may involve logicals 
    '.and.', '.or.', '.nor.', '.not.', or '!', with 'content' items 
    grouped using '(..)' and interpreted left to right. The 'content'
    items must evaluate to true/false; may be a unary (e.g. "?status" to check whether the
    packing is non-empty) or a comparison of numerical values using
    '.lt.', '.gt.', '.le.', '.ge.', '.eq.', '.ne.' See the examples.
    Failure, and the whole command is jetisoned. 
    'cmds1' and 'cmds2' are the usual type of ';' separated command
    strings.
</description>
<examples>
<instance text="IF ?status THEN disp -w -cf"> If the active packing is
    non-empty, then run this display command</instance>
<instance text="IF {count -c b}.ge.3 THEN double;max_pack;Disp -w -c"> If the
    active packing has at least 3 boundary vertices, then double it and
    compute/display the max packing.</instance>
<instance text="IF {qual b}.gt.0.1 THEN rld ELSE layout;disp -wr">If the quality of
    the active packing, based on boundary radii, is too large, then repack, layout,
    display, else just layout and display.</instance>   
</examples>
</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="[-a] {name}">
<description>This reads path data in the current "script" and puts
	it in place or appends it to the global 'ClosedPath'. 
</description>
<options>
<opt flag="-a"> If there is an existing 'ClosedPath', this will append
the new path.</opt>
</options>
<seealso>
<see>read_path</see>
</seealso>
</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>
<seealso>
<see>read</see>
</seealso>
</command>

<command cmd="j_ftn" flags="{maxgens n0 n1}">
<description>
    Deprecated: see "create tri_group".
</description>
<seealso>
<see>create</see>
</seealso>
</command>


<command cmd="layout" flags="-[ac[cdfs]defFKlrstT]">
<description>Along with "repack", this is one of the key commands in CirclePack:
    it recomputes the centers of the circles of the active pack. Generally called
    immediately after "repack", which changes radii but does not compute new centers.
    CirclePack has standard methods of specifying layout order, with 
    an "alpha" circle placed at the origin and a "gamma" circle is rotated to be on 
    the positive imaginary axis. Under the '-c' flag, various alternatives are
    offered. 
	Note: If the radii have not been adjusted to meet the packing condition, 
	then the configuration may not be cohesive -- intended neighbors may not 
	be contiguous, there may be isolated circles, etc. In fact, locations 
	will be dependent on the "drawingorder" which has been set for the circles. 
	(Replaces deprecated "fix" command)
</description>
<options> (one of)
	<opt flag="-a"> set "aims" to their defaults</opt>
	<opt flag="-c[cdfs]"> recompute pack centers.
		added options follow (allow no spaces between):</opt>
		<opt flag="      c {x}"> set decimal number 'x' as threshold for 
		   placement accuracy; e.g., x=.00001 for 5-decimal places.</opt>
		<opt flag="      d"> create "layout.log" diagnostic file in the temporary
		   directory to check for layout errors</opt>
		<opt flag="      f"> plot only circles with placement errors less
		   than assigned threshold, set 'plot_flag' appropriately
		   (as in '-l' option below)</opt>
		<opt flag="      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 current draw order; report 
	position(s) of vertex v</opt>
	<opt flag="-dt [v]"> for torus packings only; arrange for just two side
	pairings. Optional, report positions of the corner.</opt>
	<opt flag="-v {v..}"> redo drawingorder with given vertex list defining 
	the outer boundary.</opt>
	<opt flag="-f {f..}"> redo drawingorder with given facelist as a
		   (putative) red chain; the outside edges of the faces
		    are set as forbidden.</opt>
	<opt flag="-F [P]"> redo everything (aims reset to default) ('P' flag means use 'poison' verts/edges)</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>
<seealso>
<see>alpha</see>
<see>gamma</see> 
<see>set_poison</see>
<see>set_plot_flags</see>
</seealso>
</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" flags="-[f]">
<description>
        Brings up a FileChooser dialog allowing the user to load a
        circle packing from a file. By default, the packing directory
        is changed to the chosen directory.
</description>
<options>
	<opt flag="-f"> do not change the packing directory</opt>
</options>	
<seealso>
<see>read</see>
</seealso>
</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 "reflection" on (see the connection icon), the 
user can click on a circle (left mouse) or face (middle) in one of 
these packings and the corresponding object is displayed in both.
	
</description>
<options>
	<opt flag="-o"> open Map windows in Java with packs p and q</opt>
	<opt flag="-x"> close Map windows, return to active canvas</opt>
	<opt flag="-tNO"> remove action reflection between canvasses</opt>
	<opt flag="-tYES"> add action reflection between canvasses</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; '-r' must be the first flag

	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 (must appear first)</opt>
	<opt flag="-v"> circles (the default) (or -c)</opt>
	<opt flag="-f"> faces</opt>
	<opt flag="-q{q}"> for faces only, 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 test="map -r a"> Store reverse translated indices of
	all circlesin 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>
<seealso>
<see>gen_mark</see>
</seealso>
</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>
<seealso>
<see>repack</see>
<see>perp_pack</see>
<see>set_radii</see>
</seealso>
</command>


<command cmd="meld_edge" flags="{v w ..}">
<description>This call will remove the specified edges by melding
	their vertices. Edge order is important: given edge (v,w), 
	the vertices are combined to a single vertex, with w being
	orphaned. Applied carefully, this command can undo some 
	other commands that add edges.
</description>
<seealso>
<see>split_edge</see>
<see>split_flower</see>
<see>enclose</see>
</seealso>
</command>      		
     		
<command cmd="mend" flags="{data}">
<description>(Not maintained robustly) 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>
<seealso>
<see>blend</see>
</seealso>
</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 combinatoric 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.
	This has worked well, for example, with hexagonal packings.
	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>
<see>set_Mobius</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="{text}">
<description>The text is sent to the "Messages" 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>
<seealso>
<see>exec</see>
</seealso>
</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="newRed" flags="[-t, {v..}]">
<description>
	Every complex (except those triangulating a sphere) will 
	have a "red chain", which is a linked list of edges
	surrounding a fundamental domain, including bdry edges.
	For a simply connected complex, it is simply the oriented
	list of boundary edges, but it is essential for multiply
	connected situations. It is generated automatically.
	This command gives two options for redoing the red chain.
	The -t option is only for topological tori and recomputes
	the red chain so it has only two side-pairing (rather
	than the generic three). The second option is to provide
	a vertex list defining the red chain. This is difficult:
	the edges in the chain must be contiguous, closed, and
	contain all bdry edges. It can have unanticipated effects,
	such as cutting out some vertices. One use is to make
	small modifications to an existing red chain (display 
	this using the '-R' option). On failure, this command
	should not damage the packing.
</description>
<options>
<opt flag="-t"> For torus only, creates domain with only 
two side-pairings</opt>
<opt flag="{v...}"> List of vertices defining a new red chain</opt>
</options>
<seealso>
<see> set_vlist -R</see>
</seealso>
</command> 


<command cmd="norm_scale" flags="[options]">
<description>
	Normalize a packing (euclidean only) according to various options.
</description>
<options>
<opt flag="-a x"> scale so total euclidean area is x</opt>
<opt flag="-c v r"> scale so vert v gets radius r</opt>
<opt flag="-e q v w">  scale so vert v has radius of vert w in pack q</opt>
<opt flag="-h v w"> rotate so vector v to w is horizontal (left to right)</opt>
<opt flag="-i v"> scale/rotate to put vertex v at z=i (asuming v is
		not centered at the origin)</opt>
<opt flag="-m v1 v2 z1 z2"> linear transformation putting vi at zi</opt>
<opt flag="-t"> for torus only: put in normalized position, report tau</opt>		
<opt flag="-u v"> scale so eucl center of vert v is on unit circle </opt>
<opt flag="-U"> scale (down only) to fit eucl packing into the unit disc </opt>
</options>
<seealso>
<see>rotate</see>
</seealso>
</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. 
	
	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="open" flags="[window list]">
<description>
    The various windows and frames of CirclePack's GUI are normally 
    opened/closed via mouse and buttons actions. This command (and
    'close') allows these from command line or script, which is 
    particularly useful in demonstrating features of CirclePack. 
</description>
<options>
<opt flag="Active"> Frame displaying the 'active' packing, the main single-canvas window</opt>
<opt flag="Paired"> Frame displaying side-by-side packings (perhaps neither the active pack)</opt>
<opt flag="Advanced"> Control frame, droppable icons and small views of all three packings</opt>
<opt flag="Script"> Frame with current 'Script' for running CirclePack</opt>
<opt flag="www"> Browser window, good for loading scripts from the web or files</opt>
<opt flag="Message"> Frame with Messages, Scratch area, Command line</opt>
<opt flag="Help"> Help frame</opt>
<opt flag="Mobius"> Frame for managing Mobius transformations</opt>
<opt flag="Function"> Frame for setting a function and parameterized path</opt>
<opt flag="Save"> Frame with save operations</opt>
<opt flag="Screen"> Frame with screen snapshots, display settings</opt>
<opt flag="Information"> Frame with pack information</opt> 
<opt flag="Configure"> Frame with Configuration settings</opt> 
<opt flag="About"> Frame showing 'About Script' info (if a script is loaded)</opt>
</options>
<examples>
<instance text="open Script Save"> Close the Script frame and the frame for Save operations</instance>
</examples> 
<seealso>
<see>close</see>
<see>Map</see>
</seealso>
</command>

<command cmd="outlist"> 
<description> (Technical, now OBE) If the packing has a
	"red chain" (mainly in multiply connected settings), this finds 
	the chain of edges on the outside (right-hand side) of the 
	red chain. 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 
	red chain data are computed automatically after changes
	in combinatorics, 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 there is 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 = vert flower, VZ = circle center,
	     XYZ= 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,
	     FDZ = dual circle center, FDR = dual cirlce radius
	   - for edges: EI = end indices, EDZ = dual edge endpoints,
	     EDI = dual edge indices (face indices)
	        (EC = color), (EL = actual length), (ER = intended length) (some of these are not yet implemented)
	   - general: Mob = Mobius transformations, specified by label
	     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 ", \\ for single \.

</description>	
<examples>
<instance text="output %centers\nC=[ :: VZ 'quote'\n'quote' :: b :: ] -f dummy.m">	creates matlab file 'dummy.m' with 2 x n matrix C of centers for boundary vertices.
</instance>
</examples>
</command>

<command cmd="overlay" flags="-q{q} {options}">
<description> This command displays circles and other 
	objects from the active packing on the screen for packing 'q'. 
	It is not sophisticated; differences in geometry and/or screen 
	settings may complicate things. The 'options' are the norma 
	display options.
	command.
</description>
<examples>
<instance text="overlay -q2 -cf b"> displays filled boundary circles
of the active packing on the canvas for packing p2</instance>
</examples>
<seealso>
<see>disp</see>
</seealso> 
</command>	     

<command cmd="pair_mob" flags="[-1] {label}">
<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..}".
	The side-pairing Mobius transformations are labeled by letters,
	'a', 'b', etc. and their inverses, 'A', 'B'.. (See the 'Mobius'
	frame.) and these are used when you want to apply one of these
	Mobius transformations.
</description>
<options>
	<opt flag="-1"> indicates the inverse transform (edge-pairing 
	in opposite direction).</opt>
</options>
<examples>
<instance text="pair_mob B"> applies side-pairing 'B' to the packing; the
	user must do any desired redrawing.
</instance>
</examples>	 
<seealso>
<see>Mobius</see>
<see>set_Mobius</see>
</seealso>
</command>

<command cmd="path_construct" flags="[options] {v1 v ..}">
<description>This is a specialize command for setting the
	'Vlist' of vertices defining an edge path.	
	Both options require initial vertex v1, then construct the
	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.</opt>
</options>
<examples>
<instance text="path_c -i 23 57 3 3 3 ...">In a hex packing, this defines 
		a combinatorially straight path.</instance>
</examples>		
<seealso>
<see>set_Vlist</see> 
</seealso>
</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="pave" flags="{v}">
<description>In working with 'tilings' in CirclePack it is often the
    case that the 'tiles' (combinatorial polygons) are the
    flowers of selected vertices, i.e. their 'barycenters'. This command
    seeds a tiling with a given vertex 'v' (defaulting to the active vertex
    or to 'alpha') as the
    barycenter of the initial tile, then defines the rest of the tiling
    by accretion of neighboring flowers as additional tiles. The results
    are stored in the packing's 'TileData', used for example, to display
    tiles. 

Note that the process can be foiled by combinatorics, but works well 
when the combinatorics were intended as the basis of a tiling, as 
with the 'pentagonal' cases among the 'create' options.
</description>
<seealso>
<see>create</see>
</seealso>
</command>


<command cmd="pdata">
<description> The information in the "Pack Info" frame can be outdated;
	this command updates it. There is also an "update" button in the frame
	itself.
</description>
</command>


<command cmd="perp_pack" flags="[k]">
<description> This packing routine applies only to combinatorial
    closed discs. This converts the packing to euclidean and 
    computes a univalent circle packing in the plane whose 
    boundary circles are perpendicular to the unit circle (their
    centers are slighly outside the unit disc). The method involves
    doubling the complex, repacking and normalizing on the sphere,
    projecting to the plane, and reaping the resulting radii and
    centers. Because the packing computation is on the sphere,
    one cannot repeatedly repack, so one may want to set a larger
    'k' for the number of repack cycles.
</description>
<seealso>
<see>repack</see>
<see>max_pack</see>
<see>set_cycles</see>
</seealso>
</command>


<command cmd="perron" flags="-[udUD] {n}">
<description> (Technical) Apply directed 'Perron' packing algorithms in  
	hyperbolic or euclidean cases without overlaps, n passes. This is
	not intended for speed, but rather to assure monotonicity of radii.
	The 'upward' Perron method was introduced by Beardon and Stephenson,
	and is based on an algorithm suggested by Bill Thurston in his 1985
	lecture; the 'downward' Perron method was used by Phil Bowers and
	is particularly helpful in the context of branching. The options are
	'u' (resp 'd') for upward (resp downward) only (radii can only go up 
	(resp down), possibly ending with a 'superpacking' (resp 'subpacking')
	label. 'U'(resp 'D') means, up then down (resp down then up). 
	
	Perron computations us "uniform neighbor" computations and hence
	should avoid overshoot --- that is, downward changes in radii
	for a superpacking should result in a superpacking, and reverse
	for upward.
	
	Given enough cycles, 'U' and 'D' should end with the same packing label.
	NOTE: a 'superpacking' (resp 'subpacking') label has anglesums less than
	or equal to aims (resp greater than or equal) for all circles subject to 
	change (typically, all interiors).
	Deficiencies, up and down, are reported in the message window.
</description>
<options>
	<opt flag='u'> upward (only) Perron</opt> 
	<opt flag='U'> up then down Perron</opt> 
	<opt flag='d'> downward (only) Perron</opt> 
	<opt flag='D'> down then up Perron</opt>
</options> 
</command>	 

<command cmd="polypack" flags="-[o] {w ..}">
<description>
Given 3 or more boundary vertices 'w', convert this packing to euclidean
and repack/layout/display as a polygon with equal angles at the designed
boundary vertices. Normalize so first corner is on the unit circle, rotate
so first 2 vertices are in horizontal alignment, right to left.
</description>
<options>
    <opt flag='o'> use 'old reliable' versus GOpack algorithm</opt>
</options>
<seealso>
<see>repack</see>
<see>GOpack -bn {v1...vn}</see>
</seealso>
</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. 

	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. 
</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="-b"> draw bary-coord defined paths, generally grid lines (eucl only)</opt>
    <opt flag="-bs"> draw bary-coord defined paths, generally stream lines (eucl only)</opt>
	<opt flag="-g"> display the current "path", if available.</opt>
	<opt flag="-u"> draw unit circle</opt>
	<opt flag="-W {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>
<seealso>
<see>screendump</see>
</seealso>
</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' itself is called.)
</description>
<seealso>
<see>cookie</see>
<see>set_poison</see>
</seealso>
</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="prune">
<description>If the active packing has a DCEL structure,
	then this command will prune any boundary vertices
	which do not have an interior neighbor.
</description>
</command>
	
<command cmd="puncture" flags="[{v}] [-f {f}]">
<description>Remove one vertex v or one face f from the packing's 
    complex; default is vertex. The vertex/face must be at
    least two generations from the original boundary vertices,
    and will result in a new boundary component. Centers and
    radii of the packing are not changed. If a vertex is removed, 
    then various lists are adjusted for index changes. If a face
    is removed, 'flist' is emptied since since face indices will
    change. If the operation fails, the packing should not be
    affected. 
</description>
<options>
<opt text="{v}"> one interior vertex</opt>
<opt text="-f {f}"> one face</opt>
</options> 
<examples>
<instance text="puncture"> by default, puncture vertex of maximal index</instance>
<instance text="puncture 4"> puncture vertex 4</instance>
<instance text="puncture -f 4"> puncture face 4</instance> 
</examples>
<seealso>
<see>add_ideal</see>
<see>rm_cir</see>
<see>rm_bary</see>
<see>rm_edge</see>
<see>rm_quad</see>
</seealso>
</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).
</description>
<seealso>
<see>get_data</see>
</seealso>
</command>

<command cmd="pwd">
<description>Give the working directory. You can use 'cd'
	to change it.
</description>
<seealso>
<see>cd</see>
</seealso>
</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="quality" flags="-n -[ae {v..}] -[o {f..}] -[vr {e..}]">
<description> Selection of packing "quality" measurements. Default is
    worst 'visual' error among given edges (default to all). This 
    applies only to euclidean or hyperbolic packings (as do some other 
    options) and requires both centers and radii; for each edge 
    consider |length-desired length|/(smallest rad) where desired is 
    length based on eucl radii and overlap, while length is actual 
    distance based on euclidean centers. The call returns
    the worst error and reports results in 'Messages'. Default to 'all'
    edges. TODO: other options should be entertained.
</description>
<options>
    <opt flag="-a {v..}"> Worst (and average) angle sum errors; doesn't 
    need centers</opt>
    <opt flag="-r {e..}"> Worst relative distance error in native 
    geometry (versus '-v' option)</opt>
    <opt flag="-n"> first vertex encountered with radius/center 
    NaN (not-a-number), else -1</opt>
    <opt flag="-o {f..}"> first face encountered with a face with reverse 
    orientation, else -1</opt>
    <opt flag="-e {v..}"> Not yet implemented: Worst relative error among 
    'effective' radii (compared to actual radii)</opt>
    <opt flag="-v {e..}"> Worst 'visual' error (eucl relative distance
    error); eucl/hyp packings only</opt>
</options>      
<examples>
<instance text="qual ">Worst visual error on all edges</instance>
<instance text="qual -e b">Worst relative error over on boundary 
edges</instance>
<instance test="qual -a i">Worst angle sum error at interior 
vertices</instance>
</examples>
</command>
    

<command cmd="quit">
<description>
	This exits CirclePack. CAUTION: no confirmation requested, all data is lost.
	It is safer to use 'exit'.
</description>
<seealso>
<see>exit</see>
</seealso>
</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="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. 
	Then 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. (Note: this call depends on having the C++ libraries
	installed.
</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 triangulate 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|. The four corner vertices, 
			     counterclockwise from upper left, are 1, 2, 3, and 4. If a is negative, then don't add boundary
			     points </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 "packing" directory name is prepended to the filename. 
	See the "Help -- Formats" tab for the format of packing *.p and
	*.q files; for OFF *.off files, see the web; files can simply
	consist of lines, one for each face, containing indices.
	
	NOTES:
	
	The packing may have been saved in gzip form, so if 'filename' 
	is not found, then there is attempt to read 'filename.gz' instead.

    See 'delaunay' for reading packings of the sphere as
	lists of triangles.
	
	Files in OFF (Open File Format) form (3D, connectivity data,
	and possibly color data) can be read in. Default radii are set 
	and x,y,z data are stored in 'xyzpoints'.
	
	CAUTION:  No confirmation is requested for command-line arguments,
	so the current data in the active pack will be lost.
	
</description>
<seealso>
<see>Read</see>
<see>delaunay</see>
</seealso>
</command>


<command cmd="Read" flags="{filename}">
<description>
	Same as "read", except default directory is not prepended 
	to the filename, so an explicit path (possibly starting '~/')
	is allowed.
</description>
<seealso>
<see>read</see>
</seealso>
</command>

<command cmd="read_CT" flags="[-q{p}] {filename}">
<description>
	Added in 2017 to help simulate 2D "glass" with Mahdi Sadjadi
	and "jammed" configurations with Varda Faghir. Input files 
	provide a "bouquet", cclw flowers for each vertex (which is
	closed up, if necessary). This code	reads these bouguets
	and creates circle packing combinatorics for a closed surface
	and then via the 'pave' command, creates associated 'TileData'. 
	Note in particular, that every tile,
	even triangular, gets a barycenter added to it. The 'mark' is
	set to 1 for the original data vertices. If the dual graph has all 
	triple points, then the optional '-q{x}' flag will further
	create, pack x, a simple packing obtained from the tiling 
	with a circle for each tile. The idea is that its dual 
	graph may be better approximation of their result than 
	the formal tiling (which has circles surrounding each tile).
</description>
<options>
	<opt flag="-q{p}"> Create the packing with tiling in the
	parent packing, but create a corresponding simple circle
	packing in pack p.</opt>
	<opt flag="-s"> Read from the current script.</opt>
</options>
<seealso>
<see>Read_CT</see>
</seealso>
</command>


<command cmd="Read_CT" flags="[-q{p}] {filename}">
<description>
	Same as "read_CT", except default directory is not prepended 
	to the filename, so an explicit path (possibly starting '~/')
	is allowed.
</description>
<seealso>
<see>read_CT</see>
</seealso>
</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="-[as] {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
	and replaces or, optionally, appends to the existing global 'ClosedPath'.
</description>
<options>
<opt flag="-s"> reads from the script </opt>
<opt flag="-a"> read into 'ClosedPath' or append if it already exists.</opt>
</options>
<seealso>
<see>infile_path</see>
</seealso>
<examples>
<instance text="read_path -as mypathname"> read 'mypathname' data from the
script and append it to 'ClosedPath'.</instance>
</examples>
</command>

<command cmd="Read_path" flags="{filename}">
<description>
	Same as "read_path", except default directory is not prepended 
	to the filename, so an explicit path (possibly starting '~/')
	is allowed.
</description>
</command>

<command cmd="renumber">
<description> If the active packing has a DCEL structure, this
	carries our a renumbering. Namely, vertices will be indexed
	moving outward from alpha=1, picking up all interior vertices,
	and wrapping up with vertices around the red chain. Data
	should be maintained, though lists are lost.
</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>
<seealso>
<see>double</see>
</seealso>
</command>

<command cmd="red_from_elist">
<description>
	OBE. See 'newRed' 
	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="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 
	k (from 1 to 100,000), else it defaults to that the number
	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 to this in presence of 
		nontrivial inversive distances)</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.
	
<seealso>
<see> max_pack</see>
<see> polypack</see>
<see> GOpack</see>
<see> perp_pack</see>
</seealso>	 
</command>

<command cmd="ring" flags="{v..}">
<description>
	OBE: see "frackMe"
</description>
<seealso>
<see>frackMe</see>
</seealso>	
</command>

<command cmd="rld">
<description>
	Convenience command for 'repack', 'layout', and 'disp -wr'
</description>
</command>

<command cmd="rlsd">
<description>
	Convenience command for 'repack', 'layout' using schwarzians, and 'disp -wr'
</description>
</command>

<command cmd="rm_bary" flags="{v..}">
<description>
    Given a list of interior vertices (default to all), remove 
    those which are interior and degree 3 from the packing. The
    outcome can depend on order: some may not be eligible for
    removal, e.g., they have a neighbor of degree 3, or some may
    appear eligible at first, but not after some neighbors are
    removed. So the outcome can depend on the order of the vertex 
    list. (We stick to the original list of vertices --- that is,
    we do not add vertices for removal if they become 
    eligible only because others have been removed.)
</description>
<seealso>
<see>rm_edge</see>
<see>rm_quad</see>
<see>rm_cir</see>
</seealso>
</command>

<command cmd="rm_cir" flags="{v..}">
<description>
	Given a qualifying boundary or interior trivalent 
	circle; other conditions are checked so that the 
	remaining complex is legal.
</description>
<seealso>
<see>rm_bary</see>
<see>rm_edge</see>
<see>rm_quad</see>
<see>puncture</see>
</seealso>
</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>
<seealso>
<see>rm_cir</see>
<see>rm_quad</see>
</seealso>
</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>
<seealso>
<see>rm_edge</see>
<see>puncture</see>
</seealso>
</command>


<command cmd="rotate" flags="{a}">
<description>	The active pack (hyp or eucl) is rotated counterclockwise about 
	the origin by a*PI radians.
</description>
<examples>
<instance text="rotate -.5"> rotate clockwise about the origin by Pi/2.</instance>
</examples>
<seealso>
<see>norm_scale</see>
</seealso>
</command>


<command cmd="scale" flags="[t]">
<description>
	The active pack is scaled by the map z -> t*z, where t is a
	positive real factor. Default is t = 1.1. NOTE: In the hyperbolic case, 
	a circle will remain unchanged if the scaling would put it outside 
	the unit disc, so packings can be disrupted.
</description>
<seealso>
<see>path_Mobius</see> 
</seealso>
</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>
<seealso>
<see> set_aim</see>
</seealso>
</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="sch_data" flags="[d] [-rc] N -a {filename}">
<description>
	For single d-flower, append N lines to
	'filename', wach a string of d reals which are the 
	schwarzians for the spokes of a d-flower repacked with 
	random boundary radii in range [.33333, 3.0]. 
	The "-r" flag says to replace d in each of the N runs with a
	random integer in range [3,15]. The "-c" flag says to 
	randomly set the center's radius along with the petals.
	Our aim is data for studying packing criteria for Schwarzians
	of single flowers. This is subtle. The Schwarzians could be
	associated with center and petal radii, but the flower does
	not close up (e.g. use "-c" flag for examples).
</description>
<options>
<opt flag="-r"> randomize the degree d of the flower, d in [3,15]</opt>
<opt flag="-c"> randomize the center's radius along with the petals</opt>
</options>
<examples>
<instance test="sch_data 6 1000 -a hex_sch.data"> Store 1000 random
hex flower schwarzians</instance>
<instance test="sch_data -rc 1000 -a hex_sch.data"> Store 1000 random
flower schwarzians with random degrees and random central radii</instance>
</examples>
</command>


<command cmd="sch_report" flags="-[[ce]{flags}] {..}">
<description>
	(Developmental) To garner various data about schwarzians to 
	try to understand them. 
</description>
<options>
<opt flag="-c"> color code all circles, blue-to-red based on sum of
schwarzians for edges, store all colors</opt>
<opt flag="-c{flags} [{v..}]"> display flags may call for drawing 
selected circles</opt>
<opt flag="e"> color code and draw all edges, blue-to_red base on
their schwarzians</opt>
<opt flag="e{flags} [{e..}]"> color code all edges, but use display flags
to draw selected edges</opt>
</options>
<seealso>
<see>set_schwarzian</see>
<see>dual_layout</see>
</seealso>
<examples>
<instance text="sch_report -c"> set all the colors, but don't draw</instance>
<instance text="sch_report -ccnt4 {v..}"> set all, draw selected in color,
labeled, thickness 4</instance>
<instance text="sch_report -et3 {e..}"> compute all edge colors, draw selected,
thickness 3</instance>
</examples>
</command>


<command cmd="screendump" flags="[-m -d -b -n]">
<description>
	Saves a screen dump of the active packing. See tab 'ScreenShots'
	where thumbnails and their names are displayed. If any flag other
	than 'm' is given, then the command only sets the specified info 
	and does not do a screen dump --- another call is needed for this.
</description>	
<options>
	<opt flag="-m"> This dumps the side-by-side canvasses of "Map" frame</opt>
	<opt flag="-d {dir}"> set ScreenShot's 'Dir' element, no dump. May use '~/' 
	   for home directory</opt>
	<opt flag="-b {base}"> set ScreenShot's 'Base name' element</opt>
	<opt flag="-n {n}"> set file name counter</opt>
</options>
<seealso>
<see>post</see>
</seealso>
</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>
<examples>
<instance text="script">absent filename, a dialog box should appear</instance>
</examples> 
</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". (Limit is 1000 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 to which some
	actions apply to when no other vertex is indicated. One can also
	reference it as "v" in commands. The active	vertex can be set by 
	clicking left mouse on its circle in the active canvas. 
</description>
<examples>
<instance text="set_active 20"> sets 20 as the active vertex</instance>
<instance text="disp -cf v"> if 20 is active, this displaced it as 
a filled circle</instance> 
</examples>

</command>

<command cmd="set_aim" flags="[{a v..} -[cdx%]">
<description>
	The "aim" of a vertex (circle) is the angle sum which it's circle
	attempts to achieve during "repack" computations.  In its basic
	form, the 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. Other forms set aims to default, current, or
	values depending on 3D locations associated with the vertices.
</description>
<options> (one of)
	<opt flag="-a {v..}"> adjust by adding given amount, x in [-0.1,0.1]</opt>
	<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="-% a {v..}"> add real number a(*PI) to currently set aim </opt>
	<opt flag="-f a {v..}"> adjust int aim toward 2pi by factor a in (0,1] </opt>
	<opt flag="-x {v..}"> set aims based on 3D data in 'xyzpoint' (if available)</opt> 
</options>
<seealso>
<see>scale_aims</see>
</seealso>
</command>

<command cmd="set_blist" flags="[fi] {z..}, [f b1 b2]">
<description>
	Store list of 'BaryPoint' objects associated with the active packing.
	(Previous contents are	discarded.)
	
	A 'BaryPoint' specifies a face f along with barycentric coordinates 
	for a point	in f. Each face has an ordered list v1, v2, v3 of vertices
	and the barycentric coords are associated with these in order. Typically
	two coords in [0,1] are given (for v1 and v2) and the third is 1 minus
	the sum of these.  
	
	Angle-based coords for interstices treat the faces incircle as a 
	hyperbolic disc, the three tangency points as boundary points. A point
	in the interstices forms angles a, b, c when geodesics are drawn to 
	the tangency points. The barycoords are (1-a/pi), (1-b/pi), (1-c/pi).
	
</description>
<options>
<opt flag="{f} {b1} {b2}"> (default) Sets barycentric coordinates 'b1','b2', and '1-b1-b2'
for face 'f'.</opt>
<opt flag="f {z..}"> get face barycentric coordinates for the points {z..}
relative to the faces containing z.</opt>
<opt flag="i {z..}"> get angle-based barycentric coords for points {z..}
in any interstices to which they belong.</opt>
</options>  
<examples>
<instance text="set_blist 10 .5 .3333 34 .0 1.0"> removes the former list, 
enters two BaryPoints</instance>
<instance text="set_blist blist 10 .5 .33333"> appends these to the existing 'blist'
</instance>
<instance text="set_blist f Zlist"> create BaryPoints for the faces containing the points in 'Zlist'
</instance>
</examples> 
<seealso>
<see>set_Blist</see>
</seealso>
</command>

<command cmd="set_Blist" flags="{v..}">
<description>
	Store list of global 'BaryPoint' objects (irrespective of packing).
	(Previous contents are	discarded.)
	
	See description in 'set_blist'.
</description>
<seealso>
<see>set_blist</see>
</seealso>
</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}] -[mx] {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. Note that spherical centers are 
	in polar coordinates, so complex z represents (theta,phi).
</description>
<options>
	<opt flag="-m"> Transform the current center according to the
	function 'Function Frame' </opt>
	<opt flag="xyz"> Use stored xyz coords to set center</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="{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. See 'disp' for the flags. 'Disp' 
</description>
<seealso>
<see>disp</see>
<see>Disp</see>
</seealso>
<examples>
<instance text="set_disp_flags -w -cf">clear screen, show filled circles on default redraw
</instance>
</examples> 
</command>

<command cmd="set_display" flags="[-m]">
<description>
	Adjust the sizes/positions of the active canvas and
	the paired canvasses to better fit the current display
	area. If too large, reduce in size. Changes in size 
	can also be specified in the "Configuration" frame, with
	values that will then be used on startup. (This command
	does not reset those values.) 
</description>
<options>
	<opt flag="-m {x}"> Set canvases to x * maximum available size</opt>
</options>
<seealso>
<see>chgS {n}</see>
<see>chgP {n}</see>
</seealso>
<examples>
<instance text="set_display -m .5"> Reset to 1/2 of the maximal size</instance>
</examples>
</command>

<command cmd="set_dump_format" flags="[format]">
<description>
	Resets the format for 'screendump'. The choices currently are "jpg",
	"gif", "png", "bmp", "wbmp", with "jpg" the default on startup.
</description>
<examples>
<instance text="set_dump_format GIF"> Screendumps saved as "gif" files</instance>
</examples>
<seealso>
<see>screendump</see>
</seealso>	
</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>
<examples>
<instance text="set_elist 1 3  75 4  17 3"> removes the former list, 
enters these pairs in order</instance>
<instance text="set_elist elist 1 3  75 4  17 3"> appends these to the existing 'elist'
</instance>
</examples> 
<seealso>
<see>set_Elist</see>
</seealso>
</command>


<command cmd="set_Elist" flags="{e..}">
<description>
	Same as above, only stores indices in utility "Elist".
	(Validity check against active pack.)
</description>
<examples>
<instance text="set_Elist 1 3  75 4  17 3"> removes the former list, 
enters these pairs in order</instance>
<instance text="set_Elist Elist 1 3  75 4  17 3"> appends these to the existing 'Elist'
</instance>
</examples> 
<seealso>
<see>set_elist</see>
</seealso>
</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>
<examples>
<instance text="set_flist 1 75 3"> removes the former list, 
enters these in order</instance>
<instance text="set_flist flist 1 75 3"> appends these to the existing 'flist'
</instance>
</examples> 
<seealso>
<see>set_Flist</see>
</seealso>
</command>


<command cmd="set_Flist" flags="{f..}">
<description>
	Same as 'set_flist', only stores face indices in a global utility "Flist".
	(No validity check of a face indices against active pack.)
</description>
<examples>
<instance text="set_Flist 1 75 3"> removes the former list, 
enters these in order</instance>
<instance text="set_Flist Flist 1 75 3"> appends these to the existing 'Flist'
</instance>
</examples> 
<seealso>
<see>set_flist</see>
</seealso>
</command>


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


<command cmd="set_glist" flags="[options] {f1 f2 ..}">
<description>
	Store dual edges associated with the active pack; previous 
	contents are discarded. A dual edge	(oriented) is given as 
	{f,g} where f and g are indices of faces sharing an edge. 
	A dual edge {0,f} represents a root, e.g., in a tree/forest 
	in the dual graph.
	
	If faces {f1 f2 ...} are given, then try to build dual edges:
	If f1 shares an edge with f (the end index of the list's previous
	dual edge) then add {f f1}, else add a root {0,f1}.
</description>
<options>
<opt flag="a {f}">generate the full dual graph starting from face f 
(default to packing firstface).</opt>
<opt flag="R [Ra] {j}">generate a dual chain of redfaces. 'R' for all;
'Ra' for all, but closed up; given {j}, just dual chain along the
index 'j' side among the side-pairings.</opt>
<opt flag="s {f}">generate a spanning tree for the dual graph. If 'f' is
given, use it as the root face and avoid crossing any 'poison' edges. 
Otherwise, based the tree on the packing's
face drawing order.</opt>
<opt flag="?list">various lists (glist, Glist, flist, Flist) may be specified.</opt>
</options>
<examples>
<instance test="set_glist s 10">dual spanning tree starting with face 10</instance>
<instance text="set_glist 5 12 18 7"> list of faces </instance>
<instance text="set_glist glist 5 12 18 7 "> appends these to the existing 'glist'
</instance>
</examples> 
<seealso>
<see>set_Glist</see>
<see>set_poison</see>
</seealso>
</command>


<command cmd="set_Glist" flags="[a] {f1 g1 f2 g2 ..}">
<description>
	Same as 'set_glist", only it stores face indices in a global utility 
	"Glist". (No validity check of a face indices against active pack.)
	See options and examples in 'set_glist'.
</description>
<seealso>
<see>set_glist</see>
</seealso>
</command>


<command cmd="set_grid" flags="-[crg] -[n]">
<description>
	This sets a global vector of paths represented in barycentric 
	coordinates associated with faces of the active packing.
	Current options allow a grid of spokes and circles for
	the unit disc 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, the target packing 
	should have the same complex as the packing used to create the grid.
	(Note: Currently, only available for hyperbolic and euclidean
	packings, and hyperbolic data is converted to euclidean for the
	computations.)
</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="-g"> use current "ClosedPath", if defined.</opt>
	<opt flag="-n"> number of grid lines in each direction.</opt>
</options>
<examples>
	<instance text="set_grid -r -1 -1 1 1 -n 17"> 18 horizontal/vertical lines</instance>
</examples>
<seealso>
<see>disp -b</see>
</seealso>
</command>	


<command cmd="set_hlist" flags="[options] {v w, ..}">
<description>
	Like 'set_elist', except that this is a list of 
	halfedges associated with the active pack; previous 
	contents are discarded. 
</description>
<examples>
<instance text="set_hlist 1 3  75 4  17 3"> removes the former list, 
enters legal halfedges from the list</instance>
<instance text="set_hlist hlist 1 3  75 4  17 3"> appends these to the existing 'elist'
</instance>
</examples> 
<seealso>
<see>set_Hlist</see>
</seealso>
</command>


<command cmd="set_Hlist" flags="{e..}">
<description>
	Same as above, only stores indices in utility "Hlist".
	(Validity check against active pack.)
</description>
<examples>
<instance text="set_Hlist 1 3  75 4  17 3"> removes the former list, 
enters these pairs in order</instance>
<instance text="set_Hlist Hlist 1 3  75 4  17 3"> appends these to 
the existing 'Hlist'</instance>
<instance text="set_Hlist hlist"> appends hlist items to 
the existing 'Hlist'</instance>
</examples> 
<seealso>
<see>set_hlist</see>
<see>set_elist</see>
<see>set_Elist</see>
</seealso>
</command>


<command cmd="set_invdist" flags="[option] {{x} (v w)..}">
<description>
	"Inversive distance" is a conformal invariant. It is a 
	real value d in [-1, infty)	associated with a pair of 
	circles C1 and C2. If C1 and C2 are tangent, then d = 1. 
	If C1 and C2 intersect with exterior overlap angle t, 
	then d = cos(t), so d is in [-1,1). We call it a "deep" 
	overlap if the angle is in (Pi/2,Pi], in which case d 
	lies in [-1,0). In particular, d=-1 means C1 and C2 are 
	internally tangent. Value d > 1 means that C1 and C2 are
	"separated" circles; they don't intersect and are not 
	nested (mutually disjoint interiors). NOTE 1: "distance" 
	as used in "inversive distance"	is not true distance in	
	the metric sense; for example, the triangle inequality
	fails. NOTE 2: inversive distances and overlap angles 
	are independent of the geometry used for the packing. 
	NOTE 3: inversive distances x in [-1,0) (deep overlaps) 
	or in [1,infty)	(separation) can lead to layout	
	incompatibilities; circle packing theory is	most complete 
	when inversive distances are limited to values in [0,1].
	NOTE 4: "conformal invariance" means that d is preserved
	under conformal maps: so if M maps C1 to c1 and C2 to c2,
	then the inversive distance (C1,C2) is the same as the
	inversive distance (c1,c2).
</description>
<options>
	<opt flag="-d"> set to default, 1 (tangency).</opt>
	<opt flag="-c"> set to current measured values.</opt>
	<opt flag="-t  {u}"> truncate inv_distances at upper value u (u > 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 test="set_invdist"> Set all to default</instance>
	<instance text="set_invdist 0.5 7 10"> If {7 10} is an edge, then its overlap 
	angle is set to acos(0.5) = Pi/3</instance>
	<instance text="set_invdist 1.25 i"> The inversive distances for all interior 
	edges are set to 1.25</instance>
</examples>
<seealso>
<see>set_overlaps</see>
</seealso>
</command>


<command cmd="set_Mobius" flags="[options] -[f]">
<description>
	CirclePack maintains a current Mobius transformation. It defaults
	to the identity, but can be set to any other, whether orientation
	preserving (default) or orientation reversing ('-f' flag). If
	there are no flags, then default is to read in 8 real numbers, real 
	and imaginary parts for the standard four complex entries a, b, c, 
	and d. Alternatives are based on halfedge chains defining closed
	face chains: flags are passed to creating the halfedge chain, as
	in 'set_hlist'. 
</description>
<options>
    <opt flag="-xyzXYZ x y z X Y Z"> Mobius mapping one triple of 
    complex numbers to another</opt>
    <opt flag="-[]"> holonomy along halfedge chain built using these flags;
    e.g., '-R 3' for redchain side 3.</opt>
	<opt flag="{a.re a.im b.re b.im c.re c.im d.re d.im flip}"> create explicitly</opt>
</options> 
<examples>
	<instance text="set_Mobius 0.0 0.0 1.0 0.0 1.0 0.0 0.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>
<seealso>
<see> set_hlist</see>
</seealso>
</command>

 
<command cmd="set_over" flags="[option] {{x} (v w)..}">
<description>
	Circles that intersect are said to 'overlap' with an angle
	'theta' in the range [0,Pi], with 0 being external tangency, 
	Pi/2 being orthogonality, and Pi being internal tangency
	(one circle interior to the other). 'theta' measures the 
	"external angle" of overlap, the angle between the tangent
	lines to the two circles at a point of intersection and is
	related to the "inversive distance" 'invdist' between the 
	circles	by invdist=cos(theta). You can set overlaps with a
	call to 'set_invdist', but then you need to know the cosine
	of the intended angle. The 'set_overlap' call is thus helpful
	if you want to specify 'theta' directly: namely, you give
	parameter 'x' given for convenience by x=theta/Pi. I.e.,
	'theta' is x*Pi. 
</description>
<examples>
<instance text="set_overlap 0.0 6 12"> specifies that circles 6
and 12 be tangent (equivalent to "set_invdist 1.0 6 12")
</instance>
<instance text="set_overlap 0.333333 17 4"> specifies angle Pi/3
between 17 and 4 (equivalent to "set_invdist .5 17 4")
</instance>
</examples>
<seealso>
<see>set_invdist</see>
</seealso>
</command>


<command cmd="set_path_text" flags="{text}">
<description>
	CirclePack can store a parameterized curve description in
	the "Function" frame using a real variable t in [0,1]; 
	(use of 't'	is required). The "Set Closed Path" button
	will store the closed path using this description.
</description>
<examples>
<instance text="set_path+text (1+exp(i*pi*2.0*t))^2">
</instance>
</examples>
<seealso>
<see>set_function_text</see>
<see>disp -g</see>
<see>set_path</see>
</seealso>
</command>

<command cmd="set_path" flags="[{text}]">
<description>This command is for setting the closed path in the
	complex plane which is then available for various uses in
	display or packing manipulations. Used without text, it
	gets the parameterized path description entered in the 
	"Function" frame. Else it uses the given text for that
	purpose. CAUTION: in the "Function" window the variable must 
	be 'z' but in the parameterized paths section it takes real 
	values in the interval [0,1] and the path will be closed upon 
	creation.
</description>
<options>
<opt text="{text}">complex path description using variable 'z' in [0,1]</opt>
</options>
<examples>
<instance text="set_path exp(i*2.0*pi*z)">Stores the unit circle as the closed path
</instance>
<instance text="set_path (1-z)*(1-i)+z*i">Stores the segment from 1-i to i (and closes it)
</instance>
</examples>
<seealso>
<see>set_path_text</see>
<see>disp -g</see>
</seealso>
</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
	"layout -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. 
</description>
<examples>
<instance text="set_plot_flags 1 a"> 
	reset all plot flags to 1</instance>
</examples>
</command>

<command cmd="set_poison" flags="[-e {e..}] {v..}">
<description>
	'Poison' vertices and edges of the active packing are 
	typically used to help define subcomplexes, as with
	the 'cookie' command or when defining spanning trees in
	the dual graph. Eg, by setting a collection V of vertices
	or E of edges to poison, selecting a 'seed' vert w which 
	is interior and	not in V or E, and running 'cookie', one 
	can cut out the	largest connected complex containing w and 
	stopping at the poison edges or vertices.
</description>
<options>
<opt flag="-v">(default) vertices</opt>
<opt flag="-e">edges</opt>
</options>
<seealso>
<see>cookie</see>
<see>pre_cookie</see>
</seealso>
</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>
<seealso>
<see>screendump</see>
</seealso>
</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>
<seealso>
<see>adjust_rad</see>
<see>set_random</see>
</seealso>
</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 by exp(r), r chosen from Gaussian, mean 0, standard deviation x/100. 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>
<seealso>
<see>adjust_rad</see>
<see>set_rad</see>
</seealso>
</command>


<command cmd="set_schwarzian" flags="-[x] {v w ...}]">
<description>
	Compute and store the intrinsic schwarzians for given edges, 
	defaulting to 'all'. See 'Schwarzian.java' for more details
	and the PackExtender 'SchwarzMap.java' for related methods.
	If double x is given, then set specified schwarzians to x. 
	Else compute the schwarzians using current radii. This 
	"intrinsic" schwarzian is based on 'baseMobius' transforms and 
	with layoutOrder can be used to layout a packing determined 
	up to Mobius transformation by the layout of the first face. 
	(Layout works in spherical or euclidean geometry, but not 
	hyperbolic.) 
</description>
<options>
<opt flag="{v w ...}"> Set based on current radii.</opt>
<opt flag="-s {x} {v w ...}"> schwarzians set to double value x</opt>
</options>
<seealso>
<see>dual_layout</see>
<see>sch_report</see>
</seealso>
</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 set to display packings on the sphere; 
	in particular, this is a projection to the 2D screen of the
	unit sphere positioned in a user-defined way. The coordinates 
	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="-N"> look down at the north pole (i.e., the origin),
	x-axis to the right</opt>
	<opt flag="-S"> look up at the south pole (i.e., infinity),
	x-axis to the right</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 display time and output space.
</description>
</command>


<command cmd="set_tlist" flags="[options] {t1 t2 ..}">
<description>
	Store lists of tile indices for tilings associated with the 
	active pack; previous contents are discarded. Tilings are 
	combinatorial structures associated with packings, generally 
	via the 'ConformalTiling' pack extender; data is stored in 
	the 'tileData' element of a	packing. Tiles are indexed from 1; 
	they know the list of vertices that define them, associated 
	colors, etc., much like	the triangular faces of the usual carrier.
	With a 'ConformalTiling' (CT) extender, there can be dual, quad, and
	white/gray tiling structures as well, and with "subdivision rules"
	there can be 'gradedTileData' containing a tree of tiling
	structures at various subdivision depths.
</description>
<options>
<opt flag="-D...">(preceeds other flags) apply to associate "dual" tiling, if available with CT extender</opt>
<opt flag="-Q...">(preceeds other flags) apply to associate "quad" tiling, if available with CT extender</opt>
<opt flag="-B">tiles chosen based on list of 'baryVert' indicies (indicies of center circles)</opt>
<opt flag="-m">tiles with given marks</opt>
<opt flag="-M">(when 'gradedTileData' is present) tiles with given mark whose parents in the
tree also have that mark</opt>
<opt flag="-i">tiles entirely in the interior</opt>
<opt flag="-b">tiles hitting the boundary</opt>
<opt flag="-Iv"> tiles incident to one of given vertices</opt>
<opt flag="-t {t..}">tiles having one of the given "types" (must be last flag sequence)</opt>
<opt flag="-d{x}">(when 'gradedTileData' is present) depth 'x' in subdivision structure</opt>
<opt flag="-c {t..}">(when called via "|CT| set_tlist") this gives the list of children tile indices</opt> 
</options>
<examples>
<instance text="disp -Tf tlist"> Display tiles in the list as filled</instance>
<instance text="|ct| set_tlist -c 2 7"> Loads indices of child tiles (in a subdivions scheme) of tiles 2 and 7</instance> 
</examples>
<seealso>
<see>set_Tlist</see>
</seealso>
</command>


<command cmd="set_Tlist" flags="[options] {t1 t2 ..}">
<description>
	Same as 'set_tlist", only it stores tile indices in a global utility 
	"Tlist". (No validity check against the active pack.)
	See options and examples in 'set_tlist'.
</description>
<seealso>
<see>set_tlist</see>
</seealso>
</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_var" flags="{name} {str}">
<description>Alternate command for the ':=' operation of
creating named variables with string values. If 'str' has the
form "{..cmd..}" with brances, then the inside is taken as a
command and returns some string value --- perhaps a number that
the command generates. The 'set_var' command also includes
creation of "SLIDERS" for the Pack Info -> Variables tab. 
See ':=' for more examples. 
</description>
<examples>
<instance text="set_var R 2.3"> Variable 'R' is created with value 2.3</instance>
<instance text="A:=[SLIDER -m 2 -M 6 -cmd [h] -ftn z*pi] 2.0"> Variable 'A' is 
	created with a slider, min/max 2 to 6, command '[h]', values multiplied
	by Pi.</instance>
<instance text="LA:={aspect 11 9 13 2}"> Run the "aspect" command with the given
    corner vertices, get a double, set variable "LA" to that value (as a string).
    </instance> 	
<instance text="write -s packing[_N].p"> Suppose variable N is "3.0", then this
    command saves to the file named 'packing3.p'; so '3.0' converts to integer
    and brackets are removed.</instance>        
</examples>
<seealso>
<see>:=</see>
</seealso> 
</command>

<command cmd="set_vertexMap" flags="-[a] {e ..}">
<description>Each packing can hold a "vertexMap", which is
just a list of pairs of indices. This command allows the
user to set or append to this list. Typically, a pair "{v,w}"
means that vertex 'v' of the packing is somehow associated
with some index 'w', possible, e.g. a vertex in some other
packing. For instance, if the packing is cut from another,
'w' might be the index of a circle 'v' in the original
parent packing. (Note, though, that the vertexMap is often 
used internally by CirclePack for other purposes, so care
should be taken.) 
</description>
<seealso>
<see>?vertexMap</see>
</seealso> 
</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>
<examples>
<instance text="set_vlist 10 7 33"> removes the former list, 
enters these in order</instance>
<instance text="set_vlist vlist 10 7 32"> appends these to the existing 'vlist'
</instance>
</examples> 
<seealso>
<see>set_Vlist</see>
</seealso>
</command>


<command cmd="set_Vlist" flags="{v..}">
<description>
	Same as above, only stores indices in utility "Vlist".
	(Validity check against active pack.)
</description>
<examples>
<instance text="set_Vlist 1 75 3"> removes the former list, 
enters these in order</instance>
<instance text="set_Vlist Vlist 1 75 3"> appends these to the existing 'Vlist'
</instance>
</examples> 
<seealso>
<see>set_vlist</see>
</seealso>
</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="slider" flags="-[ARS] -[cmarux] {cmds} {..}">
<description>
	CirclePack allows the user to create a frame with multiple 
	sliders to control values associated with the packing using
	the mouse. Currently, 'angle sums' , 'radii', and edge 
	'schwarzians' (which must be set in advance by the user) 
	can be displayed/controlled; a single slider frame of each type
	is allowed for each packing. Slider ranges for radii and
	schwarzians are initialized to go from half the quantities 
	intiial minimum value to twice its initial maximum value, but
	can be adjusted later.
	
	Optionally, specified 'change' commands can be executed when a 
	value is changed, 'motion' commands can be executed when 
	the mouse passes over a slider's label, and/or an optional
	command can be executed by clicking a button. On initiation, 
	substring 'Obj'	in motion, change, or optional command
	strings is replaced by '_Obj' so that the command can be
	applied to the appropriate object (vertex or dual edge).
</description>
<options>
<opt flag="-A {v..}"> The sliders display selected angle sums,
usually from 0 to 3.0 (all values are multiplied by pi)</opt>
<opt flag="-R {v..}"> The sliders control specified radii</opt>
<opt flag="-S {f g..}"> The sliders control specified edge schwarzians</opt>
<opt flag="-c ''cmds''"> Optional commands to be executed when a
value is changed; here 'cmds' is a string of text enclosed by double
quotes</opt> 
<opt flag="-m ''cmds''"> Optional commands to be executed when a
a mouse moves across a slider; here 'cmds' is a string of text 
enclosed by double quotes</opt>
<opt flag="-o ''cmds''"> Optional commands to be executed by user
with a button click; here 'cmds' is a string of text 
enclosed by double quotes</opt>
<opt flag="-a {..}"> Add a slider for a new object</opt>
<opt flag="-r {.}"> Remove an individual object</opt>
<opt flag="-d"> Download data from parent packing to the sliders</opt>
<opt flag="-l {x}"> Update slider range minimum</opt>
<opt flag="-u {x}"> Update slider range maximum</opt>
<opt flag="-x"> Destroy this frame</opt>
</options>
<examples>
<instance text="slider -R {v...}"> sliders for selected vertices</instance>
<instance text="slider -R -c ''rld'' a"> sliders for all radii, execute 'rld'
on change in any slider</instance>
<instance text="slider -S -m  ''disp w -c -et5c5 Obj'' {f g ..}"> sliders 
for selected edge schwarzians, which motion in slider causing redisplay
of circles with that particular edge displayed.</instance>
</examples>
<seealso>
<see>set_schwarzian</see>
<see>dual_layout</see>
</seealso>
</command>
	

<command cmd="slit" flags="{v..}">
<description>
	Slit a complex open, typically along the given string of vertices,
	creating clones of the vertices to give the slit two sides. 
	The first vertex may be boundary or interior, thereafter, must be interior. 
	If the first is interior, the slit must have at least two edges. 
	
	Alternately, one can slit open a multiply connected complex along
	a simple closed non-dividing curve, leaving paired 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="smooth" flags=" -[abcdsx]">
<description>
    This implements 'field-based smoothing' associating a 
    "smoother" with the packing. This is often called from 
    within a 'MicroGrid' PackExtender, which then has a pointer
    'parentMG' to the 'MicroGrid' so that the smoother has access 
    to an ambient field and polygonal boundary path. If
    the smoother is started independently (with this command) 
    for a packing then constant intensity is assumed and the
    default path is either 'CPBase.ClosedPath' if it exists,
    or the unit circle. 
    Smoothing was developed to aid in design of infill patterns 
    for 3D printing and follows the 'tailored sectioning'
    generated by 'MicroGrid'. Its purpose is to (1) smooth out the
    size/combinatorial transitions that occur in tailored sectioning,
    and (2) move the boundary vertices to be centered on the enclosing 
    polygonal path. It adjusts using 'speed' and 'balance' parameters.
    The competing features are the radii, which reflect the local
    intensity field (smaller for more intense), and the centers, for
    approximating the usual packing conditions at internal vertices 
    and for moving boundary verts to the path. The original ideas
    for this method are due to John Bowers. It might also be used to
    compute actual circle packings.
</description>
<options>
	<opt flag="-a"> Adjustments to rad/centers are help separately 
		until this command accepts them as the radii centers of the
		packing</opt>
	<opt flag="-b {b}"> Set the balance parameter 'b' in [0,1],
		defaulting to 1/2. Closer to 1 means more weight on the
		intensity, closer to 0 means more weight on the packing 
		condition</opt>
	<opt flag="-c {n}"> Run n iterations. We anticipate convergence</opt>
	<opt flag="-d {flags}"> This displays p{n} using the currently
	    adjusted rad/centers; 'flags' are the usual display flags.
	    One can see the effects of adjustment and decide when done</opt>
	<opt flag="-r"> Revert to original rad/centers of p{n}.</opt>
	<opt flag="-s {u}"> Set the "speed" parameter for the iterative
		adjustment process. Normally the value 'u' is small</opt>
	<opt flag="-x"> Exit; this kills the smoothing tool within
		'MicroGrid', perhaps to restart with a new packing</opt>
</options>
</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>
<seealso>
<see>doyle_annulus</see>
<see>doyle_point</see>
</seealso>
</command>

<command cmd="split_edge" flags="v1 w1  v2 w2 ..">
<description>
	This changes the combinatorics of the active packing by splitting
	each listed edge {v, w} so that a new vertex of degree four is 
	added to the edge and each neighboring face is broken into two faces. 
	Any stored data in 'flist' and 'xyzpoint' is lost.
</description>
<seealso>
<see>split_flower</see>
<see>add_bary</see>
<see>add_edge</see>
</seealso>
</command>

<command cmd="split_flower" flags="v w [u]">
<description>
	This changes the combinatorics of the active packing by splitting
	vertex v in two, giving a new vertex v'. There are two situations:
	(A) if v is bdry, then w must be an interior neighbor and ends up as
	the common petal of the flowers of v and of v'.
	(B) if v is interior, then w and u must be distinct petals which
	determine the direction of the new edge {v',v}: namely, the 
	oriented cycle {v,u,v',w} bounds the two faces sharing edge 
	{v',v}. The new vertex v' is given the maximal index in the 
	packing. Any stored data in 'flist' and 'xyzpoint' is lost.
	To undo the split, call 'meld_edge'.
</description>
<seealso>
<see>split_edge</see>
<see>meld_edge</see>
<see>add_bary</see>
<see>add_edge</see>
</seealso>
</command>

<command cmd="socketServe" flags="n">
<description>
    This makes CirclePack into a 'socket' server to which mutiple 
    other programs can connect and communicate. Currently, an
    outside program can send commands for execution within 
    CirclePack. The 'host' for the socket is the canonical local 
    host and 'n' is the  port number. Knowing these, an outside 
    program can attach as a client and send commands to CirclePack.
    Current socket status can be ascertained with the '?socket' query.
</description>
<seealso>
<see>?socket</see>
</seealso>
</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_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="svg" flags="[-c{} {v..}] -f {filename.html}">
<description>
	Rudimentary save for 'html' file in SVG format.
	This only does euclidean and only circles. May develop
	in the future. (Sept 2016)
</description>
</command>
	 
	 
<command cmd="swap" flags="[-cma] {v w}">
<description>
	The indices of the circles v and w are swapped in the complex for
	the active pack. This is 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', first entries are
	exchanged; entries in vlist and elist are exchanged, flist is lost.
	If there are not flags, then data is left with the vertices (i.e.,
	only the index is changed, data stays). With one or more options,
	the 'color', 'mark', or 'aim' will move with the index.
</description>
<options>
    <opt flag="-c"> Vertex color is swapped along with the index</opt>
    <opt flag="-m"> Vertex 'mark' is swapped along with the index</opt>
    <opt flag="-a"> Assigned 'aim' is swapped along with the index</opt>
</options>
</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="torpack [A B]">
<description>
	If the active packing is a combinatorial packing, then
	this we create an affine torus with two side-pairings
	having affine scaling by factors A and B, defaulting to
	1 and 1.
</description>
</command>

<command cmd="torus_t">
<description>
 	This returns an error if the packing is not	a combinatorial 
 	1-torus or if there are problems in the	computations.  
 	Otherwise, this will put the packing in normalized position
 	and compute and report the conformal modulus 'tau' and its
 	reciprocol. This applies to both flat tori and affine tori;
 	the radii and layout must be computed.
</description>
</command>

<command cmd="timer -[sx]">
<description>
Simple stopwatch timer. When called, if the stopwatch is on, this call
reports the elapsed time since it was started and turns it off. If the
stopwatch is off, this starts it. To ensure a new timer, use "-s" option.
</description>
<options>
<opt flag="-s">Clear the timer and start the timer anew</opt>
<opt flag="-x">Clear the timer</opt>
</options>
<examples> 
<instance text="timer -s;repack;timer"> Starts a fresh time, 
does 'repack', then reports the elapsed time.
</instance>
</examples>
</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="triGroup" flags="[-d {a b }] [-g {n}]">
<description>
    Deprecated: see "create tri_group".
</description>
<seealso>
<see>create</see>
</seealso>
</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" flags="-[AcdegirRzZavloftmMy] {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="-d"> display options (to set on reading) </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="-S"> Schwarzians, if they are recorded</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-empty lists: vlist/flist/elist</opt>
	<opt flag="-L"> non-empty global lists: Vlist/Flist/Elist</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"> all faces (as triples of vertices)</opt>
	<opt flag="-T"> tile data ('TileData' class)</opt>
	<opt flag="-F"> set of dual faces as a tiling; no other data</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 cgriazoflv</opt>
	<opt flag="-s"> Save to end of current script file (alone, equivalent to cgirzs</opt>
	<opt flag="-x"> 3D xyz data</opt>
	<opt flag="-n"> utility list of integers</opt>
	<opt flag="-y"> utility list of real values (doubles)</opt>
	<opt flag="-w"> utility list of integerslist of complex numbers</opt>
	<opt flag="default">-cgirzv</opt>
</options>
<seealso>
<see>read</see>
<see>Write</see>
<see>write_carrier</see>
</seealso>
<examples>
<instance text="write -s packing[_N].p"> Suppose variable N is "3.0", then this
    command saves to the file named 'packing3.p'; i.e., '3.0' converts to integer
    and brackets are removed.</instance>        
</examples>
</command>

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

<command cmd="write_custom" flags="-[option] -[fa] {file}">
<description>
	This is intended to allow specialized data export. One specifies a
	flag, possibly with other info, and an output file. Java code may need
	to be written in 'CommandStrParser.java' to support the task.
</description>
<options>
<opt flag="-G {v..}"> write 'grid', meaning the dual graph for indicated
faces. Puts out face centers and pairs of indices forming edges</opt>
</options>
</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>
<seealso>
<see>write</see>
<see>Write</see>
</seealso>
</command>

<command cmd="write_path" flags="-[s] {file}">
<description>
	Writes current path (if there is one) to file as a closed contour.
</description>
<options>
	<opt flag="-s"> Save to 'Filse' section of current script </opt>
</options>
<seealso>
<see>infile_path</see>
<see>Write_path</see>
</seealso>	
</command>

<command cmd="Write_path" flags="{file}">
<description>
	Same as "write_path", except default directory is not prepended 
	to the filename, so an explicit directory path (possibly starting '~/')
	is allowed.
</description>
<seealso>
<see> write_path</see>
</seealso>
</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 "write_select_radii", except default directory is not prepended 
	to the filename, so an explicit path (possibly starting '~/')
	is allowed.
</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 "write_select_centers", except default directory is not prepended 
	to the filename, so an explicit path (possibly starting '~/')
	is allowed.
</description>
</command>

<command cmd="write_tiling" flags="-s">
<description>
    Write a "tiling" ('TileData' subclass of 'PackData' class) to a file
	or to the script ('-s' option).

	A "tiling" is a combinatorial, locally planar pattern of tiles, where
	each tile is an n-gon for some n (at least 3) and is defined by the
	counterclockwise ordered closed list of its corner vertices. (Each tile
	also has a 'type' reserved for future use.) See 'Help --> Formats' 
	tab for the tiling file format. Note that when a tiling is read in, 
	a barycentric subdivision is automatically generated, yielding a 
	standard packing complex: the vertices associated with the barycenters
	of the tiles are the larger indices.
</description>
<options>
<opt flag="-s"> save as file in the current script</opt>
</options>
<seealso>
<see>read_tiles</see>
</seealso>
</command>  

<command cmd="Write_tiling" flags="-s">
<description>
	Same as "write_tiling", except default directory is not prepended 
	to the filename, so an explicit path (possibly starting '~/')
	is allowed.
</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 directory is not prepended 
	to the filename, so an explicit path (possibly starting '~/')
	is allowed.
</description>
</command>

<command cmd="zip" flags="n v">
<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 all become interior;
	if odd, then a boundary component of three edges remains.
</description>
<seealso>
<see>adjoin</see>
<see>enclose</see>
</seealso>
</command>

<command cmd=":=" flags="[[SLIDER..]'] {x}">
<description>
   Set the name and (string) value for a variable for use in
   commands. For instance, 'v:= 7' will set the variable named 'v'
   to the string "7". In a call such as 'disp -cf _v', the "_v"
   will be replaced by "7". Variable names cannot have spaces
   and neither the name nor the value string can have semi-colons.
   The value of a variable can be overwritten without warning.
   If the string 'x' represents a real number, then when 
   preceded by the string '[SLIDER]' then a slider windw for 
   adjusting this variable is created in the "Pack Info --> Variables" 
   tab, allowing you to adjust the min/max, choose a value for the 
   variable (increments of 1/100 between the
   limits), specify a command to be repeated whenever the slider
	value is changed, or a function (of 'z') which is applied to
	the slider value to get the value of the variable. (For example,
	you may want the values to be multiplied by Pi, so you enter 'z*pi'
	and selected the 'ftn?' checkbox.)
	
	Syntax for creating sliders allows parameters to be set.
	Simplest example is 'var := [slider] 10', but general form is
	[slider -m {m} -M {M} -cmd {str} -ftn {ftn}] {value string}
</description>
<examples>
<instance text="r:= 1.4"> This sets variable 'r' to "1.4" (as a
string).</instance>
<instance text="set_rad _r b"> If 'r' is set to value "1.4", this
command will set all boundary radii to 1.4.</instance>
<instance text="set_var N 20"> Create variable 'N', value '20'</instance>
<instance text="n:=12;seed _n"> create a seed with 12 petals</instance>
<instance text="id:=?invdist 13 45"> sets 'id' to the inversive distance 
	between circles for v13 and v45.</instance>
<instance text="Y:=[slider] 3.14"> Variable 'Y' created with a slider.</instance>
<instance text="A:=[SLIDER -m 2 -M 6 -cmd [h] -ftn z*pi] 2.0"> Variable 'A' is 
	created with a slider, min/max 2 to 6, command '[h]', values multiplied
	by Pi.</instance>	
</examples>
<seealso>
<see>set_var</see>
</seealso>
</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 returns or reports information of the specified kind.
	It may appear in the "Messages" frame (though lists are limited to
	12 items) or can be stored in a variable.
</description>
<options heading="Inquiries">
<comment>(Routine data is available in the "Packing Data" window)</comment>
<opt flag="?aim {v}">  angle sum target of vertex (divided by Pi); 
a negative value means this vertex is not adjusted during repacking</opt>
<opt flag="?anglesum {v}">  angle sum of vertex (divided by Pi)</opt>
<opt flag="?antip {v...}">    vertex with maximal minimum combinatorial distance 
	     				  to point in {v...} </opt>
<opt flag="?cent {v}">		  complex center of vertex v </opt>
<opt flag="?count {..}">  count of vertices, faces, or edges (see 'count' commands)</opt>
<opt flag="?dcel"> does this packing have its DCEL structure attached?</opt>	     				  
<opt flag="?energy -[chlm]"> various measures of quality of point distributions
	     					of centers </opt>
<opt> -c (default) coulomb energy (L1 norm)
	     			sum of reciprocals of point pair distances</opt>
<opt> -h L2 norm of reciprocals of point pair distances</opt>
<opt> -l log energy, sum log(1/dist)</opt>
<opt> -m minimum distance between pairs</opt>
<opt flag="?flower {v}">	  counterclockwise flower of v</opt> 
<opt flag="?f(z) {x [y]}">	  value of current function at real [or complex] value</opt>
<opt flag="?gam(t) {t}">	  value of current parameterized path at real t</opt>
<opt flag="?invdist {v w}">   inv dist/overlap between any two circles</opt>
<opt flag="?schwarz {v w}">   real schwarzian for this edge (if allocated)</opt>
<opt flag="?mark -[vft] {.}"> mark for vert, face, or tile</opt>
<opt flag="?nodecount">       number of vertices in the packing</opt>
<opt flag="?pnum"> 			  pack number (0, 1, or 2)</opt>
<opt flag="?Redchain">		  sequence of face indices forming the 'redchain'</opt>
<opt flag="?rad {v}">		  radii</opt>
<opt flag="?screen">		  report screen size, then can use 'set_screen -b ....'</opt>
<opt flag="?socket">		  was CirclePack started with a socket for command input? 
								If yes, this gives the host and port number</opt>
<opt flag="?*list*">		  for vlist, elist, flist or Vlist, Elist, Flist</opt>
<opt flag="?_*">			  report the value of a variable</opt>
<opt flag="?vert {v}">		  Accumulated data: cent/rad, mark, flower, etc</opt>
<opt flag="?face {f}">        Accumulated data: vertices, color, etc</opt> 
<opt flag="?edge {v w}">      Accumulated data: ends, length, etc</opt>
<opt flag="?tile {t}">        Accumulated data: degree, color, mark, etc</opt>

<comment>(Many options are not yet implemented (ask Ken if you need
these or other functionality).
	     
        ?screen (data) screen information
		?parameters    program parameter
		Specials:
	     ?kappa {v..}     curvatures
	     ?alt_rad {v..}   radii in alternate geometries
	     ?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
	     ?script name	Is script file named
	     ?vertexMap		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.</comment> 
</options>
<examples>
<instance text="?rad 17"> prints the radius in "Messages"</instance>
<instance text="R:=?rad 17"> Sets variable 'R' to the radius of v17.</instance>
<instance text="v:=?vlist;disp -c _v"> stores and then displays the active pack's 'vlist' 
(stopping at 1000 entries)</instance>
<instance text="?_v"> reports the string represented by variable 'v'</instance> 
</examples>
</command>

<command cmd="#XY">
<description>
	For use in 'mytools' that can be drag/dropped onto packing 
	canvasses or have a key assigned: the mouse location is converted 
	to real x y coordinates and that pair of real numbers is substituted 
	for '#XY' (or '#xy') before the command is executed:
</description>
<examples>
<instance text="set_elist z #XY;flip elist[0]">  This chooses an edge closest to
xy-coords of the mouse, then executes the 'flip' command for the resulting edge.
</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>

<command cmd="{..cmd..}">
<description>
    A command is surrounded by braces if you want to save the value
    it returns. Only one command is allowed (with its flags) in the
    call, others are ignored. The returned value may be a number and/or
    list of numbers, or a string, and is held in a global variable
    only until another call replaces it. I am still (6/2015) developing 
    ways to use this info. 
</description>
<seealso>
    <see>set_variable</see>
</seealso>
</command>

</CPdocs>
</body>


