libE57Format

libE57Format is a library which provides read & write support for the E57 file format.

🚨 Version 3.0 Note 🚨

There have been many changes (especially to the "Simple API") in the upcoming version 3.0 - some of which will require code changes on your end. Please see the CHANGELOG for details.

Since this version is breaking the API, I am happy to discuss any other API-breaking changes which might be useful. Please raise them in this issue.

I plan to let 3.0 sit in the master branch until the end of 2022. If I don't hear any feedback I will go ahead and release it as-is.

Documentation

The doxygen-generated documentation may be found here. These docs are generated and saved in the libE57Format-docs repo.

Build, Install, & Test

Here's how you build & install a release version with the defaults:

$ cmake -B E57-build -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=E57-install libE57Format
$ cmake --build E57-build --parallel
$ cmake --install E57-build

If it can't find the xerces-c library, you can set CMAKE_PREFIX_PATH to point at it.

$ cmake -B E57-build \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=E57-install \
    -DCMAKE_PREFIX_PATH=/path/to/xerces-c \
    libE57Format

Once the library is built, you can run the tests like this:

$ cd E57-build
$ ./test/testE57
[==========] Running 36 tests from 8 test suites.
[----------] Global test environment set-up.
[----------] 1 test from TestData
[ RUN      ] TestData.RepoExists
...

See test/README for details about testing and the test data.

Dependencies

Libraries:

Xerces-C++: a validating XML parser

Tools:

clang-format: for code formatting
(optional) ccache: speed up rebuilds using caching

Installing On Linux (Ubuntu)

$ sudo apt install libxerces-c-dev clang-format

Installing On macOS (homebrew)

$ brew install ccache clang-format xerces-c

🍴 Fork

This is a fork of E57RefImpl. The original source is from E57RefImpl 1.1.332.

The original code had not been touched in years and I wanted to make changes to compile it on macOS. Forking it gave me a bit more freedom to update the code and make changes as required. Everything was stripped out except the main implementation for reading & writing E57 files.

Notes:

I changed the name of the project so that it is not confused with the E57RefImpl project.
I changed the main include file's name from E57Foundation.h to E57Format.h to make sure there is no inclusion confusion.
Versions of libE57Format started at 2.0.
I made changes for it to compile and run on macOS.
It no longer depends on Boost.
It now requires C++14. (Version 2.x required C++11.)

Many, many other changes were made prior to the first release of this fork. See the CHANGELOG and git history for details.

E57Simple API

Jiri Hörner added the E57Simple API from the old reference implementation and updated it.

This Simple API has evolved since this original port to fix some problems and to make it more foolproof & easier to use. Please see the CHANGELOG for version 3.

Tools

Ryan Baumann updated the e57unpack and e57validate tools to work with libE57Format. You can find them in the e57tools repo.

How To Contribute

These are some of the things you can do to contribute to the project:

✍ Write About The Project

If you find the project useful, spread the word! Articles, mastodon posts, tweets, blog posts, instagram photos - whatever you're into.

⭐️ Add a Star

If you found this project useful, please consider starring it! It helps me gauge how useful this project is.

☝ Raise Issues

If you run into something which doesn't work as expected, raising an issue with all the relevant information to reproduce it would be helpful.

🐞 Bug Fixes & 🧪 New Things

I am happy to review any pull requests. Please keep them as short as possible. Each pull request should be atomic and only address one issue. This helps with the review process.

Note that I will not accept everything, but I welcome discussion. If you are proposing a big change, please raise it as an issue first for discussion.

Formatting

This project uses clang-format to format the code. There is a cmake target (e57-clang-format) - which runs clang-format on the source files. After changes have been made, and before you submit your pull request, please run the following:

cmake --build . --target e57-clang-format

📖 Documentation

The documentation is a bit old and could use some lovin'. You can submit changes over in the libE57Format-docs repository.

💰 Financial

Given that I'm an independent developer without funding, financial support is always appreciated. If you would like to support the project financially (especially if you sell a product which uses this library), you can use the sponsors page for one-off or recurring support. Thank you!

License

This project as a whole is licensed under the BSL-1.0 license - see the LICENSE file for details.

Individual source files may contain the following tag instead of the full license text:

SPDX-License-Identifier: BSL-1.0

Some files are licensed under the MIT license - see the LICENSE-MIT file for details.

These files contain the following tag instead of the full license text:

SPDX-License-Identifier: MIT

Using SPDX enables machine processing of license information based on the SPDX License Identifiers and makes it easier for developers to see at a glance which license they are dealing with.

migr8/libE57Format