ITK  6.0.0
Insight Toolkit
Examples/SpatialObjects/SpatialObjectTransforms.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
//
// \index{itk::SpatialObjectTransform}
//
// This example describes the different
// transformations and the Object and World "spaces" associated with a spatial
// object.
//
// \begin{description}
// \item[Object Space]. SpatialObjects have one primary coordinate space
// that is readily available
// to them, their \code{ObjectSpace}. This is the space in which the object
// was inherently defined. No transforms are applied to the points/values that
// get/set into this space. All children of an object are added into this
// space.
//
// \item[ObjectToParentTransform]. SpatialObjects have only one transform
// that they directly control, their
// \code{ObjectToParentTransform}. This transform specifies how an object's
// \code{ObjectSpace} is
// transformed to fit into its parent's \code{ObjectSpace}. The
// \code{ObjectToParentTransform} is an affine transform, and it is confirmed
// to be invertible when assigned, or the assignment fails.
//
// \item[WorldSpace]. \code{WorldSpace} is not directly controlled by any
// SpatialObject except the
// SpatialObject at the top level of the parent-child tree hierarchy of
// Spatial Objects. That is, any SpatialObject that does not have a parent
// exists in a \code{WorldSpace} that is defined by applying its
// \code{ObjectToParentTransform} to its \code{ObjectSpace}.
//
// \end{description}
//
// Several member functions and variables are available to every SpatialObject
// so that they can readily access the WorldSpace in which they exist:
//
// \begin{description}
//
// \item[ProtectedComputeObjectToWorldTransform()]: This function is called
// whenever \code{Update()} is called. It composes the object's
// \code{ObjectToParentTransform}
// with its parent's cached \code{ObjectToWorldTransform}, to determine the
// transform from the object's \code{ObjectSpace} to \code{WorldSpace}.
// This transform is
// always invertible. This call will cause all children objects to also
// update their cached \code{ObjectToWorldTransform}. This function should
// be called on the top level object (via \code{Update()}) once all children
// object's
// \code{ObjectToParentTransform}s have been set. This function should
// be called
// on children objects when their \code{ObjectToParentTransform}s have been
// changed.
//
// \item[GetObjectToWorldTransform()]: Returns the cached
// \code{ObjectToWorldTransform}.
// It is the user's responsibility to call \code{Update()} (and thereby
// \code{ProtectedComputeObjectToWorldTransform()}) when
// necessary, prior to calling \code{GetObjectToWorldTransform()}, otherwise
// the returned transform may be "stale."
//
// \item[SetObjectToWorldTransform()]: This function updates the object's
// \code{ObjectToParentTransform}, using an inverse of the parent's cached
// \code{ObjectToWorldTransform}, so that the composition of those transforms
// equal the transform passed to this function. If an object has no parent,
// its \code{ObjectToParentTransform} is equal to its
// \code{ObjectToWorldTransform}.
//
// \end{description}
//
// Software Guide : EndLatex
int
main(int, char *[])
{
// Software Guide : BeginLatex
//
// Like the first example, we create two spatial objects and give them the
// names \code{First Object} and \code{Second Object}, respectively.
//
// Software Guide : EndLatex
// Software Guide : BeginCodeSnippet
using SpatialObjectType = itk::SpatialObject<2>;
using TransformType = SpatialObjectType::TransformType;
auto object1 = SpatialObjectType::New();
object1->GetProperty().SetName("First Object");
auto object2 = SpatialObjectType::New();
object2->GetProperty().SetName("Second Object");
object1->AddChild(object2);
// Software Guide : EndCodeSnippet
// Software Guide : BeginLatex
//
// First we define a scaling factor of 2 for the object2.
// This is done by setting the Scale of the \code{ObjectToParentTransform}.
//
// Note that this scaling would also apply to the children of object2,
// if it had children. If you wish to scale an object, but not its
// children, then those children aren't actually ``children'', but they are
// siblings. So, you should insert a \code{GroupSpatialObject} that holds
// both the object and its siblings as children. Then you can manipulate
// the object's transform/scaling independent of its siblings in that group,
// and if you wish to transform the object and its siblings, you apply that
// transform to the group.
//
// Software Guide : EndLatex
// Software Guide : BeginCodeSnippet
double scale[2];
scale[0] = 2;
scale[1] = 2;
object2->GetModifiableObjectToParentTransform()->Scale(scale);
// Software Guide : EndCodeSnippet
// Software Guide : BeginLatex
//
// Next, we apply an offset on the \code{ObjectToParentTransform} to
// \code{object1}
// which will also cause a translation of its child, \code{object2}.
//
// Software Guide : EndLatex
// Software Guide : BeginCodeSnippet
TransformType::OffsetType object1Offset;
object1Offset[0] = 4;
object1Offset[1] = 3;
object1->GetModifiableObjectToParentTransform()->SetOffset(object1Offset);
// Software Guide : EndCodeSnippet
// Software Guide : BeginLatex
//
// To realize the previous operations on the transformations, we should
// invoke the \code{Update()} that recomputes all dependent transformations.
//
// By calling this function on \code{object1}, it will also descend to its
// children, thereby also updating the \code{ObjectToWorldTransform} for
// \code{object2}.
//
// Software Guide : EndLatex
// Software Guide : BeginCodeSnippet
object1->Update();
// Software Guide : EndCodeSnippet
// Software Guide : BeginLatex
//
// We can now display the \code{ObjectToWorldTransform} for both objects.
// One should notice that the only valid members of the Affine
// transformation are a Matrix and an Offset. For instance, when we invoke
// the \code{Scale()} method the internal Matrix is recomputed to reflect
// this change.
//
// The AffineTransform performs the following
// computation
//
// \begin{equation}
// X' = R \cdot \left( S \cdot X - C \right) + C + V
// \end{equation}
//
// Where $R$ is the rotation matrix, $S$ is a scaling factor, $C$ is the
// center of rotation and $V$ is a translation vector or offset. Therefore
// the affine matrix $M$ and the affine offset $T$ are defined as:
//
// \begin{equation}
// M = R \cdot S
// \end{equation}
// \begin{equation}
// T = C + V - R \cdot C
// \end{equation}
//
// This means that \code{Scale()} and \code{GetOffset()}
// as well as the \code{GetMatrix()} might not be set to the
// expected value, especially if the transformation results from a
// composition with another transformation since the composition is done
// using the Matrix and the Offset of the affine transformation.
//
// Next, we show the two affine transformations corresponding to the two
// objects.
//
// First, the \code{ObjectToParentTransform} for \code{object2}:
//
// Software Guide : EndLatex
// Software Guide : BeginCodeSnippet
std::cout << "object2 ObjectToParent Matrix: " << std::endl;
std::cout << object2->GetObjectToParentTransform()->GetMatrix()
<< std::endl;
std::cout << "object2 ObjectToParent Offset: ";
std::cout << object2->GetObjectToParentTransform()->GetOffset()
<< std::endl;
// Software Guide : EndCodeSnippet
// Software Guide : BeginLatex
//
// Second, the \code{ObjectToWorldTransform} that is derived
// from the parent-child hierarchy and the composition of the corresponding
// \code{ObjectToParentTransform}s, computed by called to
// \code{Update()}, and cached for efficient subsequent use, for
// \code{object2}:
//
// Software Guide : EndLatex
// Software Guide : BeginCodeSnippet
std::cout << "object2 ObjectToWorld Matrix: " << std::endl;
std::cout << object2->GetObjectToWorldTransform()->GetMatrix() << std::endl;
std::cout << "object2 ObjectToWorld Offset: ";
std::cout << object2->GetObjectToWorldTransform()->GetOffset() << std::endl;
// Software Guide : EndCodeSnippet
// Software Guide : BeginLatex
//
// We can also update an object's \code{ObjectToParentTransform} by
// changing its \code{ObjectToWorldTransform} and then calling
// \code{ComputeObjectToParentTransform()},
// which changes the \code{ObjectToParentTransform} so as to achieve the
// cached \code{ObjectToWorldTransform}.
//
// Software Guide : EndLatex
// Software Guide : BeginCodeSnippet
TransformType::OffsetType Object1ToWorldOffset;
Object1ToWorldOffset[0] = 3;
Object1ToWorldOffset[1] = 3;
object1->GetModifiableObjectToWorldTransform()->SetOffset(
Object1ToWorldOffset);
object1->ComputeObjectToParentTransform();
// Software Guide : EndCodeSnippet
// Software Guide : BeginLatex
//
// Finally, we display the resulting affine transformations. First,
// for the \code{ObjectToParentTransform} for \code{object1}.
//
// Software Guide : EndLatex
// Software Guide : BeginCodeSnippet
std::cout << "object1 ObjectToParent Matrix: " << std::endl;
std::cout << object1->GetObjectToParentTransform()->GetMatrix()
<< std::endl;
std::cout << "object1 ObjectToParent Offset: ";
std::cout << object1->GetObjectToParentTransform()->GetOffset()
<< std::endl;
// Software Guide : EndCodeSnippet
// Software Guide : BeginLatex
//
// Second, for the \code{ObjectToWorldTransform} for \code{object2}.
//
// Software Guide : EndLatex
// Software Guide : BeginCodeSnippet
std::cout << "object2 ObjectToWorld Matrix: " << std::endl;
std::cout << object2->GetObjectToWorldTransform()->GetMatrix() << std::endl;
std::cout << "object2 ObjectToWorld Offset: ";
std::cout << object2->GetObjectToWorldTransform()->GetOffset() << std::endl;
// Software Guide : EndCodeSnippet
// Software Guide : BeginLatex
//
// Also, as a child is disconnected from its parent, it should not move;
// so its \code{ObjectToParentTransform} should be updated to match its
// \code{ObjectToWorldTransform}.
//
// Software Guide : EndLatex
// Software Guide : BeginCodeSnippet
object1->RemoveChild(object2);
object2->Update();
std::cout << "object2 ObjectToWorld Matrix: " << std::endl;
std::cout << object2->GetObjectToWorldTransform()->GetMatrix() << std::endl;
std::cout << "object2 ObjectToWorld Offset: ";
std::cout << object2->GetObjectToWorldTransform()->GetOffset() << std::endl;
std::cout << "object2 ObjectToParent Matrix: " << std::endl;
std::cout << object2->GetObjectToParentTransform()->GetMatrix()
<< std::endl;
std::cout << "object2 ObjectToParent Offset: ";
std::cout << object2->GetObjectToParentTransform()->GetOffset()
<< std::endl;
// Software Guide : EndCodeSnippet
// Software Guide : BeginLatex
//
// The output of this second example looks like the following:
// \small
// \begin{verbatim}
// object2 ObjectToParent Matrix:
// 2 0
// 0 2
// object2 ObjectToParent Offset: 0 0
// object2 ObjectToWorld Matrix:
// 2 0
// 0 2
// object2 ObjectToWorld Offset: 4 3
//
// object1 ObjectToParent Matrix:
// 1 0
// 0 1
// object1 ObjectToParent Offset: 3 3
// object2 ObjectToWorld Matrix:
// 2 0
// 0 2
// object2 ObjectToWorld Offset: 7 6
//
// object2 ObjectToParent Matrix:
// 2 0
// 0 2
// object2 ObjectToParent Offset: 7 6
// object2 ObjectToWorld Matrix:
// 2 0
// 0 2
// object2 ObjectToWorld Offset: 7 6
// \end{verbatim}
// \normalsize
//
// Software Guide : EndLatex
return EXIT_FAILURE;
}
itkSpatialObject.h
itk::SpatialObject
Implementation of the composite pattern.
Definition: itkSpatialObject.h:58
New
static Pointer New()