vtkCell.h 13.2 KB
Newer Older
Will Schroeder's avatar
Will Schroeder committed
1 2
/*=========================================================================

Ken Martin's avatar
Ken Martin committed
3
  Program:   Visualization Toolkit
Ken Martin's avatar
Ken Martin committed
4
  Module:    vtkCell.h
Will Schroeder's avatar
Will Schroeder committed
5 6 7 8
  Language:  C++
  Date:      $Date$
  Version:   $Revision$

Ken Martin's avatar
Ken Martin committed
9

Will Schroeder's avatar
Will Schroeder committed
10
Copyright (c) 1993-2001 Ken Martin, Will Schroeder, Bill Lorensen 
Will Schroeder's avatar
Will Schroeder committed
11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

 * Redistributions of source code must retain the above copyright notice,
   this list of conditions and the following disclaimer.

 * Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.

 * Neither name of Ken Martin, Will Schroeder, or Bill Lorensen nor the names
   of any contributors may be used to endorse or promote products derived
   from this software without specific prior written permission.

 * Modified source versions must be plainly marked as such, and must not be
   misrepresented as being the original software.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
Will Schroeder's avatar
Will Schroeder committed
33
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR
Will Schroeder's avatar
Will Schroeder committed
34 35 36 37 38 39
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Will Schroeder's avatar
Will Schroeder committed
40 41

=========================================================================*/
Ken Martin's avatar
Ken Martin committed
42
// .NAME vtkCell - abstract class to specify cell behavior
Will Schroeder's avatar
Will Schroeder committed
43
// .SECTION Description
Ken Martin's avatar
Ken Martin committed
44
// vtkCell is an abstract class that specifies the interfaces for data cells.
Will Schroeder's avatar
Will Schroeder committed
45
// Data cells are simple topological elements like points, lines, polygons, 
46
// and tetrahedra of which visualization datasets are composed. In some 
Will Schroeder's avatar
Will Schroeder committed
47
// cases visualization datasets may explicitly represent cells (e.g., 
Ken Martin's avatar
Ken Martin committed
48 49
// vtkPolyData, vtkUnstructuredGrid), and in some cases, the datasets are 
// implicitly composed of cells (e.g., vtkStructuredPoints).
Ken Martin's avatar
Ken Martin committed
50
//
51
// .SECTION Caveats
Will Schroeder's avatar
Will Schroeder committed
52 53 54
// The #define VTK_CELL_SIZE is a parameter used to construct cells and provide
// a general guideline for controlling object execution. This parameter is 
// not a hard boundary: you can create cells with more points.
Will Schroeder's avatar
Will Schroeder committed
55

56 57 58
// .SECTION See Also
// vtkHexahedron vtkLine vtkPixel vtkPolyLine vtkPolyVertex
// vtkPolygon vtkQuad vtkTetra vtkTriangle 
59
// vtkTriangleStrip vtkVertex vtkVoxel vtkWedge vtkPyramid
Ken Martin's avatar
Ken Martin committed
60

Ken Martin's avatar
Ken Martin committed
61 62
#ifndef __vtkCell_h
#define __vtkCell_h
Will Schroeder's avatar
Will Schroeder committed
63

Will Schroeder's avatar
Will Schroeder committed
64
#define VTK_CELL_SIZE 512
Will Schroeder's avatar
Will Schroeder committed
65
#define VTK_TOL 1.e-05 // Tolerance for geometric calculation
66

Ken Martin's avatar
Ken Martin committed
67
#include "vtkObject.h"
68 69
#include "vtkPoints.h"
#include "vtkScalars.h"
Ken Martin's avatar
Ken Martin committed
70
#include "vtkIdList.h"
71 72 73

// Include vtkCellType to include the defined cell types
#include "vtkCellType.h"
Will Schroeder's avatar
Will Schroeder committed
74

Ken Martin's avatar
Ken Martin committed
75
class vtkCellArray;
76
class vtkPointLocator;
Will Schroeder's avatar
Will Schroeder committed
77
class vtkPointData;
78
class vtkCellData;
Will Schroeder's avatar
Will Schroeder committed
79

Ken Martin's avatar
Ken Martin committed
80
class VTK_EXPORT vtkCell : public vtkObject
Will Schroeder's avatar
Will Schroeder committed
81 82
{
public:
83
  vtkTypeMacro(vtkCell,vtkObject);
84
  void PrintSelf(ostream& os, vtkIndent indent);
Will Schroeder's avatar
Will Schroeder committed
85

86 87 88 89 90
  // Description:
  // Initialize cell from outside with point ids and point
  // coordinates specified.
  void Initialize(int npts, int *pts, vtkPoints *p);

91
  // Description:
Ken Martin's avatar
Ken Martin committed
92 93
  // Create concrete copy of this cell. Initially, the copy is made by
  // performing a ShallowCopy() operation.
Ken Martin's avatar
Ken Martin committed
94
  virtual vtkCell *MakeObject() = 0;
Will Schroeder's avatar
Will Schroeder committed
95

96 97 98 99
  // Description:
  // Copy this cell by reference counting the internal data structures. 
  // This is safe if you want a "read-only" copy. If you modify the cell
  // you might wish to use DeepCopy().
100
  virtual void ShallowCopy(vtkCell *c);
101 102 103 104

  // Description:
  // Copy this cell by completely copying internal data structures. This is
  // slower but safer than ShallowCopy().
105
  virtual void DeepCopy(vtkCell *c);
106

Will Schroeder's avatar
Will Schroeder committed
107 108
  // Description:
  // Return the type of cell.
Will Schroeder's avatar
Will Schroeder committed
109
  virtual int GetCellType() = 0;
Will Schroeder's avatar
Will Schroeder committed
110

Will Schroeder's avatar
Will Schroeder committed
111 112
  // Description:
  // Return the topological dimensional of the cell (0,1,2, or 3).
Will Schroeder's avatar
Will Schroeder committed
113 114
  virtual int GetCellDimension() = 0;

115
  // Description:
Bill Lorensen's avatar
Bill Lorensen committed
116 117
  // Return the interpolation order of the cell. Usually linear.
  virtual int GetInterpolationOrder() {return 1;};
118

Will Schroeder's avatar
Will Schroeder committed
119 120
  // Description:
  // Get the point coordinates for the cell.
121
  vtkPoints *GetPoints() {return this->Points;};
Will Schroeder's avatar
Will Schroeder committed
122

Will Schroeder's avatar
Will Schroeder committed
123 124
  // Description:
  // Return the number of points in the cell.
125
  int GetNumberOfPoints() {return this->PointIds->GetNumberOfIds();};
Will Schroeder's avatar
Will Schroeder committed
126 127 128

  // Description:
  // Return the number of edges in the cell.
Will Schroeder's avatar
Will Schroeder committed
129
  virtual int GetNumberOfEdges() = 0;
Will Schroeder's avatar
Will Schroeder committed
130 131 132

  // Description:
  // Return the number of faces in the cell.
Will Schroeder's avatar
Will Schroeder committed
133 134
  virtual int GetNumberOfFaces() = 0;

Will Schroeder's avatar
Will Schroeder committed
135
  // Description:
136
  // Return the list of point ids defining the cell.
137
  vtkIdList *GetPointIds() {return this->PointIds;};
Will Schroeder's avatar
Will Schroeder committed
138 139 140

  // Description:
  // For cell point i, return the actual point id.
141
  int GetPointId(int ptId) {return this->PointIds->GetId(ptId);};
Will Schroeder's avatar
Will Schroeder committed
142 143 144

  // Description:
  // Return the edge cell from the edgeId of the cell.
Ken Martin's avatar
Ken Martin committed
145
  virtual vtkCell *GetEdge(int edgeId) = 0;
Will Schroeder's avatar
Will Schroeder committed
146 147 148

  // Description:
  // Return the face cell from the faceId of the cell.
Ken Martin's avatar
Ken Martin committed
149
  virtual vtkCell *GetFace(int faceId) = 0;
Will Schroeder's avatar
Will Schroeder committed
150

Will Schroeder's avatar
Will Schroeder committed
151 152 153 154 155 156
  // Description:
  // Given parametric coordinates of a point, return the closest cell boundary,
  // and whether the point is inside or outside of the cell. The cell boundary 
  // is defined by a list of points (pts) that specify a face (3D cell), edge 
  // (2D cell), or vertex (1D cell). If the return value of the method is != 0, 
  // then the point is inside the cell.
157
  virtual int CellBoundary(int subId, float pcoords[3], vtkIdList *pts) = 0;
Will Schroeder's avatar
Will Schroeder committed
158

Will Schroeder's avatar
Will Schroeder committed
159 160
  // Description:
  // Given a point x[3] return inside(=1) or outside(=0) cell; evaluate 
Will Schroeder's avatar
Will Schroeder committed
161
  // parametric coordinates, sub-cell id (!=0 only if cell is composite),
162
  // distance squared of point x[3] to cell (in particular, the sub-cell 
163 164 165
  // indicated), closest point on cell to x[3] (unless closestPoint is
  // null, in which case, the closest point and dist2 are not found), and 
  // interpolation weights 
Will Schroeder's avatar
Will Schroeder committed
166 167 168 169 170 171 172 173 174
  // in cell. (The number of weights is equal to the number of points
  // defining the cell). Note: on rare occasions a -1 is returned from the 
  // method. This means that numerical error has occurred and all data 
  // returned from this method should be ignored. Also, inside/outside 
  // is determine parametrically. That is, a point is inside if it 
  // satisfies parametric limits. This can cause problems for cells of 
  // topological dimension 2 or less, since a point in 3D can project 
  // onto the cell within parametric limits but be "far" from the cell. 
  // Thus the value dist2 may be checked to determine true in/out.
175
  virtual int EvaluatePosition(float x[3], float* closestPoint, 
Will Schroeder's avatar
Will Schroeder committed
176
                               int& subId, float pcoords[3], 
Will Schroeder's avatar
Will Schroeder committed
177
                               float& dist2, float *weights) = 0;
178

Will Schroeder's avatar
Will Schroeder committed
179
  // Description:
Will Schroeder's avatar
Will Schroeder committed
180 181
  // Determine global coordinate (x[3]) from subId and parametric coordinates.
  // Also returns interpolation weights. (The number of weights is equal to
182
  // the number of points in the cell.)
Will Schroeder's avatar
Will Schroeder committed
183
  virtual void EvaluateLocation(int& subId, float pcoords[3], 
Will Schroeder's avatar
Will Schroeder committed
184
                                float x[3], float *weights) = 0;
185

Will Schroeder's avatar
Will Schroeder committed
186
  // Description:
Will Schroeder's avatar
Will Schroeder committed
187 188 189 190 191 192
  // Generate contouring primitives. The scalar list cellScalars are
  // scalar values at each cell point. The point locator is essentially a 
  // points list that merges points as they are inserted (i.e., prevents 
  // duplicates). Contouring primitives can be vertices, lines, or
  // polygons. It is possible to interpolate point data along the edge
  // by providing input and output point data - if outPd is NULL, then
193 194 195 196 197
  // no interpolation is performed. Also, if the output cell data is
  // non-NULL, the cell data from the contoured cell is passed to the
  // generated contouring primitives. (Note: the CopyAllocate() method
  // must be invoked on both the output cell and point data. The 
  // cellId refers to the cell from which the cell data is copied.)
198
  virtual void Contour(float value, vtkScalars *cellScalars, 
199
                       vtkPointLocator *locator, vtkCellArray *verts, 
Ken Martin's avatar
Ken Martin committed
200
                       vtkCellArray *lines, vtkCellArray *polys, 
201 202
                       vtkPointData *inPd, vtkPointData *outPd,
                       vtkCellData *inCd, int cellId, vtkCellData *outCd) = 0;
203

204 205 206
  // Description:
  // Cut (or clip) the cell based on the input cellScalars and the
  // specified value. The output of the clip operation will be one or
Will Schroeder's avatar
Will Schroeder committed
207 208 209
  // more cells of the same topological dimension as the original cell. 
  // The flag insideOut controls what part of the cell is considered inside - 
  // normally cell points whose scalar value is greater than "value" are
210 211 212 213 214
  // considered inside. If insideOut is on, this is reversed. Also, if the 
  // output cell data is non-NULL, the cell data from the clipped cell is 
  // passed to the generated contouring primitives. (Note: the CopyAllocate() 
  // method must be invoked on both the output cell and point data. The
  // cellId refers to the cell from which the cell data is copied.)
215
  virtual void Clip(float value, vtkScalars *cellScalars, 
216
                    vtkPointLocator *locator, vtkCellArray *connectivity,
217 218 219
                    vtkPointData *inPd, vtkPointData *outPd,
                    vtkCellData *inCd, int cellId, vtkCellData *outCd, 
                    int insideOut) = 0;
220

221 222
  // Description:
  // Intersect with a ray. Return parametric coordinates (both line and cell)
223
  // and global intersection coordinates, given ray definition and tolerance. 
224 225 226 227
  // The method returns non-zero value if intersection occurs.
  virtual int IntersectWithLine(float p1[3], float p2[3], float tol, float& t,
                                float x[3], float pcoords[3], int& subId) = 0;

228 229 230 231 232 233 234
  // Description:
  // Generate simplices of proper dimension. If cell is 3D, tetrahedron are 
  // generated; if 2D triangles; if 1D lines; if 0D points. The form of the
  // output is a sequence of points, each n+1 points (where n is topological 
  // cell dimension) defining a simplex. The index is a parameter that controls
  // which triangulation to use (if more than one is possible). If numerical
  // degeneracy encountered, 0 is returned, otherwise 1 is returned.
235
  virtual int Triangulate(int index, vtkIdList *ptIds, vtkPoints *pts) = 0;
236 237

  // Description:
Ken Martin's avatar
Ken Martin committed
238 239 240 241 242 243 244 245 246 247 248 249
  // Compute derivatives given cell subId and parametric coordinates. The
  // values array is a series of data value(s) at the cell points. There is a
  // one-to-one correspondence between cell point and data value(s). Dim is
  // the number of data values per cell point. Derivs are derivatives in the
  // x-y-z coordinate directions for each data value. Thus, if computing
  // derivatives for a scalar function in a hexahedron, dim=1, 8 values are
  // supplied, and 3 deriv values are returned (i.e., derivatives in x-y-z
  // directions). On the other hand, if computing derivatives of velocity
  // (vx,vy,vz) dim=3, 24 values are supplied ((vx,vy,vz)1, (vx,vy,vz)2,
  // ....()8), and 9 deriv values are returned
  // ((d(vx)/dx),(d(vx)/dy),(d(vx)/dz), (d(vy)/dx),(d(vy)/dy), (d(vy)/dz),
  // (d(vz)/dx),(d(vz)/dy),(d(vz)/dz)).
250 251 252
  virtual void Derivatives(int subId, float pcoords[3], float *values, 
                           int dim, float *derivs) = 0;

253

Ken Martin's avatar
Ken Martin committed
254 255 256
  // Description:
  // Compute cell bounding box (xmin,xmax,ymin,ymax,zmin,zmax). Copy result
  // into user provided array.
Will Schroeder's avatar
Will Schroeder committed
257
  void GetBounds(float bounds[6]);
258 259


Ken Martin's avatar
Ken Martin committed
260 261 262
  // Description:
  // Compute cell bounding box (xmin,xmax,ymin,ymax,zmin,zmax). Return pointer
  // to array of six float values.
263
  float *GetBounds();
264 265


Ken Martin's avatar
Ken Martin committed
266 267
  // Description:
  // Compute Length squared of cell (i.e., bounding box diagonal squared).
Will Schroeder's avatar
Will Schroeder committed
268
  float GetLength2();
269 270


Ken Martin's avatar
Ken Martin committed
271 272 273 274 275
  // Description:
  // Return center of the cell in parametric coordinates.  Note that the
  // parametric center is not always located at (0.5,0.5,0.5). The return
  // value is the subId that the center is in (if a composite cell). If you
  // want the center in x-y-z space, invoke the EvaluateLocation() method.
276
  virtual int GetParametricCenter(float pcoords[3]);
Will Schroeder's avatar
Will Schroeder committed
277

278

Ken Martin's avatar
Ken Martin committed
279
  // Description:
Will Schroeder's avatar
Will Schroeder committed
280 281 282 283 284 285
  // Bounding box intersection modified from Graphics Gems Vol I. The method
  // returns a non-zero value if the bounding box is hit. Origin[3] starts
  // the ray, dir[3] is the vector components of the ray in the x-y-z
  // directions, coord[3] is the location of hit, and t is the parametric
  // coordinate along line. (Notes: the intersection ray dir[3] is NOT
  // normalized.  Valid intersections will only occur between 0<=t<=1.)
286 287
  static char HitBBox(float bounds[6], float origin[3], float dir[3], 
                      float coord[3], float& t);
Will Schroeder's avatar
Will Schroeder committed
288

Ken Martin's avatar
Ken Martin committed
289
  
Will Schroeder's avatar
Will Schroeder committed
290
  // left public for quick computational access
291 292
  vtkPoints *Points;
  vtkIdList *PointIds;
Will Schroeder's avatar
Will Schroeder committed
293

294
#ifndef VTK_REMOVE_LEGACY_CODE
295 296
  // Description:
  // For legacy compatibility. Do not use.
297 298 299 300 301 302
  void DeepCopy(vtkCell &c) 
    {VTK_LEGACY_METHOD(DeepCopy,"3.2"); this->DeepCopy(&c);}
  void ShallowCopy(vtkCell &c) 
    {VTK_LEGACY_METHOD(ShallowCopy,"3.2"); this->ShallowCopy(&c);}
#endif
  
303
protected:
304 305
  vtkCell();
  ~vtkCell();
306 307
  vtkCell(const vtkCell&) {};
  void operator=(const vtkCell&) {};
308

309 310
  float Bounds[6];

Will Schroeder's avatar
Will Schroeder committed
311 312 313 314 315
};

#endif