Represents the mapping of a field by a matrix transform. More...

#include <FieldMapping.h>

Inheritance diagram for MatrixFieldMapping:

Public Types
typedef MatrixFieldMapping	class_type
typedef Curve< Imath::M44d >	MatrixCurve
	Time-varying matrix.
typedef boost::intrusive_ptr < MatrixFieldMapping >	Ptr
	Convenience typedef.
Public Member Functions
const M44d &	localToWorld () const
	Returns a reference to the local to world transform.
const MatrixCurve::SampleVec &	localToWorldSamples () const
	Returns a vector of all motion samples for local to world transform.
void	makeIdentity ()
	Sets the transform to identity. This makes it functionally equivalent to a NullFieldMapping.
void	setLocalToWorld (float t, const M44d &lsToWs)
	Sets the local to world transform at a given time.
void	setLocalToWorld (const M44d &lsToWs)
	Sets the local to world transform. All other matrices will be updated based on this.
const M44d &	voxelToWorld () const
	Returns a reference to the voxel to world space transform.
const M44d &	worldToVoxel () const
	Returns a reference to the world to voxel space transform.
Constructors & destructor
	MatrixFieldMapping ()
	MatrixFieldMapping (const Box3i &extents)
From FieldMapping
virtual void	worldToVoxel (const V3d &wsP, V3d &vsP) const
	Transform from world space position into voxel space.
virtual void	worldToVoxel (const V3d &wsP, V3d &vsP, float time) const
virtual void	voxelToWorld (const V3d &vsP, V3d &wsP) const
	Transform from voxel space position into world space.
virtual void	voxelToWorld (const V3d &vsP, V3d &wsP, float time) const
virtual void	worldToLocal (const V3d &wsP, V3d &lsP) const
	Transform from world space position into local space.
virtual void	worldToLocal (const V3d &wsP, V3d &lsP, float time) const
virtual void	localToWorld (const V3d &lsP, V3d &wsP) const
	Transform from local space position into world space.
virtual void	localToWorld (const V3d &lsP, V3d &wsP, float time) const
void	worldToVoxelDir (const V3d &wsV, V3d &vsV) const
void	voxelToWorldDir (const V3d &vsV, V3d &wsV) const
void	worldToLocalDir (const V3d &wsV, V3d &lsV) const
void	localToWorldDir (const V3d &lsV, V3d &wsV) const
virtual void	extentsChanged ()
	Implement this if the subclass needs to update itself when the resolution changes.
virtual std::string	className () const
	Returns the FieldMapping type name. Used when writing/reading from disk.
virtual bool	isIdentical (FieldMapping::Ptr other, double tolerance=0.0) const
	Whether the mapping is identical to another mapping.
virtual V3d	wsVoxelSize (int, int, int) const
	Returns world-space size of a voxel at the specified coordinate.
virtual FieldMapping::Ptr	clone () const
	Returns a pointer to a copy of the mapping, pure virtual so ensure derived classes properly implement it.
Static Public Member Functions
static const char *	classType ()
Public Attributes
	DEFINE_FIELD_RTTI_CONCRETE_CLASS
Private Types
typedef FieldMapping	base
	Convenience typedef for referring to base class.
Private Member Functions
void	getLocalToVoxelMatrix (M44d &result)
void	updateTransform ()
	Updates the local to world transformation matrix.
Private Attributes
bool	m_isTimeVarying
	Stores whether the curve has more than one time sample.
M44d	m_lsToWs
	Local space to world space.
MatrixCurve	m_lsToWsCurve
	Time-varying local to world space transform.
M44d	m_vsToWs
	Voxel space to world space.
MatrixCurve	m_vsToWsCurve
	Time-varying voxel to world space transform.
M44d	m_wsToLs
	World space to local space.
M44d	m_wsToVs
	World space to voxel space.
V3d	m_wsVoxelSize
	Precomputed world-space voxel size. Calculations may assume orthogonal transformation for efficiency.

Detailed Description

Represents the mapping of a field by a matrix transform.

Refer to using_mappings for examples of how to use this in your code.

Note:: Regarding time-varying matrices. If setLocalToWorld(M44d) is called, an underlying Curve object is created with just one sample at time=0.0.

Todo:: Add calls for easily specifying the transform given grid size, offset, rotation, etc.

Definition at line 316 of file FieldMapping.h.

Member Typedef Documentation

typedef boost::intrusive_ptr<MatrixFieldMapping> MatrixFieldMapping::Ptr

Convenience typedef.

Reimplemented from FieldMapping.

Definition at line 323 of file FieldMapping.h.

typedef Curve<Imath::M44d> MatrixFieldMapping::MatrixCurve

Time-varying matrix.

Definition at line 325 of file FieldMapping.h.

typedef MatrixFieldMapping MatrixFieldMapping::class_type

Reimplemented from FieldMapping.

Definition at line 329 of file FieldMapping.h.

typedef FieldMapping MatrixFieldMapping::base [private]

Convenience typedef for referring to base class.

Reimplemented from FieldMapping.

Definition at line 502 of file FieldMapping.h.

Constructor & Destructor Documentation

MatrixFieldMapping::MatrixFieldMapping ( )

Definition at line 196 of file FieldMapping.cpp.

References makeIdentity().

Referenced by clone().

  : FieldMapping()
{ 
  makeIdentity();
}

MatrixFieldMapping::MatrixFieldMapping ( const Box3i & extents )

Definition at line 204 of file FieldMapping.cpp.

References makeIdentity().

  : FieldMapping(extents)
{ 
  makeIdentity();
}

Member Function Documentation

static const char* MatrixFieldMapping::classType ( ) [inline, static]

Reimplemented from FieldMapping.

Definition at line 332 of file FieldMapping.h.

Referenced by className().

  {
    return "MatrixFieldMapping";
  }

void MatrixFieldMapping::setLocalToWorld ( const M44d & lsToWs )

Sets the local to world transform. All other matrices will be updated based on this.

Note:: This resets the Curve to contain just one sample at time=0.0

Definition at line 212 of file FieldMapping.cpp.

References m_lsToWsCurve, makeIdentity(), and Curve< T >::numSamples().

{
  if (m_lsToWsCurve.numSamples() > 0) {
    makeIdentity();
  }
  setLocalToWorld(0.0f, lsToWs);
}

void MatrixFieldMapping::setLocalToWorld	(	float	t,
		const M44d &	lsToWs
	)

Sets the local to world transform at a given time.

Definition at line 222 of file FieldMapping.cpp.

References Curve< T >::addSample(), m_lsToWsCurve, and updateTransform().

{
  m_lsToWsCurve.addSample(t, lsToWs);
  updateTransform();
}

const M44d& MatrixFieldMapping::localToWorld ( ) const [inline]

Returns a reference to the local to world transform.

Note:: This assumes the query to be at time=0.0

Definition at line 358 of file FieldMapping.h.

References m_lsToWs.

Referenced by convertCellCenteredToMAC(), and convertMACToCellCentered().

  { return m_lsToWs; }

const M44d& MatrixFieldMapping::worldToVoxel ( ) const [inline]

Returns a reference to the world to voxel space transform.

Note:: This assumes the query to be at time=0.0

Definition at line 363 of file FieldMapping.h.

References m_wsToVs.

  { return m_wsToVs; }

const M44d& MatrixFieldMapping::voxelToWorld ( ) const [inline]

Returns a reference to the voxel to world space transform.

Note:: This assumes the query to be at time=0.0

Definition at line 368 of file FieldMapping.h.

References m_vsToWs.

  { return m_vsToWs; }

const MatrixCurve::SampleVec& MatrixFieldMapping::localToWorldSamples ( ) const [inline]

Returns a vector of all motion samples for local to world transform.

Definition at line 372 of file FieldMapping.h.

References m_lsToWsCurve, and Curve< T >::samples().

  { return m_lsToWsCurve.samples(); }

void MatrixFieldMapping::makeIdentity ( )

Sets the transform to identity. This makes it functionally equivalent to a NullFieldMapping.

Definition at line 230 of file FieldMapping.cpp.

References Curve< T >::clear(), m_lsToWsCurve, and updateTransform().

Referenced by MatrixFieldMapping(), and setLocalToWorld().

{
  m_lsToWsCurve.clear();
  updateTransform();
}

virtual void MatrixFieldMapping::worldToVoxel	(	const V3d &	wsP,
		V3d &	vsP
	)		const `[inline, virtual]`

Transform from world space position into voxel space.

Implements FieldMapping.

Definition at line 384 of file FieldMapping.h.

References m_wsToVs.

  { m_wsToVs.multVecMatrix(wsP, vsP); }

virtual void MatrixFieldMapping::worldToVoxel	(	const V3d &	wsP,
		V3d &	vsP,
		float	time
	)		const `[inline, virtual]`

Implements FieldMapping.

Definition at line 386 of file FieldMapping.h.

References Curve< T >::linear(), m_isTimeVarying, m_vsToWsCurve, and m_wsToVs.

  { 
    if (!m_isTimeVarying) {
      m_wsToVs.multVecMatrix(wsP, vsP);
    } else {
      M44d wsToVs = m_vsToWsCurve.linear(time).inverse();
      wsToVs.multVecMatrix(wsP, vsP);
    }
  }

virtual void MatrixFieldMapping::voxelToWorld	(	const V3d &	vsP,
		V3d &	wsP
	)		const `[inline, virtual]`

Transform from voxel space position into world space.

Implements FieldMapping.

Definition at line 396 of file FieldMapping.h.

References m_vsToWs.

  { m_vsToWs.multVecMatrix(vsP, wsP); }

virtual void MatrixFieldMapping::voxelToWorld	(	const V3d &	vsP,
		V3d &	wsP,
		float	time
	)		const `[inline, virtual]`

Implements FieldMapping.

Definition at line 398 of file FieldMapping.h.

References Curve< T >::linear(), m_isTimeVarying, m_vsToWs, and m_vsToWsCurve.

  { 
    if (!m_isTimeVarying) {
      m_vsToWs.multVecMatrix(vsP, wsP); 
    } else {
      M44d vsToWs = m_vsToWsCurve.linear(time);
      vsToWs.multVecMatrix(vsP, wsP);
    }
  }

virtual void MatrixFieldMapping::worldToLocal	(	const V3d &	wsP,
		V3d &	lsP
	)		const `[inline, virtual]`

Transform from world space position into local space.

Implements FieldMapping.

Definition at line 408 of file FieldMapping.h.

References m_wsToLs.

  { m_wsToLs.multVecMatrix(wsP, lsP); }

virtual void MatrixFieldMapping::worldToLocal	(	const V3d &	wsP,
		V3d &	lsP,
		float	time
	)		const `[inline, virtual]`

Implements FieldMapping.

Definition at line 410 of file FieldMapping.h.

References Curve< T >::linear(), m_isTimeVarying, m_lsToWsCurve, and m_wsToLs.

  { 
    if (!m_isTimeVarying) {
      m_wsToLs.multVecMatrix(wsP, lsP); 
    } else {
      M44d wsToLs = m_lsToWsCurve.linear(time).inverse();
      wsToLs.multVecMatrix(wsP, lsP);
    }
  }

virtual void MatrixFieldMapping::localToWorld	(	const V3d &	lsP,
		V3d &	wsP
	)		const `[inline, virtual]`

Transform from local space position into world space.

Implements FieldMapping.

Definition at line 421 of file FieldMapping.h.

References m_lsToWs.

  { m_lsToWs.multVecMatrix(lsP, wsP); }

virtual void MatrixFieldMapping::localToWorld	(	const V3d &	lsP,
		V3d &	wsP,
		float	time
	)		const `[inline, virtual]`

Implements FieldMapping.

Definition at line 423 of file FieldMapping.h.

References Curve< T >::linear(), m_isTimeVarying, m_lsToWs, and m_lsToWsCurve.

  { 
    if (!m_isTimeVarying) {
      m_lsToWs.multVecMatrix(lsP, wsP); 
    } else {
      M44d lsToWs = m_lsToWsCurve.linear(time);
      lsToWs.multVecMatrix(lsP, wsP);
    }
  }

void MatrixFieldMapping::worldToVoxelDir	(	const V3d &	wsV,
		V3d &	vsV
	)		const `[inline]`

Todo:: Generalize and make time-dependent.

Definition at line 434 of file FieldMapping.h.

References m_wsToVs.

  { m_wsToVs.multDirMatrix(wsV, vsV); }

void MatrixFieldMapping::voxelToWorldDir	(	const V3d &	vsV,
		V3d &	wsV
	)		const `[inline]`

Todo:: Generalize and make time-dependent.

Definition at line 438 of file FieldMapping.h.

References m_vsToWs.

  { m_vsToWs.multDirMatrix(vsV, wsV); }

void MatrixFieldMapping::worldToLocalDir	(	const V3d &	wsV,
		V3d &	lsV
	)		const `[inline]`

Todo:: Generalize and make time-dependent.

Definition at line 442 of file FieldMapping.h.

References m_wsToLs.

  { m_wsToLs.multDirMatrix(wsV, lsV); }

void MatrixFieldMapping::localToWorldDir	(	const V3d &	lsV,
		V3d &	wsV
	)		const `[inline]`

Todo:: Generalize and make time-dependent.

Definition at line 446 of file FieldMapping.h.

References m_lsToWs.

  { m_lsToWs.multDirMatrix(lsV, wsV); }

void MatrixFieldMapping::extentsChanged ( ) [virtual]

Implement this if the subclass needs to update itself when the resolution changes.

Reimplemented from FieldMapping.

Definition at line 238 of file FieldMapping.cpp.

References updateTransform().

{ 
  updateTransform();
}

std::string MatrixFieldMapping::className ( ) const [virtual]

Returns the FieldMapping type name. Used when writing/reading from disk.

Implements FieldMapping.

Definition at line 245 of file FieldMapping.cpp.

References classType().

{
  return std::string(classType());
}

bool MatrixFieldMapping::isIdentical	(	FieldMapping::Ptr	other,
		double	tolerance = `0.0`
	)		const `[virtual]`

Whether the mapping is identical to another mapping.

Implements FieldMapping.

Definition at line 252 of file FieldMapping.cpp.

References FIELD3D_NAMESPACE_OPEN::checkMatricesIdentical(), FIELD3D_NAMESPACE_OPEN::k_matrixMappingName(), m_lsToWsCurve, m_vsToWsCurve, and Curve< T >::samples().

{
  typedef MatrixFieldMapping::MatrixCurve::SampleVec SampleVec;

  if (other->className() != k_matrixMappingName) {
    return false;
  } else {

    MatrixFieldMapping::Ptr mm = 
      FIELD_DYNAMIC_CAST<MatrixFieldMapping>(other);

    if (mm) {

      const SampleVec lsToWs1 = m_lsToWsCurve.samples();
      const SampleVec lsToWs2 = mm->m_lsToWsCurve.samples();
      const SampleVec vsToWs1 = m_vsToWsCurve.samples();
      const SampleVec vsToWs2 = mm->m_vsToWsCurve.samples();

      size_t numSamples = lsToWs1.size();
      
      // First check if time sample counts differ
      // lsToWs and vsToWs are guaranteed to have same sample count.
      if (lsToWs1.size() != lsToWs2.size()) {
        return false;
      }
      
      // Then check if all time samples match, then check localToWorld 
      // and voxelToWorld matrices
      for (size_t i = 0; i < numSamples; ++i) {
        if (lsToWs1[i].first != lsToWs2[i].first) {
          return false;
        }
        if (!checkMatricesIdentical(lsToWs1[i].second, lsToWs2[i].second,
                                    tolerance)) {
          return false;
        }
        if (!checkMatricesIdentical(vsToWs1[i].second, vsToWs2[i].second,
                                    tolerance)) {
          return false;        
        }
      }

      return true;

    } else {
      return false;
    }
  }
  return false;
}

virtual V3d MatrixFieldMapping::wsVoxelSize	(	int	i,
		int	j,
		int	k
	)		const `[inline, virtual]`

Returns world-space size of a voxel at the specified coordinate.

Implements FieldMapping.

Definition at line 456 of file FieldMapping.h.

References m_wsVoxelSize.

  { return m_wsVoxelSize; }

FieldMapping::Ptr MatrixFieldMapping::clone ( ) const [virtual]

Returns a pointer to a copy of the mapping, pure virtual so ensure derived classes properly implement it.

Implements FieldMapping.

Definition at line 357 of file FieldMapping.cpp.

References MatrixFieldMapping().

{
  return Ptr(new MatrixFieldMapping(*this));
}

void MatrixFieldMapping::updateTransform ( ) [private]

Updates the local to world transformation matrix.

Definition at line 306 of file FieldMapping.cpp.

References Curve< T >::addSample(), Curve< T >::clear(), getLocalToVoxelMatrix(), Curve< T >::linear(), m_isTimeVarying, m_lsToWs, m_lsToWsCurve, m_vsToWs, m_vsToWsCurve, m_wsToLs, m_wsToVs, m_wsVoxelSize, Curve< T >::numSamples(), and Curve< T >::samples().

Referenced by extentsChanged(), makeIdentity(), and setLocalToWorld().

{
  typedef MatrixCurve::SampleVec::const_iterator SampleIter;

  // Build the voxel to world space transforms ---
  M44d lsToVs;
  getLocalToVoxelMatrix(lsToVs);
  M44d vsToLs = lsToVs.inverse();
  // Loop over all samples in lsToWs, append vsToLs and create new curve
  // Also handle the special case where lsToWs has no samples. In that
  // case m_vsToWsCurve still has to have one sample.
  const MatrixCurve::SampleVec &lsToWs = m_lsToWsCurve.samples();
  m_vsToWsCurve.clear();
  for (SampleIter i = lsToWs.begin(), end = lsToWs.end(); i != end; i++) {
    m_vsToWsCurve.addSample(i->first, vsToLs * i->second);
  }

  // See if the curve has more than just a single sample
  m_isTimeVarying = m_lsToWsCurve.numSamples() > 1;

  // Sample the time-varying transforms at time=0.0
  m_lsToWs = m_lsToWsCurve.linear(0.0);
  m_wsToLs = m_lsToWs.inverse();
  m_vsToWs = vsToLs * m_lsToWs;
  m_wsToVs = m_vsToWs.inverse();

  // Precompute the voxel size
  V3d voxelOrigin, nextVoxel;
  m_vsToWs.multVecMatrix(V3d(0, 0, 0), voxelOrigin);
  m_vsToWs.multVecMatrix(V3d(1, 0, 0), nextVoxel);
  m_wsVoxelSize.x = (nextVoxel - voxelOrigin).length();
  m_vsToWs.multVecMatrix(V3d(0, 1, 0), nextVoxel);
  m_wsVoxelSize.y = (nextVoxel - voxelOrigin).length();
  m_vsToWs.multVecMatrix(V3d(0, 0, 1), nextVoxel);
  m_wsVoxelSize.z = (nextVoxel - voxelOrigin).length();
}

void MatrixFieldMapping::getLocalToVoxelMatrix ( M44d & result ) [private]

Todo:: Unit test this

Definition at line 345 of file FieldMapping.cpp.

References FieldMapping::m_origin, and FieldMapping::m_res.

Referenced by updateTransform().

{
  // Local to voxel is a scale by the resolution of the field, offset
  // to the origin of the extents
  M44d scaling, translation;
  scaling.setScale(m_res);
  translation.setTranslation(m_origin);
  result = scaling * translation;
}