api.h File Reference

IZgyReader, IZgyWriter, and other user visible classes. More...

#include <cstdint>
#include <vector>
#include <array>
#include <ostream>
#include <iostream>
#include <functional>
#include <memory>
#include <string>
#include "declspec.h"

Go to the source code of this file.

Classes
class	OpenZGY::SampleStatistics
	Statistics of all sample values on the file. More...
class	OpenZGY::SampleHistogram
	Histogram of all sample values on the file. More...
class	OpenZGY::ZgyWriterArgs
	Argument package for creating a ZGY file. More...
class	OpenZGY::IZgyMeta
	Base class of IZgyReader and IZgyWriter. More...
class	OpenZGY::IZgyTools
	Base class of IZgyReader and IZgyWriter. More...
class	OpenZGY::IZgyReader
	Main API for reading ZGY files. More...
class	OpenZGY::IZgyWriter
	Main API for creating ZGY files. More...
class	OpenZGY::IZgyUtils
	Operations other than read and write. More...
class	OpenZGY::ProgressWithDots
	Simple progress bar. More...

Namespaces
	OpenZGY
	The entire public API is in this namespace.
	OpenZGY::Errors
	Exceptions that can be thrown by OpenZGY.
	OpenZGY::Impl
	Implementation of the abstract interfaces in OpenZGY.
	OpenZGY::Formatters
	operator<< for readable output of enums etc.
	InternalZGY
	Implementation not visible to clients.

Functions
std::ostream &	OpenZGY::Formatters::operator<< (std::ostream &os, SampleDataType value)
	Output the string representation of the input enum type.
std::ostream &	OpenZGY::Formatters::operator<< (std::ostream &os, UnitDimension value)
	Output the string representation of the input enum type.
std::ostream &	OpenZGY::Formatters::operator<< (std::ostream &os, DecimationType value)
	Output the string representation of the input enum type.

Variables
	unknown = 1000
	int8 = 1001
	int16 = 1002
	float32 = 1003
	time = 2001
	length = 2002
	arcangle = 2003
	LowPass = 100
	Lowpass Z / decimate XY.
	WeightedAverage
	Weighted averaging (depends on global stats).
	Average
	Simple averaging.
	Median
	Somewhat more expensive averaging.
	Minimum
	Minimum value.
	Maximum
	Maximum value.
	MinMax
	Checkerboard of minimum and maximum values.
	Decimate
	Simple decimation, use first sample.
	DecimateSkipNaN
	Use first sample that is not NaN.
	DecimateRandom
	Random decimation using a fixed seed.
	AllZero
	Just fill the LOD brick with zeroes.
	WhiteNoise
	Fill with white noise, hope nobody notices.
	MostFrequent
	The value that occurs most frequently.
	MostFrequentNon0
	The non-zero value that occurs most frequently.
	AverageNon0
	Average value, but treat 0 as NaN.

Detailed Description

IZgyReader, IZgyWriter, and other user visible classes.

This file contains the public OpenZGY API.

The API is modeled roughly after the API exposed by the Python wrapper around the existing C++ ZGY-Public API. This is probably just as good a starting point than anything else. And it makes testing simpler for those tests that compare the old and new behavior.

OpenZGY::IZgyMeta

• Has a private reference to a impl.meta.ZgyInternalMeta instance.
• Contains a large number of properties exposing meta data, most of which will present information from the ZgyInternalMeta in a way that is simpler to use and doesn't depend on the file version.
• End users will access methods from this class. Most likely via the derived ZgyReader and ZgyWriter classes. The end users might not care that there is a separate base class.

OpenZGY::ZgyMetaAndTools extends IZgyMeta

• Add coordinate conversion routines to a ZgyMeta instance.

OpenZGY::ZgyReader extends ZgyMetaAndTools with read, readconst, close OpenZGY::ZgyWriter extends ZgyMetaAndTools with write, writeconst, finalize, close

• Has a private reference to a impl.meta.ZgyInternalBulk instance.
• Add bulk read and write functionality, forwarding the requests to the internal bulk instance.
• These classes with their own and inherited methods and properties comprise the public OpenZGY API.
• Currently the ZgyWriter does not expose the bulk read() function but it does allow accessing all the metadata. Allowing read() might be added later if it appears to be useful. In practice this just means to let ZgyWriter inherit ZgyReader.

Note that enums and exceptions are problematic when it comes to encapsulation. Enums might be:

• Only visible in the public api. Often end up being mapped to a corresponding internal enum. No problem, but the mapping can be a bit tedious to maintain.

• Only visible internally. Possibly representing integer values written to file. Which makes them an implementation detail, which must absolutely not be exposed publically.

• Defined by the public api but passed unchanged from the api layer to the implementation layer. So there will be an include in some impl/xxx.h file to a part of the public API. This is frowned upon.

• Defined by the internal api but may need to be used from applications, i.e. also visible in the public api. There will be an include of e.g. "impl/ugly.h" from one of the public header files and/or application code. This is strongly discouraged except for testing.

Exceptions have similar issues. It is possible to catch all exceptions raised in the impl layer and convert those to exceptions owned by the api layer. But re-throwing an exception makes debuggig harder.