3.0.0

This major release required changes to the API in some places, so I took this opportunity to clean up and deprecate several things for readability & clarity.

There have been many changes around the Simple API in this release to fix some problems, avoid potential errors, and simplify the use of the API. Where possible these changes are marked as deprecated to be removed later. The compiler will produce warnings for these indicating what needs to change. Other changes could not be marked deprecated but will break the API, requiring code changes. The notable ones are marked with 🚧 below.

Please consider one-time or recurring support - especially if you use this library in a product you sell.

Added

• Add address (ASan) and undefined behaviour (UBSan) sanitizers. These are controlled by E57FORMAT_SANITIZE_ALL, E57FORMAT_SANITIZE_ADDRESS and E57FORMAT_SANITIZE_ADDRESS. They are not included when building with MSVC.

• Add new E57Version.h header for more convenient access to version information. (#197).

• Add ImageFile::extensionsLookupPrefix() overload for more concise user code. (#161)

• Added a constructor & destructor for E57SimpleData's Data3DPointsData_t. This will create all the required buffers based on an e57::Data3D struct and handle their cleanup. See the SimpleWriter tests for examples. (#149)

  Note: I strongly recommend these new constructors be used to simplify your code and help prevent errors.

• A new E57SimpleReader constructor takes a ReaderOptions struct which allows setting the checksum policy.

  Reader( const ustring &filePath, const ReaderOptions &options );

• {test} Added testing using GoogleTest. For details, please see test/README.md (#121)

• Added E57Exception::errorStr() to get the error string directly. (#128)

• {cmake} Use ccache if available. (#129)

• {ci} Added a CI check for proper clang-formatted code. (#125)

Changed

• Now requires a C++14 compatible compiler.
• Now requires CMake >= 3.15. (#205)
• 🚧 DEBUG and VERBOSE macros were changed to simplify and clarify:
  • New E57_ENABLE_DIAGNOSTIC_OUTPUT controls the inclusion of the code for the dump() functions on nodes. I don't see any real reason to turn this off, but I left the capability in for compatibility.
  • New E57_VALIDATION_LEVEL=N replaces E57_DEBUG (N=1) and E57_MAX_DEBUG (N=2).
  • E57_MAX_VERBOSE was consolidated with E57_VERBOSE since they were essentially the same.
• When building itself, warnings are now treated as errors. (#205, #211)
• Clean up global const and enum names to use the e57 namespace and avoid repetition. (#176)
  • i.e. instead of e57::E57_STRUCTURE, we now use e57::TypeStructure
• {format} Update clang-format rules for clang-format 15. (#168, #179)
• Change default checksum policies to an enum. (#166)

  Old	New
  CHECKSUM_POLICY_NONE	ChecksumPolicy::None
  CHECKSUM_POLICY_SPARSE	ChecksumPolicy::Sparse
  CHECKSUM_POLICY_HALF	ChecksumPolicy::Half
  CHECKSUM_POLICY_ALL	ChecksumPolicy::All

• Avoid implicit conversion in constructors. (#135)
• Update CRCpp to 1.2. (#130)
• E57Exception changes (#118):
  • mark methods as noexcept
  • use private instead of protected
• Rename E57Simple's Data3DPointsData and Data3DPointsData_d structs to Data3DPointsFloat and Data3DPointsDouble respectively. (#180)
• 🚧 E57Simple: Specifying the node type for cartesian & spherical points, time stamp, and intensity is now explicit using new fields (pointRangeNodeType, angleNodeType, timeNodeType, and intensityNodeType) and a new enum (NumericalNodeType). (#178)
  • For examples, please see test/src/testSimpleWriter.cpp.
• Simplify the E57SimpleWriter API with WriteImage2DData() for images and WriteData3DData() for 3D data. This reduces code, hides complexity, and avoids potential errors. (#171)
  • As part of this simplification, WriteData3DData() will now fill in any missing min/max values for cartesian & spherical points, intensity, and time stamps by looking at the data.(#175)
• 🚧 E57Simple: Intensity now uses double instead of float. (#178)
• 🚧 E57Simple: Colours now use uint16_t instead of uint8_t. (#167)
• 🚧 Change E57SimpleData's Data3D field name from pointsSize to pointCount. (#164)
• 🚧 Min/max fields in E57SimpleData's Data3D's point fields were a mix of floats and doubles. Since the fields are doubles, set them all to doubles and use the new Data3DPointsData_t constructor to set them properly for floats. (#153)

  Note: If you were previously relying on these to be floats and are not using the new Data3DPointsData_t constructor, you will need to set these.

• 🚧 Renamed the E57_EXT_surface_normals extension's fields in E57SimpleData's PointStandardizedFieldsAvailable to be in line with existing code. (#149)
  • normalX renamed to normalXField
  • normalY renamed to normalYField
  • normalZ renamed to normalZField

Deprecated

• e57::Utilities::getVersions(). (#197)
• e57::Data3DPointsData and e57::Data3DPointsData_d types. (#180)
• Many global const and enum names. The compiler will produce warnings including the replacement symbols (note that enumerators will not produce warnings on C++14, but they will on C++17). (#176)
• e57::Writer::NewImage2Dand e57::Writer::SetUpData3DPointsData. (#171)
• Old default checksum policies (CHECKSUM_POLICY_NONE, CHECKSUM_POLICY_SPARSE, CHECKSUM_POLICY_HALF, and CHECKSUM_POLICY_ALL). (#166)
• The old e57::Reader constructor taking only filePath. (#139)
• The old e57::Writer constructor taking only filePath. (#117)

Fixed

• Fix several potential divide-by-zero cases. (#224)
• {ci} Now builds shared library versions as well. (#219)
• {win} Fixes shared library build warnings. (#215, #216, #217)
• Fix the code which shortens floating point numbers when converted to strings. The impact of it being incorrect was negligible since it's just the floating point representation in the XML portion of the file. (#214)
• Turned on a lot of compiler warnings and fixed them. (#201, #202, #203, #204, #205, #207, #209)
• Fix writing floating point numbers when std::locale::global is set. (#174)
• E57XmlParser: Parse doubles in a locale-independent way. (#173) (Thanks Hugal31!)
• E57SimpleReader: Ensure scaled integer fields are set as best we can when reading. (#158)
• Fix the E57_EXT_surface_normals extension's URI in E57SimpleWriter. (#143)
• {win} Fix conversion warning when compiling with debug on. (#124)
• Add errno detail to E57_ERROR_OPEN_FAILED exception. (#119, #120)

New Contributors

• @Hugal31 made their first contribution in #173
• @trofi made their first contribution in #183

Full Changelog: v2.3.0...v3.0.0