|
libE57Format 3.1.1
C++ library to read & write the E57 file format for point cloud data
|
Generic handle to any of the 8 types of E57 element objects. More...
#include <E57Format.h>
Public Member Functions | |
| Node ()=delete | |
| void | checkInvariant (bool doRecurse=true, bool doDowncast=true) |
| Check whether Node class invariant is true. | |
| ImageFile | destImageFile () const |
| Get the ImageFile that was declared as the destination for the node when it was created. | |
| 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. | |
| ustring | elementName () const |
| Get element name of node. | |
| bool | isAttached () const |
| Has node been attached into the tree of an ImageFile. | |
| bool | isRoot () const |
| Is this a root node. | |
| bool | operator!= (const Node &n2) const |
| Test if two node handles refer to different underlying nodes. | |
| bool | operator== (const Node &n2) const |
| Test if two node handles refer to the same underlying node. | |
| Node | parent () const |
| Return parent of node, or self if a root node. | |
| ustring | pathName () const |
| Get absolute pathname of node. | |
| NodeType | type () const |
| Return the NodeType of a generic Node. | |
Generic handle to any of the 8 types of E57 element objects.
A Node is a generic handle to an underlying object that is any of the eight type of E57 element objects. Each of the eight node types support the all the functions of the Node class. A Node is a vertex in a tree (acyclic graph), which is a hierarchical organization of nodes. At the top of the hierarchy is a single root Node. If a Node is a container type (StructureNode, VectorNode, CompressedVectorNode) it may have child nodes. The following are non-container type nodes (also known as terminal nodes): IntegerNode, ScaledIntegerNode, FloatNode, StringNode, BlobNode. Terminal nodes store various types of values and cannot have children. Each Node has an elementName, which is a string that uniquely identifies it within the children of its parent. Children of a StructureNode have elementNames that are explicitly given by the API user. Children of a VectorNode or CompressedVectorNode have element names that are string reorientations of the Node's positional index, starting at "0". A path name is a sequence elementNames (divided by "/") that must be traversed to get from a Node to one of its descendents.
Data is organized in an E57 format file (an ImageFile) hierarchically. Each ImageFile has a predefined root node that other nodes can be attached to as children (either directly or indirectly). A Node can exist temporarily without being attached to an ImageFile, however the state will not be saved in the associated file, and the state will be lost if the program exits.
A handle to a generic Node may be safely be converted to and from a handle to the Node's true underlying type. Since an attempt to convert a generic Node to a incorrect handle type will fail with an exception, the true type should be interrogated beforehand.
Due to the set-once design of the Foundation API, terminal nodes are immutable (i.e. their values and attributes can't change after creation). Once a parent-child relationship has been established, it cannot be changed.
Only generic operations are available for a Node, to access more specific operations (e.g. StructureNode::childCount) the generic handle must be converted to the node type of the underlying object. This conversion is done in a type-safe way using "downcasting" (see discussion below).
The conversion from a general handle type to a specific handle type is called "downcasting". Each of the 8 specific node types have a downcast function (see IntegerNode::IntegerNode(const Node&) for example). If a downcast is requested to an incorrect type (e.g. taking a Node handle that is actually a FloatNode and trying to downcast it to a IntegerNode), an E57Exception is thrown with an ErrorCode of ErrorBadNodeDowncast. Depending on the program design, throwing a bad downcast exception might be acceptable, if an element must be a specific type and no recovery is possible. If a standard requires an element be one several types, then Node::type() should be used to interrogate the type in an if or switch statement. Downcasting is "dangerous" (can fail with an exception) so the API requires the programmer to explicitly call the downcast functions rather than have the c++ compiler insert them automatically.
The conversion of a specific node handle (e.g. IntegerNode) to a general Node handle is called "upcasting". Each of the 8 specific node types have an upcast function (see IntegerNode::operator Node() for example). Upcasting is "safe" (can't cause an exception) so the API allows the c++ compiler to insert them automatically. Upcasting is useful if you have a specific node handle and want to call a function that takes a generic Node handle argument. In this case, the function can be called with the specific handle and the compiler will automatically insert the upcast conversion. This implicit conversion allows one function, with an argument of type Node, to handle operations that apply to all 8 types of nodes (e.g. StructureNode::set()).
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 |
| void Node::checkInvariant | ( | bool | doRecurse = true, |
| bool | doDowncast = true |
||
| ) |
Check whether Node class invariant is true.
| [in] | doRecurse | If true, also check invariants of all children or sub-objects recursively. |
| [in] | doDowncast | If true, also check any invariants of the actual derived type in addition to the generic node invariants. |
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.
Specifying doRecurse=true only makes sense if doDowncast=true is also specified (the generic Node has no way to access any children). 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 |
| ImageFile Node::destImageFile | ( | ) | const |
Get the ImageFile that was declared as the destination for the node when it was created.
The first argument of the constructors of each of the 8 types of nodes is an ImageFile that indicates which ImageFile the node will eventually be attached to. This function returns that constructor argument. It is an error to attempt to attach the node to a different ImageFile. However it is not an error to not attach the node to any ImageFile (it's just wasteful). Use Node::isAttached to check if the node actually did get attached.
| void Node::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 |
| ustring Node::elementName | ( | ) | const |
Get element name of node.
The elementName is a string associated with each parent-child link between nodes. For a given parent, the elementName uniquely identifies each of its children. Thus, any node in a tree can be identified by a sequence of elementNames that form a path from the tree's root node (see Node::pathName for more details).
Three types of nodes (the container node types) can be parents: StructureNode, VectorNode, and CompressedVectorNode. The children of a StructureNode are explicitly given unique elementNames when they are attached to the parent (using StructureNode::set). The children of VectorNode and CompressedVectorNode are implicitly given elementNames based on their position in the list (starting at "0"). In a CompressedVectorNode, the elementName can become quite large: "1000000000" or more. However in a CompressedVectorNode, the elementName string is not stored in the file and is deduced by the position of the child.
| ErrorImageFileNotOpen | |
| ErrorInternal | All objects in undocumented state |
| bool Node::isAttached | ( | ) | const |
Has node been attached into the tree of an ImageFile.
Nodes are attached into an ImageFile tree by inserting them as children (directly or indirectly) of the ImageFile's root node. Nodes can also be attached to an ImageFile if they are used in the codecs or prototype trees of an CompressedVectorNode that is attached. Attached nodes will be saved to disk when the ImageFile is closed, and restored when the ImageFile is read back in from disk. Unattached nodes will not be saved to disk. It is not recommended to create nodes that are not eventually attached to the ImageFile.
true if node is child of (or in codecs or prototype of a child CompressedVectorNode of) the root node of an ImageFile.| ErrorImageFileNotOpen | |
| ErrorInternal | All objects in undocumented state |
| bool Node::isRoot | ( | ) | const |
Is this a root node.
A root node has itself as a parent (it is not a child of any node). Newly constructed nodes (before they are inserted into an ImageFile tree) start out as root nodes. It is possible to temporarily create small trees that are unattached to any ImageFile. In these temporary trees, the top-most node will be a root node. After the tree is attached to the ImageFile tree, the only root node will be the pre-created one of the ImageTree (the one returned by ImageFile::root). The concept of attachment is slightly larger than that of the parent-child relationship (see Node::isAttached and CompressedVectorNode::CompressedVectorNode for more details).
| ErrorImageFileNotOpen | |
| ErrorInternal | All objects in undocumented state |
| bool Node::operator!= | ( | const Node & | n2 | ) | const |
Test if two node handles refer to different underlying nodes.
| [in] | n2 | The node to compare this node with |
true if node handles refer to different underlying nodes.| No | E57Exceptions |
| bool Node::operator== | ( | const Node & | n2 | ) | const |
Test if two node handles refer to the same underlying node.
| [in] | n2 | The node to compare this node with |
true if node handles refer to the same underlying node.| No | E57Exceptions |
| Node Node::parent | ( | ) | const |
Return parent of node, or self if a root node.
Nodes are organized into trees (acyclic graphs) with a distinguished node (the "top-most" node) called the root node. A parent-child relationship is established between nodes to form a tree. Nodes can have zero or one parent. Nodes with zero parents are called root nodes.
In the API, if a node has zero parents it is represented by having itself as a parent. Due to the set-once design of the API, a parent-child relationship cannot be modified once established. A child node can be any of the 8 node types, but a parent node can only be one of the 3 container node types (TypeStructure, TypeVector, and TypeCompressedVector). Each parent-child link has a string name (the elementName) associated with it (See Node::elementName for more details). More than one tree can be formed at any given time. Typically small trees are temporarily constructed before attachment to an ImageFile so that they will be written to the disk.
| ErrorImageFileNotOpen | |
| ErrorInternal | All objects in undocumented state |
| ustring Node::pathName | ( | ) | const |
Get absolute pathname of node.
Nodes are organized into trees (acyclic graphs) by a parent-child relationship between nodes. Each parent-child relationship has an associated elementName string that is unique for a given parent. Any node in a given tree can be identified by a sequence of elementNames of how to get to the node from the root of the tree. An absolute pathname string that is formed by arranging this sequence of elementNames separated by the "/" character with a leading "/" prepended.
Some example absolute pathNames: "/data3D/0/points/153/cartesianX", "/data3D/0/points", "/cameraImages/1/pose/rotation/w", and "/". These examples have probably been attached to an ImageFile. Here is an example absolute pathName of a node in a pose tree that has not yet been attached to an ImageFile: "/pose/rotation/w".
A technical aside: the elementName of a root node does not appear in absolute pathnames, since the "path" is between the staring node (the root) and the ending node. By convention, in this API, a root node has the empty string ("") as its elementName.
| ErrorImageFileNotOpen | |
| ErrorInternal | All objects in undocumented state |
| NodeType Node::type | ( | ) | const |
Return the NodeType of a generic Node.
This function allows the actual node type to be interrogated before upcasting the handle to the actual node type (see Upcasting and Downcasting section in Node).
1.9.6