# CirclePack command details

Here is an alphabetic listing of all the commands which the user can issue to CirclePack via its command line or in its scripts, along with their various flags and options.
act {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.

add_bary {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.)

Examples:

> add_bary a | One can generate "Apollonian"-type packings by repeatedly adding barycenters to all interstices

See Also: rm_cir add_face_triple split_edge
add_cir {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.

add_edge {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.

See Also: enclose split_edge meld_edge
add_face_triple {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".

Examples:

> add_face_triple a | Repeating this will generate stages of this generalized 'Apollonian' packing

See Also: add_bary
add_gen {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.

Options:

> {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")
> {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).
> {n} -t | (Deprecated)
> 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).
> n -d | Duplicate circles, adding bearing circles to the resulting quad interstices.

See Also: add_layer
Examples:

> add_gen 4 | adds 4 generations, circle-for-circle, to every boundary component; those after the first generation will be degree 6.
> add_gen 2 -d -b 65 | adds two "duplicate" generations to the boundary component containing vertex 65

add_ideal [-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.

Options:

Examples:

> add_ideal | add an ideal vertex for every boundary component
> add_ideal 8 | add an ideal vertex for the boundary component containing vertex 8
> add_ideal -f v | add an ideal face to the bdry component containing v if it has 3 vertices
> 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

See Also: puncture
add_layer [-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).

Options:

> -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.
> -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.
> 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.

See Also: add_gen
Examples:

> add_layer 6 340 340 | add a layer to convert to degree 6 on the full boundary component containing vert 340
> | add a duplicate layer between boundary vertices 26 and 39

adjacency [-t] {file}

> Description: For packings of less than 10000 vertices, this stores the adjacency matrix for a packing complex in {file} using matlab format.

Options:

> -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.

adjoin {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.

adjust_rad {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))).

See Also: set_rad set_random
alpha {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).

See Also: gamma
alt_rect {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.

aspect {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).

See Also: polypack
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.

beta {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.

See Also: alpha gamma
BeurlingFlow ('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.

See Also: set_function_text
blend -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.

See Also: blend
break

> Description: In a command string, this stops execute of the remaining commands. It is built to prepare for "if-then" structures (6/2015).

brooks [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).

Options:

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

cd {..}

> Description: Change the working directory. Can use "pwd" to find the current directory.

Examples:

> cd ~ | change to the user's home directory

See Also: pwd
center_point {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.

See Also: center_vert set_screen focus
center_vert {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)

See Also: center_point focus
chgP {n}

> Description: Change the paired canvasses to size n-by-n, with n in range [200,800].

See Also: set_display chgS {n}
chgS {n}

> Description: Change the active canvas to size n-by-n, with n in range [200,1200].

See Also: set_display chgP {n}
cir_aspect {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).

cir_invert [-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.

Options:

> -u | Use the unit circle in place of w

See Also: Mobius
Cleanse

> Description: This applies 'cleanse' to all packings.

See Also: cleanse
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.

See Also: Cleanse
close [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.

Options:

> Active | Frame displaying the 'active' packing, the main single-canvas window
> Paired | Frame displaying side-by-side packings (perhaps neither the active pack)
> Advanced | Control frame, droppable icons and small views of all three packings
> Script | Frame with current 'Script' for running CirclePack
> www | Browser window, good for loading scripts from the web or files
> Message | Frame with Messages, Scratch area, Command line
> Help | Help frame
> Mobius | Frame for managing Mobius transformations
> Function | Frame for setting a function and parameterized path
> Save | Frame with save operations
> Screen | Frame with screen snapshots, display settings
> Information | Frame with pack information
> Configure | Frame with Configuration settings
> About | Frame showing 'About Script' info (if a script is loaded)

Examples:

> close Script Save | Close the Script frame and the frame for Save operations

See Also: open Map
color -[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.

Options:

> bg {i..} | background color for selected objects
> fg {i..} | foreground color
> {c} c {i..} | c is a color code (in [0,39]), blue to red ramp
> p{p} {i..} | copies colors from pack p (deprecated: '-p')
> area (all faces) | blue color ramp based on face areas, all faces
> rad (all circles) | blue color ramp based on radii
> q{p} {v..} | blue-red color ramp rad/area compared to pack p; (deprecated: '-q')
> q{p} angsum {v..} | blue-red color ramp comparing angle sums to p;
> d | color by degree: 6=white, 5=blue, 7=red, others various
> s {i..} | 'spread' colors: select cyclically among 16 distinct colors starting at random point
> S {i..} | same as 's', except same color for the full list
> s0 {i..} | same as 's', but start at 0 point
> S0 {i..} | same as 'S', but start at 0 point
> -k {x} | (not currently implemented) (circles only) blue-red, compare model curvature to x.
> x {f..} | (faces) compare 3D/2D eucl area (if 'xyz' data exists).
> v {f..} | (faces) use vertex colors: majority wins, else first vert's color. (deprecated: '-v')
> v {t..} | (tiles) use color assigned to baryVert vertex
> 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.
> a {v..} | (circles/faces) 'ArgWheel'; based on complex argument of center or incenter.
> z {v w ...} | (edges only) based on schwarzian
> r | (edge only) reset all to foreground

Examples:

> color -f qc q1 -m 1.5 a | color by quasiconformal dilatation, compared to p1
> color -D d a | color dual tiles based on number of edges (if dual tiling exists).
> color -e z a | color all interior edges base on their schwarzians

cookie [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.

Options:

> -v {v} | Use v instead of alpha as the 'seed' vertex.
> -e {v u ...} | (DCEL) - list of forbidden edges
> -n {v ..} | (DCEL) - 'non-keeper' vertices: edges with both ends non-keepers are added to forbidden edges.

See Also: set_poison
copy {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.

count -[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.)

Examples:

> count -v b | will count the boundary vertices

create {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.

Examples:

> hex_torus 3 6 | build 3-by-6 hex torus
> create hex 23 | hexagonal packing of 23 generations
> create sq_grid 4 | 'square grid' pattern from 4 quadruplings of a 4-flower
> create tri_group 8 2 3 5 | 8 generations of the (2 3 5) triangle group on the sphere.
> create j_ftn 8 | 8 generations of the classical j-function.
> create Kag 4 | 4 layers of Kagome lattice about a central hexagon
> create pent 5 | 5 generations of regular pentagonal tiling
> create pent3 3 | 3 generations of pent tiling centered on triple point
> create pent4 3 | 3 generations of pent tiling centered on quad point
> create pin 5 | 5 generations of Conway's pinwheel tiling, packed as a triangle (1 2 3), 1 = right angle, 2 = atan(2) = .35241638*Pi, 3 = atan(1/2) = .1475836*Pi.
> create dyadic 6 | 6 generations of Penrose's hyperbolic tiling (Carleson squares in the limit)
> create fib 5 6 3 2 | 5 generations of Fibonnacci-related tiling, W=6,H=3,X=2.
> tetra | regular tetrahedron on the sphere

See Also: seed pave
DCEL [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.

Options:

debug [drsex]

> Description: Various debug helpers. Some put results in a file in the default temporary directory (see 'Messages'), others print something.

Options:

> -d | (default) generates tmp file 'faceOrder_xxxx_log'
> -r | generates file 'RedList_xxxxx_log' of the 'red' faces
> -s | prints size/location info on 'StackBox's in the script
> -e | print commands to stderr to debug threads and lock ups
> -x | turn off -e option

delaunay -[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.

Options:

> -c | use the centers of the active packing
> -f {filename} | read points from a file
> -s {filename} | read points from a script file
> -g {hes} | geometry, hyp, eucl, or spherical

See Also: random_triangulation random_pack
Disp [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.

See Also: disp set_disp_flags
disp [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.

Common Options:

> -w | clear the canvas
> -wr | clear and refresh (i.e., issue 'disp')
> -c {v..} | open circles
> -f {f..} | open faces
> -e {v w..} | edges
> -ec{n} {e..} | colored edges with color code 'n'
> -a {f..} | sector arcs (eucl); based on edgelength
> -h {v..} | hull, meaning convex hull of tangency points with nghbs
> -nc {v..} | label circles
> -nf {f..} | label faces
> -B | all faces and circles, recomp'd by drawing order
> -C | all circles, recomp'd by drawing order
> -D | all dual faces, recomputed by drawing order (eucl only)
> -F {f..} | ``chained'' faces, recompute centers in order
> -Bs | all faces and circles, recomp'd by drawing order using schwarzians
> -Cs | all circles, recompute center by drawing order using schwarzians
> -Fs {f..} | ``chained'' faces, recompute centers in order using schwarzians
> -P {v..} | 'pavers' (polygon formed by face flower) recomp'd by drawing order (eucl only)
> -b | draw bary-coord defined paths, generally grid lines (eucl only)
> -bs | draw bary-coord defined paths, generally stream lines (eucl only)
> -bc{n} | ditto, but in color with index n
> -g | display current "path" (if available) in thicker blue
> -gc{n} | ditto, but in color with index n
> -q{p} | display on pack p' canvas (may be geometry conflict)
> -r | reset screen parameters to defaults
> -x (-xu) | turn display of axes on (resp. off)
> -u | draw unit circle
> -y {f..} | display circumcircles of given faces (useful for Delaunay triangulations)

Dual Object Options:

> -dc | dual circles (associated with packing interstices)
> -de | dual edges
> -df | dual faces
> -dh | dual face hull (polygon of tangency point)
> -dg | dual edges given, else those in pack's 'dualGraph'
> -dp | dual circle tangency points
> -dt | trinkets at dual centers
> -D? | (layout as needed, e.g. multiply connected cases)

Extended Options:

> -cc | all circles in color
> -cc {v..} | selected open circles in color
> -ccf {v..} | filled circles (color both circle and fill)
> -cffg {v..} | filled circles, foreground color
> -cfbg {v..} | filled circles, background color
> -cn {v..} | open circles, labeled with index

Specialized Options:

> -ee {v w..} | extended edges; travel thru up to 16 hex vertices from v to w (for hex_refined packs).
> -gi | draw path and the circles inside it
> -nl {v} {st} | >display string "st" at center of circle v
> -nz {x y} {st} | display string "st" at location x+iy
> -rc | draw "red" circles using the redfaces data, multiply connected case only.
> -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
> -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
> -s {v..} | closed polygon between centers of listed vertices (no interpolation of vertices between)
> -sfg {v..} |
> -sbg {v..} |
> -t* {v..} | * is a 'trinket': 0=dot (default), 1=square,2=triangle,3=plus,4=diamond
> -tc* {v..} | ditto, but using circles' colors
> -T {t..} | closed polygonal tiles (if the packing has tiling data)

See Also: set_disp_flags set_plot_flags
double {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.

See Also: reorient
doyle_annulus 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.

See Also: spiral
doyle_point 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.

See Also: spiral
dual_layout -[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'

Options:

> f | draw each new face as laid out with usual display options
> c | draw each new circle with usual display options

See Also: sch_report set_schwarzian
elist [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.

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.

embed -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.

encircle {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'.

See Also: path_to_elist elist_to_path
enclose -[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.

Options:

> n {v..} | add n circles to the flower of each v
> -t n {v..} | add enough circles to bring each v to degree n

erf_ftn {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}.

eucl_write {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".

exec [-n {moniker}] {command}

> 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.

exit

> Description: Close 'CirclePack'. If the script has changed, there is an opportunity to save it first.

See Also: quit
extender -[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.

Options:

> {type} | Where {type} is two letter abbreviation for the extender. (Currently, 'CirclePack' must already know of the associated class.)
> -x [{typ}] | close extenders of the specified type, or all extenders if the type is omitted.
> -r {typ} | close any extenders of type 'typ' and then start an extender of this type.

Examples:

> extender cf | would start a "CurvatureFlow" pack extender.
> extender -x | would close all extenders for this packing.
> extender -r ct | would close any current 'ConformalTiling' extenders for this packing and start a new one.

face_err 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].

fexec [-s] {filename}

> Description: Reads and executes commands in {filename}. Can be used as method of transferring data from remote routines.

Options:

> -s | read from open script

f_index {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.

f_next {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.

f_red {f i..}

> Description: (Technical) Sets rwb_flag of faces.

f_rnext {f g..}

> Description: (Technical) Sets next_face index of faces.

fix [options]

> Description: (Deprecated: preferred command is "layout").

See Also: layout
Fix

> Description: (Deprecated: replaced by "layout -F".)

See Also: layout
flat_hex {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.

flip {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.

Options:

> -cc | flip counterclockwise edge to each edge in the list (until a flip fails)
> -cw | flip clockwise edge to each edge in the list (until a flip fails)
> -r | flip one random edge from random interior vertex. (ignore rest of the input string.)

See Also: unflip
flip_priority [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.

See Also: flip unflip
flist [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.

Options:

> flist | produces whole list.
> flist[{i}] | produces the i_th face in the list, if there is one.
> flist[r] | produces the first face of the list and then moves it to the end of the list.
> flist[n] | produces the "next" face of the list and then removes it from the list.

focus [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.

Options:

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

See Also: center_vert center_point
for (...) -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.

Options:

> FOR | Remove the 10 iteration limit.
> -d {x} | impose a x second delay between iterations

Examples:

> for 12:20 disp -F flist[n] | layout and display 9 faces from the current flist.
> FOR (v:=1,40,2) disp -p1 -c _v | this displays odd-indexed circles from 1 to 39.

gamma {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.)

See Also: alpha
frack {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.

See Also: hex_refine add_bary
gen_cut {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.

gen_islands {v..}

> Description: Remove indicated vertices, plug each hole with single circle.

gen_mark [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.

Options:

> -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).
> -m n | mark vertices only up to generation n.

Examples:

> gen_mark A | mark vertices with their combinatorial distance from the alpha vertex
> F:={gen_mark -f b} | will set variable 'F' to the index of the face furthest from the boundary faces

See Also: mark
geom_to_[ehs] [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.

Options:

> -l | means to reestablish current numerical values of radii after conversion, even though the geometry has changed.

See Also: project
get_data -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.

Data specification flags:

> -t | translate (see above); must occur first after '-q2'
> -r | radii (same as '-cr')
> -z | centers (same as '-cz')
> -a | aims (same as '-ca')
> -cc | circle colors
> -cm | circle 'mark's
> -c[rzmca] | multiple specifications (same vertex list)
> -fc | face colors
> -fm | face 'mark's
> -f[mc] | mutilple specifications (same face list)
> -em | edge 'mark's
> -ec | edge color
> -es | schwarzians (for edges)
> -ei | inversive distances (for edges)
> -e[mcsi] | multiple specifications (same edge list)
> -v -V | vertex_map (see above); these occur alone

Examples:

> get_data -q2 -t -crz b | Copy (translated) centers and radii from p2 for all bdry vertices of the active pack.
> get_data -q2 -ems | Copy all edge marks and schwarzians from p2 to the active packing for all edges.
> get_data -q2 -fm {f...} -cz {v...} | Combined call with lists specified for each flag.
> get_data -q2 -ca {c:a.gt.3.0} | Aims for circles with aim greater than 3.0*Pi.

See Also: put_data
get_xyz [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.

Options:

> -b | set boundary radius to the average of 3D-lengths of its two edges (euclidean packing only).
> -l | find min/max/ratio of 3D edge lengths.

GOpack [-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.

Options:

> -v {v..} | special premptive flag, other flags ignored: {v..} specifies subcomplex of vertices to be considered 'interior'.
> -s | set all radii to 1, but do no riffles
> -m {n} | do the usual max packing (sph or disc), 'n' passes
> -c {n} | continue packing 'n' passes with the current local data
> -r | (eucl case only) restart the existing 'GOpacker' by getting eucl radii and centers from the parent packing
> -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)
> -h | 'harmonic' layout, i.e. solve for 'interior' with fixed boundary centers/radii (eucl only).
> -l | debugging: layout the bdry only, depending on mode
> -n {n} | set the number of passes (iterations), used in conjunction with other commands
> -q | return a value showing packing quality
> -x | kill the 'GOpacker'
> -? | print current GOpack status

See Also: max_pack repack polypack perp_pack
Examples:

> GOpack -m | computes the max packing with default number of iterations
> 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).

h_dist 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).

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.

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.

hex_slide {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.

hh_path [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.

Options:

> -a | append to given edgepath (i.e., {e} is a list {e..})
> -b | stop when the next edge would lie in the boundary
> -c | continue as long as possible --- no stop options
> -N | {n} add at most n edges (counting e)
> -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.)
> -x | stop when encountering vertex already hit by the path

Examples:

> flip -h elist[n] | will flip the clockwise edge from the next edge in 'elist', if flippable.

holonomy_trace {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.

Options:

> -f | Save to given file
> -a | Append to given file
> -s | Save to given file in the script

IF .. 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.

Examples:

> IF ?status THEN disp -w -cf | If the active packing is non-empty, then run this display command
> 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.
> 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.

infile_cmds {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.

infile_path [-a] {name}

> Description: This reads path data in the current "script" and puts it in place or appends it to the global 'ClosedPath'.

Options:

> -a | If there is an existing 'ClosedPath', this will append the new path.

See Also: read_path
infile_read {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.

See Also: read
j_ftn {maxgens n0 n1}

> Description: Deprecated: see "create tri_group".

See Also: create
layout -[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)

Options:

> -a | set "aims" to their defaults
> -c[cdfs] | recompute pack centers. added options follow (allow no spaces between):
> c {x} | set decimal number 'x' as threshold for placement accuracy; e.g., x=.00001 for 5-decimal places.
> d | create "layout.log" diagnostic file in the temporary directory to check for layout errors
> f | plot only circles with placement errors less than assigned threshold, set 'plot_flag' appropriately (as in '-l' option below)
> s | use single face for each new circle (ie straight from drawing-order) (Note: default is now to find center by averaging computations from all available plotted neighbors.
> -d [v] | comp centers using current draw order; report position(s) of vertex v
> -dt [v] | for torus packings only; arrange for just two side pairings. Optional, report positions of the corner.
> -v {v..} | redo drawingorder with given vertex list defining the outer boundary.
> -f {f..} | redo drawingorder with given facelist as a (putative) red chain; the outside edges of the faces are set as forbidden.
> -F [P] | redo everything (aims reset to default) ('P' flag means use 'poison' verts/edges)
> -K | update combinatorics, redo drawingorder
> -l | verify consistency of plotted centers for circles and faces, set corresponding flags appropriately.
> -r {f..} | recompute centers along given chain of faces
> -s | recompute angle sums
> -t | compute centers from 'tailored' drawing order; marked vertices will not (to extent possible) be used in drawing order.
> -T | same as -t, but routine will NOT use the marked vertices; it will stop once it has done all it can without them.
> default | recompute angle sums and centers.

See Also: alpha gamma set_poison set_plot_flags
legal [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.

Options:

> -c {c} | Threshhold criterion for inclusion in list: i Delaunay criterion (default), a look at all edge
> -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.

Examples:

> 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.
> 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.

load_pack -[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.

Options:

> -f | do not change the packing directory

See Also: read
locate -[cf] {x y}

> Description: Display labels for circles/faces containing point (x,y).

Options:

> -c | display labels for circles
> -f | display labels for faces

Map [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.

Options:

> -o | open Map windows in Java with packs p and q
> -x | close Map windows, return to active canvas
> -tNO | remove action reflection between canvasses
> -tYES | add action reflection between canvasses
> p q -c {v..} | show circles (default)
> p q -f {f..} | show faces

map [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.)

Options:

> -r | translate via inverse of vertex_map (must appear first)
> -v | circles (the default) (or -c)
> -f | faces
> -q{q} | for faces only, vis-a-vis pack number q.

Examples:

> map a(1,10) | This will store the translated indices of circles 1-10 of the active pack in Vlist.
> | Store reverse translated indices of all circlesin Vlist.
> 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).

mark [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.

Options:

> -w | clear all marks on all faces and circles
> -c {v..} | mark circles
> -co | mark each vertex with its position in the current drawing order
> -cw {v..} | clear marks of designated circles
> -f {f..} | mark faces
> -fw {f..} | clear marks of designated faces
> -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.)

See Also: gen_mark
match -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.

max_pack [-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.

Options:

> -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).

See Also: repack perp_pack set_radii
meld_edge {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.

See Also: split_edge split_flower enclose
mend {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.)

See Also: blend
migrate 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.

Mobius [s] {v..} (or Mobius_inv [s] {v..})

> Description: Applies the current Mobius transform (or its inverse) to the indicated vertices of the active pack.

Options:

> -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.)

See Also: pair_mob set_Mobius
mode_change {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.

molify_centers [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.

Options:

> -i n | n iterative passes through circles via drawing order or specified list.

msg {text}

> Description: The text is sent to the "Messages" window. This is useful when running a prepared "script".

msg_remote {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"

See Also: exec
nan {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.)

newRed [-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.

Options:

> -t | For torus only, creates domain with only two side-pairings
> {v...} | List of vertices defining a new red chain

See Also: set_vlist -R
norm_scale [options]

> Description: Normalize a packing (euclidean only) according to various options.

Options:

> -a x | scale so total euclidean area is x
> -c v r | scale so vert v gets radius r
> -e q v w | scale so vert v has radius of vert w in pack q
> -h v w | rotate so vector v to w is horizontal (left to right)
> -i v | scale/rotate to put vertex v at z=i (asuming v is not centered at the origin)
> -m v1 v2 z1 z2 | linear transformation putting vi at zi
> -t | for torus only: put in normalized position, report tau
> -u v | scale so eucl center of vert v is on unit circle
> -U | scale (down only) to fit eucl packing into the unit disc

See Also: rotate
NSpole [{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.

Options:

> -t x | dilation factor. E takes precedence; x defaults to 1 if E option is absent or if x.le.0.
> -a N | Use N as north and find the antipodal point as south

open [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.

Options:

> Active | Frame displaying the 'active' packing, the main single-canvas window
> Paired | Frame displaying side-by-side packings (perhaps neither the active pack)
> Advanced | Control frame, droppable icons and small views of all three packings
> Script | Frame with current 'Script' for running CirclePack
> www | Browser window, good for loading scripts from the web or files
> Message | Frame with Messages, Scratch area, Command line
> Help | Help frame
> Mobius | Frame for managing Mobius transformations
> Function | Frame for setting a function and parameterized path
> Save | Frame with save operations
> Screen | Frame with screen snapshots, display settings
> Information | Frame with pack information
> Configure | Frame with Configuration settings
> About | Frame showing 'About Script' info (if a script is loaded)

Examples:

> open Script Save | Close the Script frame and the frame for Save operations

See Also: close Map
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.

output [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 \.

Examples:

> 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.

overlay -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.

Examples:

> overlay -q2 -cf b | displays filled boundary circles of the active packing on the canvas for packing p2

See Also: disp
pair_mob [-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.

Options:

> -1 | indicates the inverse transform (edge-pairing in opposite direction).

Examples:

> pair_mob B | applies side-pairing 'B' to the packing; the user must do any desired redrawing.

See Also: Mobius set_Mobius
path_construct [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'.

Options:

> -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.
> -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.

Examples:

> path_c -i 23 57 3 3 3 ... | In a hex packing, this defines a combinatorially straight path.

See Also: set_Vlist
path_Mobius

> Description: Applies the current Mobius transformation to the current path (if there is one).

path_to_elist

> Description: Attempts to find a closed edge-path which approximates the current path. See 'elist_to_path' and 'enclose' also.

pave {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.

See Also: create
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.

perp_pack [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.

See Also: repack max_pack set_cycles
perron -[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.

Options:

> u | upward (only) Perron
> U | up then down Perron
> d | downward (only) Perron
> D | down then up Perron

polypack -[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.

Options:

> o | use 'old reliable' versus GOpack algorithm

See Also: repack GOpack -bn {v1...vn}
post [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.

Options:

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

Options:

> -c {v..} | open circles
> -f {f..} | open faces
> -e {v w..} | edges
> -l {n} | set linewidth, 0.le.n.le.15, integer multiples of unit linewidth (default=brush size)
> -nc {v..} | label circles
> -nf {f..} | label faces
> -C {v..} | all circles, recomp'd by drawing order
> -F {f..} | ``chained'' faces (see below)
> -B {v..} | all faces and circles, recomp'd by drawing order
> -b | draw bary-coord defined paths, generally grid lines (eucl only)
> -bs | draw bary-coord defined paths, generally stream lines (eucl only)
> -g | display the current "path", if available.
> -u | draw unit circle
> -W {text} | text (at most 60 characters) to appear at bottom of postscript file.

Options:

> -cc | all circles in color
> -cc {v..} | selected open circles in color
> -ccf {v..} | filled circles (color both circle and fill)
> -cffg {v..} | filled circles, foreground color
> -cfbg {v..} | filled circles, background color
> -cn {v..} | open circles, labeled with index

Options:

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

See Also: screendump
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.)

See Also: cookie set_poison
project [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.

Options:

> -e {v} | Put vertex v at the point 1.
> -m | Choose a vertex to put at the point 1 by picking one a greatest distance from alpha and the boundary.
> -t {r} | Normalize so ratio rad(alpha)/rad(S) = r where S is the south pole and these are spherical radii.
> default | to -t 1.

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.

puncture [{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.

Options:

Examples:

> puncture | by default, puncture vertex of maximal index
> puncture 4 | puncture vertex 4
> puncture -f 4 | puncture face 4

See Also: add_ideal rm_cir rm_bary rm_edge rm_quad
put_data -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).

See Also: get_data
pwd

> Description: Give the working directory. You can use 'cd' to change it.

See Also: cd
qc_dil -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.)

quality -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.

Options:

> -a {v..} | Worst (and average) angle sum errors; doesn't need centers
> -r {e..} | Worst relative distance error in native geometry (versus '-v' option)
> -n | first vertex encountered with radius/center NaN (not-a-number), else -1
> -o {f..} | first face encountered with a face with reverse orientation, else -1
> -e {v..} | Not yet implemented: Worst relative error among 'effective' radii (compared to actual radii)
> -v {e..} | Worst 'visual' error (eucl relative distance error); eucl/hyp packings only

Examples:

> qual | Worst visual error on all edges
> qual -e b | Worst relative error over on boundary edges
> | Worst angle sum error at interior vertices

quit

> Description: This exits CirclePack. CAUTION: no confirmation requested, all data is lost. It is safer to use 'exit'.

See Also: exit
random_pack [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.

random_triangulation [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.

Options:

> -N {n} | Average number of random interior points (actually number depends on the point process.)
> -T {x y} | Randomly triangulate a 1-torus with modulus Tau=x+iy.
> -g | Randomly triangulate the interior of a path; default is current path.
> -g[s] {filename} | path read from a file (if '-gs', then in the script).
> -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
> -S {n} | Random triangulation of the sphere (using 'Qhull').
> -u | Random triangulation of the unit disc.
> -d | debug mode: set seed to (long)1 for reproducability
> -h {h} | geometry. Not currently used: in future, if h>0, then we want a triangulation of a sphere.

read {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.

See Also: Read delaunay
Read {filename}

> Description: Same as "read", except default directory is not prepended to the filename, so an explicit path (possibly starting '~/') is allowed.

See Also: read
read_CT [-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).

Options:

> -q{p} | Create the packing with tiling in the parent packing, but create a corresponding simple circle packing in pack p.
> -s | Read from the current script.

See Also: Read_CT
Read_CT [-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.

See Also: read_CT
read_color [options] {filename}

> Description: Read a colortable from {filename}. Behavior of this command depends on whether you're running CirclePack in graphics or standalone version.

Options:

> -n | {name} designate a name for the color file
> -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.)
> -s | set local colors; in CirclePack these will not change the screen colors, but will change the colors in postscript output.

read_path -[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'.

Options:

> -s | reads from the script
> -a | read into 'ClosedPath' or append if it already exists.

See Also: infile_path
Examples:

> read_path -as mypathname | read 'mypathname' data from the script and append it to 'ClosedPath'.

Read_path {filename}

> Description: Same as "read_path", except default directory is not prepended to the filename, so an explicit path (possibly starting '~/') is allowed.

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.

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.

See Also: double
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.

repack [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'.

Options:

> -v {v..} | repack only specified circles
> -o | repack using "old-reliable", but slower, routines (default to this in presence of nontrivial inversive distances)

See Also: max_pack polypack GOpack perp_pack
ring {v..}

> Description: OBE: see "frackMe"

See Also: frackMe
rld

> Description: Convenience command for 'repack', 'layout', and 'disp -wr'

rlsd

> Description: Convenience command for 'repack', 'layout' using schwarzians, and 'disp -wr'

rm_bary {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.)

See Also: rm_edge rm_quad rm_cir
rm_cir {v..}

> Description: Given a qualifying boundary or interior trivalent circle; other conditions are checked so that the remaining complex is legal.

See Also: rm_bary rm_edge rm_quad puncture
rm_edge [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.

Options:

> -c | collapse edge, interior or bdry

See Also: rm_cir rm_quad
rm_quad {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.

See Also: rm_edge puncture
rotate {a}

> Description: The active pack (hyp or eucl) is rotated counterclockwise about the origin by a*PI radians.

Examples:

> rotate -.5 | rotate clockwise about the origin by Pi/2.

See Also: norm_scale
scale [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.

See Also: path_Mobius
scale_aims x {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.)

See Also: set_aim
scale_rad -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.

sch_data [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).

Options:

> -r | randomize the degree d of the flower, d in [3,15]
> -c | randomize the center's radius along with the petals

Examples:

> | Store 1000 random hex flower schwarzians
> | Store 1000 random flower schwarzians with random degrees and random central radii

sch_report -[[ce]{flags}] {..}

> Description: (Developmental) To garner various data about schwarzians to try to understand them.

Options:

> -c | color code all circles, blue-to-red based on sum of schwarzians for edges, store all colors
> -c{flags} [{v..}] | display flags may call for drawing selected circles
> e | color code and draw all edges, blue-to_red base on their schwarzians
> e{flags} [{e..}] | color code all edges, but use display flags to draw selected edges

See Also: set_schwarzian dual_layout
Examples:

> sch_report -c | set all the colors, but don't draw
> sch_report -ccnt4 {v..} | set all, draw selected in color, labeled, thickness 4
> sch_report -et3 {e..} | compute all edge colors, draw selected, thickness 3

screendump [-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.

Options:

> -m | This dumps the side-by-side canvasses of "Map" frame
> -d {dir} | set ScreenShot's 'Dir' element, no dump. May use '~/' for home directory
> -b {base} | set ScreenShot's 'Base name' element
> -n {n} | set file name counter

See Also: post
script [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.

Examples:

> script | absent filename, a dialog box should appear

seed [-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.

set_accur {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.

set_active {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.

Examples:

> set_active 20 | sets 20 as the active vertex
> disp -cf v | if 20 is active, this displaced it as a filled circle

set_aim [{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.

Options:

> -a {v..} | adjust by adding given amount, x in [-0.1,0.1]
> -d {v..} | set to default: 2(*PI),interior; -1, bdry
> -c {v..} | set aims to current angle sums
> -% a {v..} | add real number a(*PI) to currently set aim
> -f a {v..} | adjust int aim toward 2pi by factor a in (0,1]
> -x {v..} | set aims based on 3D data in 'xyzpoint' (if available)

See Also: scale_aims
set_blist [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).

Options:

> {f} {b1} {b2} | (default) Sets barycentric coordinates 'b1','b2', and '1-b1-b2' for face 'f'.
> f {z..} | get face barycentric coordinates for the points {z..} relative to the faces containing z.
> i {z..} | get angle-based barycentric coords for points {z..} in any interstices to which they belong.

Examples:

> set_blist 10 .5 .3333 34 .0 1.0 | removes the former list, enters two BaryPoints
> set_blist blist 10 .5 .33333 | appends these to the existing 'blist'
> set_blist f Zlist | create BaryPoints for the faces containing the points in 'Zlist'

See Also: set_Blist
set_Blist {v..}

> Description: Store list of global 'BaryPoint' objects (irrespective of packing). (Previous contents are discarded.) See description in 'set_blist'.

See Also: set_blist
set_brush {k}

> Description: The thickness of lines for display and for PostScript output can be set to integer k, 1.le.k.le.15.

set_center [{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).

Options:

> -m | Transform the current center according to the function 'Function Frame'
> xyz | Use stored xyz coords to set center

See Also: set_ftn_text
set_custom {name}

> Description: Sets custom PostScript file for the active packing; default is 'CP_custom.ps'.

set_cycle {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.

set_dir {dir_name}

> Description: Set the directory from which packings are read/written; typically this is 'packings/'. This is typically set by java.

set_disp_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'

See Also: disp Disp
Examples:

> set_disp_flags -w -cf | clear screen, show filled circles on default redraw

set_display [-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.)

Options:

> -m {x} | Set canvases to x * maximum available size

See Also: chgS {n} chgP {n}
Examples:

> set_display -m .5 | Reset to 1/2 of the maximal size

set_dump_format [format]

> Description: Resets the format for 'screendump'. The choices currently are "jpg", "gif", "png", "bmp", "wbmp", with "jpg" the default on startup.

Examples:

> set_dump_format GIF | Screendumps saved as "gif" files

See Also: screendump
set_elist {e..}

> Description: Store edges in "elist" of active pack. Previous contents discarded. NOTE: Currently no check that pairs are actually endpoints of edge.

Examples:

> set_elist 1 3 75 4 17 3 | removes the former list, enters these pairs in order
> set_elist elist 1 3 75 4 17 3 | appends these to the existing 'elist'

See Also: set_Elist
set_Elist {e..}

> Description: Same as above, only stores indices in utility "Elist". (Validity check against active pack.)

Examples:

> set_Elist 1 3 75 4 17 3 | removes the former list, enters these pairs in order
> set_Elist Elist 1 3 75 4 17 3 | appends these to the existing 'Elist'

See Also: set_elist
set_fill_opacity {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.

set_flist {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.

Examples:

> set_flist 1 75 3 | removes the former list, enters these in order
> set_flist flist 1 75 3 | appends these to the existing 'flist'

See Also: set_Flist
set_Flist {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.)

Examples:

> set_Flist 1 75 3 | removes the former list, enters these in order
> set_Flist Flist 1 75 3 | appends these to the existing 'Flist'

See Also: set_flist
set_function_text {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.

Examples:

> set_function_text 1+sin(3*arg(z)) |

See Also: set_path_text set_center -m {v..}
set_glist [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}.

Options:

> a {f} | generate the full dual graph starting from face f (default to packing firstface).
> 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.
> 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.
> ?list | various lists (glist, Glist, flist, Flist) may be specified.

Examples:

> | dual spanning tree starting with face 10
> set_glist 5 12 18 7 | list of faces
> set_glist glist 5 12 18 7 | appends these to the existing 'glist'

See Also: set_Glist set_poison
set_Glist [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'.

See Also: set_glist
set_grid -[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.)

Options:

> -c | spoke/circle grid in unit disc.
> -r [llx lly urx ury] | rectangular grid, lower left corner (llx, lly), upper right corner (urx, ury). Default (-1,-1), (1,1).
> -g | use current "ClosedPath", if defined.
> -n | number of grid lines in each direction.

Examples:

> set_grid -r -1 -1 1 1 -n 17 | 18 horizontal/vertical lines

See Also: disp -b
set_hlist [options] {v w, ..}

> Description: Like 'set_elist', except that this is a list of halfedges associated with the active pack; previous contents are discarded.

Examples:

> set_hlist 1 3 75 4 17 3 | removes the former list, enters legal halfedges from the list
> set_hlist hlist 1 3 75 4 17 3 | appends these to the existing 'elist'

See Also: set_Hlist
set_Hlist {e..}

> Description: Same as above, only stores indices in utility "Hlist". (Validity check against active pack.)

Examples:

> set_Hlist 1 3 75 4 17 3 | removes the former list, enters these pairs in order
> set_Hlist Hlist 1 3 75 4 17 3 | appends these to the existing 'Hlist'
> set_Hlist hlist | appends hlist items to the existing 'Hlist'

See Also: set_hlist set_elist set_Elist
set_invdist [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).

Options:

> -d | set to default, 1 (tangency).
> -c | set to current measured values.
> -t {u} | truncate inv_distances at upper value u (u > 1.0)
> -x | use xyz data, setting based on min of all edgelengths, as though each radius was 1/2 the length of shortest edge.
> -x {name} | read in xyz data from this file, then use it
> -x -s {name} | from this file in the current script
> -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.
> deprecated: -f {v..} | set for edges from v; use incidence 'Iv' to get edges

Examples:

> | Set all to default
> set_invdist 0.5 7 10 | If {7 10} is an edge, then its overlap angle is set to acos(0.5) = Pi/3
> set_invdist 1.25 i | The inversive distances for all interior edges are set to 1.25

See Also: set_overlaps
set_Mobius [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'.

Options:

> -xyzXYZ x y z X Y Z | Mobius mapping one triple of complex numbers to another
> -[] | holonomy along halfedge chain built using these flags; e.g., '-R 3' for redchain side 3.
> {a.re a.im b.re b.im c.re c.im d.re d.im flip} | create explicitly

Examples:

> 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
> set_Mobius 2.0 0.0 0.0 0.0 1.0 0.0 0.0 0.0 | specifies z maps to 2*z
> 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)

See Also: set_hlist
set_over [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.

Examples:

> set_overlap 0.0 6 12 | specifies that circles 6 and 12 be tangent (equivalent to "set_invdist 1.0 6 12")
> set_overlap 0.333333 17 4 | specifies angle Pi/3 between 17 and 4 (equivalent to "set_invdist .5 17 4")

See Also: set_invdist
set_path_text {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.

Examples:

> set_path+text (1+exp(i*pi*2.0*t))^2 |

See Also: set_function_text disp -g set_path
set_path [{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.

Options:

Examples:

> set_path exp(i*2.0*pi*z) | Stores the unit circle as the closed path
> set_path (1-z)*(1-i)+z*i | Stores the segment from 1-i to i (and closes it)

See Also: set_path_text disp -g
set_pix_box lx ly rx ry

> Description: Resets the pixel box size in lower/upper corner form (integers).

set_plot_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.

Examples:

> set_plot_flags 1 a | reset all plot flags to 1

set_poison [-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.

Options:

> -v | (default) vertices
> -e | edges

See Also: cookie pre_cookie
set_post_size {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.)

See Also: screendump
set_ps_viewer {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.

set_ps {name}

> Description: Sets the screen postscript file (see "Config" window).

set_rad [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.

Options:

> -q{p} | Use along with pack number p according to suboptions:
> -M | Use max of active pack and pack p radii
> -m | Use min of active pack and pack p radii
> -a | Use average of active pack and pack p radii

See Also: adjust_rad set_random
set_ratio 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.

set_random [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.)

Options:

> -o | adjust overlaps instead of radii (must be first option)
> -r {l h} | specify range, low to high
> -f | means the random quantity will be used as a multiplicative factor for the current value
> -j {x} | "jiggle" radii by exp(r), r chosen from Gaussian, mean 0, standard deviation x/100. This may help distribute round-off error.

Examples:

> set_random -r .5 1.2 -f b | will multiply each boundary radius by a factor uniformly distributed between .5 and 1.2.
> set_random i | will randomly set all interior radii to random values between (about) 0.005 and 5.0 (the default range).
> set_rand -o -r .1 10 a | sets overlaps between .1 (overlap)and 10 (inversive distance).

See Also: adjust_rad set_rad
set_schwarzian -[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.)

Options:

> {v w ...} | Set based on current radii.
> -s {x} {v w ...} | schwarzians set to double value x

See Also: dual_layout sch_report
set_screen [options]

> Description: This sets the screen center and width (always equal to height) for a canvas

Options:

> -a | show all circles by expanding about current center; eucl packings only.
> -b lx ly ux uy | set real world canvas box, lowerleft/upperright
> -d | set to default size
> -h {x} | sets the height
> -i {dx, dy} | translate by increment
> -f {x} | multiplies height by x > 0. Note: width is determined from height by proportions of the canvas window.
> -v {v} | at coords of vertex v
> -z {x y} | sets the coords of the point to be centered
> -c {x y} | (deprecated version of 'z')

set_sphere_view [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.

Options:

> -d | set to default.
> -N | look down at the north pole (i.e., the origin), x-axis to the right
> -S | look up at the south pole (i.e., infinity), x-axis to the right
> -i | increment current view by additional rotations.
> -t {m00, m01, .., m22} | set transformation directly using 3x3 matrix entries. (It is assumed that this is an orthogonal matrix.)

Examples:

> set_sphere_view 0.0 0.0 0.0 | will put z-axis vertical, x-axis directly towards the viewer.
> 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.

set_sph_opacity {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.

set_sph_pts {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.

set_tlist [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.

Options:

> -D... | (preceeds other flags) apply to associate "dual" tiling, if available with CT extender
> -Q... | (preceeds other flags) apply to associate "quad" tiling, if available with CT extender
> -B | tiles chosen based on list of 'baryVert' indicies (indicies of center circles)
> -m | tiles with given marks
> -M | (when 'gradedTileData' is present) tiles with given mark whose parents in the tree also have that mark
> -i | tiles entirely in the interior
> -b | tiles hitting the boundary
> -Iv | tiles incident to one of given vertices
> -t {t..} | tiles having one of the given "types" (must be last flag sequence)
> -d{x} | (when 'gradedTileData' is present) depth 'x' in subdivision structure
> -c {t..} | (when called via "|CT| set_tlist") this gives the list of children tile indices

Examples:

> disp -Tf tlist | Display tiles in the list as filled
> |ct| set_tlist -c 2 7 | Loads indices of child tiles (in a subdivions scheme) of tiles 2 and 7

See Also: set_Tlist
set_Tlist [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'.

See Also: set_tlist
set_toler {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.

set_var {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.

Examples:

> set_var R 2.3 | Variable 'R' is created with value 2.3
> 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.
> 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).
> 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.

See Also: :=
set_vertexMap -[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.)

See Also: ?vertexMap
set_vlist {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.

Examples:

> set_vlist 10 7 33 | removes the former list, enters these in order
> set_vlist vlist 10 7 32 | appends these to the existing 'vlist'

See Also: set_Vlist
set_Vlist {v..}

> Description: Same as above, only stores indices in utility "Vlist". (Validity check against active pack.)

Examples:

> set_Vlist 1 75 3 | removes the former list, enters these in order
> set_Vlist Vlist 1 75 3 | appends these to the existing 'Vlist'

See Also: set_vlist
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.)

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.

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.

skeleton {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.

slider -[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).

Options:

> -A {v..} | The sliders display selected angle sums, usually from 0 to 3.0 (all values are multiplied by pi)
> -R {v..} | The sliders control specified radii
> -S {f g..} | The sliders control specified edge schwarzians
> -c ''cmds'' | Optional commands to be executed when a value is changed; here 'cmds' is a string of text enclosed by double quotes
> -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
> -o ''cmds'' | Optional commands to be executed by user with a button click; here 'cmds' is a string of text enclosed by double quotes
> -a {..} | Add a slider for a new object
> -r {.} | Remove an individual object
> -d | Download data from parent packing to the sliders
> -l {x} | Update slider range minimum
> -u {x} | Update slider range maximum
> -x | Destroy this frame

Examples:

> slider -R {v...} | sliders for selected vertices
> slider -R -c ''rld'' a | sliders for all radii, execute 'rld' on change in any slider
> 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.

See Also: set_schwarzian dual_layout
slit {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.

smooth -[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.

Options:

> -a | Adjustments to rad/centers are help separately until this command accepts them as the radii centers of the packing
> -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
> -c {n} | Run n iterations. We anticipate convergence
> -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
> -r | Revert to original rad/centers of p{n}.
> -s {u} | Set the "speed" parameter for the iterative adjustment process. Normally the value 'u' is small
> -x | Exit; this kills the smoothing tool within 'MicroGrid', perhaps to restart with a new packing

spiral [-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".)

Options:

> -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.

Examples:

> 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.

> spiral 1 9.9 | p=q=3
> spiral 1 4.61 | p=q=4
> spiral 1 3.2205 | p=q=5
> spiral 1 2.59 | p=q=6
> spiral 1 2.2365 | p=q=7
> spiral 1 2.01 | p=q=8
> spiral 4.82374 1.87652 | p=2, q=8
> spiral 3.45903 1.51236 | p=2, q=10
> spiral 2.22209 1.30493 | p=3, q=15
> spiral 3.459050632 1.512350036 | p=4, q=6
> spiral 1.218 .67407066 | p=4, q=8
> spiral 2.222084374 1.304928925 | p=6, q=9
> spiral 1.807161471 1.218051525 | p=8, q=12
> spiral 2.89 24.137569 | p=2, q=3
> 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.)
> 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.)
> spiral 1.623 6.939 | Brooks' spiral: p=4, q=1: (Comes from Brooks quad with parameter g. Don't know exact values.)

Examples:

> Others, unclassified are:(spiral 1.876554 4.82542), (spiral 1.2238 1.2238), (spiral 1.10335 2.19637), and (spiral 1.500527 1.22496).

See Also: doyle_annulus doyle_point
split_edge 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.

See Also: split_flower add_bary add_edge
split_flower 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'.

See Also: split_edge meld_edge add_bary add_edge
socketServe 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.

See Also: ?socket
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).

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.

surf_write [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'.

Options:

> -3D | Use stored xyz-data
> -o {name} | file name, default is 'surf_write.jvx'

svg [-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)

swap [-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.

Options:

> -c | Vertex color is swapped along with the index
> -m | Vertex 'mark' is swapped along with the index
> -a | Assigned 'aim' is swapped along with the index

test_repack [options]

> Description: For testing new repack routines. Options will change. Main issue at present concerns incompatibilities for overlap/inv. dist. packings.

Options:

> -d | adjust compatible vertices as usual, avoiding creation of incompatibilities
> -c k | test_cycle limit between status reports, default 1
> -n k | total passes, default 200

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.

torus_t

> Description: Computes the modulus of a packing for a 1-torus. It returns an error if the packing is not a combinatorial 1-torus or if no edge-pairings have been computed.

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.

Options:

> -s | Clear the timer and start the timer anew
> -x | Clear the timer

Examples:

> timer -s;repack;timer | Starts a fresh time, does 'repack', then reports the elapsed time.

transition {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.

tree_pack [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.)

Options:

> -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.

triGroup [-d {a b }] [-g {n}]

> Description: Deprecated: see "create tri_group".

See Also: create
unflip {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").

unweld -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.

Options:

> -o | extract the outside of edge-path and put it in q; an ideal vertex is added if the active packing has a boundary.

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.)

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.

vlist [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.

weld {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.

Options:

> -a | use arclength (normalized to total 1) on bdry of each packing. (This is default behavior if given packings are euclidean, for now.)
> -f {filename} | file containing a real welding map (normally orientation preserving homeomorphism of [0,1] or [0,2pi], linearly interpolated.)
> -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').

weld_map {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".)

Options:

> -m | output in 'matlab' form (default is postscript)
> -g | popup ghostviewer for the postscript file
> -w | fingerprint output, suitable for input to 'weld'.

write -[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.)

Options:

> Any combination of these:
> -A | append specified data to existing file
> -c | combinatorics: flowers, a/b/c.
> -d | display options (to set on reading)
> -g | geometry (needed by calls for data r and z)
> -i | non-default inv_dist and aims
> -S | Schwarzians, if they are recorded
> -r | radii
> -z | centers
> -a | angle sums
> -v | vertex_map
> -l | non-empty lists: vlist/flist/elist
> -L | non-empty global lists: Vlist/Flist/Elist
> -o | non-default face/circle colors
> -f | non-zero plot_flags (Note: this info may immediately be overridden if centers are not also included in data)
> -t | all faces (as triples of vertices)
> -T | tile data ('TileData' class)
> -F | set of dual faces as a tiling; no other data
> -e | edge-pairing mobius transformations. (Only for multiply connected packings; be sure to 'layout' to update data.)
> -m | minimal: equivalent to cgri
> -M | Maximal: equivalent to cgriazoflv
> -s | Save to end of current script file (alone, equivalent to cgirzs
> -x | 3D xyz data
> -n | utility list of integers
> -y | utility list of real values (doubles)
> -w | utility list of integerslist of complex numbers
> default | -cgirzv

See Also: read Write write_carrier
Examples:

> 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.

Write -[AcgirzavloftTmMy] {filename}

> Description: Same as "write", except default path is not prepended to filename.

See Also: write write_carrier
write_custom -[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.

Options:

> -G {v..} | write 'grid', meaning the dual graph for indicated faces. Puts out face centers and pairs of indices forming edges

write_carrier [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".

Options:

> -3D | Use stored xyzdata (if it exists)
> -jvx | Use JavaView *.jvx files

See Also: write Write
write_path -[s] {file}

> Description: Writes current path (if there is one) to file as a closed contour.

Options:

> -s | Save to 'Filse' section of current script

See Also: infile_path Write_path
Write_path {file}

> Description: Same as "write_path", except default directory is not prepended to the filename, so an explicit directory path (possibly starting '~/') is allowed.

See Also: write_path
write_select_radii {file} {v..}

> Description: Write file with radii for vertices v..

Write_select_radii {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.

write_select_centers {file} {v..}

> Description: Write file with centers for vertices v..

Write_select_centers {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.

write_tiling -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.

Options:

> -s | save as file in the current script

See Also: read_tiles
Write_tiling -s

> Description: Same as "write_tiling", except default directory is not prepended to the filename, so an explicit path (possibly starting '~/') is allowed.

write_vert_list {filename} {v..}

> Description: Adjoin info to *.vl filename: VERT_LIST: v1 v2 ... (done)

Write_vert_list {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.

zip 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.

See Also: adjoin enclose
:= [[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}

Examples:

> r:= 1.4 | This sets variable 'r' to "1.4" (as a string).
> set_rad _r b | If 'r' is set to value "1.4", this command will set all boundary radii to 1.4.
> set_var N 20 | Create variable 'N', value '20'
> n:=12;seed _n | create a seed with 12 petals
> id:=?invdist 13 45 | sets 'id' to the inversive distance between circles for v13 and v45.
> Y:=[slider] 3.14 | Variable 'Y' created with a slider.
> 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.

See Also: set_var
!!

> Description: This repeats the last command (omitting instances of "!!" itself). You can also repeat previous commands in the "History" tab.

?{*}

> 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.

Inquiries:

> (Routine data is available in the "Packing Data" window)
> ?aim {v} | angle sum target of vertex (divided by Pi); a negative value means this vertex is not adjusted during repacking
> ?anglesum {v} | angle sum of vertex (divided by Pi)
> ?antip {v...} | vertex with maximal minimum combinatorial distance to point in {v...}
> ?cent {v} | complex center of vertex v
> ?count {..} | count of vertices, faces, or edges (see 'count' commands)
> ?dcel | does this packing have its DCEL structure attached?
> ?energy -[chlm] | various measures of quality of point distributions of centers
> ?flower {v} | counterclockwise flower of v
> ?f(z) {x [y]} | value of current function at real [or complex] value
> ?gam(t) {t} | value of current parameterized path at real t
> ?invdist {v w} | inv dist/overlap between any two circles
> ?schwarz {v w} | real schwarzian for this edge (if allocated)
> ?mark -[vft] {.} | mark for vert, face, or tile
> ?nodecount | number of vertices in the packing
> ?pnum | pack number (0, 1, or 2)
> ?Redchain | sequence of face indices forming the 'redchain'
> ?rad {v} | radii
> ?screen | report screen size, then can use 'set_screen -b ....'
> ?socket | was CirclePack started with a socket for command input? If yes, this gives the host and port number
> ?*list* | for vlist, elist, flist or Vlist, Elist, Flist
> ?_* | report the value of a variable
> ?vert {v} | Accumulated data: cent/rad, mark, flower, etc
> ?face {f} | Accumulated data: vertices, color, etc
> ?edge {v w} | Accumulated data: ends, length, etc
> ?tile {t} | Accumulated data: degree, color, mark, etc
> (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.

Examples:

> ?rad 17 | prints the radius in "Messages"
> R:=?rad 17 | Sets variable 'R' to the radius of v17.
> v:=?vlist;disp -c _v | stores and then displays the active pack's 'vlist' (stopping at 1000 entries)
> ?_v | reports the string represented by variable 'v'

#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:

Examples:

> 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.

[{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).

{..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.

See Also: set_variable