CGAL 6.1 - IO Streams

Loading...
Searching...
No Matches
Supported File Formats

CGAL provides a large number of data structures and algorithms dedicated to various applications.

This page lists the various supported file formats and the data structures offered by CGAL that may be used to read and write files of each specific format.

- Object File Format (OFF)
- Wavefront Advanced Visualizer Object Format (OBJ)
- OpenMesh (OM) File format
- STereoLithography (STL) File Format
- Polygon File Format (PLY)
- XYZ File Format
- VTK (VTU / VTP / legacy) File Formats
- GOCAD (TS) File Format
- 3D Manufacturing Format (3MF)
- Virtual Reality Modeling Language (VRML) File Format
- LAS (Lidar) File Format
- Avizo File Format
- Medit File Format
- Tetgen File Format
- Well-Known Text (WKT) File Format

# Object File Format (OFF)

The `OFF` file format, using the file extension `.off`, can be used to represent collections of planar polygons with possibly shared vertices. Although it can be as light as providing points and faces described by IDs, the format also allows users to provide more properties such as associating normals or colors to vertices.

A precise specification of the format is available at geomview.org.

Note that the format defines both ASCII and binary OFF formats, but only the ASCII OFF format is supported in CGAL.

The following table lists some CGAL data structures that have I/O functions compatible with this file format.

Object File Format (OFF)
Input | Polygon Mesh | `CGAL::Surface_mesh` | CGAL::IO::read_OFF(const std::string&, CGAL::Surface_mesh&)
`CGAL::Polyhedron_3` | CGAL::IO::read_OFF(std::istream& in, CGAL::Polyhedron_3<Traits>& P)
Any model of `MutableFaceGraph` | CGAL::IO::read_OFF(const std::string&, Graph&)
Point Set | `CGAL::Point_set_3` | CGAL::IO::read_OFF(const std::string&, CGAL::Point_set_3&)
Any point range | CGAL::IO::read_OFF(const std::string&, PointOutputIterator)
Polygon Soup | Any point + polygon range | CGAL::IO::read_OFF(const std::string&, PointRange&, PolygonRange&)
Output | Polygon Mesh | `CGAL::Surface_mesh` | CGAL::IO::write_OFF(const std::string, CGAL::Surface_mesh&)
`CGAL::Polyhedron_3` | CGAL::IO::write_OFF(std::ostream&, const CGAL::Polyhedron_3<Traits>&)
Any model of `FaceGraph` | CGAL::IO::write_OFF(const std::string&, const Graph&)
Point Set | `CGAL::Point_set_3` | CGAL::IO::write_OFF(const std::string&, const CGAL::Point_set_3&)
Any point range | CGAL::IO::write_OFF(const std::string&, const PointRange&)
Polygon Soup | Any point + polygon range | CGAL::IO::write_OFF(const std::string&, const PointRange&, const PolygonRange&)

If the data of a polygon mesh cannot be read in a `FaceGraph` due to bad orientation or manifoldness issues, consider using `CGAL::Polygon_mesh_processing::IO::read_polygon_mesh()` , which offers combinatorial repairing while reading bad inputs.

# Wavefront Advanced Visualizer Object Format (OBJ)

The `OBJ` file format, using the file extension `.obj`, is a simple ASCII data format that represents 3D geometry. Vertices are stored in a counterclockwise order by default, making explicit declaration of face normals unnecessary.

A precise specification of the format is available here.

Wavefront Advanced Visualizer Object Format (OBJ)
Input | Polygon Mesh | Any model of `MutableFaceGraph` | CGAL::IO::read_OBJ(const std::string&, Graph&)
Polygon Soup | Any point + polygon range | CGAL::IO::read_OBJ(const std::string&, PointRange&, PolygonRange&)
Output | Polygon Mesh | Any model of `FaceGraph` | CGAL::IO::write_OBJ(const std::string&, const Graph&)
Polygon Soup | Any point + polygon range | CGAL::IO::write_OBJ(const std::string&, const PointRange&, const PolygonRange&)

If the data of a polygon mesh cannot be read in a `FaceGraph` due to bad orientation or manifoldness issues, consider using `CGAL::Polygon_mesh_processing::IO::read_polygon_mesh()` , which offers combinatorial repairing while reading bad inputs.

# OpenMesh (OM) File format

The OpenMesh proprietary format, using the file extension `.om`, can be used to represent collections of planar polygons with possibly shared vertices. Additionally, it allows to store and restore custom properties along with the standard properties.

More information are provided here.

OpenMesh Format (OM)
Input | Polygon Mesh | Any model of `MutableFaceGraph` | CGAL::IO::read_OM(const std::string&, Graph&)
Output | Polygon Mesh | Any model of `FaceGraph` | CGAL::IO::write_OM(const std::string&, const Graph&)

# STereoLithography (STL) File Format

The `STL` file format, using the file extension `.stl`, is an ASCII or binary format native to the stereolithography CAD software created by 3D Systems. STL files describe the surface geometry of a three-dimensional object.

A precise specification of those formats is available here.

STereoLithography (STL)
Input | Polygon Mesh | Any model of `MutableFaceGraph` | CGAL::IO::read_STL(const std::string&, Graph&)
Polygon Soup | Any point + polygon range | CGAL::IO::read_STL(const std::string&, PointRange&, TriangleRange&)
Output | Polygon Mesh | Any model of `FaceGraph` | CGAL::IO::write_STL(const std::string&, const Graph&)
Polygon Soup | Any point + polygon range | CGAL::IO::write_STL(const std::string&, const PointRange&, const TriangleRange&)

Note that the STL file format exports triangular faces as geometric triangles and thus combinatorial information is lost.

If the data of a polygon mesh cannot be read in a `FaceGraph` due to bad orientation or manifoldness issues, consider using `CGAL::Polygon_mesh_processing::IO::read_polygon_mesh()` , which offers combinatorial repairing while reading bad inputs.

# Polygon File Format (PLY)

The `PLY` file format, using the file extension `.ply`, is an ASCII or binary format conceived to store the data obtained during 3D scans. Objects are stored as a simple list of polygons and external properties can be stored.

A precise specification of those formats is available here.

Polygon File Format (PLY)
Input | Polygon Mesh | `CGAL::Surface_mesh` | CGAL::IO::read_PLY(const std::string&, CGAL::Surface_mesh&)
Any model of `MutableFaceGraph` | CGAL::IO::read_PLY(const std::string&, Graph&)
Point Set | `CGAL::Point_set_3` | CGAL::IO::read_PLY(const std::string&, CGAL::Point_set_3&)
Any point range | CGAL::IO::read_PLY(const std::string&, PointRange&)
Polygon Soup | Any point + polygon range | CGAL::IO::read_PLY(const std::string&, PointRange&, PolygonRange&)
Output | Polygon Mesh | `CGAL::Surface_mesh` | CGAL::IO::write_PLY(const std::string&, const CGAL::Surface_mesh&)
Any model of `FaceGraph` | CGAL::IO::write_PLY(const std::string&, const Graph&)
Point Set | `CGAL::Point_set_3` | CGAL::IO::write_PLY(const std::string&, const CGAL::Point_set_3&)
Any point range | CGAL::IO::write_PLY(const std::string&, const PointRange&)
Polygon Soup | Any point + polygon range | CGAL::IO::write_PLY(const std::string&, const PointRange&, PolygonRange&)

If the data of a polygon mesh cannot be read in a `FaceGraph` due to bad orientation or manifoldness issues, consider using `CGAL::Polygon_mesh_processing::IO::read_polygon_mesh()` , which offers combinatorial repairing while reading bad inputs.

# LAS (Lidar) File Format

The `LAS` file format, using the file extension `.las`, is similar to the Polygon File Format (PLY), except for some characteristics: this format is binary-only and does not handle normals. The LASlib library is required to read or write using this format.

A precise specification of those formats is available here.

LAS (Lidar) File Format
Input | Point Set | `CGAL::Point_set_3` | CGAL::IO::read_LAS(const std::string&, CGAL::Point_set_3&)
Any point range | CGAL::IO::read_LAS(const std::string&, PointRange&)
Output | Point Set | `CGAL::Point_set_3` | CGAL::IO::write_LAS(const std::string&, const CGAL::Point_set_3&)
Any point range | CGAL::IO::write_LAS(const std::string&, const PointRange&)

# XYZ File Format

The `XYZ` format, using the file extension `.xyz`, is a non-standard ASCII data format regularly used to describe point sets. Each line represent a point, and is composed of its coordinates and other properties. Only coordinates and normals are currently supported in CGAL.

XYZ File Format
Input | Point Set | `CGAL::Point_set_3` | CGAL::IO::read_XYZ(const std::string&, CGAL::Point_set_3&)
Any point range | CGAL::IO::read_XYZ(const std::string&, PointRange&)
Output | Point Set | `CGAL::Point_set_3` | CGAL::IO::write_XYZ(const std::string&, const CGAL::Point_set_3&)
Any point range | CGAL::IO::write_XYZ(const std::string&, const PointRange&)

# GOCAD (TS) File Format

The `GOCAD` format, using the file extension `.ts`, is an ASCII file format that enables a range of primitive types to be imported into the GOCAD package.

A precise specification of the format is available here.

GOCAD (TS) File Format
Input | Polygon Mesh | Any model of `MutableFaceGraph` | CGAL::IO::read_GOCAD(const std::string&, Graph&)
Polygon Soup | Any point + polygon range | CGAL::IO::read_GOCAD(const std::string&, PointRange&, PolygonRange&)
Output | Polygon Mesh | Any model of `FaceGraph` | CGAL::IO::write_GOCAD(const std::string&, const Graph&)
Polygon Soup | Any point + polygon range | CGAL::IO::write_GOCAD(const std::string&, const PointRange&, const PolygonRange&)

If the data of a polygon mesh cannot be read in a `FaceGraph` due to bad orientation or manifoldness issues, consider using `CGAL::Polygon_mesh_processing::IO::read_polygon_mesh()` , which offers combinatorial repairing while reading bad inputs.

# 3D Manufacturing Format (3MF)

Attention
  CGAL needs to be configured with the 3MF Libraries for this function to be available.

The `3MF`, using the file extension `.3mf`, is an open source file format created by the 3MF Consortium. It is an XML-based format that aims to enhance the STereoLithography (STL) File Format by adding means to include extra information such as colors.

A precise specification of the format is available at 3mf.io; note that only versions `1.x` are currently supported in CGAL.

3D Manufacturing Format (3MF)
Input | Polygon Mesh | `CGAL::Surface_mesh` | CGAL::IO::read_3MF(const std::string&, Surface_meshRange&)
Polygon Soup | Any point + polygon range | CGAL::IO::read_3MF(const std::string&, PointRanges&, PolygonRanges&)
Output | Polygon Mesh | Any model of `FaceGraph` | CGAL::IO::write_3MF(const std::string&, const GraphRange&)
Polygon Soup | Any point + polygon range | CGAL::IO::write_3MF(const std::string&, const PointRanges&, const PolygonRanges&)

If the data of a polygon mesh cannot be read in a `FaceGraph` due to bad orientation or manifoldness issues, consider using `CGAL::Polygon_mesh_processing::IO::read_polygon_mesh()` , which offers combinatorial repairing while reading bad inputs.

# Virtual Reality Modeling Language (VRML) File Format

The `VRML` format, using the file extension `.wrl`, is an ASCII format often used by browser plug-ins to display virtual reality environments. VRML files are known as “worlds,” which is what "WRL" stands for. A WRL file includes data specifying 3-D details such as vertices, edges for a 3-D polygon, surface color, ...

A precise specification of the format is available here.

3D VRML Format (WRL)
Output | Polygon Mesh | Any model of `FaceGraph` | CGAL::IO::write_WRL(const std::string&, const Graph&)

# VTK (VTU / VTP / legacy) File Formats

Attention
  CGAL needs to be configured with the VTK Libraries for this function to be available.

The VTK libraries use different file formats to handle data structures, but we only support two:

- The `VTU` format can be used to store a collection of 3D cells, like tetrahedra, but also points, triangles, lines, etc. In the VTK Libraries. It is the format reserved to store `Unstructured Grids`, and in CGAL, we use it to store triangulations (2D and 3D).
- The `VTP` format can be used to store collections of points, lines, and triangles. In the VTK Libraries, it is the format reserved to store `PolyData`, and in CGAL, we use it to store polygon meshes.

We additionally provide a read function for the legacy non-XML `VTK` file format for polygon meshes.

A precise specification of those formats is available at vtk.org.

VTK (VTU / VTP / legacy) File Formats
Input | Polygon Mesh | Any model of `MutableFaceGraph` | CGAL::IO::read_VTP(const std::string&, Graph&)
Polygon Soup | Any point + polygon range | CGAL::IO::read_VTP(const std::string&, PointRange&, PolygonRange&), CGAL::IO::read_VTK(const std::string&, PointRange&, PolygonRange&)
Output | Polygon Mesh | Any model of `FaceGraph` | CGAL::IO::write_VTP(const std::string&, const Graph&)
Polygon Soup | Any point + polygon range | CGAL::IO::write_VTP(const std::string&, const PointRange&, const PolygonRange&)

The following CGAL data structures can be exported into the `.VTU` file format:

- `CGAL::Mesh_complex_3_in_triangulation_3`, using `CGAL::IO::output_to_vtu()`
- `CGAL::Constrained_Delaunay_triangulation_2`, using the function `CGAL::IO::write_VTU()`

# Avizo File Format

The AmiraMesh format, using file extension `.am`, is used by the Avizo software to read 3D geometry.

A single CGAL data structure, `CGAL::Mesh_complex_3_in_triangulation_3`, can be exported into `.am` files. This can be done using the function `CGAL::IO::output_to_avizo()`.

A precise specification of the format is available in this guide.

# Medit File Format

The Medit format, using file extension `.mesh`, is a format used by the Medit software. In CGAL, it is used to represent 3D meshes.

A precise specification of the format is available in this report, in the appendices (section 7.2.1, page 36).

The following CGAL data structures can be exported into the `.mesh` file format:

- `CGAL::Mesh_complex_3_in_triangulation_3`, using the function `CGAL::IO::write_MEDIT(` , and
- `CGAL::Conforming_constrained_Delaunay_triangulation_3`, using the function `CGAL::IO::write_MEDIT(` .

# Tetgen File Format

The `Tetgen` file formats can be used to represent lists of nodes, edges, faces, ... A precise specification of the format is available at wias-berlin.de.

Only the `CGAL::Mesh_complex_3_in_triangulation_3` CGAL data structure can be exported into some of the Tetgen file formats, namely `.node`, `.ele` and `.face`. This can be done using the function `CGAL::IO::output_to_tetgen()`.

# Well-Known Text (WKT) File Format

The `WKT` format, using the file extension `.wkt`, is a text markup language for representing vector geometry objects on a geographical map.

A precise specification of the format is available on wikipedia.

See Section Simple 2D Geometry IO for a list of available functions.