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

Public Member Functions

Constructor/Destructor, basic operations
 ecm (double semi_major_axis, double semi_minor_axis)
 ecm ()
void reset (double semi_major_axis, double semi_minor_axis)
bool operator== (const ecm &e) const
bool operator!= (const ecm &e) const
bool is_valid () const
double semi_major_axis () const
double semi_minor_axis () const

Constants

enum  side {
  side_front = 0, side_right = 1, side_back = 2, side_left = 3,
  side_top = 4, side_bottom = 5
}
enum  direction { dir_up = 0, dir_right = 1, dir_down = 2, dir_left = 3 }
enum  corner { corner_tl = 0, corner_tr = 1, corner_bl = 2, corner_br = 3 }
static const double semi_major_axis_earth_wgs84
 Semi-major axis of Earth (WGS84)
static const double semi_minor_axis_earth_wgs84
 Semi-minor axis of Earth (WGS84)
static const double radius_moon_nasa
 Radius of Moon (NASA)
static const double semi_major_axis_mars_nasa
 Semi-major axis of Mars (NASA)
static const double semi_minor_axis_mars_nasa
 Semi-minor axis of Mars (NASA)

Coordinate conversions

void ecm_to_geocentric (double ecm_x, double ecm_y, double *geoc_lat, double *lon) const
void ecm_to_geodetic (double ecm_x, double ecm_y, double *geod_lat, double *lon) const
void ecm_to_cartesian (double ecm_x, double ecm_y, double *cart) const
void cartesian_to_geocentric (const double *cart, double *geoc_lat, double *lon) const
void geocentric_to_cartesian (double geoc_lat, double lon, double geoc_alt, double *cart) const
double geocentric_to_geodetic (double geoc_lat) const
double geodetic_to_geocentric (double geod_lat) const
void geodetic_to_cartesian (double geod_lat, double lon, double geod_alt, double *cart) const
void cartesian_to_geodetic (const double *cart, double *geod_lat, double *lon, double *geod_alt) const
static int ecm_to_sidenumber (double ecm_x, double ecm_y)
static void ecm_to_side (double ecm_x, double ecm_y, double *side_x, double *side_y, int *sidenumber=NULL)
static void side_to_ecm (int sidenumber, double side_x, double side_y, double *ecm_x, double *ecm_y)
static void geodetic_normal (double geod_lat, double lon, double *normal)

ECM quadtree quads

void quad_plane (int quad_side, int quad_level, int quad_x, int quad_y, const double *quad_tl_cart, const double *quad_tr_cart, const double *quad_bl_cart, const double *quad_br_cart, double *plane_normal, double *plane_distance) const
double max_quad_plane_distance_estimation (int quad_side, int quad_level, int quad_x, int quad_y, const double *quad_plane_normal, double quad_plane_distance) const
void quad_base_data (int quad_side, int quad_level, int quad_x, int quad_y, const double *quad_tl_cart, const double *quad_tr_cart, const double *quad_bl_cart, const double *quad_br_cart, const double *quad_plane_normal, double quad_plane_distance, int quad_size, int quad_overlap, float *offsets, float *normals, double *max_quad_plane_distance) const
static void quad_to_ecm (int quad_side, int quad_level, int quad_x, int quad_y, double qx, double qy, double *ecm_x, double *ecm_y)
static void quad_to_ecm (int quad_side, int quad_level, int quad_x, int quad_y, int corner, double *ecm_x, double *ecm_y)
static void symmetry_quad (int quad_side, int quad_level, int quad_x, int quad_y, int *sym_quad_side, int *sym_quad_level, int *sym_quad_x, int *sym_quad_y, bool *mirror_x, bool *mirror_y, float matrix[9])

Detailed Description

Ellipsoid Cube Map (ECM):

An Ellipsoid Cube Map (ECM) maps an ellipsoid to a cube.

The ellipsoid is defined by its semi-major axis (a) and semi-minor axis (b). The cube side length is 2a.

By convention, the cube is axis-aligned with the origin at its center. Its six sides are numbered as follows: side 0 is at x=+a (front), 1 is at y=+a (right), 2 is at x=-a (back), 3 is at y=-a (left), 4 is at z=+a (top), and 5 is at z=-a (bottom).

Also by convention, the four directions are numbered as follows: up = 0, right = 1, bottom = 2, left = 3.

Ellipsoid Cube Map coordinates (ecx,ecy) use the following coordinate system:

 ecy
  
 +3  +-------+
  |  |       |
 +2  |   4   |
  |  |       |
 +1  +-------+-------+-------+-------+
  |  |       |       |       |       |
  0  |   0   |   1   |   2   |   3   |
  |  |       |       |       |       |
 -1  +-------+-------+-------+-------+
  |  |       |
 -2  |   5   |
  |  |       |
 -3  +-------+

    -1---0---1---2---3---4---5---6---7  ecx

For sides 0-3, the following applies: the lower bound for ecx,ecy for each side is inclusive, the higher bound is exclusive. Thus, the cartesian point (-a,-a,0) belongs to area 0, and (+a,-a,0) belongs to area 1. For side 4, both lower bounds and upper bounds of ecx,ecy are exclusive (i.e. side 4 includes none of its edges). For side 5, both lower bounds and upper bounds of ecx,ecy are inclusive (i.e. side 5 includes all of its edges).

Inside each cube side, the Quadrilateralized Spherical Cube projection is used to map the unit sphere to the unit cube. This is an equal-area projection and therefore minimizes sampling problems (both in terms of sampling errors and in terms of data storage efficiency). This projection is described in this paper: E.M. O'Neill and R.E. Laubscher, "Extended Studies of a Quadrilateralized Spherical Cube Earth Data Base", Naval Environmental Prediction Research Facility Tech. Report NEPRF 3-76 (CSC), May 1976.

Ellipsoid Cube Map Quadtree:

A quadtree on an Ellipsoid Cube Map is a group of 6 quadtrees (i.e. it has 6 root nodes), one for each side of the cube, with proper neighboring relations as given by the cube edges. For example, the level 0 quad that represents the top side of the cuboid is a neighbor of the level 0 quads on the front, back, left, and right sides of the cuboid; similar for higher quadtree levels.

A quadtree node always either has zero children or four children. By convention, the four children of a quad are numbered as follows:

+---+---+
| 0 | 1 |
+---+---+
| 2 | 3 |
+---+---+

Member Enumeration Documentation

enum ecm::side

Cube sides

Enumerator:
side_front 

Cube side: front.

side_right 

Cube side: right.

side_back 

Cube side: back.

side_left 

Cube side: left.

side_top 

Cube side: top.

side_bottom 

Cube side: bottom.

Directions

Enumerator:
dir_up 

Direction: up.

dir_right 

Direction: right.

dir_down 

Direction: down.

dir_left 

Direction: left.

Quad corners

Enumerator:
corner_tl 

Corner: top left.

corner_tr 

Corner: top right.

corner_bl 

Corner: bottom left.

corner_br 

Corner: bottom right.

Constructor & Destructor Documentation

ecm::ecm ( double  semi_major_axis,
double  semi_minor_axis 
)
Parameters
semi_major_axisSemi-major axis of the ellipsoid.
semi_minor_axisSemi-minor axis of the ellipsoid.

Constructor.

ecm::ecm ( )

Constructor. This will create an invalid ECM! Only the constructor with two arguments creates valid ECMs.

Member Function Documentation

void ecm::reset ( double  semi_major_axis,
double  semi_minor_axis 
)
Parameters
semi_major_axisSemi-major axis of the ellipsoid.
semi_minor_axisSemi-minor axis of the ellipsoid.

Reset.

bool ecm::operator== ( const ecm e) const
inline

Return true if two ECMs are identical.

bool ecm::operator!= ( const ecm e) const
inline

Return true if two ECMs are not identical.

bool ecm::is_valid ( ) const
inline

Return true if this ECM is valid.

double ecm::semi_major_axis ( ) const
inline

Return the semi-major axis.

double ecm::semi_minor_axis ( ) const
inline

Return the semi-major axis.

static int ecm::ecm_to_sidenumber ( double  ecm_x,
double  ecm_y 
)
static
Parameters
ecm_xECM x coordinate.
ecm_yECM y coordinate.
Returns
The cube side.

Extract the cube side from ecm coordinates.

static void ecm::ecm_to_side ( double  ecm_x,
double  ecm_y,
double *  side_x,
double *  side_y,
int *  sidenumber = NULL 
)
static
Parameters
ecm_xECM x coordinate.
ecm_yECM y coordinate.
side_xPointer to the resulting side x coordinate.
side_yPointer to the resulting side y coordinate.
sidenumberPointer to the resulting side number (optional; may be zero).

Return the side-relative coordinates.

static void ecm::side_to_ecm ( int  sidenumber,
double  side_x,
double  side_y,
double *  ecm_x,
double *  ecm_y 
)
static
Parameters
sidenumberSide number.
side_xSide x coordinate.
side_ySide y coordinate.
ecm_xPointer to the resulting ECM x coordinate.
ecm_yPointer to the resulting ECM y coordinate.

Return ECM coordinates for side-relative coordinates.

void ecm::ecm_to_geocentric ( double  ecm_x,
double  ecm_y,
double *  geoc_lat,
double *  lon 
) const
Parameters
ecm_xECM x coordinate.
ecm_yECM y coordinate.
geoc_latPointer to the resulting geocentric latitude.
lonPointer to the resulting longitude.

Convert ECM coordinates to geocentric latitude and longitude.

void ecm::ecm_to_geodetic ( double  ecm_x,
double  ecm_y,
double *  geod_lat,
double *  lon 
) const
Parameters
ecm_xECM x coordinate.
ecm_yECM y coordinate.
geod_latPointer to the resulting geodetic latitude.
lonPointer to the resulting longitude.

Convert ECM coordinates to geodetic latitude and longitude.

void ecm::ecm_to_cartesian ( double  ecm_x,
double  ecm_y,
double *  cart 
) const
Parameters
ecm_xECM x coordinate.
ecm_yECM y coordinate.
cartPointer to the resulting cartesian coordinates (3 components).

Convert ECM coordinates to planetocentric cartesian coordinates.

void ecm::cartesian_to_geocentric ( const double *  cart,
double *  geoc_lat,
double *  lon 
) const
Parameters
cartCartesian coordinates (3 components).
geoc_latPointer to the resulting geocentric latitude.
lonPointer to the resulting longitude.

Convert planetocentric cartesian coordinates to geocentric latitude and longitude.

void ecm::geocentric_to_cartesian ( double  geoc_lat,
double  lon,
double  geoc_alt,
double *  cart 
) const
Parameters
geoc_latGeocentric latitude.
lonLongitude.
geoc_altGeocentric altitude.
cartPointer to the resulting cartesian coordinates (3 components).

Convert geocentric coordinates to planetocentric cartesian coordinates.

double ecm::geocentric_to_geodetic ( double  geoc_lat) const
Parameters
geoc_latGeocentric latitude.
Returns
Geodetic latitude.

Convert geocentric latitude to geodetic latitude. (Note that there is no difference between geocentric and geodetic longitude).

double ecm::geodetic_to_geocentric ( double  geod_lat) const
Parameters
geod_latGeodetic latitude.
Returns
Geocentric latitude.

Convert geodetic latitude to geocentric latitude. (Note that there is no difference between geocentric and geodetic longitude).

void ecm::geodetic_to_cartesian ( double  geod_lat,
double  lon,
double  geod_alt,
double *  cart 
) const
Parameters
geod_latGeodetic latitude.
lonLongitude.
geod_altGeodetic altitude.
cartPointer to the resulting cartesian coordinates (3 components).

Convert geodetic coordinates to planetocentric cartesian coordinates.

void ecm::cartesian_to_geodetic ( const double *  cart,
double *  geod_lat,
double *  lon,
double *  geod_alt 
) const
Parameters
cartCartesian coordinates (3 components).
geod_latPointer to the resulting geodetic latitude.
lonPointer to the resulting longitude.
geod_altPointer to the resulting geodetic altitude.

Convert planetocentric cartesian coordinates to geodetic coordinates.

static void ecm::geodetic_normal ( double  geod_lat,
double  lon,
double *  normal 
)
static
Parameters
geod_latGeodetic latitude.
lonLongitude.
normalPointer to the resulting normal (3 components).

Return the ellipsoid surface normal at the geodetic latitude and longitude. The returned normal has length 1.

static void ecm::quad_to_ecm ( int  quad_side,
int  quad_level,
int  quad_x,
int  quad_y,
double  qx,
double  qy,
double *  ecm_x,
double *  ecm_y 
)
static
Parameters
quad_sideQuadtree side.
quad_levelQuadtree level.
quad_xQuad x coordinate.
quad_yQuad y coordinate.
qxQuad-relative x position.
qyQuad-relative y position.
ecm_xPointer to the resulting ECM x coordinate.
ecm_yPointer to the resulting ECM y coordinate.

Compute the ECM coordinates of a point on a quad.

static void ecm::quad_to_ecm ( int  quad_side,
int  quad_level,
int  quad_x,
int  quad_y,
int  corner,
double *  ecm_x,
double *  ecm_y 
)
static
Parameters
quad_sideQuadtree side.
quad_levelQuadtree level.
quad_xQuad x coordinate.
quad_yQuad y coordinate.
cornerThe corner of the quad.
ecm_xPointer to the resulting ECM x coordinate.
ecm_yPointer to the resulting ECM y coordinate.

Compute the ECM coordinates of a corner of a quad.

void ecm::quad_plane ( int  quad_side,
int  quad_level,
int  quad_x,
int  quad_y,
const double *  quad_tl_cart,
const double *  quad_tr_cart,
const double *  quad_bl_cart,
const double *  quad_br_cart,
double *  plane_normal,
double *  plane_distance 
) const
Parameters
quad_sideQuadtree side.
quad_levelQuadtree level.
quad_xQuad x coordinate.
quad_yQuad y coordinate.
quad_tl_cartQuad corner top left: cartesian coordinates (3 components).
quad_tr_cartQuad corner top right: cartesian coordinates (3 components).
quad_bl_cartQuad corner bottom left: cartesian coordinates (3 components).
quad_br_cartQuad corner bottom right: cartesian coordinates (3 components).
plane_normalPointer to the normalized quad plane normal (3 components).
plane_distancePointer to the quad plane distance.

Returns the quad plane E for the given quad in Hesse normal form: E: plane_normal * x = plane_distance

double ecm::max_quad_plane_distance_estimation ( int  quad_side,
int  quad_level,
int  quad_x,
int  quad_y,
const double *  quad_plane_normal,
double  quad_plane_distance 
) const
Parameters
quad_sideQuadtree side.
quad_levelQuadtree level.
quad_xQuad x coordinate.
quad_yQuad y coordinate.
quad_plane_normalNormalized quad plane normal (3 components).
quad_plane_distanceQuad plane distance.

Estimate the maximum distance of the quad plane to the ellipsoid surface. This estimation might be bad, but can be computed quickly. The correct value is computed by quad_base_data().

static void ecm::symmetry_quad ( int  quad_side,
int  quad_level,
int  quad_x,
int  quad_y,
int *  sym_quad_side,
int *  sym_quad_level,
int *  sym_quad_x,
int *  sym_quad_y,
bool *  mirror_x,
bool *  mirror_y,
float  matrix[9] 
)
static
Parameters
quad_sideQuadtree side.
quad_levelQuadtree level.
quad_xQuad x coordinate.
quad_yQuad y coordinate.
sym_quad_sidePointer to the symmetry quadtree side.
sym_quad_levelPointer to the symmetry quadtree level.
sym_quad_xPointer to the symmetry quad x coordinate.
sym_quad_yPointer to the symmetry quad y coordinate.
mirror_xPointer to the mirror-horizontally flag, or NULL.
mirror_yPointer to the mirror-vertically flag, or NULL.
matrixThe transformation matrix, or NULL.

Quads in ECM quadtrees are symmetrical: the top and bottom sides of the cube are mirrors of each other, and the four remaining sides can be rotated into each other. Furthermore, the four quarters of each side can be mirrored into each other. This can be used to reduce the number of quads for which base data needs to be computed with quad_base_data().
This function returns a symmetry quad for an original quad, and tells you how to transform the base data computed by quad_base_data() for this symmetry quad so that it applies to the original quad: mirror the texture coordinates according to the mirror flags, and apply the column-major transformation matrix.

void ecm::quad_base_data ( int  quad_side,
int  quad_level,
int  quad_x,
int  quad_y,
const double *  quad_tl_cart,
const double *  quad_tr_cart,
const double *  quad_bl_cart,
const double *  quad_br_cart,
const double *  quad_plane_normal,
double  quad_plane_distance,
int  quad_size,
int  quad_overlap,
float *  offsets,
float *  normals,
double *  max_quad_plane_distance 
) const
Parameters
quad_sideQuadtree side.
quad_levelQuadtree level.
quad_xQuad x coordinate.
quad_yQuad y coordinate.
quad_tl_cartQuad corner top left: cartesian coordinates (3 components).
quad_tr_cartQuad corner top right: cartesian coordinates (3 components).
quad_bl_cartQuad corner bottom left: cartesian coordinates (3 components).
quad_br_cartQuad corner bottom right: cartesian coordinates (3 components).
quad_plane_normalNormalized quad plane normal (3 components).
quad_plane_distanceQuad plane distance.
quad_sizeThe quad size in samples.
quad_overlapThe quad overlap size in samples.
offsetsStorage space for (quad_size + 2*quad_overlap)^2 offset vectors (3 floats).
normalsStorage space for (quad_size + 2*quad_overlap)^2 normal vectors (2 floats, only x and y).
max_quad_plane_distancePointer to the maximum distance of the quad plane to the ellipsoid surface.

Compute base data for a quad.
It is recommended that this expensive function is only called for symmetry quads (see summetry_quad()). Offsets between positions interpolated from the quad corners and the real ellipsoid surface are stored in the offsets array. Ellipsoid surface normals are stored in the normals array (but only the x and y components; z can be computed from them since the normals have length 1).


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