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(const std::string&, CGAL::Polyhedron_3&)
		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(const std::string&, const CGAL::Polyhedron_3&)
		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 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 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).

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