# Importing and Exporting Data

## Chapter 8. Importing and Exporting Data

By default, Regina reads and writes `.rga` data files in its own compressed XML file format. However, Regina can also import data from and export data to several other file formats, which allows you to pass data between Regina 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 Regina's own XML file format, select Help->File Format Reference from the menu.

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

Regina can import data from the following file formats:

### Regina Data Files

You can import another Regina 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.

### SnapPea Triangulations

You can import a 3-manifold triangulation from SnapPea / SnapPy, the excellent software for studying hyperbolic 3-manifolds by Culler, Dunfield and Weeks. Note that you can also perform some SnapPea calculations directly within Regina.

After the import, the triangulation will appear in Regina 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 Regina'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 UTF-8.

        % 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

### Orb / Casson Triangulations

You can import a 3-manifold triangulation from Orb / Casson format. Orb 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 Orb / Casson 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 UTF-8.

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

        ...

### Isomorphism Signature Lists

You can import a list of isomorphism signatures from a text file. This is a space-efficient, plain-text method of storing a list of either 2-manifold or 3-manifold triangulations.

An isomorphism signature is a compact sequence of letters, digits and/or punctuation that identifies a triangulation uniquely up to combinatorial isomorphism. See the composition viewer for a more detailed discussion on isomorphism signatures, or [Bur11c] 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 per line. Each line may contain an arbitrary amount of data, but the first word of each line should be the isomorphism signature. Note that isomorphism signatures are case sensitive (i.e., upper-case and lower-case matter). An example file is shown below.

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

An isomorphism signature list must contain either all 2-manifold triangulations, or all 3-manifold triangulations (not a mix of both). The File->Import has different menu items for importing lists for each dimension.

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 from a single isomorphism signature (not from many signatures), you can do this more easily by creating a new triangulation.

### 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. They feature in hyperbolic census papers such as [CHW99], 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.

### PDF Documents

You can import a PDF document, which will appear in your data file as a PDF packet. This you to document your work with formulae, diagrams and anything else that can appear on the printed page.

This is the only way of creating a PDF packet within Regina. If you select Packet Tree->New PDF Document from the menu, Regina will go through exactly the same import process as described here.

### 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, Regina 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.getFirstTreeChild()
        while t != None:
            print t.getPacketLabel() + ":", t.getHomologyH1()
            t = t.getNextTreeSibling()

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 Regina a default label for your new packet. Each line of the form “`### Variable `name`: `value``” tells Regina 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, Regina 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 UTF-8 (a popular modern standard and the default in Regina), 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 Regina's options. If you only ever use letters or symbols on a typical English keyboard, you do not need to worry about this at all.