libecmdb  0.7.0
Ellipsoidal Cube Map (ECM) projection and hierarchical data base
Classes | List of all members
ecmdb Class Reference


class  metadata

Public Types

enum  category_t {
  category_invalid = 0, category_elevation = 1, category_texture = 2, category_sar_amplitude = 3,
  category_data = 4
enum  type_t { type_uint8 = 0, type_int16 = 1, type_float32 = 2 }

Static Public Attributes

static const int max_levels = 31
 Maximum number of quadtree levels; required to prevent overflow of quad coordinates.
static const int max_channels = 16
 Arbitrary limit, but keep it low to avoid overhead.
static const int max_quad_size = 2048
 Arbitrary limit, but keep it low to avoid overhead.
static const int max_overlap = 16
 Arbitrary limit, but keep it low to avoid overhead.

Meta data

 ecmdb ()
void save (std::ostream &os) const
void load (std::istream &is)
bool is_valid () const
bool is_compatible (const ecmdb &database)
class ecmecm () const
double semi_major_axis () const
double semi_minor_axis () const
category_t category () const
type_t type () const
size_t type_size () const
int channels () const
size_t element_size () const
int quad_size () const
int overlap () const
int total_quad_size () const
size_t data_size () const
size_t mask_size () const
float data_offset () const
float data_factor () const
const std::string & short_description () const
const std::vector< std::string > & description () const
int levels () const
bool has_quad (int side, int level, int x, int y) const
void open (const std::string &dirname, const std::string &original_url="")
void load_quad (const std::string &filename, void *data, uint8_t *mask, bool *all_valid, metadata *meta) const
void create (double semi_major_axis, double semi_minor_axis, int quad_size, int levels, category_t category, type_t type, int channels, int overlap, float data_offset, float data_factor, const std::string &short_description, const std::vector< std::string > &description)
void write (const std::string &dirname) const
void load_quad_meta (const std::string &filename, metadata *meta) const
void save_quad (const std::string &filename, const void *data, const uint8_t *mask, bool all_valid, const metadata *meta, int compression, int lossy_compression_quality=80) const
void add_quad (int side, int x, int y)
void close ()
static std::string quad_filename (int side, int level, int x, int y)

Detailed Description

Ellipsoid Cube Map (ECM) data bases

An ECM data base consists of a directory that is filled with data files, organized in subdirectories. This class helps to manage such a directory structure.

The data stored in an ECM data base has one of three types: elevation data, texture data (in the SRGB color space), or undefined data that is later converted to elevation or texture data by a rendering system. The data can have several channels (between 1 and ecmdb::max_channels), e.g. 3 for SRGB data. The data is stored using one of three data types: uint8, int16, or float32. Elevation data has one channel and data type int16 or float32, SRGB texture data has one or three channels and data type uint8.

The data is managed in six quadtree hierarchies (one for each side of the circumscribing cube). One quad provides a fixed number of samples (quad_size x quad_size). Additionally, quads may overlap. This is useful to avoid artefacts when the rendering system needs to access elevation or texture samples at the quad borders.

Each quad stores one data array, containing the data samples for all the channels, and one mask array that determines which of the data samples are valid. This allows to manage holes in data sets, which is common for remote sensing data.

For elevation data, a rendering system typically needs meta data for level of detail purposes. This meta data consists of the global minimum and maximum elevation, and of the minimum and maximum elevation per quad. The global meta data is read when opening a data base, the per-quad metadata is stored with each quad data file.

Each data set is only valid for a specific ellipsoid defined by its semi-major and semi-minor axes.

A rendering system can typically combine data bases that use the same ellipsoid and the same quad size. Such data bases are called compatible data bases.

Member Enumeration Documentation

Data category


Invalid data base.


Elevation data (one channel, type int16 or float32)


Texture data SRGB (three channels, type uint8)


SAR amplitude data (one channel, type float32 normalized to [0,1])


Unspecified data.

Data type


Data type uint8.


Data type int16.


Data type float32.

Constructor & Destructor Documentation

ecmdb::ecmdb ( )

Constructor for an invalid (empty) database

Member Function Documentation

void ecmdb::save ( std::ostream &  os) const

Serialization: save this object to a stream

void ecmdb::load ( std::istream &  is)

Serialization: load this object from a stream

bool ecmdb::is_valid ( ) const

Check if this database is valid (non-empty).

bool ecmdb::is_compatible ( const ecmdb database)

Check if this database is compatible with another database, i.e. data from both databases can be combined into a single view.

class ecm& ecmdb::ecm ( ) const

Return the ECM.

double ecmdb::semi_major_axis ( ) const

Return the semi-major axis of the ellipsoid.

double ecmdb::semi_minor_axis ( ) const

Return the semi-minor axis of the ellipsoid.

category_t ecmdb::category ( ) const

Return the category of data stored in this database.

type_t ecmdb::type ( ) const

Return the data type used by this database.

size_t ecmdb::type_size ( ) const

Return the size of the data type used by this database.

int ecmdb::channels ( ) const

Return the number of channels of the data, e.g. 3 for RGB texture data.

size_t ecmdb::element_size ( ) const

Return the size of one data element.

int ecmdb::quad_size ( ) const

Return the base quad size, without overlap, e.g. 512 for quads of size 512x512.

int ecmdb::overlap ( ) const

Return the overlap size. For example, a 512x512 quad with an overlap of 2 leads to 516x516 data samples.

int ecmdb::total_quad_size ( ) const

Return the total quad size, including overlap areas.

size_t ecmdb::data_size ( ) const

Return the size of one quad worth of data, including overlap.

size_t ecmdb::mask_size ( ) const

Return the size of the validity mask for one quad, including overlap.

float ecmdb::data_offset ( ) const

Return the data offset that needs to be applied when interpreting values from this database: real_value = factor * value + offset.

float ecmdb::data_factor ( ) const

Return the data factor that needs to be applied when interpreting values from this database: real_value = factor * value + offset.

const std::string& ecmdb::short_description ( ) const

Return the short description (one line) for this database.

const std::vector<std::string>& ecmdb::description ( ) const

Return the long description (a vector of lines) for this database.

int ecmdb::levels ( ) const

Return the number of quadtree levels available in this database.

bool ecmdb::has_quad ( int  side,
int  level,
int  x,
int  y 
) const
sideECM cube side.
levelCube side quadtree level.
xX coordinate of quad.
yY coordinate of quad.

Check if this database potentially contains a given quad.

If this returns false, then you know the database does not contain the quad. If this returns true, then the database contains the quad, but note that this does not necessarily mean that the corresponding quad file exists. Only quads with valid data are stored on disk. If the quad file does not exist, then the quad does not contain any valid data (for example if the data set has a hole).

void ecmdb::open ( const std::string &  dirname,
const std::string &  original_url = "" 
dirnameDatabase directory.
original_urlOriginal URL.

Open a database. The original URL is useful for error messages if this database actually lives somewhere on the network and the directory only refers to a locally cached copy.

static std::string ecmdb::quad_filename ( int  side,
int  level,
int  x,
int  y 

Return the name of the quad file that stores data and mask for the given quad. Note that this quad file only exists if the quad contains valid data. The quad file name is relative to the database directory: abs_quadfilename = dbdir + '/' + quad_filename();

void ecmdb::load_quad ( const std::string &  filename,
void *  data,
uint8_t *  mask,
bool *  all_valid,
metadata meta 
) const

Load quad data and validity mask from a quad file. If the all_valid flag is set afterwards, then all data samples are valid, and the mask buffer was not touched. Otherwise, the mask buffer stores the value 255 for all valid data samples and 0 for all invalid data samples.

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