CompressedVectorNode Class Reference

An E57 element containing ordered vector of child nodes, stored in an efficient binary format. More...

List of all members.

Public Member Functions
	CompressedVectorNode (ImageFile destImageFile, Node prototype, VectorNode codecs)
	Create an empty CompressedVectorNode, for writing, that will store records specified by the prototype.
int64_t	childCount () const
	Get current number of records in a CompressedVectorNode.
Node	prototype () const
	Get the prototype tree that describes the types in the record.
VectorNode	codecs () const
	Get the codecs tree that describes the encoder/decoder configuration of the CompressedVectorNode.
CompressedVectorWriter	writer (std::vector< SourceDestBuffer > &sbufs)
	Create an iterator object for writing a series of blocks of data to a CompressedVectorNode.
CompressedVectorReader	reader (const std::vector< SourceDestBuffer > &dbufs)
	Create an iterator object for reading a series of blocks of data from a CompressedVectorNode.
	operator Node () const
	Upcast a CompressedVectorNode handle to a generic Node handle.
	CompressedVectorNode (const Node &n)
	Downcast a generic Node handle to a CompressedVectorNode handle.
bool	isRoot () const
	Is this a root node.
Node	parent () const
	Return parent of node, or self if a root node.
ustring	pathName () const
	Get absolute pathname of node.
ustring	elementName () const
	Get elementName string, that identifies the node in its parent..
ImageFile	destImageFile () const
	Get the ImageFile that was declared as the destination for the node when it was created.
bool	isAttached () const
	Has node been attached into the tree of an ImageFile.
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	checkInvariant (bool doRecurse=true, bool doUpcast=true)
	Check whether CompressedVectorNode class invariant is true.

---

Detailed Description

An E57 element containing ordered vector of child nodes, stored in an efficient binary format.

The CompressedVectorNode encodes very long sequences of identically typed records. In an E57 file, the per-point information (coordinates, intensity, color, time stamp etc.) are stored in a CompressedVectorNode. For time and space efficiency, the CompressedVectorNode data is stored in a binary section of the E57 file.

Conceptually, the CompressedVectorNode encodes a structure that looks very much like a homogeneous VectorNode object. However because of the huge volume of data (E57 files can store more than 10 billion points) within a CompressedVectorNode, the functions for accessing the data are dramatically different. CompressedVectorNode data is accessed in large blocks of records (100s to 1000s at a time).

Two attributes are required to create a new CompressedVectorNode. The first attribute describes the shape of the record that will be stored. This record type description is called the prototype of the CompressedVectorNode. Often the prototype will be a StructNode with a single level of named child elements. However, the prototype can be a tree of any depth consisting of the following node types: IntegerNode, ScaledIntegerNode, FloatNode, StringNode, StructureNode, or VectorNode (i.e. CompressedVectorNode and BlobNode are not allowed). Only the node types and attributes are used in the prototype, the values stored are ignored. For example, if the prototype contains an IntegerNode, with a value=0, minimum=0, maximum=1023, then this means that each record will contain an integer that can take any value in the interval [0,1023]. As a second example, if the prototype contains an ScaledIntegerNode, with a value=0, minimum=0, maximum=1023, scale=.001, offset=0 then this means that each record will contain an integer that can take any value in the interval [0,1023] and if a reader requests the scaledValue of the field, the rawValue should be multiplied by 0.001.

The second attribute needed to describe a new CompressedVectorNode is the codecs description of how the values of the records are to be represented on the disk. The codec object is a VectorNode of a particular format that describes the encoding for each field in the record, which codec will be used to transfer the values to and from the disk. Currently only one codec is defined for E57 files, the bitPackCodec, which copies the numbers from memory, removes any unused bit positions, and stores the without additional spaces on the disk. The bitPackCodec has no configuration options or parameters to tune. In the ASTM standard, if no codec is specified, the bitPackCodec is assumed. So specifying the codecs as an empty VectorNode is equivalent to requesting at all fields in the record be encoded with the bitPackCodec.

Other than the prototype and codecs attributes, the only other state directly accessible is the number of children (records) in the CompressedVectorNode. The read/write access to the contents of the CompressedVectorNode is coordinated by two other Foundation API objects: CompressedVectorReader and CompressedVectorWriter.

Class Invariant

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:

void CompressedVectorNode::checkInvariant(bool doRecurse, bool doUpcast) {
    // If destImageFile not open, can't test invariant (almost every call would throw)
    if (!destImageFile().isOpen())
        return;

    // If requested, call Node::checkInvariant
    if (doUpcast)
        static_cast<Node>(*this).checkInvariant(false, false);

    // Check prototype is good Node
    prototype().checkInvariant(doRecurse);

    // prototype attached state not same as this attached state
    if (prototype().isAttached() != isAttached())
       throw E57_EXCEPTION1(E57_ERROR_INVARIANCE_VIOLATION);

    // prototype not root
    if (!prototype().isRoot())
       throw E57_EXCEPTION1(E57_ERROR_INVARIANCE_VIOLATION);

    // prototype dest ImageFile not same as this dest ImageFile
    if (prototype().destImageFile() != destImageFile())
       throw E57_EXCEPTION1(E57_ERROR_INVARIANCE_VIOLATION);

    // Check codecs is good Node
    codecs().checkInvariant(doRecurse);

    // codecs attached state not same as this attached state
    if (codecs().isAttached() != isAttached())
       throw E57_EXCEPTION1(E57_ERROR_INVARIANCE_VIOLATION);

    // codecs not root
    if (!codecs().isRoot())
       throw E57_EXCEPTION1(E57_ERROR_INVARIANCE_VIOLATION);

    // codecs dest ImageFile not same as this dest ImageFile
    if (codecs().destImageFile() != destImageFile())
       throw E57_EXCEPTION1(E57_ERROR_INVARIANCE_VIOLATION);
} // end CompressedVectorNode::checkInvariant

See also:

CompressedVectorReader, CompressedVectorWriter, Node