An ASTM E57 3D format file object. More...

Detailed Description

An ASTM E57 3D format file object.

Class overview

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.

The open/close state

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.

Extensions

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.

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:

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

FreeCAD/src/3rdParty/libE57Format/src/E57Format.cpp