|
E57 Foundation API v1.1.312
Aug. 10, 2011
|
|
E57 Foundation API v1.1.312
Aug. 10, 2011
|
This browser-based document describes the E57 Foundation API (Application Programmer Interface) version 0.51, which is a collection of functions that help a C++ programmer read and write ASTM E57 format files. The API acts a documented software connector between an application (above the interface) and an implementation of the API (also called an E57 Foundation Implementation, below the interface). There could (and hopefully will be) more than one E57 Foundation Implementation of this API (perhaps written by a different programmer, or with different performance characteristics), but initially there is a single implementation: the Reference Implementation.
There are two main goals for the Reference Implementation. The first is to provide a kick-start for vendors that want to support the E57 format, lowering the barrier to adoption. The Foundation API and underlying Reference Implementation hide much of the complexity of using the E57 data format standard. The second goal of the Reference Implementation is to promote interoperability by being a paragon of functionality. Test applications linked with the Reference Implementation can attempt to interoperate with a vendor's application.
Vendors are not required to incorporate the Reference Implementation into their own applications (they can roll their own E57 format reader/writer library). But if they do compile the Reference Implementation into their application, they increase the likelihood that the application will interoperate smoothly. The rest of this document is not about the Reference Implementation, but about the interface (the Foundation API) that controls it.
The Foundation API and libe57 aren't part of the ASTM standard; they support it. The Foundation API and libe57 aren't sanctioned or approved in any way by ASTM. The designer of the API and author of the Reference Implementation (Kevin Ackley) was heavily involved in the drafting of the E57 format standard. However, the E57 Standard for 3D Imaging Data Exchange is the final word on what is a legal/valid .e57 file.
Yes. The Foundation API provides the building blocks (the E57 primitive elements) for constructing and interpreting an E57 file, but the data structures that are built with these building blocks are up to the user of the API. The required names and types of these data structures (not to mention their meanings) are specified in the ASTM standard, so you need a copy.
ASTM owns the standard, which is currently being balloted. ASTM E57 committee members can get draft versions of standards. After approval, everyone will need to purchase the standard from the ASTM website. Only a very few of the 100+ ASTM committees make money, and E57 isn't one of them. So support your industry and buy a copy.
Only partially, but it's a highly specialized XML. It's better think of an E57 file as hierarchical tree of eight data types, that happens to be partly encoded in XML on the disk. The E57 format is a hybrid of XML (encoding the tree) and binary sections (which efficiently encode the records of point data). For efficiency, the binary sections must be read/written in large blocks of records. The XML section, although it holds most of the complexity in the file, is much smaller and objects can be accessed individually. The binary sections aren't embedded in the XML section. The XML section makes references to the binary sections, which are stored separately within the E57 file.
The Foundation API is described in C++, and is object-oriented. There are 15 types of objects, each described in a C++ class. There is a class that encapsulates the E57 file (ImageFile), a class for each of the eight E57 primitive elements described in the standard (IntegerNode, ScaledIntegerNode, FloatNode, StringNode, BlobNode, StructureNode, VectorNode, and CompressedVectorNode) and a base class that encapsulates the common functionality of all nodes (Node). There are two classes that keep track of the block reads/writes to the binary sections (CompressedVectorReader, CompressedVectorWriter) and a class to manage buffers for these block transfers (SourceDestBuffer). Finally, there is a class to organize the reporting of errors (E57Exception), and a class for miscellaneous functions that are not associated with any of the other objects (E57Utilities).
The primary motivation for the E57 file is to be a conduit between the proprietary formats of two different vendors' software (the reader and the writer). It is not a general-purpose 3D database. The API design reflects this use case by not allowing modifications of data. This simplifies the implementation. For example, it is not possible to change a value of a node, or delete an attached child node, and it is an error to attempt to attach a node to the tree using an already existing name.
All but one of the classes (the exception being E57Exception) have handle semantics, which means that there is a level of indirection. The Foundation API classes are actually just pointers to an underlying object. The pointers are smart (they have reference counts), so the user doesn't have to explicitly free them. If two handles exist to the same underlying object, the object is not deleted until both handles are destroyed. So the programmer is not burdened with keeping track of who is going to delete an object, the object "deletes itself" when all the references to it are gone. This simplifies the use of the API, especially in the creation of trees of objects. After you attach some object into a tree, there will be two references to the object, yours and the parent of the object in the tree. So when you delete your reference, the parent's reference will keep the object alive (until the parent is destroyed).
A second benefit of smart pointers is that the copy and assignment functions in the classes are very cheap. They just copy or assign the handle, not the underlying object. So function call arguments (that are API objects) are always "call-by-reference", and the underlying object is not copied. It is impossible to assign the underlying state of one object directly into another. This restriction fits well into the set-once scheme described above.
The bottom line is that you should not use new/delete with the E57 Foundation objects, nor reference types (e.g. ImageFile&). You don't have to keep track of who will delete the object, nor try to speed up the passing of handles to functions. And the API objects clean up after themselves when an exception occurs.
None of the API classes contain default constructors, so there is no equivalent to a NULL handle (with no underlying object). So if you have an API handle, you know it points to a valid object.
There are three separate entities that have version numbers: the ASTM E57 format standard itself, the E57 Library (libe57), and the Foundation API.
When the E57 standard is approved, its version will start out at version 1.0. Until that time, and until it is verified that the Reference Implementation writes the correct format, the E57 format version number written in an .e57 file is less than 1.0 (currently 0.5). The Reference Implementation is currently configured to reject any E57 format version numbers less than the one it was built to write. So don't invest a lot of time in creating .e57 files that can't be recreated, because the format version number in the file will advance at least once more.
The E57 library (libe57) is a collection of tools, examples, data files, tests, and software libraries that help read and write .e57 files. The Reference Implementation is a key component of the libe57, but there are other parts as well. For example, libe57 contains tools that sit on top of the Foundation API, that process E57 files (e.g. las2e57, e57fields). The entire collection of tools and software libraries is tracked by a single version number: the version of libe57. The libe57 version identifier has 3 parts, the major version number, the minor version number, and the build number. The E57 Library version will start at about 0.1.20. The minor version number will advance with each phase of beta release. The build number always increases, it is basically the version number from the source code tracking system. The version will be advanced to 1.0.XX at the end of the beta period.
The Foundation API version is tracked by two numbers: the major version number, and the minor version number. The minor version number of the Foundation API version will advance when there is any change to the interface (either backwardly compatible or not). The major version number will advance for changes that are not backward compatible. Currently the API is at version 0.51. When the API has completely solidified, the version number will advance to 1.00. In some situations, a third number (the subversion build number of libe57) may be listed in the Foundation API version identifier. This number can be ignored. Changes in the build number do not imply changes in the API. If the major and minor version number haven't changed, the API hasn't changed.
To learn about the API, start reading at the HelloWorld.cpp example. It has a lot of detail about the basics of the API and the basic mechanics of using it. You might try pasting the HelloWorld.cpp example into a file, compile it, and link with the Reference Implementation. Then read the Detailed Descriptions at the bottom of each of the 15 class pages listed on the Class/ClassList tab. Then look at the discussion of each of the example program listings on the Files/FileList tab. Finally, find DemoWrite01.cpp, included in libe57, which writes a real .e57 file that meets all the specifications of the ASTM standard.
If your existing software already writes LAS format v1.0 to v1.2, look at the utility las2e57.exe. You may be able to use it to write an LAS file and convert to it E57 without any programming at all. Two utilities are useful for examining what you have written: e57xmldump.exe and e57fields.exe.
The full source of libe57 is available to anyone on the SourceForge website: http://sourceforge.net/projects/e57-3d-imgfmt/. The libe57 source is distributed under the very liberal Boost Software License. Binary distributions may be made available for some compiler/OSes.
Help is available by email through E57 SourceForge repository. To get help during the beta phase of the software release you have to agree to be a beta tester (you have to describe what you are doing and hopefully to give a review of your experience). To get more information about the beta test, contact Roland Schwarz by email at roland_schwarz@users.sourceforge.net.
1.7.5.1
