Summary of Changes

• Robustify all I/O functions
• Add missing overloads
• Uniformize calls of I/O functions to read_XXX/write_XXX, deprecate old stuff
• Regroup functions into only a few packages + remove duplicates + remove useless packages
• Add new convenience functions : read_points, read_polygon_soup, read_polygon_mesh, ...
• Document stuff in IO Stream

Release Management

• Affected package(s): Triangulation_2
• Issue(s) solved (if any):
• Feature/Small Feature (if any): https://cgal.geometryfactory.com/CGAL/Members/wiki/Features/Polgyon_soup_mesh_IO

Relates : #2196, #4332,

TODO

Mael:

• Check all @todo / @fixme in BGL/IO and Stream_support/IO
• Re-introduce functions that were documented in CGAL 5.0 but that have been removed, and deprecate them all
• Go over read/write_xxx (small xxx) and replace with new API + deprecate all old ones
• Get rid of the various local "read_mesh" functions (check for e.g. "off")
• Fix documentation of operator<< >> CGAL::Color
• Binary shenanigans, LAS is always binary
• Put links to LAS_with_properties in PSP3::read/write_LAS()
• Don't use Graph in PMP
• partition.h and split_graph_into_polylines into BGL > Partitioning operations
• Hide CGAL_DEPRECATED from the doc
• Fix "polgyon"
• Add an "extension: " in Stream support
• Fix XYZ and Gocad tables in stream support
• check flushing of writers
• check that all readers use reserve() when they ought to
• fix std::precision interaction with geomview_stream
• fix OFF reading requiring larger kernels than before
• fix broken logic of && !std::distance < 0
• Add note about std::binary to lower level overloads for PLY.
• Nef_3/Nef_3_problematic_construction.cpp runtime error.
• Go over the issues of the project (https://github.com/CGAL/cgal/projects/3), check if changes from related issues haven't been lost / fixed

Maxime:

• Polyhedron "save as XXX" but filename "asd.YYY" --> saves in YYY format
• Can't load .obj if it's not a polygon mesh (can be a simple soup if there are multiple objects). Probably can merge most readers (like load_off and load_obj to be the same function using PMP::read_polygon_mesh()`).
• Convex_hull_3/demo is broken at runtime (even in master).

major:

• Fix skip_to_next_vertex in File_scanner_OFF that should also have has_textures() has_normals() checks
• Make sure all OFF reading works (everything now uses the File_scanner_OFF rather than having 10 different implementations).).
• The property maps in BGL::write_PLY use the Surface_mesh API only (it should use NP like in read_off to read them) + add overload in SM/IO like read_off(surface_mesh)
• Extend IO that uses std::vector (SS/IO) to ranges
• Don't return in.good() otherwise it fails if eof bit is set -> return !in.fail() instead
• Make sure all facegraph IO (except overloads for a particular class) is in BGL
• Check if read_point_set() exists and add it if not (get advice from @sgiraudot on what he thinks is best)
• Introduce CGAL::read_polygon_soup in Stream_support/IO that dispatchs based on the file extension
• Introduce CGAL::read_polygon_mesh in BGL/IO that dispatchs based on the file extension (gotta mind .off, .coff etc.)
• Introduce PMP::IO::read_polygon_mesh in PMP/IO that dispatchs based on the file extension (gotta mind .off, .coff etc.) and which call orient_PS if CGAL::read_polygon_mesh fails
• Move as much code away from the demo and into the correct SS/IO (polygon soup) BGL/IO (polygon mesh) SM (specific overloads) files
• Make sure all readers/writers actually work (not just that it doesn't crash but that the data read is the one that is expected)
• Document IO: section in BGL pointing to SS/IO, all classes that can be read from files have an IO section and point to SS/IO, etc.
• Mind CGAL_LINKED_WITH_3MF (I used this macro to hide 3MF code, but it needs to be added to CMakeLists.txt)
• Make sure that all readers fail graciously, there are still many in >> x >> y that should be if(in >> x >> y) (and similar)
• Fix broken links to IO::Mode
• Go over the operator<< >> for FaceGraphs and make sure they are working and document what they do
• Check that I properly re-applied CGAL 3D Demo: Enhancement of the Scene Saving System #4212 (manually re-applied changes to 3MF)
• Check if changes from Fix OFF reader #4501 should be applied to the OFF scanner
• Check that Surf_reader : Enhancement #4674 was correctly applied
• import IO: Add binary support for surf reading. #4727
• Use iformat/oformat (see e.g. STL reader)
• Fix point sets sometimes being read as read_PLY_points and sometimes read_PLY
• Use binary for default input / output format when it makes sense (e.g. PLY) + document
• Fix read/write_point_set extension extraction (see read_polygon_soup)
• Test all IO, all overloads, binary/ascii, all extensions (SS, BGL, PMP, SM, Polyhedron, etc.). Check the output are the correct geometry, combinatorics. Check for bad inputs. See test_bgl_read_write.cpp.
• Fully document IO functions (most are missing template parameters / parameters documentation). Document INP?
• Use the read_point_set / read_polygon_soup / read_polygon_mesh in examples / demos (not fully done, see TriMesh.cpp, face_selection_borders_regularization_example.cpp, etc.).

minor:

• Fix VTK reading (check the vtp/vtu consistency)
• write_vtu/output_to_avizo / output_to_tetgen etc. (newly documented) don't fit the standard names
• Bench flat_map vs CGAL::Inverse_index vs std::unordered_map (generic_facegraph_builder)

extra:

• Also rename Point_set I/O functions?
• read_XXX_with_properties() function could not be simply renamed as read_XXX() because then, the overload with properties and the one with NP conflict. We could probably find a way to deal with it at some point.
• Go over Triangulations IO (mind the IO from tetrahedral_remeshing)
• np::point_map in polygon soup readers/writers
• Document NPs in SS/IO ?

extra extra:

• Factorize VTU code (mesh_2/mesh_3) and move it into IO
• Go over C3T3 IO
• Go over LCC IO
• Create GOCAD file writer in SS and use it in BGL
• Kernel objects IO
• Add << and >> operators for LCC and BGL Facegraphs.