Subsections

4.1 OESurface

class OESurface : public OESystem::OEBase

This class represents a surface as a first class object. It derives from OESystem::OEBase and has all the properties thereof. See Chapter 2 for more information on the concepts that this class embodies. The OESurface contains the properties in the following table:

Property	Get Methods	Set Methods
Vertex	`GetVertices`	`SetVertices`
	`GetVerticesElement`	`SetVerticesElement`
Triangle	`GetTriangles`	`GetTriangles`
	`GetTrianglesElement`	`GetTrianglesElement`
Face	`GetFaceNormals`	`SetFaceNormals`
Normal	`GetFaceNormalsElement`	`SetFaceNormalsElement`
Vertex	`GetNormals`	`SetNormals`
Normal	`GetNormalsElement`	`SetNormalsElement`
Curvature	`GetCurvature`	`SetCurvature`
	`GetCurvatureElement`	`SetCurvatureElement`
Distance	`GetDistances`	`SetDistances`
	`GetDistancesElement`	`SetDistancesElement`
Atom	`GetAtoms`	`SetAtoms`
Index	`GetAtomsElement`	`SetAtomsElement`
Color	`GetColor`	`SetColor`
	`GetColorElement`	`SetColorElement`
Potential	`GetPotential`	`SetPotential`
	`GetPotentialElement`	`SetPotentialElement`
Vertex Clique	`GetVertexClique`	`SetVertexClique`
	`GetVertexCliqueElement`	`SetVertexCliqueElement`

OESurface objects provide two types of access methods: entire array copy and individual array element access. The methods with the Element suffix will get or set one element at a time and require that an index, unsigned int n, be specified.

Each array has a specific size based upon the number of vertices and triangles of the surface. Some properties are also multidimensional and require more space. The following is a table with the appropriate type and size for each property:

Property	Type	Size
Vertex	`float`	`GetNumVertices()*3`

Triangle	`unsigned int`	`GetNumTriangles()*3`

Face	`float`	`GetNumTriangles()*3`
Normal
Vertex	`float`	`GetNumVertices()*3`
Normal
Curvature	`float`	`GetNumVertices()`

Distance	`float`	`GetNumVertices()`

Atom	`unsigned int`	`GetNumVertices()`
Index
Color	`float` or	`GetNumVertices() * 4`
	`unsigned char`
Potential	`float`	`GetNumVertices()`

Vertex Clique	`unsigned int`	`GetNumVertices()`

4.1.1 Constructors

OESurface()
OESurface(const OESurface &rhs)

Default and copy constructors.

4.1.2 operator bool

operator bool() const

Whether the surface contains any data (vertices).

4.1.3 operator+=

OESurface &operator+=(const OESurface &rhs)

In-place addition of one surface to another. The title's are concatenated together with an underscore. The vertex indices in the triangles array of rhs are increased by GetNumVertices(). All other data is copied from rhs as well. In the case where one of the surfaces does not have data and the other does, the data array for the surface that does not will be zero'd out.

4.1.4 operator=

OESurface &operator=(const OESurface &rhs)

Assignment operator for a surface. Will copy all data from rhs to the surface.

4.1.5 Clear

void Clear()

Delete and deallocate all data associated with this surface. This includes all OEBase data as well.

4.1.6 ClearVertexClique

bool ClearVertexClique()

Sets every vertex clique value to zero. Afterwards, IsVertexCliqueSet() will return false. This will prevent vertex clique values from being output by OEWriteSurface.

4.1.7 CreateCopy

virtual OESystem::OEBase *CreateCopy() const

4.1.8 GetAtoms

bool GetAtoms(unsigned int *atoms) const

Fills the memory pointed to by atoms with the atom index associated with every vertex of the surface. The array passed in should be of at least size

GetNumVertices() *
sizeof(unsigned int)

. See Section 2.1.5 for more information on the atoms associated with the surface.

4.1.9 GetAtomsElement

unsigned int GetAtomsElement(unsigned int n) const

Retrieves an element from the internal atoms array. The index n should be less than GetNumVertices(). See Section 2.1.5 for more information on the atoms associated with the surface.

4.1.10 GetColor

bool GetColor(float *color) const
bool GetColor(unsigned char *color) const

Fills the memory pointed to by color with the color associated with every vertex of the surface. The array passed in should be of at least size GetNumVertices() * 4 * sizeof(float) or GetNumVertices() * 4 * sizeof(unsigned char), depending on which overload is used. See Section 2.1.5 for more information on colors.

4.1.11 GetColorElement

void GetColorElement(unsigned int n, float &r, float &g, float &b, float &a) const
void GetColorElement(unsigned int n, unsigned char &r, unsigned char &g,
                     unsigned char &b, unsigned char &a) const

Retrieves an element from the internal color array. The index n should be less than GetNumVertices(). See Section 2.1.5 for more information on colors.

4.1.12 GetCurvature

bool GetCurvature(float *curvature) const

Fills the memory pointed to by curvature with the curvature associated with every vertex of the surface. The array passed in should be of at least size

GetNumVertices() *
sizeof(float)

. See Section 2.1.4 for more information on curvature.

4.1.13 GetCurvatureElement

float GetCurvatureElement(unsigned int n) const

Retrieves an element from the internal curvature array. The index n should be less than GetNumVertices(). See Section 2.1.4 for more information on curvature.

4.1.14 GetDataType

virtual const void *GetDataType() const

4.1.15 GetDistance

bool GetDistance(float *distance) const

Fills the memory pointed to by distance with the distance each vertex is from another object. The array passed in should be of at least size

GetNumVertices() *
sizeof(float)

. See Section 2.1.4 for more information on vertex distances.

4.1.16 GetDistanceElement

float GetDistanceElement(unsigned int n) const

Retrieves an element from the internal distance array. The index n should be less than GetNumVertices(). See Section 2.1.4 for more information on vertex distances.

4.1.17 GetFaceNormals

bool GetFaceNormals(float *faceNormals) const

Fills the memory pointed to by faceNormals with a normal vector associated with every triangle of the surface. The array passed in should be of at least size

GetNumTriangles() * 3 *
sizeof(float)

. See Section 2.1.3 for more information on normal vectors.

4.1.18 GetFaceNormalsElement

float GetFaceNormalsElement(unsigned int n) const

Retrieves an element from the internal face normals array. The index n should be less than GetNumTriangles() * 3. Note that each individual vector is composed of three floats: a float for every component of the vector. The user will normally need to call this function three times incrementing n by one each time to obtain the full 3-dimensional vector. See Section 2.1.3 for more information on normal vectors.

4.1.19 GetNormals

bool GetNormals(float *normals) const

Fills the memory pointed to by normals with a normal vector associated with every vertex of the surface. The array passed in should be of at least size

GetNumVertices() * 3 *
sizeof(float)

. A vertex normal is calculated by averaging the face normals of all the triangles in which the vertex resides. See Section 2.1.3 for more information on normal vectors.

4.1.20 GetNormalsElement

float GetNormalsElement(unsigned int n) const

Retrieves an element from the internal vertex normals array. The index n should be less than

GetNumVertices() *
3

. Note that each individual vector is composed of three floats: a float for every component of the vector. The user will normally need to call this function three times incrementing n by one each time to obtain the full 3-dimensional vector. See Section 2.1.3 for more information on normal vectors.

4.1.21 GetNumTriangles

unsigned int GetNumTriangles() const

Returns the number of triangles in the surface.

4.1.22 GetNumVertices

unsigned int GetNumVertices() const

Returns the number of vertices in the surface.

4.1.23 GetPotential

bool GetPotential(float *potential) const

Fills the memory pointed to by potential with the potential associated with every vertex of the surface. The array passed in should be of at least size

GetNumVertices() *
sizeof(float)

4.1.24 GetPotentialElement

float GetPotentialElement(unsigned int n) const

Retrieves an element from the internal potentials array. The index n should be less than GetNumVertices().

4.1.25 GetPotentialName

const char *GetPotentialName() const

Returns name of the potentials stored in the surface's potential array.

4.1.26 GetResolution

float GetResolution() const

Returns the grid spacing used in the surface construction.

4.1.27 GetTitle

const char *GetTitle() const

Returns the title of the surface.

4.1.28 GetTriangles

bool GetTriangles(unsigned int *triangles) const

Fills the memory pointed to by triangles with the vertex indices that compose every triangle in the surface. The vertex indices will obey the clockwise ordering rule described in Section 2.1.2. The array passed in should be of at least size GetNumTriangles() * 3 * sizeof(unsigned int).

4.1.29 GetTrianglesElement

unsigned int GetTrianglesElement(unsigned int n) const

Retrieves an element from the internal triangles array. The index n should be less than GetNumTriangles() * 3. Note that each individual triangle is composed of three integers. The user will normally need to call this function three times incrementing n by one each time to obtain all three vertices of the triangle. See Section 2.1.2 for more information on triangles.

4.1.30 GetVertexClique

bool GetVertexClique(unsigned int *vertexClique) const

Fills the memory pointed to by vertexClique with the clique values associated with every vertex of the surface. The array passed in should be of at least size

GetNumVertices() * sizeof(unsigned
int)

. See Section 2.3.1 for more information on cliques.

4.1.31 GetVertexCliqueElement

unsigned int GetVertexCliqueElement(unsigned int n) const

Retrieves an element from the internal cliques array. The index n should be less than GetNumVertices(). See Section 2.3.1 for more information on cliques.

4.1.32 GetVertices

bool GetVertices(float *vertices) const

Fills the memory pointed to by vertices with the vertex coordinates of the surface. Vertices are aligned every three places in the array as described in Section 2.1.1. The array passed in should be of at least size

GetNumVertices() * 3 *
sizeof(float)

4.1.33 GetVerticesElement

float GetVerticesElement(unsigned int n) const

Retrieves an element from the internal vertex array. The index n should be less than GetNumVertices() * 3. Note that each individual vertex is composed of three floats. The user will normally need to call this function three times, incrementing n by one each time, to obtain all three dimensions of the vertex. See Section 2.1.1 for more information on vertices.

4.1.34 IsAtomsSet

bool IsAtomsSet() const

Determine whether the surface has atom indices associated with each vertex. Surfaces generated from OEMakeAccessibleSurface and OEMakeAccessibleSurface automatically set this data.

4.1.35 IsColorSet

bool IsColorSet() const

Determine whether the surface has color values associated with each vertex.

4.1.36 IsCurvatureSet

bool IsCurvatureSet() const

Determine whether the surface has curvature value calculated for each vertex.

4.1.37 IsDataType

virtual bool IsDataType(const void *type) const

4.1.38 IsDistanceSet

bool IsDistanceSet() const

Determine whether the surface has a distance value associated with each vertex.

4.1.39 IsFaceNormalsSet

bool IsFaceNormalsSet() const

Determine whether the surface has face normals calculated for each triangle.

4.1.40 IsNormalsSet

bool IsNormalsSet() const

Determine whether the surface has vertex normals calculated for each vertex. Surfaces generated from OEMakeAccessibleSurface and OEMakeAccessibleSurface automatically set this data.

4.1.41 IsPotentialSet

bool IsPotentialSet() const

Determine whether the surface has a potential value associated with each vertex.

4.1.42 IsVertexCliqueSet

bool IsVertexCliqueSet() const

Determine whether the surface has a clique value associated with each vertex.

4.1.43 SetAtoms

bool SetAtoms(const unsigned int *atoms)

Sets the internal atoms array data to the values pointed to by atoms. This should be a pointer to an array of

unsigned
int

s of length GetNumVertices() * sizeof(unsigned int). See Section 2.1.5 for more information on associative data. Returns true upon success.

4.1.44 SetAtomsElement

bool SetAtomsElement(unsigned int n, unsigned int value)

Sets an element in the internal atoms array. The index n should be less than GetNumVertices(). See Section 2.1.5 for more information on associative data. Returns true upon success.

4.1.45 SetColor

bool SetColor(const float *color)
bool SetColor(const unsigned char *color)

Sets the internal color array data to the values pointed to by color. This should be a pointer to an array of floats or unsigned chars of length

GetNumVertices() * 4 *
sizeof(float)

or GetNumVertices() * 4 * sizeof(unsigned char) respectively. See Section 2.1.5 for more information on associative data. Returns true upon success.

4.1.46 SetColorElement

bool SetColorElement(unsigned int n, float r, float g, float b, float a=1.0f)
bool SetColorElement(unsigned int n, unsigned char r, unsigned char g,
                     unsigned char b, unsigned char a=255)

Sets an element in the internal color array. The index n should be less than GetNumVertices(). The alpha value, a, defaults to be opaque. See Section 2.1.5 for more information on associative data. Returns true upon success.

4.1.47 SetCurvature

bool SetCurvature(const float *curvature)

Sets the internal curvature array data to the values pointed to by curvature. This should be a pointer to an array of floats of length GetNumVertices() * sizeof(float). See Section 2.1.4 for more information on surface curvature. Returns true upon success.

4.1.48 SetCurvatureElement

bool SetCurvatureElement(unsigned int n, float value)

Sets an element in the internal curvature array. The index n should be less than GetNumVertices(). See Section 2.1.4 for more information on surface curvature. Returns true upon success.

4.1.49 SetDistance

bool SetDistance(const float *distance)

Sets the internal distance array data to the values pointed to by distance. This should be a pointer to an array of floats of length GetNumVertices() * sizeof(float). See Section 2.1.4 for more information on surface distances. Returns true upon success.

4.1.50 SetDistanceElement

bool SetDistanceElement(unsigned int n, float value)

Sets an element in the internal distance array. The index n should be less than GetNumVertices(). See Section 2.1.4 for more information on surface distances. Returns true upon success.

4.1.51 SetFaceNormals

bool SetFaceNormals(const float *faceNormals)

Sets the internal face normals array data to the values pointed to by faceNormals. This should be a pointer to an array of floats of length

GetNumTriangles() * 3 *
sizeof(float)

. Face normals are associated with triangles by their location in the array. See Section 2.1.3 for more information on surface normals. Returns true upon success.

4.1.52 SetFaceNormalsElement

bool SetFaceNormalsElement(unsigned int n, float value)

Sets an element in the internal face normals array. The index n should be less than GetNumTriangles()*3. Note that each individual vector is composed of three floats: a float for every component of the vector. The user will normally need to call this function three times incrementing n by one each time to obtain the full 3-dimensional vector. See Section 2.1.3 for more information on surface normals. Returns true upon success.

4.1.53 SetNormals

bool SetNormals(const float *normals)

Sets the internal vertex normals array data to the values pointed to by normals. This should be a pointer to an array of floats of length

GetNumVertices() * 3 *
sizeof(float)

. Vertex normals are associated with vertices by their location in the array. See Section 2.1.3 for more information on surface normals. Returns true upon success.

4.1.54 SetNormalsElement

bool SetNormalsElement(unsigned int n, float value)

Sets an element in the internal vertex normals array. The index n should be less than GetNumVertices()*3. Note that each individual vector is composed of three floats: a float for every component of the vector. The user will normally need to call this function three times, incrementing n by one each time, to obtain the full 3-dimensional vector. See Section 2.1.3 for more information on surface normals. Returns true upon success.

4.1.55 SetNumTriangles

bool SetNumTriangles(unsigned int n)

WARNING: Expert use only.

Set the number of triangles in this surface. Setting this to a value lower than GetNumTriangles() effectively erases triangles from the surface. The memory for the OESurface is not freed immediately, but cached for reuse. The Clear method should be used if deallocation is desired. This is handled automatically by the class destructor ÕESurface.

If the user wants to add more triangles to the surface, SetNumTriangles should be called first to resize the internal triangles array. Note that the *Element methods should not be used after a call to SetNumTriangles. Any data reliant on the number of triangles should first be set using the array based methods. This includes SetTriangles and SetFaceNormals.

4.1.56 SetNumVertices

bool SetNumVertices(unsigned int n)

WARNING: Expert use only.

Set the number of vertices in this surface. Setting this to a value lower than GetNumVertices() effectively erases vertices from the surface. The memory for the OESurface is not freed immediately, but cached for reuse. The Clear method should be used if deallocation is desired. This is handled automatically by the class destructor ÕESurface.

If the user wants to add more vertices to the surface, SetNumVerices should be called first to resize the internal vertices array. Note that the *Element methods should not be used after a call to SetNumVertices. Any data reliant on the number of vertices should first be set using the array based methods. These include the following: SetVertices, SetNormals, SetCurvature, SetDistance, SetAtoms, SetColor, SetPotential, and SetVertexClique.

4.1.57 SetPotential

bool SetPotential(const float *potential)

Sets the internal potential array data to the values pointed to by potential. This should be a pointer to an array of floats of length

GetNumVertices() *
sizeof(float)

. Returns true upon success.

4.1.58 SetPotentialElement

bool SetPotentialElement(unsigned int n, float value)

Sets an element in the internal potential array. The index n should be less than GetNumVertices(). Returns true upon success.

4.1.59 SetPotentialName

void SetPotentialName(const char *name)

Set the name of the potentials stored in the surface's potentials array.

4.1.60 SetTitle

bool SetTitle(const char *title)
bool SetTitle(const std::string &title)

Set the title of the surface.

4.1.61 SetTriangles

bool SetTriangles(const unsigned int *triangles)

Sets the internal triangles array data to the values pointed to by triangles. This should be a pointer to an array of unsigned ints of length

GetNumTriangles() * 3 *
sizeof(unsigned int)

. See Section 2.1.2 for more information on triangles. Returns true upon success.

4.1.62 SetTrianglesElement

bool SetTrianglesElement(unsigned int n, unsigned int value)

Sets an element in the internal triangles array. The index n should be less than GetNumTriangles()*3. See Section 2.1.2 for more information on triangles. Returns true upon success.

4.1.63 SetVertexClique

bool SetVertexClique(const unsigned int *vertexClique)

Sets the internal vertex clique array data to the values pointed to by vertexClique. This should be a pointer to an array of unsigned ints of length

GetNumVertices() *
sizeof(unsigned int)

. See Section 2.3.1 for more information on cliques. Returns true upon success.

4.1.64 SetVertexCliqueElement

bool SetVertexCliqueElement(unsigned int n, unsigned int value)

Sets an element in the internal vertex clique array. The index n should be less than GetNumVertices(). See Section 2.3.1 for more information on cliques. Returns true upon success.

4.1.65 SetVertices

bool SetVertices(const float *vertices)

Sets the internal vertices array data to the values pointed to by vertices. This should be a pointer to an array of floats of length GetNumVertices() * 3 * sizeof(float). See Section 2.1.1 for more information on vertices. Returns true upon success.

4.1.66 SetVerticesElement

bool SetVerticesElement(unsigned int n, float value)

Sets an element in the internal vertices array. The index n should be less than GetNumVertices()*3. See Section 2.1.1 for more information on vertices. Returns true upon success.

				OESpicoli Toolkit: Generation, Manipulation, and Comparison of Surfaces