Importing and Exporting Data

The contents of a native Regina data file can be imported. In this case, the packet tree from the imported file will be inserted into the packet tree of the current working file.

Importing a Regina data file is therefore a convenient way of merging two data files into one. See also the regconcat utility for a way of doing this from the command-line.

A triangulation obtained from SnapPea can be imported. SnapPea is the excellent software by Jeffrey Weeks for studying hyperbolic 3-manifolds, and is also discussed in the section on SnapPea calculations.

The file 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
   

A triangulation in Orb / Casson format can be imported. Orb is a variant of SnapPea for calculating hyperbolic structures on 3-orbifolds and 3-manifolds, written by Damien Heard.

The file should be a plain text file in Orb / Casson format, which describes a triangulation in terms of its 1-skeleton. The beginning of such a 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

    ...
   

A list of dehydrated triangulation strings can be imported. A dehydration string is a set of letters such as dadbcccaqhx containing enough information to recreate the triangulation. Dehydration strings appear in census papers such as the hyperbolic cusped census of Callahan, Hildebrand and Weeks [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 dehydrated triangulation string. A sample 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
   

When importing a dehydrated triangulation list, each individual triangulation will be rehydrated and inserted beneath a common container packet, which will then be inserted into the current packet tree. If you just wish to rehydrate a single triangulation string (not many), it may be simpler to use the New Triangulation dialog instead.

Any PDF document can be imported directly into the packet tree. This allows users to document their work with formulae, diagrams and anything else that can appear on the printed page.

Because all PDF packets must be created externally (such as in LaTeX, or some other typesetting system or word processor), the Packet Tree->New PDF Document menu item brings up exactly the same import dialog as File->Import->PDF Document.

An arbitrary Python script can be imported, in which case it will be inserted into the working packet tree as a new script packet.

Recall that a script packet may have associated variables that reference other packets in the packet tree. If the imported Python file begins with a specially formatted comment block, it can direct Regina to include certain variables in the new script packet (and also suggest a default label for the new script packet).

An example of such a comment block is shown below.

    ### Regina Script: Homology Summary
    ###
    ### Variable tri: Triangulations
    ###
    ### 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, with each line beginning with three hashes (###). A suggested packet label is indicated with a line of the form ### Regina Script: label. Each variable is listed in a line of the form ### Variable name: value, where name is the name of the script variable and value is the label of the packet that it should represent.

Note that this comment block will not appear in the code section of the new script packet. That is, Regina will read in the suggested packet label, make the requested variable assignments and then throw the entire comment block away.

If the script contains any international characters, you must specify the text encoding used (such as UTF-8 or LATIN1). When you are selecting the file to an import, a drop-down list of encodings should appear in the dialog, as illustrated below.