CGAL 6.0  IO Streams

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.
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.
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.
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.
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 threedimensional 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.
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.
The LAS
file format, using the file extension .las
, is similar to the Polygon File Format (PLY), except for some characteristics: this format is binaryonly 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&) 
The XYZ
format, using the file extension .xyz
, is a nonstandard 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&) 
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.
The 3MF
, using the file extension .3mf
, is an open source file format created by the 3MF Consortium. It is an XMLbased 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.
The VRML
format, using the file extension .wrl
, is an ASCII format often used by browser plugins to display virtual reality environments. VRML files are known as “worlds,” which is what "WRL" stands for. A WRL file includes data specifying 3D details such as vertices, edges for a 3D 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&) 
The VTK libraries use different file formats to handle data structures, but we only support two:
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).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 nonXML 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()
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.
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()
.
The Tetgen
file formats can be used to represent lists of nodes, edges, faces, ... A precise specification of the format is available at wiasberlin.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()
.
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.