ENH: Added documentation.

include/CleanP.hh

@@ -15,8 +15,8 @@ Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994
 =========================================================================*/
 // .NAME vlCleanPolyData - merge duplicate points and remove degenerate primitives
 // .SECTION Description
-// vlCleanPolyData is a filter that takes as input vlPolyData and 
-// generates vlPolyData as output. vlCleanPolyData merges duplicate 
+// vlCleanPolyData is a filter that takes as input polygonal data and 
+// generates polygonal as output. vlCleanPolyData merges duplicate 
 // points (within specified tolerance) and transforms degenerate 
 // topology into appropriate form (for example, triangle is converted
 // into line if two points of triangle are merged).
@@ -39,7 +39,7 @@ public:
 
   // Description:
   // Specify tolerance in terms of percentage of bounding box.
-  vlSetClampMacro(Tolerance,float,0.0,1.0); //% of bounding box
+  vlSetClampMacro(Tolerance,float,0.0,1.0);
   vlGetMacro(Tolerance,float);
 
   // Description:

include/ConnectF.hh

@@ -6,8 +6,6 @@
   Date:      $Date$
   Version:   $Revision$
 
-Description:
----------------------------------------------------------------------------
 This file is part of the Visualization Library. No part of this file
 or its contents may be copied, reproduced or altered in any way
 without the express written consent of the authors.
@@ -15,9 +13,14 @@ without the express written consent of the authors.
 Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994 
 
 =========================================================================*/
-//
-// Extracts geometry connected at common vertices.
-//
+// .NAME vlConnectivityFilter - extract geometry based on geometric connectivity
+// .SECTION Description
+// vlConnectivityFilter is a filter that extracts cells that share common 
+// points. The filter works in one of four ways: 1) extract the largest
+// connected region in the dataset, 2) extract specified region numbers,
+// 3) extract all regions sharing specified point ids, and 4) extract
+// all regions sharing specified cell ids.
+
 #ifndef __vlConnectivityFilter_h
 #define __vlConnectivityFilter_h
 
@@ -36,17 +39,6 @@ public:
   char *GetClassName() {return "vlConnectivityFilter";};
   void PrintSelf(ostream& os, vlIndent indent);
 
-  vlSetClampMacro(RecursionDepth,int,10,LARGE_INTEGER);
-  vlGetMacro(RecursionDepth,int);
-
-  vlSetMacro(ColorRegions,int);
-  vlGetMacro(ColorRegions,int);
-  vlBooleanMacro(ColorRegions,int);
-
-  void InitializeSeedList();
-  void AddSeed(int id);
-  void DeleteSeed(int id);
-
   void ExtractPointSeededRegions();
   void ExtractCellSeededRegions();
 
@@ -59,6 +51,22 @@ public:
 
   int GetNumberOfExtractedRegions();
 
+  void InitializeSeedList();
+  void AddSeed(int id);
+  void DeleteSeed(int id);
+
+  // Description:
+  // Extraction algorithm works recursively. In some systems the stack depth
+  // is limited. This methods specifies the maximum recursion depth.
+  vlSetClampMacro(RecursionDepth,int,10,LARGE_INTEGER);
+  vlGetMacro(RecursionDepth,int);
+
+  // Description:
+  // Turn on/off the coloring of connected regions.
+  vlSetMacro(ColorRegions,int);
+  vlGetMacro(ColorRegions,int);
+  vlBooleanMacro(ColorRegions,int);
+
 protected:
   // Usual data generation method
   void Execute();

include/FeatEdge.hh

@@ -6,8 +6,6 @@
   Date:      $Date$
   Version:   $Revision$
 
-Description:
----------------------------------------------------------------------------
 This file is part of the Visualization Library. No part of this file
 or its contents may be copied, reproduced or altered in any way
 without the express written consent of the authors.
@@ -15,11 +13,16 @@ without the express written consent of the authors.
 Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994 
 
 =========================================================================*/
-//
-// Generates edges that are either 1) boundary (used by one polygon)
-// 2) non-manifold (used by three or more polygons) 3) feature edges (edges 
-// who are used by two triangles and the dihedral angle > FeatureAngle).
-//
+// .NAME vlFeatureEdges - extract boundary, non-manifold, and/or sharp edges from polygonal data
+// .SECTION Description
+// vlFeatureEdges is a filter to extract special types edges of edges from
+// input polygonal data. These edges that are either 1) boundary (used by 
+// one polygon) or a line cell, 2) non-manifold (used by three or more 
+// polygons) 3) feature edges (edges used by two triangles and whose
+// dihedral angle > FeatureAngle). These edges may be extracted in any
+// combination. Edges may also be "colored" (i.e., scalar values assigned)
+// based on edge type.
+
 #ifndef __vlFeatureEdges_h
 #define __vlFeatureEdges_h
 
@@ -33,21 +36,31 @@ public:
   char *GetClassName() {return "vlFeatureEdges";};
   void PrintSelf(ostream& os, vlIndent indent);
 
-  vlSetClampMacro(FeatureAngle,float,0.0,180.0);
-  vlGetMacro(FeatureAngle,float);
-
+  // Description:
+  // Turn on/off the extraction of boundary edges.
   vlSetMacro(BoundaryEdges,int);
   vlGetMacro(BoundaryEdges,int);
   vlBooleanMacro(BoundaryEdges,int);
 
+  // Description:
+  // Turn on/off the extraction of feature edges.
   vlSetMacro(FeatureEdges,int);
   vlGetMacro(FeatureEdges,int);
   vlBooleanMacro(FeatureEdges,int);
 
+  // Description:
+  // Specify the feature angle for extracting feature edges.
+  vlSetClampMacro(FeatureAngle,float,0.0,180.0);
+  vlGetMacro(FeatureAngle,float);
+
+  // Description:
+  // Turn on/off the extraction of non-manifold edges.
   vlSetMacro(NonManifoldEdges,int);
   vlGetMacro(NonManifoldEdges,int);
   vlBooleanMacro(NonManifoldEdges,int);
 
+  // Description:
+  // Turn on/off the coloring of edges by type.
   vlSetMacro(Coloring,int);
   vlGetMacro(Coloring,int);
   vlBooleanMacro(Coloring,int);

include/PolyNrml.hh

@@ -6,8 +6,6 @@
   Date:      $Date$
   Version:   $Revision$
 
-Description:
----------------------------------------------------------------------------
 This file is part of the Visualization Library. No part of this file
 or its contents may be copied, reproduced or altered in any way
 without the express written consent of the authors.
@@ -15,9 +13,17 @@ without the express written consent of the authors.
 Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994 
 
 =========================================================================*/
-//
-// Generates normals for PolyData
-//
+// .NAME vlPolyNormals - compute normals for polygonal mes
+// .SECTION Description
+// vlPolyNormals is a filter that computes point normals for a polygonal 
+// mesh. The filter can reorder polygons to insure consistent orientation
+// across polygon neighbors. Sharp edges can be split and points duplicated
+// with separate normals to give crisp (rendered) surface definition. It is
+// also possible to globally flip the normal orientation.
+//     The algorithm works by determing normals for each polyon and then
+// averaging them at shared points. When sharp edges are present, the edges
+// are split and new points generated to prevent blurry edges.
+
 #ifndef __vlPolyNormals_h
 #define __vlPolyNormals_h
 
@@ -31,21 +37,34 @@ public:
   char *GetClassName() {return "vlPolyNormals";};
   void PrintSelf(ostream& os, vlIndent indent);
 
+  // Description:
+  // Specify the angle that defines a sharp edge. If the difference in
+  // angle across neighboring polygons is greater than this value, the
+  // shared edge is considered "sharp".
   vlSetClampMacro(FeatureAngle,float,0.0,180.0);
   vlGetMacro(FeatureAngle,float);
 
+  // Description:
+  // Turn on/off the splitting of sharp edges.
   vlSetMacro(Splitting,int);
   vlGetMacro(Splitting,int);
   vlBooleanMacro(Splitting,int);
 
+  // Description:
+  // Turn on/off the enforcement of consistent polygon ordering.
   vlSetMacro(Consistency,int);
   vlGetMacro(Consistency,int);
   vlBooleanMacro(Consistency,int);
 
+  // Description:
+  // Turn on/off the global flipping of normal orientation.
   vlSetMacro(FlipNormals,int);
   vlGetMacro(FlipNormals,int);
   vlBooleanMacro(FlipNormals,int);
 
+  // Description:
+  // Control the depth of recursion used in this algorithm. (Some systems
+  // have limited stack depth.)
   vlSetClampMacro(RecursionDepth,int,10,LARGE_INTEGER);
   vlGetMacro(RecursionDepth,int);
 

include/TriF.hh

@@ -6,8 +6,6 @@
   Date:      $Date$
   Version:   $Revision$
 
-Description:
----------------------------------------------------------------------------
 This file is part of the Visualization Library. No part of this file
 or its contents may be copied, reproduced or altered in any way
 without the express written consent of the authors.
@@ -34,10 +32,14 @@ public:
   char *GetClassName() {return "vlTriangleFilter";};
   void PrintSelf(ostream& os, vlIndent indent);
 
+  // Description:
+  // Turn on/off passing vertices through filter.
   vlBooleanMacro(PassVerts,int);
   vlSetMacro(PassVerts,int);
   vlGetMacro(PassVerts,int);
 
+  // Description:
+  // Turn on/off passing lines through filter.
   vlBooleanMacro(PassLines,int);
   vlSetMacro(PassLines,int);
   vlGetMacro(PassLines,int);

src/ConnectF.cc

@@ -6,8 +6,6 @@
   Date:      $Date$
   Version:   $Revision$
 
-Description:
----------------------------------------------------------------------------
 This file is part of the Visualization Library. No part of this file
 or its contents may be copied, reproduced or altered in any way
 without the express written consent of the authors.
@@ -17,6 +15,8 @@ Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994
 =========================================================================*/
 #include "ConnectF.hh"
 
+// Description:
+// Construct with default extraction mode to extract largest regions.
 vlConnectivityFilter::vlConnectivityFilter()
 {
   this->ExtractionMode = EXTRACT_LARGEST_REGIONS;
@@ -228,11 +228,15 @@ void vlConnectivityFilter::TraverseAndMark (int cellId)
   return;
 }
 
+// Description:
+// Obtain the number of connected regions.
 int vlConnectivityFilter::GetNumberOfExtractedRegions()
 {
   return this->RegionSizes.GetSize();
 }
 
+// Description:
+// Set the extraction mode to extract regions sharing specified point ids.
 void vlConnectivityFilter::ExtractPointSeededRegions()
 {
   if ( this->ExtractionMode != EXTRACT_POINT_SEEDED_REGIONS )
@@ -242,6 +246,8 @@ void vlConnectivityFilter::ExtractPointSeededRegions()
     }
 }
 
+// Description:
+// Set the extraction mode to extract regions sharing specified cell ids.
 void vlConnectivityFilter::ExtractCellSeededRegions()
 {
   if ( this->ExtractionMode != EXTRACT_CELL_SEEDED_REGIONS )
@@ -251,6 +257,9 @@ void vlConnectivityFilter::ExtractCellSeededRegions()
     }
 }
 
+// Description:
+// Set the extraction mode to extract regions of specified id. You may 
+// have to execute filter first to determine region ids.
 void vlConnectivityFilter::ExtractSpecifiedRegions()
 {
   if ( this->ExtractionMode != EXTRACT_SPECIFIED_REGIONS )
@@ -260,6 +269,8 @@ void vlConnectivityFilter::ExtractSpecifiedRegions()
     }
 }
 
+// Description:
+// Set the extraction mode to extract the largest region found.
 void vlConnectivityFilter::ExtractLargestRegions(int numRegions)
 {
   if ( this->ExtractionMode != EXTRACT_LARGEST_REGIONS 
@@ -271,36 +282,48 @@ void vlConnectivityFilter::ExtractLargestRegions(int numRegions)
     }
 }
 
+// Description:
+// Initialize list of point ids/cell ids used to seed regions.
 void vlConnectivityFilter::InitializeSeedList()
 {
   this->Modified();
   this->Seeds.Reset();
 }
 
+// Description:
+// Add a seed id (point or cell id).
 void vlConnectivityFilter::AddSeed(int id)
 {
   this->Modified();
   this->Seeds.InsertNextId(id);
 }
 
+// Description:
+// Delete a seed id (point or cell id).
 void vlConnectivityFilter::DeleteSeed(int id)
 {
   this->Modified();
   this->Seeds.DeleteId(id);
 }
 
+// Description:
+// Initialize list of region ids to extract.
 void vlConnectivityFilter::InitializeSpecifiedRegionList()
 {
   this->Modified();
   this->SpecifiedRegionIds.Reset();
 }
 
+// Description:
+// Add a region id to extract.
 void vlConnectivityFilter::AddSpecifiedRegion(int id)
 {
   this->Modified();
   this->SpecifiedRegionIds.InsertNextId(id);
 }
 
+// Description:
+// Delete a region id to extract.
 void vlConnectivityFilter::DeleteSpecifiedRegion(int id)
 {
   this->Modified();

src/FeatEdge.cc

@@ -6,8 +6,6 @@
   Date:      $Date$
   Version:   $Revision$
 
-Description:
----------------------------------------------------------------------------
 This file is part of the Visualization Library. No part of this file
 or its contents may be copied, reproduced or altered in any way
 without the express written consent of the authors.
@@ -21,6 +19,9 @@ Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994
 #include "Polygon.hh"
 #include "FNormals.hh"
 
+// Description:
+// Construct object with feature angle = 30; all types of edges extracted
+// and colored.
 vlFeatureEdges::vlFeatureEdges()
 {
   this->FeatureAngle = 30.0;

src/PolyNrml.cc

@@ -6,8 +6,6 @@
   Date:      $Date$
   Version:   $Revision$
 
-Description:
----------------------------------------------------------------------------
 This file is part of the Visualization Library. No part of this file
 or its contents may be copied, reproduced or altered in any way
 without the express written consent of the authors.
@@ -20,6 +18,9 @@ Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen 1993, 1994
 #include "vlMath.hh"
 #include "FNormals.hh"
 
+// Description:
+// Construct with feature angle=30, splitting and consistency turned on, 
+// and flipNormals turned off.
 vlPolyNormals::vlPolyNormals()
 {
   this->FeatureAngle = 30.0;
@@ -62,7 +63,6 @@ void vlPolyNormals::Execute()
   vlIdList cellIds(MAX_CELL_SIZE);
 
   vlDebugMacro(<<"Generating surface normals");
-
   this->Initialize();
 
   if ( (numPts=this->Input->GetNumberOfPoints()) < 1 || 

src/TriF.cc

@@ -6,8 +6,6 @@
   Date:      $Date$
   Version:   $Revision$
 
-Description:
----------------------------------------------------------------------------
 This file is part of the Visualization Library. No part of this file
 or its contents may be copied, reproduced or altered in any way
 without the express written consent of the authors.
@@ -33,7 +31,6 @@ void vlTriangleFilter::Execute()
   vlPointData *pd;
 
   vlDebugMacro(<<"Executing triangle filter");
-
   this->Initialize();
 
   newPolys = new vlCellArray();