libE57Format 3.1.1
C++ library to read & write the E57 file format for point cloud data
|
An ASTM E57 3D format file object. More...
#include <E57Format.h>
Public Member Functions | |
ImageFile ()=delete | |
ImageFile (const char *input, uint64_t size, ReadChecksumPolicy checksumPolicy=ChecksumAll) | |
ImageFile (const ustring &fname, const ustring &mode, ReadChecksumPolicy checksumPolicy=ChecksumAll) | |
Open an ASTM E57 imaging data file for reading/writing. | |
void | cancel () |
Stop I/O operations and delete a partially written ImageFile on the disk. | |
void | checkInvariant (bool doRecurse=true) const |
Check whether ImageFile class invariant is true. | |
void | close () |
Complete any write operations on an ImageFile, and close the file on the disk. | |
void | dump (int indent=0, std::ostream &os=std::cout) const |
Diagnostic function to print internal state of object to output stream in an indented format. | |
void | elementNameParse (const ustring &elementName, ustring &prefix, ustring &localPart) const |
Parse element name into prefix and localPart substrings. | |
void | extensionsAdd (const ustring &prefix, const ustring &uri) |
Declare the use of an E57 extension in an ImageFile being written. | |
size_t | extensionsCount () const |
Get number of E57 extensions declared in the ImageFile. | |
bool | extensionsLookupPrefix (const ustring &prefix) const |
Look up an E57 extension prefix in the ImageFile. | |
bool | extensionsLookupPrefix (const ustring &prefix, ustring &uri) const |
Get URI associated with an E57 extension prefix in the ImageFile. | |
bool | extensionsLookupUri (const ustring &uri, ustring &prefix) const |
Get an E57 extension prefix associated with a URI in the ImageFile. | |
ustring | extensionsPrefix (size_t index) const |
Get an E57 extension prefix declared in an ImageFile by index. | |
ustring | extensionsUri (size_t index) const |
Get an E57 extension URI declared in an ImageFile by index. | |
ustring | fileName () const |
Get the file name the ImageFile was created with. | |
bool | isElementNameExtended (const ustring &elementName) const |
Test whether an E57 element name has an extension prefix. | |
bool | isOpen () const |
Test whether ImageFile is still open for accessing. | |
bool | isWritable () const |
Test whether ImageFile was opened in write mode. | |
bool | operator!= (const ImageFile &imf2) const |
Test if two ImageFile handles refer to different underlying ImageFile. | |
bool | operator== (const ImageFile &imf2) const |
Test if two ImageFile handles refer to the same underlying ImageFile. | |
int | readerCount () const |
Get current number of open CompressedVectorReader objects reading from ImageFile. | |
StructureNode | root () const |
Get the pre-established root StructureNode of the E57 ImageFile. | |
int | writerCount () const |
Get current number of open CompressedVectorWriter objects writing to ImageFile. | |
An ASTM E57 3D format file object.
The ImageFile class represents the state of an ASTM E57 format data file. An ImageFile may be created from an E57 file on the disk (read mode). An new ImageFile may be created to write an E57 file to disk (write mode).
E57 files are organized in a tree structure. Each ImageFile object has a predefined root node (of type StructureNode). In a write mode ImageFile, the root node is initially empty. In a read mode ImageFile, the root node is populated by the tree stored in the .e57 file on disk.
An ImageFile object, opened in either mode (read/write), can be in one of two states: open or closed. An ImageFile in the open state is ready to perform transfers of data and to be interrogated. An ImageFile in the closed state cannot perform any further transfers, and has very limited ability to be interrogated. Note entering the closed state is different than destroying the ImageFile object. An ImageFile object can still exist and be in the closed state. When created, the ImageFile is initially open.
The ImageFile state can transition to the closed state in two ways. The programmer can call ImageFile::close after all required processing has completed. The programmer can call ImageFile::cancel if it is determined that the ImageFile is no longer needed.
Basically in an E57 file, "extension = namespace + rules + meaning". The "namespace" ensures that element names don't collide. The "rules" may be written on paper, or partly codified in a computer grammar. The "meaning" is a definition of what was measured, what the numbers in the file mean.
Extensions are identified by URIs. Extensions are not identified by prefixes. Prefixes are a shorthand, used in a particular file, to make the element names more palatable for humans. When thinking about a prefixed element name, in your mind you should immediately substitute the URI for the prefix. For example, think "http://www.example.com/DemoExtension:extra2" rather than "demo:extra2", if the prefix "demo" is declared in the file to be a shorthand for the URI "http://www.example.com/DemoExtension".
The rules are statements of: what is valid, what element names are possible, what values are possible. The rules establish the answer to the following yes/no question: "Is this extended E57 file valid?". The rules divide all possible files into two sets: valid files and invalid files.
The "meanings" part of the above equation defines what the files in the first set, the valid files, actually mean. This definition usually comes in the form of documentation of the content of each new element in the format and how they relate to the other elements.
An element name in an E57 file is a member of exactly one namespace (either the default namespace defined in the ASTM standard, or an extension namespace). Rules about the structure of an E57 extension (what element names can appear where), are implicitly assumed only to govern the element names within the namespace of the extension. Element names in other namespaces are unconstrained. This is because a reader is required to ignore elements in namespaces that are unfamiliar (to treat them as if they didn't exist). This enables a writer to "tack on" new elements into pre-defined structures (e.g. structures defined in the ASTM standard), without fear that it will confuse a reader that is only familiar with the old format. This allows an extension designer to communicate to two sets of readers: the old readers that will understand the information in the old base format, and the new-fangled readers that will be able to read the base format and the extra information stored in element names in the extended namespace.
A class invariant is a list of statements about an object that are always true before and after any operation on the object. An invariant is useful for testing correct operation of an implementation. Statements in an invariant can involve only externally visible state, or can refer to internal implementation-specific state that is not visible to the API user. The following C++ code checks externally visible state for consistency and throws an exception if the invariant is violated:
|
delete |
ImageFile::ImageFile | ( | const ustring & | fname, |
const ustring & | mode, | ||
ReadChecksumPolicy | checksumPolicy = ChecksumAll |
||
) |
Open an ASTM E57 imaging data file for reading/writing.
[in] | fname | File name to open. Support of '\' as a directory separating character is system dependent. For maximum portability, it is recommended that '/' be used as a directory separator in file names. Special device file name support are implementation dependent (e.g. "\\.\PhysicalDrive3" or "/dev/hd3"). It is recommended that files that meet all of the requirements for a legal ASTM E57 file format use the extension ".e57" . It is recommended that files that utilize the low-level E57 element data types, but do not have all the required element names required by ASTM E57 file format standard use the file extension "._e57" . |
[in] | mode | Either "w" for writing or "r" for reading. |
[in] | checksumPolicy | The percentage of checksums we compute and verify as an int. Clamped to 0-100. |
open
state if constructor succeeds (no exception thrown).ImageFile::ImageFile | ( | const char * | input, |
uint64_t | size, | ||
ReadChecksumPolicy | checksumPolicy = ChecksumAll |
||
) |
void ImageFile::cancel | ( | ) |
Stop I/O operations and delete a partially written ImageFile on the disk.
If the ImageFile is write mode, the associated file on the disk is closed and deleted, and the ImageFile goes to the closed state. If the ImageFile is read mode, the behavior is same as calling ImageFile::close, but no exceptions are thrown. It is not an error if ImageFile is already closed.
closed
state.No | E57Exceptions. |
void ImageFile::checkInvariant | ( | bool | doRecurse = true | ) | const |
Check whether ImageFile class invariant is true.
[in] | doRecurse | If true, also check invariants of all children or sub-objects recursively. |
This function checks at least the assertions in the documented class invariant description (see class reference page for this object). Other internal invariants that are implementation-dependent may also be checked. If any invariant clause is violated, an E57Exception with errorCode of ErrorInvarianceViolation is thrown.
Checking the invariant recursively may be expensive if the tree is large, so should be used judiciously, in debug versions of the application.
ErrorInvarianceViolation | or any other E57 ErrorCode |
void ImageFile::close | ( | ) |
Complete any write operations on an ImageFile, and close the file on the disk.
Completes the writing of the state of the ImageFile to the disk. Some API implementations may store significant portions of the state of the ImageFile in memory. This state is moved into the disk file before it is closed. Any errors in finishing the writing are reported by throwing an exception. If an exception is thrown, depending on the error code, the ImageFile may enter the closed state. If no exception is thrown, then the file on disk will be an accurate representation of the ImageFile.
It is not an error if ImageFile is already closed.
closed
state.ErrorSeekFailed | |
ErrorReadFailed | |
ErrorWriteFailed | |
ErrorCloseFailed | |
ErrorBadChecksum | |
ErrorInternal | All objects in undocumented state |
void ImageFile::dump | ( | int | indent = 0 , |
std::ostream & | os = std::cout |
||
) | const |
Diagnostic function to print internal state of object to output stream in an indented format.
[in] | indent | Number of spaces to indent all the printed lines of this object. |
[in] | os | Output stream to print on. |
All objects in the E57 Foundation API (with exception of E57Exception) support a dump() function. These functions print out to the console a detailed listing of the internal state of objects. The content of these printouts is not documented, and is really of interest only to implementation developers/maintainers or the really adventurous users. In implementations of the API other than the Reference Implementation, the dump() functions may produce no output (although the functions should still be defined). The output format may change from version to version.
No | E57Exceptions |
void ImageFile::elementNameParse | ( | const ustring & | elementName, |
ustring & | prefix, | ||
ustring & | localPart | ||
) | const |
Parse element name into prefix and localPart substrings.
[in] | elementName | The string element name to parse into prefix and local parts. |
[out] | prefix | The prefix (if any) in the elementName. |
[out] | localPart | The part of the element name after the prefix. |
A legal element name may be in prefixed (ID:ID) or unprefixed (ID) form, where ID is a string whose first character is in {a-z,A-Z,_} followed by zero or more characters in {a-z,A-Z,_,0-9,-,.}. If in prefixed form, the prefix does not have to be declared in the ImageFile.
ErrorBadPathName | |
ErrorInternal | All objects in undocumented state |
Declare the use of an E57 extension in an ImageFile being written.
[in] | prefix | The shorthand name of the extension to use in element names. |
[in] | uri | The Uniform Resource Identifier string to associate with the prefix in the ImageFile. |
The (prefix, uri) pair is registered in the known extensions of the ImageFile. Both prefix and uri must be unique in the ImageFile. It is not legal to declare a URI associated with the default namespace (prefix = ""). It is not an error to declare a namespace and not use it in an element name. It is an error to use a namespace prefix in an element name that is not declared beforehand.
A writer is free to "hard code" the prefix names in the element name strings that it uses (since it established the prefix declarations in the file). A reader cannot assume that any given prefix is always mapped to the same URI or vice versa. A reader might check an ImageFile, and if the prefixes aren't the way it likes, the reader could give up.
A better scheme would be to lookup the URI that the reader is familiar with, and store the prefix that the particular file uses in a variable. Then every time the reader needs to form a prefixed element name, it can assemble the full element name from the stored prefix variable and the constant documented base name string. This is less convenient than using a single "hard coded" string constant for an element name, but it is robust against any choice of prefix/URI combination.
See the class discussion at bottom of ImageFile page for more details about namespaces.
ErrorBadAPIArgument | |
ErrorImageFileNotOpen | |
ErrorFileReadOnly | |
ErrorDuplicateNamespacePrefix | |
ErrorDuplicateNamespaceURI | |
ErrorInternal | All objects in undocumented state |
size_t ImageFile::extensionsCount | ( | ) | const |
Get number of E57 extensions declared in the ImageFile.
The default E57 namespace does not count as an extension.
ErrorImageFileNotOpen | |
ErrorInternal | All objects in undocumented state |
bool ImageFile::extensionsLookupPrefix | ( | const ustring & | prefix | ) | const |
Look up an E57 extension prefix in the ImageFile.
[in] | prefix | The shorthand name of the extension to look up. |
If prefix = "" or prefix is declared in the ImageFile, then the function returns true. It is an error if prefix contains an illegal character combination for E57 namespace prefixes.
ErrorBadAPIArgument | |
ErrorImageFileNotOpen | |
ErrorInternal | All objects in undocumented state |
Get URI associated with an E57 extension prefix in the ImageFile.
[in] | prefix | The shorthand name of the extension to look up. |
[out] | uri | The URI that was associated with the given prefix. |
If prefix = "", then uri is set to the default namespace URI, and the function returns true. if prefix is declared in the ImageFile, then uri is set the corresponding URI, and the function returns true. It is an error if prefix contains an illegal character combination for E57 namespace prefixes. It is not an error if prefix is well-formed, but not defined in the ImageFile (the function just returns false).
ErrorBadAPIArgument | |
ErrorImageFileNotOpen | |
ErrorInternal | All objects in undocumented state |
Get an E57 extension prefix associated with a URI in the ImageFile.
[in] | uri | The URI of the extension to look up. |
[out] | prefix | The shorthand prefix that was associated with the given uri. |
If uri is declared in the ImageFile, then prefix is set the corresponding prefix, and the function returns true. It is an error if uri contains an illegal character combination for E57 namespace URIs. It is not an error if uri is well-formed, but not defined in the ImageFile (the function just returns false).
ErrorBadAPIArgument | |
ErrorImageFileNotOpen | |
ErrorInternal | All objects in undocumented state |
ustring ImageFile::extensionsPrefix | ( | size_t | index | ) | const |
Get an E57 extension prefix declared in an ImageFile by index.
[in] | index | The index of the prefix to get, starting at 0. |
The order that the prefixes are stored in is not necessarily the same as the order they were created. However the prefix order will correspond to the URI order. The default E57 namespace is not counted as an extension.
ErrorBadAPIArgument | |
ErrorImageFileNotOpen | |
ErrorInternal | All objects in undocumented state |
ustring ImageFile::extensionsUri | ( | size_t | index | ) | const |
Get an E57 extension URI declared in an ImageFile by index.
[in] | index | The index of the URI to get, starting at 0. |
The order that the URIs are stored is not necessarily the same as the order they were created. However the URI order will correspond to the prefix order. The default E57 namespace is not counted as an extension.
ErrorBadAPIArgument | |
ErrorImageFileNotOpen | |
ErrorInternal | All objects in undocumented state |
ustring ImageFile::fileName | ( | ) | const |
Get the file name the ImageFile was created with.
No | E57Exceptions. |
bool ImageFile::isElementNameExtended | ( | const ustring & | elementName | ) | const |
Test whether an E57 element name has an extension prefix.
The element name has a prefix if the function elementNameParse(elementName,prefix,dummy) would succeed, and returned prefix != "".
[in] | elementName | The string element name to test. |
No | E57Exceptions. |
bool ImageFile::isOpen | ( | ) | const |
Test whether ImageFile is still open for accessing.
open
state.No | E57Exceptions. |
bool ImageFile::isWritable | ( | ) | const |
Test whether ImageFile was opened in write mode.
No | E57Exceptions. |
bool ImageFile::operator!= | ( | const ImageFile & | imf2 | ) | const |
bool ImageFile::operator== | ( | const ImageFile & | imf2 | ) | const |
int ImageFile::readerCount | ( | ) | const |
Get current number of open CompressedVectorReader objects reading from ImageFile.
CompressedVectorReader objects that still exist, but are in the closed state aren't counted. CompressedVectorReader objects are created by the CompressedVectorNode::reader function.
ErrorImageFileNotOpen | |
ErrorInternal | All objects in undocumented state |
StructureNode ImageFile::root | ( | ) | const |
Get the pre-established root StructureNode of the E57 ImageFile.
The root node of an ImageFile always exists and is always type StructureNode. The root node is empty in a newly created write mode ImageFile.
ErrorImageFileNotOpen | |
ErrorInternal | All objects in undocumented state |
int ImageFile::writerCount | ( | ) | const |
Get current number of open CompressedVectorWriter objects writing to ImageFile.
CompressedVectorWriter objects that still exist, but are in the closed state aren't counted. CompressedVectorWriter objects are created by the CompressedVectorNode::writer function.
ErrorImageFileNotOpen | |
ErrorInternal | All objects in undocumented state |