CGAL 5.3 - IO Streams
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)

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 char*, CGAL::Surface_mesh&)
CGAL::Polyhedron_3 CGAL::IO::read_OFF(const char*, CGAL::Polyhedron_3&)
Any model of MutableFaceGraph CGAL::IO::read_OFF(const char*, Graph&)
Point Set CGAL::Point_set_3 CGAL::IO::read_OFF(const char*, CGAL::Point_set_3&)
Any point range CGAL::IO::read_OFF(const char*, PointRange&)
Polygon Soup Any point + polygon range CGAL::IO::read_OFF(const char*, PointRange&, PolygonRange&)
Output Polygon Mesh CGAL::Surface_mesh CGAL::IO::write_OFF(const char*, CGAL::Surface_mesh&)
CGAL::Polyhedron_3 CGAL::IO::write_OFF(const char*, CGAL::Polyhedron_3&)
Any model of FaceGraph CGAL::IO::write_OFF(const char*, Graph&)
Point Set CGAL::Point_set_3 CGAL::IO::write_OFF(const char*, CGAL::Point_set_3&)
Any point range CGAL::IO::write_OFF(const char*, PointRange&)
Polygon Soup Any point + polygon range CGAL::IO::write_OFF(const char*, 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.

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 counter-clockwise 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 char*, Graph&)
Polygon Soup Any point + polygon range CGAL::IO::read_OBJ(const char*, PointRange&, PolygonRange&)
Output Polygon Mesh Any model of FaceGraph CGAL::IO::write_OBJ(const char*, Graph&)
Polygon Soup Any point + polygon range CGAL::IO::write_OBJ(const char*, 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.

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 char*, Graph&)
Polygon Soup Any point + polygon range CGAL::IO::read_STL(const char*, PointRange&, TriangleRange&)
Output Polygon Mesh Any model of FaceGraph CGAL::IO::write_STL(const char*, Graph&)
Polygon Soup Any point + polygon range CGAL::IO::write_STL(const char*, PointRange&, 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 char*, CGAL::Surface_mesh&)
Any model of MutableFaceGraph CGAL::IO::read_PLY(const char*, Graph&)
Point Set CGAL::Point_set_3 CGAL::IO::read_PLY(const char*, CGAL::Point_set_3&)
Any point range CGAL::IO::read_PLY(const char*, PointRange&)
Polygon Soup Any point + polygon range CGAL::IO::read_PLY(const char*, PointRange&, PolygonRange&)
Output Polygon Mesh CGAL::Surface_mesh CGAL::IO::write_PLY(const char*, CGAL::Surface_mesh&)
Any model of FaceGraph CGAL::IO::write_PLY(const char*, Graph&)
Point Set CGAL::Point_set_3 CGAL::IO::write_PLY(const char*, CGAL::Point_set_3&)
Any point range CGAL::IO::write_PLY(const char*, PointRange&)
Polygon Soup Any point + polygon range CGAL::IO::write_PLY(const char*, 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 char*, CGAL::Point_set_3&)
Any point range CGAL::IO::read_LAS(const char*, PointRange&)
Output Point Set CGAL::Point_set_3 CGAL::IO::write_LAS(const char*, CGAL::Point_set_3&)
Any point range CGAL::IO::write_LAS(const char*, 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 char*, CGAL::Point_set_3&)
Any point range CGAL::IO::read_XYZ(const char*, PointRange&)
Output Point Set CGAL::Point_set_3 CGAL::IO::write_XYZ(const char*, CGAL::Point_set_3&)
Any point range CGAL::IO::write_XYZ(const char*, 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 char*, Graph&)
Polygon Soup Any point + polygon range CGAL::IO::read_GOCAD(const char*, PointRange&, PolygonRange&)
Output Polygon Mesh Any model of FaceGraph CGAL::IO::write_GOCAD(const char*, Graph&)
Polygon Soup Any point + polygon range CGAL::IO::write_GOCAD(const char*, 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.

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 char*, Surface_meshRange&)
Polygon Soup Any point + polygon range CGAL::IO::read_3MF(const char*, PointRanges&, PolygonRanges&)
Output Polygon Mesh Any model of FaceGraph CGAL::IO::write_3MF(const char*, GraphRange&)
Polygon Soup Any point + polygon range CGAL::IO::write_3MF(const char*, PointRanges&, 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 Manufacturing Format (3MF)
Output Polygon Mesh Any model of FaceGraph CGAL::IO::write_WRL(const char*, Graph&)

VTK (VTU / VTP) 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.

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

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

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

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

Only the CGAL::Mesh_complex_3_in_triangulation_3 CGAL data structure can be exported into .mesh This can be done using the function CGAL::IO::output_to_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.