Data file formats for CirclePack: (preliminary)

All files associated with CirclePack are plain ASCII encoded. Here are the key types of data files:

	1 packings: data on specified circle configurations (details below).
	  In the "packings" subdirectory, generally "*.p", "*.q".
	
	2 lite packings: data in linear form (details below) 
	  for faster communication, extension "*.pl".
	  
	3 tilings: for tilings (details below)
	
	4 triangulations: OFF format for triangulations, convenient for 
	  building packing combinatorics using outside sources, e.g. matlab.
	  May have extension "*.p".
	  
	5 paths: x,y pairs specifying polygonal paths, extension "*.g"
	   
	6 scripts: files of prepared commands for easy execution.
	  In "scripts" subdirectory, generally with ".xmd"
	  extension.
	  
The combinatorics of circle patterns are represented by 2-complexes; that is, collections of triangles, edges and vertices. These are always 
oriented and have connected interior. The 2-complexes are stored by numbering the vertices and keeping track of the "flower" of each vertex; 
that is, the positively oriented list of its neighbors, a closed list for interior vertices. Special vertices are: "alpha", an interior vertex which serves as the combinatoric origin, and "gamma", another vertex used for display orientation (Typically alpha is at the origin and gamma is on the positive imaginary axis.) There are generous limits on sizes: the largest packing to date has nearly five million circles.

1. Packings: These files are "keyword" based, so the data is located and read based on keywords. 
"NODECOUNT:" (or "CHECKCOUNT:", see below) must occur first. Whitespace is ignored, but line breaks
make a difference: formats below indicate when data must be on separate lines.

	NODECOUNT: N	
	ALPHA/BETA/GAMMA: a b c
	GEOMETRY: ("hyp", "eucl", or "sph")
	FLOWERS:
		n m   v_0 v_1 .. v_m
		... 
		(n=index, m=#faces, v_j=nghb list, may be closed)
	RADII:             (optional)
		r1 r2 ...
	SELECT_RADII:		   (optional, only with CHECKCOUNT file)
		v1 r1
		v2 r2
		...
		(done)
	CENTERS:		   (optional)
		x1 y1  x2 y2  ...   
	ANGLESUMS:         (optional)
		a1 a2 ...
	ANGLE_AIMS:		   (optional)
		v1 a1  
		v2 a2 
		... 
		(done)
		(vj=circle index, aj=intended angle sum)
	INV_DISTANCES:	   (optional)
		v1 w1 D1
		v2 w2 D2 
		... 
		(done)
		(vj,wj=circle indices, Dj=inversive distance
		Dj in (-1,1) overlap; 1 tangency; > 1 separated)
	SCHWARZIANS:       (optional, non trivial)
	    v1 w1 S1
	    v2 w2 S2
	    ...
	    vN wN SN
	CIRCLE_COLORS: 	   (optional, deprecated)
		v1 c1
		v2 c2 
		... 
		(done)
		(vj=circle index, cj=color code)
	C_COLORS:          (optional)
		v1 r1 g1 b1
		v2 r2 g2 b2 
		... 
		(done)
		(vj=circle index, rj,gj,bj=rgb int values in [0,255])
	TRI_COLORS:    	   (optional, deprecated)
		u1 v1 w1 c1
		u2 v2 w2 c2 
		... 
		(done)	
		(three verts of face, cj=color code)
	T_COLORS:          (optional)
		u1 v1 w1 r1 g1 b1
		u2 v2 w2 r2 g2 b2 
		... 
		(done)
		(three verts of face, rj,gj,bj=rgb int values in [0,255])
	TILE_COLORS:	   (optional, packing must have 'TileData')
		n1 v1_0 ... v1_(n-1) r1 g1 b1
		n2 ..
		...
	 	(number of edges, nj, vertices, vj_0 vj_1 ... vj_(nj-1)
	 	and rj,gj,bj = rgb int values in [0,255]
	VERT_LIST: 	   	   (optional)
		v1 v2 ... (done)
		(utility list of vertices)
	FACE_TRIPLES: 	   (optional)
		v1 w1 u1
		v2 w2 u3
		...
		(done)
		(utility list of faces by their vertex triples)
	EDGE_LIST: 	   	   (optional)
		u1 v1
		u2 v2
		...
		(done)
		(utility list of edges)
	RADII_INTERACTIONS: (optional)
		v1 u1 x1
		v2 u2 x2
		...
		(done)
		(specialized: vj uj are vertices, xj is real number)
	VERTEX_MAP: 	   	   (optional)
		v1 l1
		v2 l2
		v3 l3
		...
		(done)
		(integer 'labels' for vertices; e.g, when you want
		to specify a map from vertices to circles in another
		packing.)
	VERT_MARK: 	   	   (optional)
		v1 m1
		v2 m2
		v3 m3
		...
		(done)
		(set 'mark' to mj for vertex mj; e.g, encoding some
		information.)
	EDGE_PAIRING MOBIUS: n   (optional, not for reading in)
		Prints n side-pairing Mobius transformations (if they
		exist); for each, it prints the complex values a, b, c, d, 
		and 0 or 1 (for orientation reversing)
	POINTS: n  (optional, reads floating point xyz coords for vertices 1 to n.)
		x1 y1 z1
		...
		xn yn zn
	DOUBLES: n          (optional, list of n doubles)
		y1
		y2
		...
		yn		
	DISP_FLAGS:     (optional, sets screen display options)
		Disp -w -cf -f     	  
	TILES: N          (optional for tilings)
		t1 n1 v_0 v_1 ... v_(n1-1)
		t2 n2 ..
		...
		(t=tile index, n=# of edges, v_j=list of n corners)
	TILES: (augmented) N (optional for tilings with extra edge vertices
	     t1 n1 v_0 w_1 w_2 w_3 v_1 .... w_(n-1)
	     t2 n2 ..
	     ...
		(t=tile index, n=# of edges, v_j= n corners, w_k = 3 intervening)
	TILEFLOWERS: N     (optional for tilings -- don't use with 'TILES')
	     t1 n1  t_0 e_0  t_1 e_1  t_2 e_2  ... t_(n1-1) e_(n1-1)
	     t2 n2 ..
	     ...
	     (t=tile index, n=# of edges, t_j=neighbor tile on edge j, 
	      e_j=index of edge of t_j shared with t)
	BARY_VECTOR:	(optional: lists of curves (in barycentric coords))
		BARYLIST:
			v0 v1 v2 sb0 sb1 eb0 eb1 (verts, start/end barycoords)
			...
			(done)
		BARYLIST:  (optionally more than one list)
			v0 v1 v2  sb0 sb1  eb0 eb1
			...
			(done)
		...
		END
		.
	END

Alternately: Files with other data but no combinatorics are stored as *.q files. They must begin with keyword "CHECKCOUNT:" instead of "NODECOUNT:".

2. 'Lite' packings: OBE: all "Lite" reading/writing/processing has been
removed from the code in version 5.0 (2021).

This was a compressed form for speedy communication and was a continuous string of values as follows. 
Local vertex indexing is enforced with interiors coming first, followed by boundary in counterclockwise order (though there
maybe more than one boundary component). Files typically saved with .pl extension.

 *  1234321 = magic number to identify as 'Lite' packing file
 
 * First 20 integers MUST be present: They specify numbers of various strings to come or flags:
    1: checkCount (= parent's nodeCount) for (weak) consistency checking
    2: hes = geometry (-1=hyp, 0=eucl, 1=sph)
    3: vertCount (count of local indices) = size of 'orig_indices', 'radii', 'centers' blocks
    4: intVertCount (rest are "bdry" for purpose, e.g., of Tutte embedding in Orick's algorithm)
    5: vCount = count of "variable" verts (whose radii can be changed)
    6: flowerCount = size of flower block, may be 0.
    7: aimCount = count of non-default aims = size of 'aimIndices' block = size of aim block, may be 0
    8: invDistCount = count of edges having non-default inversive distances = size 'invDistances' = half the size of 'invDistEdges', may be 0. 
       Caution: it's possible that neither end is 'variable' vertex.
    9: 0 ==> no radii, 1 ==> radii
    10: 0 ==> no centers, 1 ==> centers
    11: 0 (future use)
    12: 0 (future use)
    13: 0 (future use)
    14: 0 (future use)
    15: 0 (future use)
    16: 0 (future use)
    17: 0 (future use)
    18: 0 (future use)
    19: 0 (future use)
    20: 0 (future use)
    
 * Variable verts: (local indices)
   v_1 ... v_vCount    

 * Flowers of all vertices (local indices 1 to vertCount):
   ..
   v num p_0 p_1 .... p_num
   ..

 * Original indices in parent: 
   (CAREFUL: entry '-j' means jth ideal added in processing)
   i_1 i_2 .... i_vertCount

 * Radii: (in hyperbolic case, these are 'x-radii', x=1-exp(-2h),
 		   and for horocycles, x=-r where r is the euclidean radius)
   r_1 r_2 ... r_vertCount
  
 * Centers:
   x_1 y_1 ... x_vertCount y_vertCount

 * Aim indices: (local indices)
   i_1 i_2 ... i_aimCount

 * Aims:
   a_1 a_2 ... a_aimCount

 * Inv distance edges: (local indices)

   v_1 w_1  v_2 w_2 ..... v_invDistCount w_invDistCount

 * Inv distances:

   d_1 d_2 ... d_invDistCount

 * eof


3. Tilings: Tilings are combinatorial locally planar patterns of tiles. Each 'tile' is an n-gon for some n at (least 3) specified by a counterclockwise list
of boundary vertices. The tiles are numbered contiguously from 1. The vertices' indices are not necessarily contiguous; if not, they will be changed when the packing is read in (with
the original indiced maintained).

A file starting with TILECOUNT (as below) creates a new packing (old data is lost): it reads the tiling and creates its barycentric packing. 
There are two optional formats with key word either TILES or TILEFLOWERS. The latter allows multiple edges and/or edges a tile shares with itself.

	TILECOUNT: N
	TILES: N
        .
		t   n   v_0 v_1 ... v_(n-1) v_0
		(t=tile index (ignored), n=# of edges, v_j=close list of corners)
		.
	END
	
or

	TILECOUNT: N	
	TILEFLOWERS: 
		t n  t0 e0  t1 e1   t2 e2  ...  t(n-1) e(n-1)' 
        t=tile index (ignored), n=# of edges, 
        list of pairs, tj = index of tile across this edge (or 0) 
           and ej is the index in tile tj of the corresponding 
           edge shared with t 
	END
	
4. Triangulations: This allows any of several ascii formats, 
such as "OFF" (open file format), "VTK" (visual tool kit), 
"TRIANGULATION" (a CirclePack format), or generic data. 

  * No radii are specified, only centers and combinatorics.
  * CirclePack looks for lines starting with 2 or more doubles 
and then reads successive lines as the node data: form is
    x y [z] [r g b [a]] % 2D or 3D and optional colors
  * CirclePack also looks for line starting with at least 3 integers and then reads the combinatorial data in form
    v0 v1 v2 (trianglar) or n v0 v1 ... vn (polygonal)
  * Note that CirclePack may reindex vertices to be contiguous
from 1, with 'vertexMap' holding <new,old> information.
  * For n-gon faces with n>3, CirclePack will add a barycenter
and subdivide get a valid triangulation.

Here's an "OFF" type example:

	OFF
	V F 	(number of vertices and faces) (will be disregarded)
	x_0 y_0 [z_0 [r_0 g_0 b_0 [a_0]]]  (coords, optional colors and alpha value)
	...
	x_{V-1} y_{V-1} [z_{V-1} [r_{V-1} g_{V-1} b_{V-1} [a_{V-1}]]]
	n_1  u_1 v_1 w_1   (n1 is number of vertices, normally 3)
	...
	n_F  u_F v_F w_F
	 		
      
5. Paths: A path is a list of x y - coordinates, or a concatenation of lists separated by 'BREAK"; if not closed, each list is closed upon reading.

	  PATH
	  x1 y1
	  x2 y2
	  ...
	  BREAK
	  X1 Y1
	  X2 Y2
	  ...
	  END


6. Scripts: These are XML-structured documents. The XML schema is given below. The formating is very strict and rigidly checked by the DOM parser used with CirclePack. The heart of the file is the <cmd> "command string" </cmd> tagged items; these are the commands that go to CirclePack.


<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<!-- This schema developed for use with CirclePack, copyright 2005 -->

<xs:element name="CP_Scriptfile">	
  <xs:complexType>
    <xs:sequence>
	<xs:element name="CPscript">	
	  <xs:complexType mixed="true">
	    <xs:sequence>
		<xs:element name="header" type="xs:string" minOccurs="1" maxOccurs="1">
		<xs:element name="Section" minOccurs="0">
  		  <xs:complexType mixed="true">
		    <xs:attribute name="type">
			  <xs:simpleType>
	  		    <xs:restriction base="xs:string">
    				<xs:enumeration value="title">
    				<xs:enumeration value="section">
    				<xs:enumeration value="subsection">
  			    </xs:restriction>
			  </xs:simpleType>
			</xs:attribute>		
  		  </xs:complexType>
		</xs:element>
		<xs:element name="cmd" minOccurs="0" maxOccurs="100">
  		  <xs:complexType mixed="true">
			<xs:attribute name="name" type="xs:string" use="optional">
			<xs:attribute name="inline" default="yes">
		  	  <xs:simpleType>
    			    <xs:restriction base="xs:string">
      				<xs:pattern value="yes|no">
    			    </xs:restriction>
  			  </xs:simpleType>
			</xs:attribute>
			<xs:attribute name="hint" type="xs:string" use="optional">
  		  </xs:complexType>
		</xs:element>
	    </xs:sequence>
	  </xs:complexType>
	</xs:element>
	<xs:element name="CPdata">	
	  <xs:complexType>
	    <xs:sequence>
		<xs:element name="name" type="xs:string" min0ccurs="0"> 
                  <!-- 'name' no longer used; now use 'name' attrib -->
		<xs:element name="circlepacking" minOccurs="0">
		    <xs:attribute name="name" type="xs:string" use="optional">
		<xs:element name="commands" minOccurs="0">
		    <xs:attribute name="name" type="xs:string" use="optional">
		<xs:element name="path" minOccurs="0">
		    <xs:attribute name="name" type="xs:string" use="optional">
		<xs:element name="xyzData" minOccurs="0">
		    <xs:attribute name="name" type="xs:string" use="optional">
		<xs:element name="rawdata" minOccurs="0">
		    <xs:attribute name="name" type="xs:string" use="optional">
	    </xs:sequence>
	  </xs:complexType>
	</xs:element>
    </xs:sequence>
  </xs:complexType>
</xs:element>

</xs:schema>

			


