Definition of a analytical 2D plane embedded in 3D space. More...

#include <hyperplane3D.h>

Collaboration diagram for olb::Hyperplane3D< T >:

Public Member Functions
	Hyperplane3D ()=default

Hyperplane3D &	originAt (const Vector< T, 3 > &origin)
	Center the hyperplane at the given origin vector.

Hyperplane3D &	centeredIn (const Cuboid3D< T > &cuboid)
	Center the hyperplane relative to the given cuboid.

Hyperplane3D &	spannedBy (const Vector< T, 3 > &u, const Vector< T, 3 > &v)
	Span the hyperplane using two span vectors.

Hyperplane3D &	normalTo (const Vector< T, 3 > &normal)
	Calculate the spanning vectors of the hyperplane to be orthogonal to the given normal.

Hyperplane3D &	applyMatrixToSpan (const Vector< T, 3 > &row0, const Vector< T, 3 > &row1, const Vector< T, 3 > &row2)
	Apply a matrix given by its row vectors to both span vectors.

Hyperplane3D &	rotateSpanAroundX (T r)
	Rotate the spanning vectors around the X axis.

Hyperplane3D &	rotateSpanAroundY (T r)
	Rotate the spanning vectors around the Y axis.

Hyperplane3D &	rotateSpanAroundZ (T r)
	Rotate the spanning vectors around the Z axis.

Hyperplane3D &	parseFromXML (const std::string &xml)
	Read origin and normal from XML.

bool	isXYPlane () const

bool	isXZPlane () const

bool	isYZPlane () const

Vector< T, 3 >	project (const Vector< T, 2 > &x) const

Public Attributes
Vector< T, 3 >	origin

Vector< T, 3 >	u

Vector< T, 3 >	v

Vector< T, 3 >	normal

Detailed Description

template<typename T>
struct olb::Hyperplane3D< T >

Definition of a analytical 2D plane embedded in 3D space.

Hyperplane3D defines a hyperplane using its origin and two span vectors.

In practice it might be preferable to define a hyperplane using a normal vector or to automatically center the origin in a given cuboid. For this purpose a fluent construction interface is offered:

// construct a hyperplane positioned at (1,1,1) and normal to (1,0,0)
auto plane = Hyperplane3D<T>().originAt({1,1,1})
                              .normalTo({1,0,0});

The primary reason for this development was the increasing constructor clutter in BlockReduction3D2D: Instead of using the correct Vector<T,3> types for passing span and origin vectors they were passed as a mix between raw values and array types to prevent the constructor from becoming ambiguous. e.g. on the type level passing two span vectors is indistinguishable from passing normal and origin vectors.

Definition at line 53 of file hyperplane3D.h.

Constructor & Destructor Documentation

◆ Hyperplane3D()

template<typename T >

olb::Hyperplane3D< T >::Hyperplane3D ( )

explicitdefault

Member Function Documentation

◆ applyMatrixToSpan()

template<typename T >

Hyperplane3D< T > & olb::Hyperplane3D< T >::applyMatrixToSpan	(	const Vector< T, 3 > &	row0,
		const Vector< T, 3 > &	row1,
		const Vector< T, 3 > &	row2 )

Apply a matrix given by its row vectors to both span vectors.

Returns: Hyperplane3D reference for further construction

Definition at line 107 of file hyperplane3D.hh.

{
  const auto u_prime = u;
  const auto v_prime = v;
 
  u[0] = row0 * u_prime;
  u[1] = row1 * u_prime;
  u[2] = row2 * u_prime;
 
  v[0] = row0 * v_prime;
  v[1] = row1 * v_prime;
  v[2] = row2 * v_prime;
 
  return *this;
}

◆ centeredIn()

template<typename T >

Hyperplane3D< T > & olb::Hyperplane3D< T >::centeredIn ( const Cuboid3D< T > & cuboid )

Center the hyperplane relative to the given cuboid.

Returns: Hyperplane3D reference for further construction

Definition at line 90 of file hyperplane3D.hh.

{
  const Vector<T,3>& cuboidOrigin = cuboid.getOrigin();
  const Vector<int,3>& extend     = cuboid.getExtent();
  const T deltaR = cuboid.getDeltaR();
 
  origin[0] = (cuboidOrigin[0] + 0.5 * deltaR * extend[0]);
  origin[1] = (cuboidOrigin[1] + 0.5 * deltaR * extend[1]);
  origin[2] = (cuboidOrigin[2] + 0.5 * deltaR * extend[2]);
  origin[0] -= 2*std::numeric_limits<T>::epsilon()*util::fabs(origin[0]);
  origin[1] -= 2*std::numeric_limits<T>::epsilon()*util::fabs(origin[1]);
  origin[2] -= 2*std::numeric_limits<T>::epsilon()*util::fabs(origin[2]);
 
  return *this;
}

References olb::util::fabs(), olb::Cuboid< T, D >::getDeltaR(), olb::Cuboid< T, D >::getExtent(), and olb::Cuboid< T, D >::getOrigin().

Here is the call graph for this function:

◆ isXYPlane()

template<typename T >

bool olb::Hyperplane3D< T >::isXYPlane ( ) const

Returns: true iff normal is orthogonal to X, Y axis

Definition at line 189 of file hyperplane3D.hh.

{
  return util::nearZero(util::dotProduct3D(normal, {1,0,0})) &&
         util::nearZero(util::dotProduct3D(normal, {0,1,0}));
}

References olb::util::dotProduct3D(), and olb::util::nearZero().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isXZPlane()

template<typename T >

bool olb::Hyperplane3D< T >::isXZPlane ( ) const

Returns: true iff normal is orthogonal to X, Z axis

Definition at line 196 of file hyperplane3D.hh.

{
  return util::nearZero(util::dotProduct3D(normal, {1,0,0})) &&
         util::nearZero(util::dotProduct3D(normal, {0,0,1}));
}

References olb::util::dotProduct3D(), and olb::util::nearZero().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isYZPlane()

template<typename T >

bool olb::Hyperplane3D< T >::isYZPlane ( ) const

Returns: true iff normal is orthogonal to Y, Z axis

Definition at line 203 of file hyperplane3D.hh.

{
  return util::nearZero(util::dotProduct3D(normal, {0,1,0})) &&
         util::nearZero(util::dotProduct3D(normal, {0,0,1}));
}

References olb::util::dotProduct3D(), and olb::util::nearZero().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ normalTo()

template<typename T >

Hyperplane3D< T > & olb::Hyperplane3D< T >::normalTo ( const Vector< T, 3 > & normal )

Calculate the spanning vectors of the hyperplane to be orthogonal to the given normal.

Returns: Hyperplane3D reference for further construction

Definition at line 49 of file hyperplane3D.hh.

{
  normal = n;
 
  if ( util::nearZero(normal[0]*normal[1]*normal[2]) ) {
    if ( util::nearZero(normal[0]) ) {
      u = {T(1), T(), T()};
    }
    else if ( util::nearZero(normal[1]) ) {
      u = {T(), T(1), T()};
    }
    else if ( util::nearZero(normal[2]) ) {
      u = {T(), T(), T(1)};
    }
  }
  else {
    u = {normal[2], T(), -normal[0]};
  }
 
  v = normalize(crossProduct3D(normal,u));
  u = normalize(u);
  normal = normalize(normal);
 
  OLB_POSTCONDITION(util::nearZero(util::dotProduct3D(u,v)));
  OLB_POSTCONDITION(util::nearZero(util::dotProduct3D(u,normal)));
  OLB_POSTCONDITION(util::nearZero(util::dotProduct3D(v,normal)));
 
  return *this;
}

References olb::crossProduct3D(), olb::util::dotProduct3D(), olb::util::nearZero(), olb::normalize(), and OLB_POSTCONDITION.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ originAt()

template<typename T >

Hyperplane3D< T > & olb::Hyperplane3D< T >::originAt ( const Vector< T, 3 > & origin )

Center the hyperplane at the given origin vector.

Returns: Hyperplane3D reference for further construction

Definition at line 80 of file hyperplane3D.hh.

{
  origin[0] = o[0] - 2*std::numeric_limits<T>::epsilon()*util::fabs(o[0]);
  origin[1] = o[1] - 2*std::numeric_limits<T>::epsilon()*util::fabs(o[1]);
  origin[2] = o[2] - 2*std::numeric_limits<T>::epsilon()*util::fabs(o[2]);
 
  return *this;
}

References olb::util::fabs().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ parseFromXML()

template<typename T >

Hyperplane3D< T > & olb::Hyperplane3D< T >::parseFromXML ( const std::string & xml )

Read origin and normal from XML.

Returns: Hyperplane3D reference for further construction

Definition at line 158 of file hyperplane3D.hh.

{
  using namespace tinyxml2;
  XMLDocument doc;
  if (doc.Parse(xmlData.c_str()) != XML_SUCCESS) {
    throw std::runtime_error("Failed to parse XML: " + std::string(doc.ErrorStr()));
  }
  XMLElement* root = doc.FirstChildElement("UpdateSlice");
  if (!root) {
    throw std::runtime_error("Root element <UpdateSlice> not found.");
  }
  XMLElement* origin = root->FirstChildElement("origin");
  if (!origin) {
    throw std::runtime_error("Element <origin> not found.");
  }
  const T ox = origin->DoubleAttribute("x");
  const T oy = origin->DoubleAttribute("y");
  const T oz = origin->DoubleAttribute("z");
  XMLElement* normal = root->FirstChildElement("normal");
  if (!normal) {
    throw std::runtime_error("Element <normal> not found.");
  }
  const T nx = normal->DoubleAttribute("x");
  const T ny = normal->DoubleAttribute("y");
  const T nz = normal->DoubleAttribute("z");
  Vector n{nx, ny, nz};
  return originAt({ox,oy,oz})
        .normalTo(normalize(n));
}

References olb::normalize().

Here is the call graph for this function:

◆ project()

template<typename T >

Vector< T, 3 > olb::Hyperplane3D< T >::project ( const Vector< T, 2 > & x ) const

Returns: 2D vector relative to origin projected to 3D

Definition at line 210 of file hyperplane3D.hh.

{
  return origin + x[0]*u + x[1]*v;
}

Here is the caller graph for this function:

◆ rotateSpanAroundX()

template<typename T >

Hyperplane3D< T > & olb::Hyperplane3D< T >::rotateSpanAroundX ( T r )

Rotate the spanning vectors around the X axis.

Returns: Hyperplane3D reference for further construction

Definition at line 127 of file hyperplane3D.hh.

{
  return applyMatrixToSpan(
  {1, 0,       0     },
  {0, util::cos(r), -util::sin(r)},
  {0, util::sin(r),  util::cos(r)}
  );
 
}

References olb::util::cos(), and olb::util::sin().

Here is the call graph for this function:

◆ rotateSpanAroundY()

template<typename T >

Hyperplane3D< T > & olb::Hyperplane3D< T >::rotateSpanAroundY ( T r )

Rotate the spanning vectors around the Y axis.

Returns: Hyperplane3D reference for further construction

Definition at line 138 of file hyperplane3D.hh.

{
  return applyMatrixToSpan(
  { util::cos(r), 0, util::sin(r)},
  { 0,      1, 0     },
  {-util::sin(r), 0, util::cos(r)}
  );
}

References olb::util::cos(), and olb::util::sin().

Here is the call graph for this function:

◆ rotateSpanAroundZ()

template<typename T >

Hyperplane3D< T > & olb::Hyperplane3D< T >::rotateSpanAroundZ ( T r )

Rotate the spanning vectors around the Z axis.

Returns: Hyperplane3D reference for further construction

Definition at line 148 of file hyperplane3D.hh.

{
  return applyMatrixToSpan(
  {util::cos(r), -util::sin(r), 0},
  {util::sin(r),  util::cos(r), 0},
  {0,       0,      1}
  );
}

References olb::util::cos(), and olb::util::sin().

Here is the call graph for this function:

◆ spannedBy()

template<typename T >

Hyperplane3D< T > & olb::Hyperplane3D< T >::spannedBy	(	const Vector< T, 3 > &	u,
		const Vector< T, 3 > &	v )

Span the hyperplane using two span vectors.

Returns: Hyperplane3D reference for further construction

Definition at line 35 of file hyperplane3D.hh.

{
  u = a;
  v = b;
  normal = normalize(crossProduct3D(a,b));
 
  OLB_POSTCONDITION(util::nearZero(util::dotProduct3D(u,v)));
  OLB_POSTCONDITION(util::nearZero(util::dotProduct3D(u,normal)));
  OLB_POSTCONDITION(util::nearZero(util::dotProduct3D(v,normal)));
 
  return *this;
}