Foreign File Formats

Reading and writing foreign file formats. More...

## Enumerations

enum

regina::SurfaceExportFields {
regina::surfaceExportName = 0x0001, regina::surfaceExportEuler = 0x0002, regina::surfaceExportOrient = 0x0004, regina::surfaceExportSides = 0x0008,
regina::surfaceExportBdry = 0x0010, regina::surfaceExportLink = 0x0020, regina::surfaceExportType = 0x0040, regina::surfaceExportNone = 0,
regina::surfaceExportAllButName = 0x007e, regina::surfaceExportAll = 0x007f
}

| Indicates a set of additional fields that can be exported as part of a normal surface list. More...

## Functions

REGINA_API bool | regina::writeCSVStandard (const char *filename, NNormalSurfaceList &surfaces, int additionalFields=surfaceExportAll)
| Exports the given list of normal surfaces as a plain text CSV (comma-separated value) file. More...
REGINA_API bool | regina::writeCSVEdgeWeight (const char *filename, NNormalSurfaceList &surfaces, int additionalFields=surfaceExportAll)
| Exports the given list of normal surfaces as a plain text CSV (comma-separated value) file. More...
REGINA_API NContainer * | regina::readDehydrationList (const char *filename, unsigned colDehydrations=0, int colLabels=-1, unsigned long ignoreLines=0)
| Reads a list of dehydrated triangulations from the given text file. More...
REGINA_API NContainer * | regina::readIsoSigList (const char *filename, unsigned dimension=3, unsigned colSigs=0, int colLabels=-1, unsigned long ignoreLines=0)
| Reads a list of isomorphism signatures from the given text file. More...
REGINA_API NTriangulation * | regina::readOrb (const char *filename)
| Reads a triangulation from the given Orb / Casson file. More...
REGINA_API NPDF * | regina::readPDF (const char *filename)
| Reads a PDF document from the given file. More...
REGINA_API bool | regina::writePDF (const char *filename, const NPDF &pdf)
| Writes the given PDF document to the given file. More...
REGINA_API bool | regina::writeRecogniser (const char *filename, NTriangulation &tri)
| Writes the given triangulation to the given file in Matveev's 3-manifold recogniser format. More...
REGINA_API bool | regina::writeRecognizer (const char *filename, NTriangulation &tri)
| A synonym for writeRecogniser(). More...
REGINA_API NTriangulation * | regina::readSnapPea (const char *filename)
| Reads a triangulation from the given SnapPea file. More...
REGINA_API NTriangulation * | regina::readSnapPea (std::istream &in)
| Reads a triangulation from an input stream that contains the contents of a SnapPea file. More...
REGINA_API bool | regina::writeSnapPea (const char *filename, const NTriangulation &tri)
| Writes the given triangulation to the given file in SnapPea format. More...
REGINA_API void | regina::writeSnapPea (std::ostream &out, const NTriangulation &tri)
| Writes the given triangulation to the given output stream using SnapPea's file format. More...

## Detailed Description

Reading and writing foreign file formats.

## Enumeration Type Documentation

enum regina::SurfaceExportFields

Indicates a set of additional fields that can be exported as part of a normal surface list.

This type can be used as a bitmask: to describe a set of fields, simply combine several individual fields using bitwise or.

The list of available fields may grow with future releases of Regina.

Enumerator
surfaceExportName | Represents the user-assigned surface name.
surfaceExportEuler | Represents the calculated Euler characteristic of a surface. This will be an integer, and will be left empty if the Euler characteristic cannot be computed.
surfaceExportOrient | Represents the calculated property of whether a surface is orientable. This will be `TRUE` or `FALSE`, or will be left empty if the orientability cannot be computed.
surfaceExportSides | Represents the calculated property of whether a surface is one-sided or two-sided. This will be the integer 1 or 2, or will be left empty if the "sidedness" cannot be computed.

surfaceExportBdry

Represents the calculated property of whether a surface is bounded.

In most cases, this will be one of the strings "closed", "real bdry" or "infinite" (where "infinite" indicates a surface with infinitely many discs). For spun-normal surfaces in certain ideal triangulations, this string will be followed by the boundary slopes of the surface at the cusps: these written as a list of pairs (p, q), one for each cusp, indicating that the boundary curves of the surface run p times around the meridian and q times around the longitude. See NNormalSurface::boundarySlopes() for further information on interpreting these values.

surfaceExportLink | Represents whether a surface is a single vertex link or a thin edge link. See NNormalSurface::isVertexLink() and NNormalSurface::isThinEdgeLink() for details. This will be written as a human-readable string.
surfaceExportType | Represents any additional high-level properties of a surface, such as whether it is a splitting surface or a central surface. This will be written as a human-readable string. This field is somewhat arbitrary, and the precise properties it describes are subject to change in future releases of Regina.
surfaceExportNone | Indicates that no additional fields should be exported.
surfaceExportAllButName | Indicates that all available fields should be exported, except for the user-assigned surface name. Since the list of available fields may grow with future releases, the numerical value of this constant may change as a result.
surfaceExportAll | Indicates that all available fields should be exported, including the user-assigned surface name. Since the list of available fields may grow with future releases, the numerical value of this constant may change as a result.

## Function Documentation

REGINA_API NContainer* regina::readDehydrationList | ( | const char * | filename,
|  | unsigned | colDehydrations = `0`,
|  | int | colLabels = `-1`,
|  | unsigned long | ignoreLines = `0`
| ) |  |

Reads a list of dehydrated triangulations from the given text file.

The file should contain one dehydration string per line. These strings will be rehydrated as described in NTriangulation::insertRehydration().

A newly allocated container will be returned; the imported triangulations will be inserted as children of this container. The container will not be assigned a label. The individual triangulations will be assigned labels according to the parameter colLabels.

If any dehydrations strings are invalid, these will be recorded in an additional text packet that will be the last child of the returned container.

If an I/O error occurred while trying to read the given file, 0 will be returned.

In its simplest form, the text file can simply contain one dehydration string per line and nothing else. However, more complex formats are allowed. In particular, by passing appropriate values for the arguments colDehydrations and colLabels, the dehydration strings and triangulation packet labels can be taken from arbitrary columns of the text file. Columns are considered to be separated by whitespace and are numbered beginning at 0.

Internationalisation:
  This routine makes no assumptions about the character encoding used in the given file name, and simply passes it through unchanged to low-level C/C++ file I/O routines. It assumes however that the contents of the file are in UTF-8.

Parameters

  filename | the name of the text file from which to read.
  colDehydrations | the column of the text file containing the dehydration strings.
  colLabels | the column of the text file containing the triangulation packet labels. If this is negative then the dehydration strings themselves will be used as packet labels.
  ignoreLines | the number of lines at the beginning of the text file that should be ignored completely.

Returns
  a new container as described above, or 0 if an I/O error occurred whilst reading the given file.

REGINA_API NContainer* regina::readIsoSigList | ( | const char * | filename,
|  | unsigned | dimension = `3`,
|  | unsigned | colSigs = `0`,
|  | int | colLabels = `-1`,
|  | unsigned long | ignoreLines = `0`
| ) |  |

Reads a list of isomorphism signatures from the given text file.

The file should contain one isomorphism signature per line. These isomorphism signatures will be converted into triangulations using NTriangulation::fromIsoSig().

A newly allocated container will be returned; the imported triangulations will be inserted as children of this container. The container will not be assigned a label. The individual triangulations will be assigned labels according to the parameter colLabels.

If any isomorphism signatures are invalid, these will be recorded in an additional text packet that will be the last child of the returned container.

If an I/O error occurred while trying to read the given file, 0 will be returned.

In its simplest form, the text file can simply contain one isomorphism signature per line and nothing else. However, more complex formats are allowed. In particular, by passing appropriate values for the arguments colSigs and colLabels, the isomorphism signatures and triangulation packet labels can be taken from arbitrary columns of the text file. Columns are considered to be separated by whitespace and are numbered beginning at 0.

Internationalisation:
  This routine makes no assumptions about the character encoding used in the given file name, and simply passes it through unchanged to low-level C/C++ file I/O routines. It assumes however that the contents of the file are in UTF-8.

Parameters

  filename | the name of the text file from which to read.
  dimension | must be set to 3, indicating that isomorphism signatures should be expanded into 3-manifold triangulations. This argument is a placeholder for future expansion, and currently no value other than 3 is allowed.
  colSigs | the column of the text file containing the isomorphism signatures.
  colLabels | the column of the text file containing the triangulation packet labels. If this is negative then the isomorphism signatures themselves will be used as packet labels.
  ignoreLines | the number of lines at the beginning of the text file that should be ignored completely.

Returns
  a new container as described above, or 0 if an I/O error occurred whilst reading the given file.

REGINA_API NTriangulation* regina::readOrb | ( | const char * | filename | ) |

Reads a triangulation from the given Orb / Casson file.

A newly allocated triangulation will be returned; it is the user's responsibility to deallocate this when it is finished with.

The packet label of the new triangulation will be the manifold name read from the second line of the Orb / Casson file. The first line of the Orb / Casson file must simply be ```% orb`''.

If the file could not be read or if the data was not in the correct format, 0 will be returned.

Internationalisation:
  This routine makes no assumptions about the character encoding used in the given file name, and simply passes it through unchanged to low-level C/C++ file I/O routines. It assumes however that the contents of the file are in UTF-8.

Parameters

  filename | the name of the Orb / Casson file from which to read.

Returns
  a new triangulation containing the data read from the Orb / Casson file, or 0 on error.

Author
  Ryan Budney, also with code from Damien Heard

REGINA_API NPDF* regina::readPDF | ( | const char * | filename | ) |

Reads a PDF document from the given file.

A newly allocated PDF packet will be returned; it is the user's responsibility to deallocate this when it is finished with.

This routine does not check whether the given file looks like a PDF document; it simply loads the file contents blindly.

The packet label of the new PDF packet will be left empty.

If the file could not be read, 0 will be returned.

Internationalisation:
  This routine makes no assumptions about the character encoding used in the given file name, and simply passes it through unchanged to low-level C/C++ file I/O routines.

Parameters

  filename | the filename of the PDF document to read.

Returns
  a new PDF packet containing the PDF document, or 0 on error.

REGINA_API NTriangulation* regina::readSnapPea | ( | const char * | filename | ) |

Reads a triangulation from the given SnapPea file.

This routine reads from the filesystem; see readSnapPea(std::istream&) for a variant of this routine that can read from an arbitrary input stream.

A newly allocated triangulation will be returned; it is the user's responsibility to deallocate this when it is finished with.

The packet label of the new triangulation will be the manifold name read from the second line of the SnapPea file. The first line of the SnapPea file must simply be ```% Triangulation`.

If the file could not be read or if the data was not in the correct format, 0 will be returned.

Precondition
  The first two lines of the SnapPea file each contain at most 1000 characters.

Internationalisation:
  This routine makes no assumptions about the character encoding used in the given file name, and simply passes it through unchanged to low-level C/C++ file I/O routines. It assumes however that the contents of the file are in UTF-8.

Parameters

  filename | the name of the SnapPea file from which to read.

Returns
  a new triangulation containing the data read from the SnapPea file, or 0 on error.

REGINA_API NTriangulation* regina::readSnapPea | ( | std::istream & | in | ) |

Reads a triangulation from an input stream that contains the contents of a SnapPea file.

This is essentially the same as readSnapPea(const char*), except that it can work with any input stream.

A newly allocated triangulation will be returned; it is the user's responsibility to deallocate this when it is finished with.

The packet label of the new triangulation will be the manifold name read from the second line of the SnapPea file. The first line of the SnapPea file must simply be ```% Triangulation`.

If the input stream could not be read or if the data was not in the correct format, 0 will be returned.

Precondition
  The first two lines of the SnapPea file each contain at most 1000 characters.

Internationalisation:
  This routine makes no assumptions about the character encoding used in the given file name, and simply passes it through unchanged to low-level C/C++ file I/O routines. It assumes however that the contents of the file are in UTF-8.

Python:
  Not present, although the filesystem variant readSnapPea(const char*) is available.

Parameters

  in | the input stream from which to read.

Returns
  a new triangulation containing the data read from the SnapPea data, or 0 on error.

REGINA_API bool regina::writeCSVEdgeWeight | ( | const char * | filename,
|  | NNormalSurfaceList & | surfaces,
|  | int | additionalFields = `surfaceExportAll`
| ) |  |

Exports the given list of normal surfaces as a plain text CSV (comma-separated value) file.

CSV files are human-readable and human-editable, and are suitable for importing into spreadsheets and databases.

The surfaces will be exported in edge weight coordinates. Thus there will be one coordinate for each edge of the underlying triangulation; each such coordinate will become a separate field in the CSV file.

As well as the normal surface coordinates, additional properties of the normal surfaces (such as Euler characteristic, orientability, and so on) can be included as extra fields in the export. Users can select precisely which properties to include by passing a bitmask formed from regina::SurfaceExportFields constants.

The CSV format used here begins with a header row, and uses commas as field separators. Text fields with arbitrary contents are placed inside double quotes, and the double quote character itself is represented by a pair of double quotes. Thus the string `my "normal" surface's name` would be stored as `"my ""normal"" surface's name"`.

Internationalisation:
  This routine makes no assumptions about the character encoding used in the given file name, and simply passes it through unchanged to low-level C/C++ file I/O routines. Any user strings such as surface names will be written in UTF-8.

Parameters

  filename | the name of the CSV file to export to.
  surfaces | the list of normal surfaces to export.
  additionalFields | a bitwise combination of regina::SurfaceExportFields constants indicating which additional properties of surfaces should be included in the export.

Returns
  `true` if the export was successful, or `false` otherwise.

REGINA_API bool regina::writeCSVStandard | ( | const char * | filename,
|  | NNormalSurfaceList & | surfaces,
|  | int | additionalFields = `surfaceExportAll`
| ) |  |

Exports the given list of normal surfaces as a plain text CSV (comma-separated value) file.

CSV files are human-readable and human-editable, and are suitable for importing into spreadsheets and databases.

The surfaces will be exported in standard coordinates (tri-quad coordinates for normal surfaces, or tri-quad-oct coordinates for almost normal surfaces). Each coordinate will become a separate field in the CSV file.

As well as the normal surface coordinates, additional properties of the normal surfaces (such as Euler characteristic, orientability, and so on) can be included as extra fields in the export. Users can select precisely which properties to include by passing a bitmask formed from regina::SurfaceExportFields constants.

The CSV format used here begins with a header row, and uses commas as field separators. Text fields with arbitrary contents are placed inside double quotes, and the double quote character itself is represented by a pair of double quotes. Thus the string `my "normal" surface's name` would be stored as `"my ""normal"" surface's name"`.

Internationalisation:
  This routine makes no assumptions about the character encoding used in the given file name, and simply passes it through unchanged to low-level C/C++ file I/O routines. Any user strings such as surface names will be written in UTF-8.

Parameters

  filename | the name of the CSV file to export to.
  surfaces | the list of normal surfaces to export.
  additionalFields | a bitwise combination of regina::SurfaceExportFields constants indicating which additional properties of surfaces should be included in the export.

Returns
  `true` if the export was successful, or `false` otherwise.

REGINA_API bool regina::writePDF | ( | const char * | filename,
|  | const NPDF & | pdf
| ) |  |

Writes the given PDF document to the given file.

This routine does not check whether the contents of the given packet look like a PDF document; it simply writes them blindly to the given file.

If the given PDF packet is empty (i.e., does not contain a real block of data) then the resulting file will be created but left empty.

Internationalisation:
  This routine makes no assumptions about the character encoding used in the given file name, and simply passes it through unchanged to low-level C/C++ file I/O routines.

Parameters

  filename | the filename of the PDF document to write.
  pdf | the PDF packet to write to the given file.

Returns
  `true` if the export was successful, or `false` otherwise.

REGINA_API bool regina::writeRecogniser | ( | const char * | filename,
|  | NTriangulation & | tri
| ) |  |

Writes the given triangulation to the given file in Matveev's 3-manifold recogniser format.

Precondition
  The given triangulation is not invalid, and does not contain any boundary triangles.

Internationalisation:
  This routine makes no assumptions about the character encoding used in the given file name, and simply passes it through unchanged to low-level C/C++ file I/O routines. The contents of the file will be written using UTF-8.

Parameters

  filename | the name of the Recogniser file to which to write. This may be the null pointer (or the empty string), in which case the data will be written to standard output instead.
  tri | the triangulation to write to the Recogniser file.

Returns
  `true` if the export was successful, or `false` otherwise.

bool regina::writeRecognizer | ( | const char * | filename,
|  | NTriangulation & | tri
| ) |  |

inline

A synonym for writeRecogniser().

See writeRecogniser() for details.

REGINA_API bool regina::writeSnapPea | ( | const char * | filename,
|  | const NTriangulation & | tri
| ) |  |

Writes the given triangulation to the given file in SnapPea format.

This routine writes to the filesystem; see writesnapPea(std::ostream&, NTriangulation&) for a variant of this routine that can write to an arbitrary output stream.

All information aside from tetrahedron gluings will be flagged as unknown for SnapPea to recalculate. The manifold name written in the file will be derived from the packet label.

Precondition
  The given triangulation is not invalid, and does not contain any boundary triangles.

Internationalisation:
  This routine makes no assumptions about the character encoding used in the given file name, and simply passes it through unchanged to low-level C/C++ file I/O routines. The contents of the file will be written using UTF-8.

Parameters

  filename | the name of the SnapPea file to which to write.
  tri | the triangulation to write to the SnapPea file.

Returns
  `true` if the export was successful, or `false` if there was a problem writing to the file.

REGINA_API void regina::writeSnapPea | ( | std::ostream & | out,
|  | const NTriangulation & | tri
| ) |  |

Writes the given triangulation to the given output stream using SnapPea's file format.

This is essentially the same as writeSnapPea(const char*, NTriangulation&), except that it can work with any output stream.

All information aside from tetrahedron gluings will be flagged as unknown for SnapPea to recalculate. The manifold name written in the file will be derived from the packet label.

Precondition
  The given triangulation is not invalid, and does not contain any boundary triangles.

Internationalisation:
  The contents of the SnapPea file will be written using UTF-8.

Python:
  Not present, although the filesystem variant writeSnapPea(const char*, NTriangulation&) is available.

Parameters

  out | the output stream to which to write.
  tri | the triangulation to write to the SnapPea file.

Copyright © 1999-2013, The Regina development team
This software is released under the GNU General Public License, with some additional permissions; see the source code for details.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@debian.org).