An E57 element encoding a fixed point number. More...

#include <E57Format.h>

Public Member Functions
	ScaledIntegerNode ()=delete

	ScaledIntegerNode (const ImageFile &destImageFile, double scaledValue, double scaledMinimum, double scaledMaximum, double scale=1.0, double offset=0.0)
	This second constructor creates an E57 element for storing a fixed point number but does the scaling for you.

	ScaledIntegerNode (const ImageFile &destImageFile, int rawValue, int minimum, int maximum, double scale=1.0, double offset=0.0)

	ScaledIntegerNode (const ImageFile &destImageFile, int rawValue, int64_t minimum, int64_t maximum, double scale=1.0, double offset=0.0)

	ScaledIntegerNode (const ImageFile &destImageFile, int64_t rawValue, int64_t minimum, int64_t maximum, double scale=1.0, double offset=0.0)
	Create an E57 element for storing a fixed point number.

	ScaledIntegerNode (const Node &n)
	Downcast a generic Node handle to an ScaledIntegerNode handle.

void	checkInvariant (bool doRecurse=true, bool doUpcast=true) const
	Check whether ScaledIntegerNode 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 elementName string, that identifies the node in its parent.

bool	isAttached () const
	Has node been attached into the tree of an ImageFile.

bool	isRoot () const
	Is this a root node.

int64_t	maximum () const
	Get the declared maximum that the raw value may take.

int64_t	minimum () const
	Get the declared minimum that the raw value may take.

double	offset () const
	Get declared offset.

	operator Node () const
	Upcast a ScaledIntegerNode handle to a generic Node handle.

Node	parent () const
	Return parent of node, or self if a root node.

ustring	pathName () const
	Get absolute pathname of node.

int64_t	rawValue () const
	Get raw unscaled integer value of element.

double	scale () const
	Get declared scaling factor.

double	scaledMaximum () const
	Get the declared scaled maximum that the scaled value may take.

double	scaledMinimum () const
	Get the declared scaled minimum that the scaled value may take.

double	scaledValue () const
	Get scaled value of element.

Detailed Description

An E57 element encoding a fixed point number.

An ScaledIntegerNode is a terminal node (i.e. having no children) that holds a fixed point number encoded by an integer rawValue, a double precision floating point scale, an double precision floating point offset, and integer minimum/maximum bounds.

The minimum attribute may be a number in the interval [-2^63, 2^63).

The maximum attribute may be a number in the interval [minimum, 2^63).

The rawValue may be a number in the interval [minimum, maximum].

The scaledValue is a calculated double precision floating point number derived from: scaledValue = rawValue*scale + offset.

See Node class discussion for discussion of the common functions that StructureNode supports.

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 ScaledIntegerNode::checkInvariant( bool /*doRecurse*/, bool doUpcast ) const
{
   // 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 );
   }
 
   // If value is out of bounds
   if ( rawValue() < minimum() || rawValue() > maximum() )
   {
      throw E57_EXCEPTION1( ErrorInvarianceViolation );
   }
 
   // If scale is zero
   if ( scale() == 0 )
   {
      throw E57_EXCEPTION1( ErrorInvarianceViolation );
   }
 
   // If scaled value is not calculated correctly
   if ( scaledValue() != rawValue() * scale() + offset() )
   {
      throw E57_EXCEPTION1( ErrorInvarianceViolation );
   }
}
 

See also: Node

Constructor & Destructor Documentation

◆ ScaledIntegerNode() [1/6]

e57::ScaledIntegerNode::ScaledIntegerNode ( )

delete

◆ ScaledIntegerNode() [2/6]

ScaledIntegerNode::ScaledIntegerNode	(	const ImageFile &	destImageFile,
		int64_t	rawValue,
		int64_t	minimum,
		int64_t	maximum,
		double	scale = `1.0`,
		double	offset = `0.0`
	)

explicit

Create an E57 element for storing a fixed point number.

Parameters

[in]	destImageFile	The ImageFile where the new node will eventually be stored.
[in]	rawValue	The raw integer value of the element.
[in]	minimum	The smallest rawValue that the element may take.
[in]	maximum	The largest rawValue that the element may take.
[in]	scale	The scaling factor used to compute scaledValue from rawValue.
[in]	offset	The offset factor used to compute scaledValue from rawValue.

A ScaledIntegerNode stores an integer value, a lower and upper bound, and two conversion factors. The ScaledIntegerNode class corresponds to the ASTM E57 standard ScaledInteger element. See the class discussion at bottom of ScaledIntegerNode page for more details.

The destImageFile indicates which ImageFile the ScaledIntegerNode will eventually be attached to. A node is attached to an ImageFile by adding it underneath the predefined root of the ImageFile (gotten from ImageFile::root). It is not an error to fail to attach the ScaledIntegerNode to the destImageFile. It is an error to attempt to attach the ScaledIntegerNode to a different ImageFile.

Warning: It is an error to give an rawValue outside the minimum / maximum bounds, even if the ScaledIntegerNode is destined to be used in a CompressedVectorNode prototype (where the rawValue will be ignored). If the ScaledIntegerNode is to be used in a prototype, it is recommended to specify a rawValue = 0 if 0 is within bounds, or a rawValue = minimum if 0 is not within bounds.

Precondition: The destImageFile must be open (i.e. destImageFile.isOpen() must be true).; The destImageFile must have been opened in write mode (i.e. destImageFile.isWritable() must be true).; minimum <= rawValue <= maximum; scale != 0

Exceptions

ErrorBadAPIArgument
ErrorImageFileNotOpen
ErrorFileReadOnly
ErrorValueOutOfBounds
ErrorInternal	All objects in undocumented state

See also: ScaledIntegerNode::rawValue, Node, CompressedVectorNode, CompressedVectorNode::prototype

◆ ScaledIntegerNode() [3/6]

ScaledIntegerNode::ScaledIntegerNode	(	const ImageFile &	destImageFile,
		int	rawValue,
		int64_t	minimum,
		int64_t	maximum,
		double	scale = `1.0`,
		double	offset = `0.0`
	)

explicit

◆ ScaledIntegerNode() [4/6]

ScaledIntegerNode::ScaledIntegerNode	(	const ImageFile &	destImageFile,
		int	rawValue,
		int	minimum,
		int	maximum,
		double	scale = `1.0`,
		double	offset = `0.0`
	)

explicit

◆ ScaledIntegerNode() [5/6]

ScaledIntegerNode::ScaledIntegerNode	(	const ImageFile &	destImageFile,
		double	scaledValue,
		double	scaledMinimum,
		double	scaledMaximum,
		double	scale = `1.0`,
		double	offset = `0.0`
	)

explicit

This second constructor creates an E57 element for storing a fixed point number but does the scaling for you.

Parameters

[in]	destImageFile	The ImageFile where the new node will eventually be stored.
[in]	scaledValue	The scaled integer value of the element.
[in]	scaledMinimum	The smallest scaledValue that the element may take.
[in]	scaledMaximum	The largest scaledValue that the element may take.
[in]	scale	The scaling factor used to compute scaledValue from rawValue.
[in]	offset	The offset factor used to compute scaledValue from rawValue.

A ScaledIntegerNode stores an integer value, a lower and upper bound, and two conversion factors. This ScaledIntegerNode constructor calculates the rawValue, minimum, and maximum by doing the floor((scaledValue - offset)/scale + .5) on each scaled parameters.

Warning: It is an error to give an rawValue outside the minimum / maximum bounds, even if the ScaledIntegerNode is destined to be used in a CompressedVectorNode prototype (where the rawValue will be ignored). If the ScaledIntegerNode is to be used in a prototype, it is recommended to specify a rawValue = 0 if 0 is within bounds, or a rawValue = minimum if 0 is not within bounds.

Precondition: The destImageFile must be open (i.e. destImageFile.isOpen() must be true).; The destImageFile must have been opened in write mode (i.e. destImageFile.isWritable() must be true).; scaledMinimum <= scaledValue <= scaledMaximum; scale != 0

Exceptions

ErrorBadAPIArgument
ErrorImageFileNotOpen
ErrorFileReadOnly
ErrorValueOutOfBounds
ErrorInternal	All objects in undocumented state

See also: ScaledIntegerNode::scaledValue, Node, CompressedVectorNode, CompressedVectorNode::prototype

◆ ScaledIntegerNode() [6/6]

ScaledIntegerNode::ScaledIntegerNode ( const Node & n )

explicit

Downcast a generic Node handle to an ScaledIntegerNode handle.

Parameters

[in] n The generic handle to downcast.

The handle n must be for an underlying ScaledIntegerNode, otherwise an exception is thrown. In designs that need to avoid the exception, use Node::type() to determine the actual type of the n before downcasting. This function must be explicitly called (c++ compiler cannot insert it automatically).

Exceptions

ErrorBadNodeDowncast

See also: Node::type(), ScaledIntegerNode::operator, Node()

Member Function Documentation

◆ checkInvariant()

void ScaledIntegerNode::checkInvariant	(	bool	doRecurse = `true`,
		bool	doUpcast = `true`
	)		const

Check whether ScaledIntegerNode class invariant is true.

Parameters

[in]	doRecurse	If true, also check invariants of all children or sub-objects recursively.
[in]	doUpcast	If true, also check invariants of the generic Node class.

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 ErrorInvarianceViolation E57Exception 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.

Postcondition: No visible state is modified.

Exceptions

ErrorInvarianceViolation or any other E57 ErrorCode

◆ destImageFile()

ImageFile ScaledIntegerNode::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.

Postcondition: No visible object state is modified.

Returns: The ImageFile that was declared as the destination for the node when it was created.

See also: Node::isAttached, StructureNode::StructureNode(), VectorNode::VectorNode(), CompressedVectorNode::CompressedVectorNode(), IntegerNode::IntegerNode(), ScaledIntegerNode::ScaledIntegerNode(), FloatNode::FloatNode(), StringNode::StringNode(), BlobNode::BlobNode()

◆ dump()

void ScaledIntegerNode::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.

Parameters

[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.

Postcondition: No visible object state is modified.

Exceptions

No	E57Exceptions

◆ elementName()

ustring ScaledIntegerNode::elementName ( ) const

Get elementName string, that identifies the node in its parent.

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.

Precondition: The destination ImageFile must be open (i.e. destImageFile().isOpen()).

Postcondition: No visible state is modified.

Returns: The element name of the node, or "" if a root node.

Exceptions

ErrorImageFileNotOpen
ErrorInternal	All objects in undocumented state

See also: Node::pathName, Node::parent, Node::isRoot

◆ isAttached()

bool ScaledIntegerNode::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.

Precondition: The destination ImageFile must be open (i.e. destImageFile().isOpen()).

Postcondition: No visible object state is modified.

Returns: true if node is child of (or in codecs or prototype of a child CompressedVectorNode of) the root node of an ImageFile.

Exceptions

ErrorImageFileNotOpen
ErrorInternal	All objects in undocumented state

See also: Node::destImageFile, ImageFile::root

◆ isRoot()

bool ScaledIntegerNode::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).

Precondition: The destination ImageFile must be open (i.e. destImageFile().isOpen()).

Postcondition: No visible state is modified.

Returns: true if this node is a root node.

Exceptions

ErrorImageFileNotOpen
ErrorInternal	All objects in undocumented state

See also: Node::parent, Node::isAttached, CompressedVectorNode::CompressedVectorNode

◆ maximum()

int64_t ScaledIntegerNode::maximum ( ) const

Get the declared maximum that the raw value may take.

Precondition: The destination ImageFile must be open (i.e. destImageFile().isOpen()).

Postcondition: No visible state is modified.

Returns: The declared maximum that the rawValue may take.

Exceptions

ErrorImageFileNotOpen
ErrorInternal	All objects in undocumented state

See also: ScaledIntegerNode::minimum, ScaledIntegerNode::rawValue

◆ minimum()

int64_t ScaledIntegerNode::minimum ( ) const

Get the declared minimum that the raw value may take.

Precondition: The destination ImageFile must be open (i.e. destImageFile().isOpen()).

Postcondition: No visible state is modified.

Returns: The declared minimum that the rawValue may take.

Exceptions

ErrorImageFileNotOpen
ErrorInternal	All objects in undocumented state

See also: ScaledIntegerNode::maximum, ScaledIntegerNode::rawValue

◆ offset()

double ScaledIntegerNode::offset ( ) const

Get declared offset.

Precondition: The destination ImageFile must be open (i.e. destImageFile().isOpen()).

Postcondition: No visible state is modified.

Returns: The offset used to compute scaledValue from rawValue.

Exceptions

ErrorImageFileNotOpen
ErrorInternal	All objects in undocumented state

See also: ScaledIntegerNode::scaledValue

◆ operator Node()

ScaledIntegerNode::operator Node ( ) const

Upcast a ScaledIntegerNode handle to a generic Node handle.

An upcast is always safe, and the compiler can automatically insert it for initializations of Node variables and Node function arguments.

Returns: A smart Node handle referencing the underlying object.

Exceptions

No	E57Exceptions.

See also: Explanation in Node, Node::type(), ScaledIntegerNode(const Node&)

◆ parent()

Node ScaledIntegerNode::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.

Warning: User algorithms that use this function to walk the tree must take care to handle the case where a node is its own parent (it is a root node). Use Node::isRoot to avoid infinite loops or infinite recursion.

Precondition: The destination ImageFile must be open (i.e. destImageFile().isOpen()).

Postcondition: No visible state is modified.

Returns: A smart Node handle referencing the parent node or this node if is a root node.

Exceptions

ErrorImageFileNotOpen
ErrorInternal	All objects in undocumented state

See also: Node::isRoot, Node::isAttached, CompressedVectorNode::CompressedVectorNode, Node::elementName

◆ pathName()

ustring ScaledIntegerNode::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.

Precondition: The destination ImageFile must be open (i.e. destImageFile().isOpen()).

Postcondition: No visible state is modified.

Returns: The absolute path name of the node.

Exceptions

ErrorImageFileNotOpen
ErrorInternal	All objects in undocumented state

See also: Node::elementName, Node::parent, Node::isRoot

◆ rawValue()

int64_t ScaledIntegerNode::rawValue ( ) const

Get raw unscaled integer value of element.

Precondition: The destination ImageFile must be open (i.e. destImageFile().isOpen()).

Postcondition: No visible state is modified.

Returns: The raw unscaled integer value stored.

Exceptions

ErrorImageFileNotOpen
ErrorInternal	All objects in undocumented state

See also: ScaledIntegerNode::scaledValue, ScaledIntegerNode::minimum, ScaledIntegerNode::maximum

◆ scale()

double ScaledIntegerNode::scale ( ) const

Get declared scaling factor.

Precondition: The destination ImageFile must be open (i.e. destImageFile().isOpen()).

Postcondition: No visible state is modified.

Returns: The scaling factor used to compute scaledValue from rawValue.

Exceptions

ErrorImageFileNotOpen
ErrorInternal	All objects in undocumented state

See also: ScaledIntegerNode::scaledValue

◆ scaledMaximum()

double ScaledIntegerNode::scaledMaximum ( ) const

Get the declared scaled maximum that the scaled value may take.

Precondition: The destination ImageFile must be open (i.e. destImageFile().isOpen()).

Postcondition: No visible state is modified.

Returns: The declared maximum that the rawValue may take.

Exceptions

ErrorImageFileNotOpen
ErrorInternal	All objects in undocumented state

See also: ScaledIntegerNode::scaledMinimum, ScaledIntegerNode::scaledValue

◆ scaledMinimum()

double ScaledIntegerNode::scaledMinimum ( ) const

Get the declared scaled minimum that the scaled value may take.

Precondition: The destination ImageFile must be open (i.e. destImageFile().isOpen()).

Postcondition: No visible state is modified.

Returns: The declared minimum that the rawValue may take.

Exceptions

ErrorImageFileNotOpen
ErrorInternal	All objects in undocumented state

See also: ScaledIntegerNode::scaledMaximum, ScaledIntegerNode::scaledValue

◆ scaledValue()

double ScaledIntegerNode::scaledValue ( ) const

Get scaled value of element.

Precondition: The destination ImageFile must be open (i.e. destImageFile().isOpen()).

Postcondition: No visible state is modified.

Returns: The scaled value (rawValue*scale + offset) calculated from the rawValue stored.

Exceptions

ErrorImageFileNotOpen
ErrorInternal	All objects in undocumented state

See also: ScaledIntegerNode::rawValue

The documentation for this class was generated from the following files:

Public Member Functions

Detailed Description

Class Invariant

Constructor & Destructor Documentation

◆ ScaledIntegerNode() [1/6]

◆ ScaledIntegerNode() [2/6]

◆ ScaledIntegerNode() [3/6]

◆ ScaledIntegerNode() [4/6]

◆ ScaledIntegerNode() [5/6]

◆ ScaledIntegerNode() [6/6]

Member Function Documentation

◆ checkInvariant()

◆ destImageFile()

◆ dump()

◆ elementName()

◆ isAttached()

◆ isRoot()

◆ maximum()

◆ minimum()

◆ offset()

◆ operator Node()

◆ parent()

◆ pathName()

◆ rawValue()

◆ scale()

◆ scaledMaximum()

◆ scaledMinimum()

◆ scaledValue()