contour Class Reference

Calculate contour lines from a two-dimensional data set. More...

#include <contour.h>


Detailed Description

Calculate contour lines from a two-dimensional data set.

Basic Usage

The contours are generated as a series of x- and y-coordinates, defining a line. If the contour is closed, then the first and the last set of coordinates will be equal.

The storage of the matrix to be specified in the function set_data() and this function is designed to follow the format:

\[ \begin{array}{cccc} & x_0 & x_1 & x_2 \\ y_0 & M_{00} & M_{01} & M_{02} \\ y_1 & M_{10} & M_{11} & M_{12} \\ y_2 & M_{20} & M_{21} & M_{22} \end{array} \]

thus the matrix should be M[i][j] where i is the y index and j is the row index. (See also the discussion in the User's guide in the section called Rows and columns vs. x and y.)

The data is copied by set_data(), so changing the data will not change the contours unless set_data() is called again. The functions set_levels() and calc() can be called several times for the same data without calling set_data() again.

Note that in order to simplify the algorithm for computing contour lines, the calc_contours() function will adjust the user-specified contour levels slightly in order to ensure that no contour line passes exactly through any data point on the grid. The contours are adjusted by multiplying the original contour level by 1 plus a small number ($ 10^{-8} $ by default), which is specified in lev_adjust.

Linear interpolation is used to decide whether or not a line segment and a contour cross. This choice is intentional, since (in addition to making the algorithm much simpler) it is the user (and not the class) which is likely best able to refine the data. In case a simple refinement scheme is desired, the method regrid_data() is provided which refines the data for any interpolation type.

Since linear interpolation is used, the contour calculation implicitly assumes that there is not more than one intersection of any contour level with any line segment. For contours which do not close inside the region of interest, the results will always end at either the minimum or maximum values of the x or y grid points (no extrapolation is ever done). Note also that the points defining the contour are not necessarily equally spaced, but two neighboring points will never be farther apart than the distance across opposite corners of one cell in the grid.

The Algorithm:

This works by viewing the data as defining a square two-dimensional grid. The function calc_contours() exhaustively enumerates every line segment in the grid which involves a level crossing and then organizes the points defined by the intersection of a line segment with a level curve into a full contour.

Idea for future:
Rewrite the code which adjusts the contour levels to ensure contours don't go through the data to adjust the internal copy of the data instead.
Idea for future:
It would be nice to have a function which creates a set of closed regions to fill which represent the data. However, this likely requires a completely new algorithm, because it's not easy to simply close the contours already generated by the calc_contours() function. There are, for example, several cases which are difficult to handle, such as filling a region in between several closed contours.

Definition at line 164 of file contour.h.


Public Member Functions

Basic usage
template<class vec_t , class mat_t >
int set_data (size_t sizex, size_t sizey, const vec_t &x_fun, const vec_t &y_fun, const mat_t &udata)
 Set the data.
template<class vec_t >
int set_levels (size_t nlevels, vec_t &ulevels)
 Set the contour levels.
int calc_contours (std::vector< contour_line > &clines, bool debug=false)
 Calculate the contours.
Regrid function
int regrid_data (size_t xfact, size_t yfact, base_interp_mgr< ovector_const_view > &bim1, base_interp_mgr< ovector_const_subvector > &bim2)
 Regrid the data.
Obtain internal data
int get_data (size_t &sizex, size_t &sizey, ovector *&x_fun, ovector *&y_fun, omatrix *&udata)
 Get the data.
int get_edges (std::vector< edge_crossings > &rt_edges, std::vector< edge_crossings > &bm_edges)
 Return the edges.
int print_edges (edge_crossings &right, edge_crossings &bottom)
 Print out the edges to cout.

Data Fields

int verbose
 Verbosity parameter.
double lev_adjust
 (default $ 10^{-8} $)

Protected Member Functions

int find_next_point_right (int j, int k, int &jnext, int &knext, int &dir_next, int nsw, edge_crossings &right, edge_crossings &bottom)
 Find next point starting from a point on a right edge.
int find_next_point_bottom (int j, int k, int &jnext, int &knext, int &dir_next, int nsw, edge_crossings &right, edge_crossings &bottom)
 Find next point starting from a point on a bottom edge.
int find_intersections (size_t ilev, double &level, edge_crossings &right, edge_crossings &bottom)
 Find all of the intersections of the edges with the contour level.
int right_edges (double level, o2scl::sm_interp *si, edge_crossings &right)
 Interpolate all right edge crossings.
int bottom_edges (double level, o2scl::sm_interp *si, edge_crossings &bottom)
 Interpolate all bottom edge crossings.
int process_line (int j, int k, int dir, ovector &x, ovector &y, bool first, edge_crossings &right, edge_crossings &bottom)
 Create a contour line from a starting edge.
int check_data ()
 Check to ensure the x- and y-arrays are monotonic.

Protected Attributes

std::vector< edge_crossingsred
 Right edge list.
std::vector< edge_crossingsbed
 Bottom edge list.
User-specified data
int nx
int ny
ovector xfun
ovector yfun
omatrix data
User-specified contour levels
int nlev
ovector levels
bool levels_set

Static Protected Attributes

Edge direction
static const int dright = 0
static const int dbottom = 1
Edge status
static const int empty = 0
static const int edge = 1
static const int contourp = 2
static const int endpoint = 3
Edge found or not found
static const int efound = 1
static const int enot_found = 0

Member Function Documentation

int calc_contours ( std::vector< contour_line > &  clines,
bool  debug = false 
)

Calculate the contours.

The function calc_contours() returns the total number of contours found. Since there may be more than one disconnected contours for the same contour level, or no contours for a given level, the total number of contours may be less than or greater than the number of levels given by set_levels().

If an error occurs, zero is returned.

int get_data ( size_t &  sizex,
size_t &  sizey,
ovector *&  x_fun,
ovector *&  y_fun,
omatrix *&  udata 
) [inline]

Get the data.

This is useful to see how the data has changed after a call to regrid_data().

Idea for future:
There is probably a better way than returning pointers to the internal data.

Definition at line 277 of file contour.h.

int regrid_data ( size_t  xfact,
size_t  yfact,
base_interp_mgr< ovector_const_view > &  bim1,
base_interp_mgr< ovector_const_subvector > &  bim2 
)

Regrid the data.

Use interpolation to refine the data set. This can be called before calc_contours() in order to make the contour levels smoother by providing a smaller grid size. If the original number of data points is $ (\mathrm{nx},\mathrm{ny}) $, then the new number of data points is

\[ (\mathrm{xfact}~(\mathrm{nx}-1)+1, \mathrm{yfact}~(\mathrm{ny}-1)+1) \]

The parameters xfact and yfact must both be larger than zero and they cannot both be 1.

int set_data ( size_t  sizex,
size_t  sizey,
const vec_t &  x_fun,
const vec_t &  y_fun,
const mat_t &  udata 
) [inline]

Set the data.

The types vec_t and mat_t can be any types which have operator[] and operator[][] for array and matrix indexing.

Note that this method copies all of the user-specified data to local storage so that changes in the data after calling this function will not be reflected in the contours that are generated.

Definition at line 187 of file contour.h.

int set_levels ( size_t  nlevels,
vec_t &  ulevels 
) [inline]

Set the contour levels.

This is separate from the function calc_contours() so that the user can compute the contours for different data sets using the same levels

Definition at line 218 of file contour.h.


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

Documentation generated with Doxygen and provided under the GNU Free Documentation License. See License Information for details.

Project hosting provided by SourceForge.net Logo, O2scl Sourceforge Project Page