Examples/DataRepresentation/Mesh/PointSet1.cxx

/*=========================================================================
 *
 *  Copyright NumFOCUS
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *         https://www.apache.org/licenses/LICENSE-2.0.txt
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *
 *=========================================================================*/
 
//  Software Guide : BeginLatex
//
//  The \doxygen{PointSet} is a basic class intended to represent geometry
//  in the form of a set of points in $N$-dimensional space. It is the base
//  class for the \doxygen{Mesh} providing the methods necessary to
//  manipulate sets of points. Points can have values associated with
//  them. The type of such values is defined by a template parameter of the
//  \code{itk::PointSet} class (i.e., \code{TPixelType}). Two basic
//  interaction styles of PointSets are available in ITK. These styles are
//  referred to as \emph{static} and \emph{dynamic}. The first style is used
//  when the number of points in the set is known in advance and is not
//  expected to change as a consequence of the manipulations performed on the
//  set. The dynamic style, on the other hand, is intended to support
//  insertion and removal of points in an efficient manner. Distinguishing
//  between the two styles is meant to facilitate the fine tuning of a
//  \code{PointSet}'s behavior while optimizing performance and memory
//  management.
//
//  \index{itk::PointSet}
//  \index{itk::PointSet!Static}
//  \index{itk::PointSet!Dynamic}
//
//  In order to use the PointSet class, its header file should be included.
//
//  Software Guide : EndLatex
 
// Software Guide : BeginCodeSnippet
#include "itkPointSet.h"
// Software Guide : EndCodeSnippet
 
int
main(int, char *[])
{
  //  Software Guide : BeginLatex
  //
  //  Then we must decide what type of value to associate with the
  //  points. This is generally called the \code{PixelType} in order to make
  //  the terminology consistent with the \code{itk::Image}. The PointSet is
  //  also templated over the dimension of the space in which the points are
  //  represented. The following declaration illustrates a typical
  //  instantiation of the PointSet class.
  //
  //  \index{itk::PointSet!Instantiation}
  //
  //  Software Guide : EndLatex
 
  // Software Guide : BeginCodeSnippet
  using PointSetType = itk::PointSet<unsigned short, 3>;
  // Software Guide : EndCodeSnippet
 
 
  //  Software Guide : BeginLatex
  //
  //  A \code{PointSet} object is created by invoking the \code{New()} method
  //  on its type.  The resulting object must be assigned to a
  //  \code{SmartPointer}.  The PointSet is then reference-counted and can be
  //  shared by multiple objects. The memory allocated for the PointSet will
  //  be released when the number of references to the object is reduced to
  //  zero. This simply means that the user does not need to be concerned
  //  with invoking the \code{Delete()} method on this class.  In fact, the
  //  \code{Delete()} method should \textbf{never} be called directly within
  //  any of the reference-counted ITK classes.
  //
  //  \index{itk::PointSet!New()}
  //  \index{itk::PointSet!Pointer}
  //
  //  Software Guide : EndLatex
 
  // Software Guide : BeginCodeSnippet
  auto pointsSet = PointSetType::New();
  // Software Guide : EndCodeSnippet
 
 
  //  Software Guide : BeginLatex
  //
  //  Following the principles of Generic Programming, the \code{PointSet}
  //  class has a set of associated defined types to ensure that interacting
  //  objects can be declared with compatible types. This set of type
  //  definitions is commonly known as a set of \emph{traits}.  Among the
  //  traits of the \code{PointSet} class is \code{PointType}, which is used
  //  by the point set to represent points in space. The following declaration
  //  takes the point type as defined in the \code{PointSet} traits and
  //  renames it to be conveniently used in the global namespace.
  //
  //  \index{itk::PointSet!PointType}
  //
  //  Software Guide : EndLatex
 
  // Software Guide : BeginCodeSnippet
  using PointType = PointSetType::PointType;
  // Software Guide : EndCodeSnippet
 
 
  //  Software Guide : BeginLatex
  //
  //  The \code{PointType} can now be used to declare point objects to be
  //  inserted in the \code{PointSet}. Points are fairly small objects, so
  //  it is inconvenient to manage them with reference counting and smart
  //  pointers. They are simply instantiated as typical C++ classes. The Point
  //  class inherits the \code{[]} operator from the \code{itk::Array} class.
  //  This makes it possible to access its components using index notation.
  //  For efficiency's sake no bounds checking is performed during index
  //  access. It is the user's responsibility to ensure that the index used is
  //  in the range
  //  $\{0,Dimension-1\}$. Each of the components in the point is associated
  //  with space coordinates. The following code illustrates how to
  //  instantiate a point and initialize its components.
  //
  //  Software Guide : EndLatex
 
  // Software Guide : BeginCodeSnippet
  PointType p0;
  p0[0] = -1.0; //  x coordinate
  p0[1] = -1.0; //  y coordinate
  p0[2] = 0.0;  //  z coordinate
  // Software Guide : EndCodeSnippet
 
 
  PointType p1;
 
  p1[0] = 1.0; // Point 1 = { 1,-1,0 }
  p1[1] = -1.0;
  p1[2] = 0.0;
 
 
  PointType p2; // Point 2 = { 1,1,0 }
  p2[0] = 1.0;
  p2[1] = 1.0;
  p2[2] = 0.0;
 
  //  Software Guide : BeginLatex
  //
  //  Points are inserted in the PointSet by using the \code{SetPoint()}
  //  method. This method requires the user to provide a unique identifier for
  //  the point. The identifier is typically an unsigned integer that will
  //  enumerate the points as they are being inserted. The following code
  //  shows how three points are inserted into the PointSet.
  //
  //  \index{itk::PointSet!SetPoint()}
  //
  //  Software Guide : EndLatex
 
  // Software Guide : BeginCodeSnippet
  pointsSet->SetPoint(0, p0);
  pointsSet->SetPoint(1, p1);
  pointsSet->SetPoint(2, p2);
  // Software Guide : EndCodeSnippet
 
 
  //  Software Guide : BeginLatex
  //
  // It is possible to query the PointSet in order to determine how many
  // points have been inserted into it. This is done with the
  // \code{GetNumberOfPoints()} method as illustrated below.
  //
  //  \index{itk::PointSet!GetNumberOfPoints()}
  //
  //  Software Guide : EndLatex
 
  // Software Guide : BeginCodeSnippet
  const unsigned int numberOfPoints = pointsSet->GetNumberOfPoints();
  std::cout << numberOfPoints << std::endl;
  // Software Guide : EndCodeSnippet
 
 
  //  Software Guide : BeginLatex
  //
  // Points can be read from the PointSet by using the \code{GetPoint()}
  // method and the integer identifier. The point is stored in a pointer
  // provided by the user. If the identifier provided does not match an
  // existing point, the method will return \code{false} and the contents of
  // the point will be invalid. The following code illustrates point access
  // using defensive programming.
  //
  //  \index{itk::PointSet!GetPoint()}
  //
  //  Software Guide : EndLatex
 
  // Software Guide : BeginCodeSnippet
  PointType  pp;
  const bool pointExists = pointsSet->GetPoint(1, &pp);
 
  if (pointExists)
  {
    std::cout << "Point is = " << pp << std::endl;
  }
  // Software Guide : EndCodeSnippet
 
 
  //  Software Guide : BeginLatex
  //
  // \code{GetPoint()} and \code{SetPoint()} are not the most efficient
  // methods to access points in the PointSet. It is preferable to get direct
  // access to the internal point container defined by the \emph{traits} and
  // use iterators to walk sequentially over the list of points (as shown in
  // the following example).
  //
  //  Software Guide : EndLatex
 
  return EXIT_SUCCESS;
}