# Importing and Exporting Data

By default, ®ina; reads and writes `.rga` data files in its own compressed &xml; file format. The current (third-generation) file format was introduced in ®ina; 7.0.

Besides this, ®ina; can also import data from and export data to several other file formats (including ®ina;'s own older second-generation format). This allows you to pass data between ®ina; and other applications. This chapter outlines the available import and export formats.

If you are writing filters for some other program and you need a full specification for ®ina;'s own &xml; file format, select Help File Format Reference from the menu. You can also read the most up-to-date specification of ®ina;'s file format on the ®ina; website.

## Importing

An import involves reading data from some foreign file format and inserting it into your working packet tree (effectively merging it into whatever file you already have open). All imports are done through the File Import menu.

When you select an action from the File Import menu, you will first be asked to select a file. Once you have chosen the file to import, a second window will appear asking for additional details:

Import beneath:

Here you select where in the packet tree the imported data will appear. The import will appear as a child packet, directly beneath whatever “parent” you choose here.

Label:

This will be the label (i.e., the name) of the new packet containing the imported data.

®ina; can import data from the following file formats:

### ®ina; Data Files

You can import another ®ina; data file. This effectively lets you insert the contents of one file inside another.

This is a convenient way of merging two data files into one. You can also merge data files from the command-line using the `regconcat` utility.

®ina; can happily import either the new (third-generation, since ®ina; 7.0) or older (second-generation, until ®ina; 6.0.1) file formats, and can read both compressed and uncompressed &xml;.

### &snappea; Triangulations

You can import a 3-manifold triangulation from &snappeapylink;, the excellent software for studying hyperbolic 3-manifolds by Culler, Dunfield and Weeks. Note that you can also perform some &snappea; calculations directly within ®ina;.

After the import, the triangulation will appear in ®ina; as a hybrid &snappea; triangulation; this ensures that &snappea;-specific data (such as fillings and peripheral curves) will be preserved. You can then convert this to one of ®ina;'s native triangulations if you wish.

The file that you import should be a plain text file in &snappea;'s triangulation format; an example is shown below. Any international characters should be encoded in &utf8;.

        % Triangulation
        m002
        geometric_solution  2.02988321
        nonorientable_manifold
        CS_unknown

        0 2
            Klein   0.000000000000   0.000000000000
            Klein   0.000000000000   0.000000000000

        2
           1    1    1    1
         0132 3120 2130 3102
           0    1    0    0
          0  0  0  0  0  0  1 -1  0  0  0  0  1 -1  0  0
          0  1 -1  0  0  0  0  0 -1  0  0  1  0  0  0  0
          0  0  1 -1 -1  0  1  0  1  0  0 -1 -1  1  0  0
          0  0  1 -1 -1  0  1  0  1  0  0 -1 -1  1  0  0
          0.500000000000   0.866025403784

           0    0    0    0
         0132 3120 2130 3102
           0    1    0    0
          0  1 -1  0  0  0  0  0 -1  0  0  1  0  0  0  0
          0  0  0  0  0  0  1 -1  0  0  0  0  1 -1  0  0
          0 -1  1  0  1  0  0 -1  1  0  0 -1 -1  0  1  0
          0 -1  1  0  1  0  0 -1  1  0  0 -1 -1  0  1  0
          0.500000000000   0.866025403784

### &orbcasson; Triangulations

You can import a 3-manifold triangulation from &orbcasson; format. &orburl; is a variant of &snappea; for calculating hyperbolic structures on 3-orbifolds and 3-manifolds, written by Damien Heard.

The file that you import should be a plain text file in &orbcasson; format, which describes a triangulation in terms of its 1-skeleton. The beginning of an example file is illustrated below. Any international characters should be encoded in &utf8;.

        % orb
        8knot
        1  0  1.000  1vu  2uw  1ux  2xv  1xw  2vu
        2  0  1.000  1wu  2wx  1xv  2xu  1vw  2vw

        ...

### Isomorphism / Knot Signature Lists

You can import a list of isomorphism signatures or knot/link signatures from a text file. These signatures are a space-efficient, plain-text method of storing a list of triangulations or link diagrams.

An isomorphism signature is a compact sequence of letters, digits and/or punctuation that identifies a triangulation uniquely up to combinatorial isomorphism. A knot/link signature is a similar type of sequence of symbols that encodes a link diagram up to various relabelling, rotation, reflection and/or reversal operations. See the composition viewer for a more detailed discussion on isomorphism signatures, or bib-burton-pachner-orprime for examples of their use and a precise description of the 3-manifold signature format.

The list should be stored in a plain text file with one triangulation or knot per line. Each line may contain an arbitrary amount of data, but the first word of each line should be the isomorphism or knot/link signature. Note that signatures are case sensitive (i.e., upper-case and lower-case matter). An example file for 3-manifold triangulations is shown below.

        dLQbcbchxjn   L(11,3)
        dLQbcbchxjj   L(10,3)
        dLQbcbcahrs   L(5,2)
        dLQbcbcahks   S3
        dLQbcbchhjw   L(9,2)

In an isomorphism signature list, all signatures must represent triangulations of the same dimension (so, for example, the list cannot contain a mix of 3-manifold and 4-manifold signatures; likewise, it cannot contain a mix of signatures for triangulations and links). The File Import menu has different menu items for importing lists in dimensions 2, 3 and 4, and for importing lists of knot/link signatures. ®ina; does support isomorphism signatures in higher dimensions, but for this you will need to use &python;.

The import will appear in your packet tree as a new container, which will contain a new triangulation for each isomorphism signature in the list.

If you just wish to reconstruct a triangulation or knot from a single signature (not from many signatures), you can do this more easily by creating a new triangulation or a new link.

### Dehydrated Triangulation Lists

You can import a list of dehydration strings from a text file. Like isomorphism signatures, dehydration strings allow you to encode a list of 3-manifold triangulations in a space-efficient, plain-text manner.

Dehydration strings are less powerful than isomorphism signatures: only some triangulations have them (the triangulation must be connected with no boundary triangles and ≤ 25 tetrahedra), and they are not unique up to isomorphism (so relabelling tetrahedra might change the dehydration string). They feature in hyperbolic census papers such as bib-cuspedcensus, in which the dehydration format is explicitly described.

The list should be stored in a plain text file with one triangulation per line. Each line may contain an arbitrary amount of data, but the first word of each line should be the dehydration string. An example file is shown below.

        dafbcccaadl   N3,1   Z/3 + Z
        dadcbccdjkd   N3,2   Z
        dadbcccbbcv   N3,3   Z
        dadbcccccdm   N3,4   Z
        dadbcccaqhx   N3,5   Z/2 + Z/2 + Z

As with isomorphism signatures, the import will appear in your packet tree as a new container, which will contain a new triangulation for each dehydration string in the list.

If you just wish to reconstruct a triangulation from a single dehydration string (not from many strings), you can do this more easily by creating a new triangulation.

### &python; Scripts

You can import a &python; script, which will appear in your data file as a script packet.

Script packets can include pre-set variables that reference other packets in your data file. If the imported file begins with a specially formatted comment block, ®ina; will recognise this and set variables in your script packet accordingly. This comment block will be written automatically when you export a script packet to a &python; file. The special comment block is used only for setting variables, and will not appear in the code for your new script packet.

An example of such a comment block appears below.

        ### Regina Script: Homology Summary
        ###
        ### Variable tri: 3-Manifolds
        ###
        ### Begin Script

        # See the users' handbook for more elaborate sample Python
        # sessions.

        # Output the homology of each triangulation.
        t = tri.firstChild()
        while t != None:
            print t.label() + ":", t.homology()
            t = t.nextSibling()

The comment block must appear at the very beginning of the file, and each line must begin with three hashes (`###`). A line of the form “`### Regina Script: `label``” suggests to ®ina; a default label for your new packet. Each line of the form “`### Variable `name`: `value``” tells ®ina; to add the variable `name` to the new script packet, and to make it refer to the packet in your data file named `value`.

During the import, ®ina; will tell you how it will interpret any international characters in the script (that is, letters or symbols not found on a typical English keyboard). Such characters are stored using a text encoding, such as &utf8; (a popular modern standard and the default in ®ina;), or &latin1; (which has a long history of use with many Western European languages). If your script uses a different encoding, you will need to set this in ®ina;'s options. If you only ever use letters or symbols found on a typical English keyboard, you do not need to worry about this at all.

### Attachments

You can insert any other file into your ®ina; data file by importing it as an attachment. For example, you could import a &pdf; document that documents your work with detailed formulae and diagrams.

To do this, select Packet Tree New Attachment from the menu. ®ina; will go through the same import process as described above.

Once you have imported your attachment, you can safely edit, move or even delete the original file from your computer, since your ®ina; data file will keep its own internal copy.

## Exporting

An export involves writing data from your working packet tree into some foreign file format. For most formats you can only export small pieces of your packet tree at a time (such as individual triangulations). All exports are done through the File Export menu.

When you select an action from the File Export menu, ®ina; will ask you which packet to export. For most export formats ®ina; will only export the selected packet, but for some formats (such as ®ina;'s own data format) it will export an entire packet subtree.

After selecting a packet, you will be asked to choose a filename for your export. ®ina; will then save the exported data to that file.

®ina; can export data to the following file formats:

### ®ina; Data Files

This is ®ina;'s native file format, which saves data as compressed &xml;. ®ina; can export an entire packet subtree to this format: just choose the root of of the subtree as the packet to export. ®ina; will export not just the packet you select, but all of the packets beneath it in the tree.

This is a convenient way of extracting a small portion from a larger data file.

The packet that you select for export will become the top-level packet in the new tree (i.e., ®ina; will not add a new container to the top of the export data file).

There are three menu items for exporting to a ®ina; data file:

- File Export ®ina; Data File will export the data as compressed &xml; using the new file format introduced with ®ina; 7.0. This is the default file format that is used when you select File Save .

- File Export ®ina; Data File (Uncompressed) will export the data as plain &xml; (which means you can view the &xml; in your favourite text editor), again using the new file format introduced with ®ina; 7.0. Note that ®ina; can happily read data files in either compressed or uncompressed format.

- File Export Legacy ®ina; Data File (≤ 6.0.1) will export the data as compressed &xml; using the old file format from ®ina; 3.0–6.0.1.

If you simply want to view the raw &xml; content of an existing data file, you do not need to go to the trouble of exporting it in uncompressed format. Instead you can just pipe the data file through `gunzip`:

        example$ cat file.rga | gunzip

### &snappea; Triangulations

You can export a 3-manifold triangulation (either one of ®ina;'s native triangulations or a hybrid &snappea; triangulation) to the file format used by &snappeapylink;. This is a plain text format, and is described in more detail in the section on &snappea; imports.

Not every ®ina; triangulation can be exported to &snappea; format. For instance, the triangulation cannot be invalid, and it may not have any boundary triangles. ®ina; will tell you if your triangulation cannot be exported.

If you are exporting one of ®ina;'s native triangulation packets, then ®ina; will mark any &snappea;-specific information (such as fillings or peripheral curves) as unknown. If you are exporting one of ®ina;'s hybrid &snappea; triangulations, then ®ina; will include this extra &snappea;-specific information in the exported file.

Any international characters in the exported &snappea; file will be encoded using &utf8;.

### &recogniser; Triangulations

You can export a 3-manifold triangulation (either one of ®ina;'s native triangulations or a hybrid &snappea; triangulation) to a plain text file that can be given as input to Matveev's &recogniserlink;.

As with the &snappea; format, not every data file can be exported to the &recogniser;. In particular, the triangulation cannot be invalid, and it may not have any boundary triangles. ®ina; will tell you if your triangulation cannot be exported.

### Spreadsheet-Readable (&csv;) Surface Lists

You can export a normal surface list to a plain-text &csv; file (comma-separated values), which you can easily import into a spreadsheet or database.

The &csv; file will begin with a header row, followed by one line for each normal surface in the list. Surfaces will be exported in standard coordinates (that is, tri-quad coordinates for normal surfaces, or tri-quad-oct coordinates for almost normal surfaces). The fields in the &csv; file will mirror the columns that you see in the normal surface coordinate viewer, and will include properties such as Euler characteristic and orientability as well as the surface coordinates themselves.

If any of the surfaces have names that include international characters, these names will be exported in &utf8;.

### &python; Scripts

You can export a script packet as a regular &python; file. ®ina; will add a special comment block to the top of the file, describing the packet label and the script variables. This special comment block allows you to import the script seamlessly back into ®ina;; see &python; imports for details.

During the export, ®ina; will tell you how it will write any international characters in the script (that is, letters or symbols not found on a typical English keyboard). Such characters are stored using a text encoding, such as &utf8; (a popular modern standard and the default in ®ina;), or &latin1; (which has a long history of use with many Western European languages). If you wish to use a different encoding, you will need to set this in ®ina;'s options. If you are not sure, the default of &utf8; is typically a good choice. If you only ever use letters or symbols found on a typical English keyboard, you do not need to worry about text encodings at all.