E57 Foundation API

http://libe57.org/FoundationAPI/html/
Admin
The E57 Foundation API is a collection of C++ functions designed to help programmers read and write...
Tokens:131,141
Snippets:493
Trust Score:4.4
Update:1 year ago
Show doc for...
Tokens:
Raw
### Basic HelloWorld.cpp Example

Demonstrates the basic usage of the E57 Foundation API, specifically the ImageFile class. This example is intended to be a starting point for new users.

```C++
#include "E57Foundation.h"

int main(int argc, char **argv) {
  // Example use of ImageFile.
  return 0;
}
```

--------------------------------

### Example: E57 Foundation API Basics

A fundamental example showcasing the basic operations and usage patterns of the E57 Foundation API. This serves as a starting point for new users.

```cpp
// examples/HelloWorld.cpp| Example: the basics
```

--------------------------------

### Example: Getting E57 Implementation Library Versions

Shows how to retrieve the version information of the E57 implementation library. This is useful for compatibility checks and understanding the library's build.

```cpp
// examples/Versions.cpp| Example: get versions of the E57 implementation library
```

--------------------------------

### IntegerNode Example Usage

Main function demonstrating the use of IntegerNode functions. This example shows how to create, retrieve, and interact with IntegerNodes, including printing their information. It utilizes the `printIntegerInfo` helper function.

```C++
int main (int, char **)
{
  ImageFile imf("IntegerExample.e57", "w");

  // Create an IntegerNode
  imf.createIntegerNode("/myInteger", 12345);
  printIntegerInfo(imf, "/myInteger");

  // Create another IntegerNode with a different value
  imf.createIntegerNode("/anotherInteger", -987);
  printIntegerInfo(imf, "/anotherInteger");

  return 0;
}
```

--------------------------------

### Create IntegerNode

Example of creating an IntegerNode. This function demonstrates the basic steps involved in instantiating and initializing an IntegerNode within the E57 Foundation API. It requires an ImageFile object and a path name for the node.

```C++
void printIntegerInfo (ImageFile imf, ustring pathName)
{
  NodeImpl* node = imf.getNode(pathName.c_str());
  if (node)
    {
      if (node->nodeType() == E57_NODE_INTEGER)
        {
          IntegerNodeImpl* integerNode = (IntegerNodeImpl*)node;
          int64_t value = integerNode->getValue();
          std::cout << "Integer node '" << pathName << "' value: " << value << std::endl;
        }
      else
        {
          std::cerr << "Error: Node '" << pathName << "' is not an IntegerNode." << std::endl;
        }
      node->unrefer();
    }
  else
    {
      std::cerr << "Error: Could not get node '" << pathName << "'." << std::endl;
    }
}
```

--------------------------------

### Example E57ExceptionFunctions.cpp Usage

Demonstrates the example usage of E57Exception functions. This snippet illustrates basic error handling within the E57 Foundation API.

```cpp
int main(int argc, char **argv)
{
  // Example use of E57Exception functions.
  return 0;
}
```

--------------------------------

### Example: Creating IntegerNodes

Shows how to create IntegerNodes for storing integer values within the E57 file format. This example covers the fundamental aspects of IntegerNode creation.

```cpp
// examples/IntegerCreate.cpp| Example: creating IntegerNodes
```

--------------------------------

### C++ Example: Creating and Printing E57 IntegerNodes

This C++ code demonstrates how to create an E57 file and populate it with IntegerNodes. It shows different ways to initialize IntegerNodes with default or specified values, minimums, and maximums. The code also includes a function to print information about existing IntegerNodes and handles potential E57 exceptions.

```cpp
/*** IntegerCreate.cpp example: creating IntegerNodes */
#include <iostream>
#include "E57Foundation.h"
using namespace e57;
using namespace std;

void printIntegerInfo(ImageFile imf, ustring pathName)
{
    cout << pathName << ":" << endl;

    StructureNode root = imf.root();

    if (root.isDefined(pathName)) {
        Node n = root.get(pathName);
        if (n.type() == E57_INTEGER) {
            IntegerNode iNode = static_cast<IntegerNode>(n);
            cout << "  value   = " << iNode.value()   << endl;
            cout << "  minimum = " << iNode.minimum() << endl;
            cout << "  maximum = " << iNode.maximum() << endl;
        } else
            cout << "oops " << n.pathName() << " isn't an Integer" << endl;
    }
}

int main(int /*argc*/, char** /*argv*/) {
    try {
        ImageFile imf("temp._e57", "w");
        StructureNode root = imf.root();

        // Create 4 example Integers 
        root.set("i1", IntegerNode(imf));
        root.set("i2", IntegerNode(imf, 123));
        root.set("i3", IntegerNode(imf, 123, 0, 1023));
        root.set("i4", IntegerNode(imf, 0, -128, 127));

        printIntegerInfo(imf, "/i1");
        printIntegerInfo(imf, "/i2");
        printIntegerInfo(imf, "/i3");
        printIntegerInfo(imf, "/i4");

        imf.close(); // don't forget to explicitly close the ImageFile
    } catch(E57Exception& ex) {
        ex.report(__FILE__, __LINE__, __FUNCTION__);
        return(-1);
    }
    return(0);
}

```

--------------------------------

### Example: Get Info About VectorNodes (C++)

This C++ code snippet demonstrates how to use VectorNode functions from the E57 Foundation API to get information about VectorNodes. It serves as a basic example for developers integrating with the API.

```C++
int main (int, char **)
{
  // Example use of VectorNode functions.
  return 0;
}
```

--------------------------------

### Example: SourceDestBuffer Functions in C++

Demonstrates the example usage of SourceDestBuffer functions within the E57 Foundation API. This snippet shows a typical `main` function entry point for testing or demonstrating these functionalities. It requires the E57 Foundation API library to be linked.

```cpp
int main (int argc, char **argv)
{
  // Example use of SourceDestBuffer functions.
  // ... implementation details ...
  return 0;
}
```

--------------------------------

### Example: Creating StringNodes

Shows how to create StringNodes for storing text data within the E57 Foundation API. This example covers the basic instantiation and usage of StringNodes.

```cpp
// examples/StringCreate.cpp| Example: creating StringNodes
```

--------------------------------

### Example: Handling E57 Exceptions

Demonstrates how to retrieve information about E57Exceptions. This example is crucial for understanding and managing potential errors that may occur during E57 file operations.

```cpp
// examples/E57ExceptionFunctions.cpp| Example: get info about E57Exceptions
```

--------------------------------

### Example: Creating VectorNodes

Provides an example of how to create VectorNodes, which are used to store ordered lists of elements. This is a common data structure in the E57 format.

```cpp
// examples/VectorCreate.cpp| Example: creating VectorNodes
```

--------------------------------

### Example of BlobNode Creation in C++

Demonstrates the example usage of BlobNode functions within the E57 Foundation API. This function serves as a basic illustration for developers looking to create and manipulate BlobNodes. No specific external dependencies are mentioned, and it takes standard integer arguments for argc and argv, returning an integer status.

```c++
int | main (int, char **)
| Example use of BlobNode functions.
  
* * *

```

--------------------------------

### Example: SourceDestBuffer Functionality

Provides information about the SourceDestBuffer class, a key component for data transfer within the E57 Foundation API. This example covers its general usage.

```cpp
// examples/SourceDestBufferFunctions.cpp| Example: get info about a SourceDestBuffer
```

--------------------------------

### Example: Node Functionality

Provides information and examples related to generic Nodes within the E57 Foundation API. This covers common operations applicable to various node types.

```cpp
// examples/NodeFunctions.cpp| Example: get info about generic Nodes
```

--------------------------------

### Example: Creating CompressedVectorNodes

Provides an example of how to create CompressedVectorNodes from arrays. This is useful for efficiently storing and retrieving large datasets in a compressed format within an E57 file.

```cpp
// examples/CompressedVectorCreate.cpp| Example: creating CompressedVectorNodes from arrays
```

--------------------------------

### Example: Creating FloatNodes

Illustrates the creation of FloatNodes, which are used to store floating-point numbers in the E57 file format. This example covers the basic instantiation and usage of FloatNodes.

```cpp
// examples/FloatCreate.cpp| Example: creating FloatNodes
```

--------------------------------

### Create and Print ScaledIntegerNode Information (C++)

This snippet demonstrates how to create ScaledIntegerNodes and retrieve their information using the E57 Foundation API. It includes a `main` function for example usage and a helper function `printScaledIntegerInfo` to display node details. This requires the E57 Foundation API library.

```c++
#include "E57Foundation.h"

using namespace e57;

void printScaledIntegerInfo (ImageFile imf, ustring pathName) {
    NodeImpl* node = imf.getNode(pathName);
    if (node != nullptr && node->nodeType() == E57_SCALED_INTEGER) {
        ScaledIntegerNodeImpl* sin = static_cast<ScaledIntegerNodeImpl*>(node);
        std::cout << "Path: " << pathName << std::endl;
        std::cout << "  Value: " << sin->getValue() << std::endl;
        std::cout << "  Scale: " << sin->getScale() << std::endl;
        std::cout << "  Offset: " << sin->getOffset() << std::endl;
    }
}

int main (int, char **) {
    ImageFile imf("temp.e57", true);

    // Create a ScaledIntegerNode
    ScaledIntegerNodeImpl* sin = static_cast<ScaledIntegerNodeImpl*>(imf.createNode(E57_SCALED_INTEGER, "/root/scaledInteger"));
    sin->setValue(123);
    sin->setScale(0.1);
    sin->setOffset(5.0);

    printScaledIntegerInfo(imf, "/root/scaledInteger");

    imf.deleteNode("/root/scaledInteger");

    return 0;
}
```

--------------------------------

### Get Info About VectorNodes using C++ E57 Foundation API

This C++ code snippet demonstrates how to create a VectorNode, append IntegerNodes to it, and then retrieve information about the VectorNode and its children. It utilizes the E57 Foundation API for file and node manipulation. The code includes error handling for E57 exceptions and ensures the ImageFile is properly closed.

```cpp
/*** VectorFunctions.cpp example: get info about VectorNodes */
#include <iostream>
#include "E57Foundation.h"
using namespace e57;
using namespace std;

int main(int /*argc*/, char** /*argv*/) {
    try {
        ImageFile imf("temp._e57", "w");
        StructureNode root = imf.root();

        // Create vector /exampleVector, with 2 child elements
        VectorNode v(imf, false);
        root.set("exampleVector", v);
        v.append(IntegerNode(imf, 100));
        v.append(IntegerNode(imf, 101));

        cout << v.pathName() << " has " << v.childCount() << " children:" << endl;
        for (int i = 0; i < v.childCount(); i++) {
            Node n = v.get(i);
            if (n.type() == E57_INTEGER) {
                IntegerNode iNode = static_cast<IntegerNode>(n);
                cout << "  " << iNode.pathName() << " IntegerNode = " << iNode.value() << endl;
           } else
                cout << "  " << n.pathName() << endl;
        }

        if (v.isDefined("1"))
            cout << v.pathName() << " has a second child element" << endl;
        if (!v.isDefined("2"))
            cout << v.pathName() << " doesn't have a third child element" << endl;

        Node n = root.get("/exampleVector");
        if (n.type() == E57_VECTOR) {
            VectorNode v2 = static_cast<VectorNode>(n);
            cout << v2.pathName() << " has " << v2.childCount() << " children" << endl;
        }

        imf.close(); // don't forget to explicitly close the ImageFile
    } catch(E57Exception& ex) {
        ex.report(__FILE__, __LINE__, __FUNCTION__);
        return(-1);
    }
    return(0);
}

```

--------------------------------

### Create StructureNode Example (C++)

Demonstrates the creation and usage of StructureNodes using the E57 Foundation API. This example serves as a basic illustration of how to manipulate hierarchical data structures within the E57 format.

```C++
int main(int, char **)
{
  // Example use of StructureNode functions.
  return 0;
}
```

--------------------------------

### Example: Creating BlobNodes

Demonstrates the process of creating BlobNodes within the E57 Foundation API. This involves understanding how to represent binary data within the E57 file format.

```cpp
// examples/BlobCreate.cpp| Example: creating BlobNodes
```

--------------------------------

### Example: Creating String SourceDestBuffers

Illustrates the creation of SourceDestBuffers for handling string data. This is crucial for managing textual information within E57 files.

```cpp
// examples/SourceDestBufferStringCreate.cpp| Example: creating SourceDestBuffers of Strings
```

--------------------------------

### Create FloatNode and Print Info - FloatCreate.cpp

Demonstrates the creation of FloatNodes and retrieving their information using the E57 Foundation API. Requires the ImageFile object and a path name for the node.

```cpp
void printFloatInfo (ImageFile imf, ustring pathName)
{
  // Get and print some info about a FloatNode.
}

int main (int, char **)
{
  // Example use of FloatNode functions.
  return 0;
}
```

--------------------------------

### Example: Creating Numeric SourceDestBuffers

Demonstrates the creation of SourceDestBuffers specifically for numeric data types. This is essential for efficient reading and writing of numerical data.

```cpp
// examples/SourceDestBufferNumericCreate.cpp| Example: creating SourceDestBuffers of numbers
```

--------------------------------

### Example Usage of Node Functions in C++

Demonstrates the practical application of generic and specific Node functions. This main function serves as an entry point for showcasing API usage.

```C++
int main (int argc, char **argv)
{
  // Example code using printGenericInfo and printSpecificInfo
  return 0;
}
```

--------------------------------

### Example: Creating StructureNodes

Demonstrates the creation of StructureNodes, which are used to group other nodes in a hierarchical manner. This is fundamental for organizing data within an E57 file.

```cpp
// examples/StructureCreate.cpp| Example: creating StructureNodes
```

--------------------------------

### Example: Parsing Element Names

Illustrates the process of parsing both valid and invalid element names according to E57 naming conventions. This is essential for ensuring correct data structure and referencing.

```cpp
// examples/NameParse.cpp| Example: parse good and bad element names
```

--------------------------------

### Example: Vector Node Functionality

Explains and demonstrates the functionalities associated with VectorNodes. This includes operations like adding, accessing, and iterating through elements within a vector.

```cpp
// examples/VectorFunctions.cpp| Example: get info about VectorNodes
```

--------------------------------

### Example: Dumping E57 File Diagnostics

Demonstrates how to print diagnostic information about an ImageFile and other related objects. This function is useful for debugging and understanding the structure of an E57 file.

```cpp
// examples/ImageFileDump.cpp| Example: print diagnostics about an ImageFile and other objects
```

--------------------------------

### Example: Reading Raw XML from E57 File

Demonstrates how to read the raw XML section from an E57 file. This allows access to metadata and other XML-based information stored within the file.

```cpp
// examples/RawXML.cpp| Example: read XML section from E57 file
```

--------------------------------

### Create and Read E57 File with String Node (C++)

This C++ code demonstrates the fundamental operations of the E57 Foundation API. It first creates a new E57 file, writes a simple 'Hello world.' string element to the root structure, and then reopens the file to read and print the string value. It includes error handling using E57 exceptions and demonstrates basic file I/O.

```cpp
/*** HelloWorld.cpp example: the basics */
#include <iostream>
#include "E57Foundation.h"
using namespace e57;
using namespace std;

int main(int /*argc*/, char** /*argv*/) {
    try {
        ImageFile imf("temp._e57", "w");
        StructureNode root = imf.root();
        
        root.set("greeting", StringNode(imf, "Hello world."));

        imf.close(); // don't forget to explicitly close the ImageFile
    } catch(E57Exception& ex) {
        ex.report(__FILE__, __LINE__, __FUNCTION__);
        return(-1);
    }

    try {
        ImageFile imf("temp._e57", "r");
        StructureNode root = imf.root();

        StringNode greeting(root.get("greeting"));
        cout << "Value of /greeting = " << greeting.value() << endl;

        imf.close(); // don't forget to explicitly close the ImageFile
    } catch(E57Exception& ex) {
        ex.report(__FILE__, __LINE__, __FUNCTION__);
        return(-1);
    }
    return(0);
}
```

--------------------------------

### Opening and Creating E57 Files

Source: https://context7.com/context7/libe57_foundationapi_html/llms.txt

This section demonstrates how to create a new E57 file for writing and how to open an existing E57 file for reading. It also shows how to add basic metadata to the root structure and how to retrieve it.

```APIDOC
## Opening and Creating E57 Files

### Description
Demonstrates creating a new E57 file for writing and opening an existing file for reading. Includes adding and retrieving root-level metadata.

### Method
C++ API calls

### Endpoint
N/A (File operations)

### Parameters
None

### Request Example
```cpp
#include "E57Foundation.h"
using namespace e57;

try {
    // Create new E57 file for writing
    ImageFile imf("output.e57", "w");
    StructureNode root = imf.root();

    // Add simple metadata
    root.set("formatName", StringNode(imf, "ASTM E57 3D Imaging Data File"));
    root.set("majorVersion", IntegerNode(imf, 1, 0, 255));
    root.set("minorVersion", IntegerNode(imf, 0, 0, 255));

    // Must explicitly close to ensure data is written
    imf.close();

    // Open existing file for reading
    ImageFile readFile("output.e57", "r");
    StructureNode readRoot = readFile.root();

    // Check if element exists before reading
    if (readRoot.isDefined("formatName")) {
        StringNode name = readRoot.get("formatName");
        std::cout << "Format: " << name.value() << std::endl;
    }

    readFile.close();

} catch(E57Exception& ex) {
    ex.report(__FILE__, __LINE__, __FUNCTION__);
    return -1;
}
```

### Response
#### Success Response
File is created/opened, metadata is written/read.

#### Response Example
Output to console:
```
Format: ASTM E57 3D Imaging Data File
```
```

--------------------------------

### Open and Create E57 Files with libE57 Foundation API

Source: https://context7.com/context7/libe57_foundationapi_html/llms.txt

Demonstrates how to open existing E57 files for reading and create new ones for writing using the libE57 Foundation API. It includes basic error handling with C++ exceptions and closing files to ensure data integrity.

```cpp
#include "E57Foundation.h"
using namespace e57;

try {
    // Create new E57 file for writing
    ImageFile imf("output.e57", "w");
    StructureNode root = imf.root();

    // Add simple metadata
    root.set("formatName", StringNode(imf, "ASTM E57 3D Imaging Data File"));
    root.set("majorVersion", IntegerNode(imf, 1, 0, 255));
    root.set("minorVersion", IntegerNode(imf, 0, 0, 255));

    // Must explicitly close to ensure data is written
    imf.close();

    // Open existing file for reading
    ImageFile readFile("output.e57", "r");
    StructureNode readRoot = readFile.root();

    // Check if element exists before reading
    if (readRoot.isDefined("formatName")) {
        StringNode name = readRoot.get("formatName");
        std::cout << "Format: " << name.value() << std::endl;
    }

    readFile.close();

} catch(E57Exception& ex) {
    ex.report(__FILE__, __LINE__, __FUNCTION__);
    return -1;
}

```

--------------------------------

### Get E57 API Versions (C++)

This C++ code snippet demonstrates how to retrieve the ASTM major and minor version numbers, and the implementation library identifier using the E57Utilities::getVersions function. It requires the E57Foundation.h header and uses standard C++ I/O streams for output. The output includes the retrieved version details. The getVersions function is called on an instance created at run-time.

```cpp
/*** Versions.cpp example: get versions of the E57 implementation library */
#include <iostream>
#include "E57Foundation.h"
using namespace e57;
using namespace std;

int main(int /*argc*/, char** /*argv*/) {
    int astmMajor;
    int astmMinor;
    ustring libraryId;
    E57Utilities().getVersions(astmMajor, astmMinor, libraryId);

    cout << "astm major version     = " << astmMajor << endl;        
    cout << "astm minor version     = " << astmMinor << endl;        
    cout << "implementation library = " << libraryId << endl;        
    return(0);
}

```

--------------------------------

### Write and Read StringNode with E57 Foundation API in C++

This C++ code snippet demonstrates how to create an E57 file, write a StringNode with the value 'Hello world.', close the file, reopen it in read mode, retrieve the StringNode, and print its value. It utilizes the E57 Foundation API and includes exception handling for E57-related errors.

```cpp
#include <iostream>
#include "E57Foundation.h"
using namespace e57;
using namespace std;

int main(int /*argc*/, char** /*argv*/) {
    try {
        ImageFile imf("temp._e57", "w");
        StructureNode root = imf.root();
        
        root.set("greeting", StringNode(imf, "Hello world."));

        imf.close(); // don't forget to explicitly close the ImageFile
    } catch(E57Exception& ex) {
        ex.report(__FILE__, __LINE__, __FUNCTION__);
        return(-1);
    }

    try {
        ImageFile imf("temp._e57", "r");
        StructureNode root = imf.root();

        StringNode greeting(root.get("greeting"));
        cout << "Value of /greeting = " << greeting.value() << endl;

        imf.close(); // don't forget to explicitly close the ImageFile
    } catch(E57Exception& ex) {
        ex.report(__FILE__, __LINE__, __FUNCTION__);
        return(-1);
    }
    return(0);
}

```

--------------------------------

### main() Function - HelloWorld.cpp and others

The main() function serves as the entry point for various C++ source files within the E57 Foundation API. It is typically used for demonstration or testing purposes. Dependencies include standard C++ libraries.

```cpp
int main(int argc, char** argv) {
    // Example implementation for HelloWorld.cpp
    // ...
    return 0;
}
```

--------------------------------

### Register E57 Extension Prefix and URI (C++)

This C++ code snippet demonstrates how to declare an E57 extension prefix and URI in an ImageFile. It includes adding the extension, looking up its URI and prefix, iterating through defined extensions, and setting a node with an extended element name. It requires the E57 Foundation library and handles potential exceptions.

```cpp
/*** Extensions.cpp example: register use of extended element names */
#include <iostream>
#include "E57Foundation.h"
using namespace e57;
using namespace std;

int main(int /*argc*/, char** /*argv*/) {
    try {
        ImageFile imf("temp._e57", "w");

        imf.extensionsAdd("ext1", "http://www.example.com/MyExtension1");

        ustring uri;
        if (!imf.extensionsLookupPrefix("ext1", uri))
            cout << "Oops, ext1 should have been defined" << endl;
        else
            cout << "ext1 is prefix for uri=" << uri << endl;

        ustring prefix;
        if (!imf.extensionsLookupUri("http://www.example.com/MyExtension1", prefix))
            cout << "Oops, URI http://www.example.com/MyExtension1 should have been defined" << endl;
        else
            cout << "URI http://www.example.com/MyExtension1 has prefix=" << prefix << endl;

        cout << "Defined extensions:" << endl;
        for (int i = 0; i < imf.extensionsCount(); i++)
            cout << "  prefix:" << imf.extensionsPrefix(i) << " URI:" << imf.extensionsUri(i) << endl;

        imf.root().set("ext1:greeting", StringNode(imf, "Hello world."));

        imf.close(); // don't forget to explicitly close the ImageFile
    } catch(E57Exception& ex) {
        ex.report(__FILE__, __LINE__, __FUNCTION__);
        return(-1);
    }
    return(0);
}


```

--------------------------------

### Get E57 ImageFile Reader Count

Gets the current number of open CompressedVectorReader objects that are reading from the ImageFile. This indicates how many concurrent read streams are active for the file. Useful for tracking read access.

```C++
int | readerCount () const
```

--------------------------------

### C++ E57 Foundation API Example: Creating and Inspecting Nodes

This is the main function demonstrating the usage of the E57 Foundation API. It creates an E57 file, adds various nodes (Structure, String) with nesting, and then uses the printSpecificInfo function to display details about these nodes. It also shows the creation and inspection of unattached nodes.

```cpp
int main(int /*argc*/, char** /*argv*/) {
    try {
        ImageFile imf("temp._e57", "w");
        StructureNode root = imf.root();

        // Add a String element in /child/grandchild
        StructureNode child   = StructureNode(imf);
        StringNode grandchild = StringNode(imf, "I'm a grandchild");
        root.set("child", child);
        child.set("grandchild", grandchild);

        cout << "root node:" << endl;
        printSpecificInfo(root);

        cout << "child node:" << endl;
        printSpecificInfo(child);

        cout << "grandchild node:" << endl;
        printSpecificInfo(grandchild);

        StructureNode unattached = StructureNode(imf);
        StringNode unattachedChild = StringNode(imf, "I'm a child of an unattached node");
        unattached.set("unattachedChild", unattachedChild);

        cout << "unattached node:" << endl;
        printSpecificInfo(unattached);

        cout << "unattached child node:" << endl;
        printSpecificInfo(unattachedChild);

        imf.close(); // don't forget to explicitly close the ImageFile
    } catch(E57Exception& ex) {
        ex.report(__FILE__, __LINE__, __FUNCTION__);
        return(-1);
    }
    return(0);
}
```

--------------------------------

### Get E57 ImageFile Writer Count

Gets the current number of open CompressedVectorWriter objects that are writing to the ImageFile. This indicates how many concurrent write streams are active for the file. Helps in managing write operations.

```C++
int | writerCount () const
```

--------------------------------

### Example: Using checkInvariant Function in C++

This snippet demonstrates the example usage of various `checkInvariant` functions within the E57 Foundation API, specifically for objects like `ImageFile`. It is intended to show how to verify the internal consistency of data structures.

```cpp
int main(int argc, char **argv)
{
  // Example use of various checkInvariant functions.
  // ... implementation details ...
  return 0;
}
```

--------------------------------

### Get StructureNode and VectorNode using get()

This function retrieves a StructureNode or VectorNode. It's part of the E57 Foundation API and is used for accessing data structures within E57 files. Specific return types depend on the context of its usage.

```c++
StructureNode get();
VectorNode get();
```

--------------------------------

### Create VectorNodes in E57 Foundation API (C++)

This C++ example demonstrates how to create VectorNodes within the E57 Foundation API. It shows the creation of both homogeneous (same child types) and heterogeneous (differing child types) vectors and appends different data types to them. The example utilizes the E57Foundation.h header and handles potential exceptions.

```cpp
/*** VectorCreate.cpp example: creating VectorNodes */
#include <iostream>
#include "E57Foundation.h"
using namespace e57;
using namespace std;

int main(int /*argc*/, char** /*argv*/) {
    try {
        ImageFile imf("temp._e57", "w");
        StructureNode root = imf.root();

        // Create vector /v1, with 2 child elements: /v1/0, /v1/1
        VectorNode v1(imf, false);
        root.set("v1", v1);
        v1.append(StringNode(imf, "some string"));
        v1.append(StringNode(imf, "another string"));

        // Create vector /v2, with 2 child elements: /v2/0, /v2/1
        VectorNode v2(imf, true);
        root.set("v2", v2);
        v2.append(StringNode(imf, "yet another string"));
        v2.append(FloatNode(imf, 1.234));
        
        if (!v1.allowHeteroChildren())
            cout << "/v1 cannot contain children with different types" << endl;
        if (v2.allowHeteroChildren())
            cout << "/v2 can contain children with different types" << endl;

        imf.close(); // don't forget to explicitly close the ImageFile
    } catch(E57Exception& ex) {
        ex.report(__FILE__, __LINE__, __FUNCTION__);
        return(-1);
    }
    return(0);
}

```

--------------------------------

### Create and Print ScaledIntegerNodes using E57 Foundation API

This C++ code snippet creates an E57 file and demonstrates the creation of ScaledIntegerNodes with different configurations. It then defines a helper function to print the details of these nodes, including raw value, scaled value, minimum, maximum, scale, and offset. The main function orchestrates the file creation, node population, and printing of node information, with robust exception handling.

```cpp
/*** ScaledIntegerCreate.cpp example: creating ScaledIntegerNodes */
#include <iostream>
#include "E57Foundation.h"
using namespace e57;
using namespace std;

void printScaledIntegerInfo(ImageFile imf, ustring pathName)
{
    cout << pathName << ":" << endl;

    StructureNode root = imf.root();

    if (root.isDefined(pathName)) {
        Node n = root.get(pathName);
        if (n.type() == E57_SCALED_INTEGER) {
            ScaledIntegerNode si = static_cast<ScaledIntegerNode>(n);
            cout << "  rawValue    = " << si.rawValue()      << endl;
            cout << "  scaledValue = " << si.scaledValue()   << endl;
            cout << "  minimum     = " << si.minimum()    << endl;
            cout << "  maximum     = " << si.maximum()    << endl;
            cout << "  scale       = " << si.scale()      << endl;
            cout << "  offset      = " << si.offset()     << endl;
        } else
            cout << "oops " << n.pathName() << " isn't an ScaledInteger" << endl;
    }
}

int main(int /*argc*/, char** /*argv*/) {
    try {
        ImageFile imf("temp._e57", "w");
        StructureNode root = imf.root();

        // Create 5 example ScaledIntegers
        root.set("si1", ScaledIntegerNode(imf, int64_t(), E57_INT64_MIN, E57_INT64_MAX));
        root.set("si2", ScaledIntegerNode(imf, int64_t(123), E57_INT64_MIN, E57_INT64_MAX));
        root.set("si3", ScaledIntegerNode(imf, 123, 0, 1023));
        root.set("si4", ScaledIntegerNode(imf, 123, 0, 1023, .001));
        root.set("si5", ScaledIntegerNode(imf, 123, 0, 1023, .001, 100.0));

        printScaledIntegerInfo(imf, "/si1");
        printScaledIntegerInfo(imf, "/si2");
        printScaledIntegerInfo(imf, "/si3");
        printScaledIntegerInfo(imf, "/si4");
        printScaledIntegerInfo(imf, "/si5");

        imf.close(); // don't forget to explicitly close the ImageFile
    } catch(E57Exception& ex) {
        ex.report(__FILE__, __LINE__, __FUNCTION__);
        return(-1);
    }
    return(0);
}

```

--------------------------------

### ScaledIntegerNode::scaledMinimum

Retrieves the declared scaled minimum value for a ScaledIntegerNode. This method is used to get the lower bound of the acceptable range for the scaled value.

```APIDOC
## ScaledIntegerNode::scaledMinimum

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

### Method
GET (conceptual, as this is likely a getter method within a class)

### Endpoint
N/A (Class method)

### Parameters
None

### Request Example
N/A

### Response
#### Success Response (Return Value)
- **scaledMinimum** (double) - The declared minimum that the rawValue may take.

#### Response Example
```json
{
  "scaledMinimum": 0.0
}
```

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

### Postcondition
No visible state is modified.

### Exceptions
- E57_ERROR_IMAGEFILE_NOT_OPEN
- E57_ERROR_INTERNAL: All objects in undocumented state.

### See also
ScaledIntegerCreate.cpp example, ScaledIntegerNode::scaledMaximum, ScaledIntegerNode::scaledValue
```

--------------------------------

### Node::pathName

Retrieves the absolute pathname of a node within the E57 file structure. Pathnames are formed by a sequence of elementNames separated by '/', starting from the root.

```APIDOC
## Node::pathName

### Description
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.

### Method
GET (Assumed, as it retrieves information)

### Endpoint
Not explicitly defined, but conceptually related to a node object.

### Parameters
None explicitly defined for this method.

### Request Example
```json
{
  "method": "getNodePathName",
  "nodeId": "some_node_identifier"
}
```

### Response
#### Success Response (200)
- **pathname** (string) - The absolute path name of the node.

#### Response Example
```json
{
  "pathname": "/data3D/0/points/153/cartesianX"
}
```

### Exceptions
- **E57_ERROR_IMAGEFILE_NOT_OPEN** - The destination ImageFile must be open (i.e. destImageFile().isOpen()).
- **E57_ERROR_INTERNAL** - All objects in undocumented state.
```

--------------------------------

### StructureNode::pathName

Retrieves the absolute path name of a node within the E57 data structure. This path is a sequence of element names separated by '/' characters, starting from the root.

```APIDOC
## StructureNode::pathName

### Description
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.

### Method
const ustring

### Endpoint
N/A (This is a class method)

### Parameters
None

### Request Example
N/A (This is a method call, not an HTTP request)

### Response
#### Success Response
- **pathName** (ustring) - The absolute path name of the node.

#### Response Example
```json
{
  "pathName": "/data3D/0/points/153/cartesianX"
}
```

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

### Postcondition
No visible state is modified.

### Exceptions
- E57_ERROR_IMAGEFILE_NOT_OPEN
- E57_ERROR_INTERNAL
```

--------------------------------

### Example: Creating ScaledIntegerNodes

Shows how to create ScaledIntegerNodes, which represent integer values with an associated scale factor. This is useful for representing fixed-point numbers.

```cpp
// examples/ScaledIntegerCreate.cpp| Example: creating ScaledIntegerNodes
```

--------------------------------

### Node - Get Parent

Retrieves the parent node of the current node. This allows for traversal up the node hierarchy within the E57 file structure.

```APIDOC
## Node::parent

### Description
Get the parent node of the current node. This function is essential for navigating the hierarchical structure of nodes within an E57 file.

### Method
(Implicitly GET, as it retrieves information)

### Endpoint
N/A (This is a library function, not a web endpoint)

### Parameters
None

### Request Example
N/A (Library function call)

### Response
#### Success Response
- **Node** (Node) - A pointer or reference to the parent Node object. Returns null or equivalent if the node is a root node.

#### Response Example
(Conceptual representation of returning a Node object or null)
```

--------------------------------

### Read Compressed Vector and Image File Data in C++

This snippet demonstrates reading data from a compressed vector and an image file using the libe57 foundation API. It handles potential exceptions and ensures resources are closed properly. Dependencies include the E57Exception class and the ImageFile and CompressedVectorReader classes from the libe57 library. It takes a path name and a size 'N' as implicit inputs and outputs scaled values to the console.

```cpp
vector<SourceDestBuffer> dbufs2;
                dbufs2.push_back(SourceDestBuffer(imf, n.pathName(), scaledValue, N, true, true));

                CompressedVectorReader reader = cv.reader(dbufs2);
                if (reader.read() != N)
                    return(-1);
                for (unsigned j = 0; j < N; j++)
                    cout << "  scaledValue[" << j << "] = " << scaledValue[j] << endl;
                reader.close(); // don't forget to explicitly close the CompressedVectorReader
            } catch(E57Exception& /*ex*/) {
                cout << "**** Reading " << n.pathName() << " failed"
            }
        }

        imf.close(); // don't forget to explicitly close the ImageFile
    } catch(E57Exception& ex) {
        ex.report(__FILE__, __LINE__, __FUNCTION__);
        return(-1);
    }
    return(0);
```

--------------------------------

### Read Compressed Point Cloud Data using E57 Foundation API (C++)

Source: https://context7.com/context7/libe57_foundationapi_html/llms.txt

Illustrates reading compressed point cloud data from an E57 file in batches. It shows how to retrieve a compressed vector, set up destination buffers with correct strides for interleaved data, and process points read in chunks. Error handling and resource cleanup are also demonstrated.

```cpp
#include "E57Foundation.h"
#include <vector>
using namespace e57;

struct Point {
    double x, y, z;
    int64_t intensity;
};

try {
    ImageFile imf("pointcloud.e57", "r");
    StructureNode root = imf.root();

    // Get compressed vector
    CompressedVectorNode points(root.get("points"));
    int64_t totalPoints = points.childCount();
    std::cout << "File contains " << totalPoints << " points" << std::endl;

    // Allocate buffer for batch reading
    const size_t BATCH_SIZE = 1000;
    Point* pointBuffer = new Point[BATCH_SIZE];

    // Set up destination buffers with stride for interleaved data
    std::vector<SourceDestBuffer> destBuffers;
    destBuffers.push_back(SourceDestBuffer(imf, "cartesianX",
                          &pointBuffer[0].x, BATCH_SIZE, false, false, sizeof(Point)));
    destBuffers.push_back(SourceDestBuffer(imf, "cartesianY",
                          &pointBuffer[0].y, BATCH_SIZE, false, false, sizeof(Point)));
    destBuffers.push_back(SourceDestBuffer(imf, "cartesianZ",
                          &pointBuffer[0].z, BATCH_SIZE, false, false, sizeof(Point)));
    destBuffers.push_back(SourceDestBuffer(imf, "intensity",
                          &pointBuffer[0].intensity, BATCH_SIZE, false, false, sizeof(Point)));

    // Read in batches
    CompressedVectorReader reader = points.reader(destBuffers);
    uint64_t totalRead = 0;
    unsigned numRead = 0;

    while ((numRead = reader.read()) > 0) {
        std::cout << "Read batch of " << numRead << " points" << std::endl;

        // Process points
        for (unsigned i = 0; i < numRead; i++) {
            if (totalRead + i < 5) {  // Print first 5 points
                std::cout << "Point " << (totalRead + i) << ": "
                         << "(" << pointBuffer[i].x << ", "
                         << pointBuffer[i].y << ", "
                         << pointBuffer[i].z << ") "
                         << "intensity=" << pointBuffer[i].intensity << std::endl;
            }
        }
        totalRead += numRead;
    }

    reader.close();
    delete[] pointBuffer;
    imf.close();

    std::cout << "Total points read: " << totalRead << std::endl;

} catch(E57Exception& ex) {
    ex.report(__FILE__, __LINE__, __FUNCTION__);
    return -1;
}

```

--------------------------------

### Get Element Name (C++)

Fetches the element name of a Node object. This name uniquely identifies the node among its siblings within its parent node.

```C++
ustring elementName () const
```
Tokens:
Raw