bvIntersector.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies, Inc.
** All rights reserved.
*******************************************************************************/
/*******************************************************************************
** $RCSfile: bvIntersector.h,v $ $Revision: 1.6 $ $State: Exp $
*******************************************************************************/

#ifndef bvIntersector_H
#define bvIntersector_H

class Dt3dBoundingVolume;
class DtDcm;

#include "geometry/geometryDefines.h"
#include "geometry/boundingVolumeFace.h"
#include <matrix/vlVector.h>

// ------------------
// Fast how to use guide:
// ------------------
//    Test a bounding volume for intersection with another object 
//    by passing the following parameters:
//          Bounding volume of interest,
//          Position and orientation of the BV, 
//          Other object with which you wish to test intersection, 
//          Position and orientation of the other object.
//
//    Note:
//    The positions and orientations can be in ANY coordinate system,
//    provided:
//          1. they are ALL defined in the SAME CS.
//          2. the coordinate system has the same scale as the dimensions.
//             (we typically use meters for everything, so you shouldn't
//             have to worry about this ever)
//          3. it is a Cartesian coordinate system (not polar, cylindrical etc.)
//
//
// ------------------
// High level concepts:
// ------------------
//
// Please read the bounding volume header.  I don't want to replicate
// information here, since the chances of it getting out of date are too
// high.
//
// A bounding volume (BV) is like a box, with a length, width and height.
// It is centered at an origin.  The origin may be offset from a position.
//
// So, the conceptual pieces of any bounding volume in any coordinate system are:
//    1. dimensions of the "box" 
//    2. position of the box
//    3. offset of the origin from the position, may be zero. 
//    4. orientation of the box, relative to the coordinate system
//
// There are three coordinate systems (CSs) involved:
//    1. The lattice coordinate system in which the first BV is defined.
//    2. The lattice coordinate system in which the second object is defined.
//    3. The reference, or common coordinate system.  This the is CS
//       in which both objects can be concurrently situated.  
//       Often it is the CS of the terrain database. 
//       The position and orientation we specify are in this common,
//       reference CS.
//
// We also need a way of "moving" from one coordinate system to the other.
// This is called a transformation.  The scales are the same in all of our
// coordinate systems.  Hence, compared to an arbitrary CS transformation,
// we can optimize our transformation and use just a translation and a 
// rotation (orientation).
//
//
//  ***                                                                  *** 
//  *   Some might find this conceptually hard, but it is key to           *
//  *   to understanding:                                                  *
//  *   The transformation from lattice to reference coordinate systems    *
//  *   is the same as the transformation from the origin in reference     *
//  *   coordinates to the orientation in reference coordinates.           * 
//  *   i.e. you can use the same transformation to either switch between  *
//  *   two different coordinate systems, or to switch between two         *
//  *   locations in the same coordinate system.                           *
//  ***                                                                  *** 
//  
//
// So, the conceptual pieces of a bounding volume, and the coordinate
// system in which they are specified are:
//    - (latticeCS) dimensions of the "box" 
//    - (latticeCS) position of the box (always zero)
//    - (latticeCS) offset of the origin from the local position, may be zero. 
//    - (latticeCS) origin (local position + local offset)
//    - (latticeCS) orientation of the box (always the same as the latticeCS)
//
//    - (refCS) dimensions of the "box" (always same as lattice dimensions)
//    - (refCS) position (often of an associated entity) 
//    - (refCS) offset of the origin from the reference position, may be zero. 
//    - (refCS) origin (reference position + reference offset)
//    - (refCS) orientation of the box 
//
//    - transformation from the latticeCS to the refCS
//       - translation (same as refCS position)
//       - rotation    (same as refCS orientation)
//       - scale       (always 1 since we have defined it that way)
//       - skew        (never skewed since we have defined it that way)
//
//

class DT_DLL_geometry DtBvIntersector
{

public: // constructors, operators etc.

   DtBvIntersector();
   DtBvIntersector( const DtBvIntersector & orig );

   virtual ~DtBvIntersector();

   DtBvIntersector& operator=( const DtBvIntersector & orig );


public:
   // Intersection tests
   //
   // Test if a bounding volume would intersect with another object
   // were they at the given positions and orientations which are
   // all specified in the common reference coordinate system.

   // Bounding volume & bounding volume intersection.
   virtual bool intersectsBoundingVolume(
      const Dt3dBoundingVolume & bv,
      const DtVector& bvPosition, const DtDcm& bvOrientation,
      const Dt3dBoundingVolume & secondBV,
      const DtVector& secondBVPosition, const DtDcm& secondBVOrientation ) const;

   // Bounding volume & point intersection.
   virtual bool intersectsPoint(
      const Dt3dBoundingVolume& bv,
      const DtVector& bvPosition, const DtDcm& bvOrientation,
      const DtVector& pointPosition ) const;

   // Bounding volume & chord intersection.
   //
   // If there was an intersection, distInChordLengthsFirst and
   // distInChordLengthslast give the distance along the chord in chord
   // lengths to the first and last encounters with the bounding volume along
   // the line.  If the chord represents velocity, these are the enter and
   // exit times.  The faces of the first and last encounters are faceFirst
   // and faceLast.
   virtual bool intersectsLineOfChord(
      const Dt3dBoundingVolume & bv,
      const DtVector& bvPosition, const DtDcm& bvOrientation,
      const DtVector& point1, const DtVector& point2,
      double& distInChordLengthsFirst, double& distInChordLengthsLast,
      DtBoundingVolumeFace& faceFirst, DtBoundingVolumeFace& faceLast ) const;

   // Bounding volume & chord intersection.
   //
   // The following method performs the same as the above, plus returns the
   // points of the first and last encounters with the bounding volume along
   // the line (pointFirst and pointLast).
   virtual bool intersectsLineOfChord(
      const Dt3dBoundingVolume & bv,
      const DtVector& bvPosition, const DtDcm& bvOrientation,
      const DtVector& point1, const DtVector& point2,
      double& distInChordLengthsFirst, double& distInChordLengthsLast,
      DtBoundingVolumeFace& faceFirst, DtBoundingVolumeFace& faceLast,
      DtVector& pointFirst, DtVector& pointLast ) const;

   // The following method returns the incidence angle between a
   // vector and a face of a bounding volume.  The orientation of the
   // BV is passed to the routine along with a ray. 
   // The returned angle is always positive and in radians.
   virtual double incidenceAngle(const Dt3dBoundingVolume & bv,
      const DtDcm & bvOrientation,
      const DtVector& rayWorld, 
      DtBoundingVolumeFace& face) const;

protected:
   // If the bounding spheres don't intersect, there is no way the bounding 
   // volumes can intersect.
   // However, the converse is not true, i.e. false positives are possible
   // with this test.  Use as a fast first test.
   virtual bool intersectsMaxBoundingSphere(const Dt3dBoundingVolume & bv,
      const DtVector & bvPosition,
      const Dt3dBoundingVolume& secondBV,
      const DtVector & secondBVPosition) const;

public:
   // Updates world bounding volume based on lattice BV and reference orientation.
   virtual DtDcm calcRefBV(const Dt3dBoundingVolume & bv,
                            const DtVector & bvPosition,
                            const DtDcm& latticeToRef ) const;

   // Updates origin based on oriented BV and offset.
   virtual DtVector calcRefOrigin(const Dt3dBoundingVolume & bv,
                                   const DtVector & bvPosition,
                                   const DtDcm& latticeToRef ) const;

protected:
   // The following method takes a column vector from a bounding
   // volume matrix (columnVector), two faces perpendicular to this
   // column vector (facePos and faceNeg), a vector giving the center
   // of a bounding volume (point1ToBVCenter), and a ray (ray) and
   // uses them to refine intersection parameters passed
   // to it.  These intersection parameters are the distance of
   // first encounter (distFirst), distance of last encounter
   // (distLast), face of first encounter (faceFirst), and face of
   // last encounter (faceLast).  The routine returns false if
   // there is no chance of further intersection, otherwise it
   // returns true.
   virtual bool refineSegmentIntersection(
      const DtVector& columnVector, const DtVector& point1ToBVCenter,
      const DtVector& ray, double& distFirst, double& distLast,
      DtBoundingVolumeFace& faceFirst, DtBoundingVolumeFace& faceLast,
      const DtBoundingVolumeFace facePos, const DtBoundingVolumeFace faceNeg) const;

protected:
   // No member data.  
   // Member data may be added later to hold temporary values as
   // an optimization step.
   
};


#endif