This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
GfRay Class Reference

Basic type: Ray used for intersection testing. More...

#include <ray.h>

Public Member Functions

 GfRay ()
 The default constructor leaves the ray parameters undefined.
 
 GfRay (const GfVec3d &startPoint, const GfVec3d &direction)
 This constructor takes a starting point and a direction.
 
GF_API void SetPointAndDirection (const GfVec3d &startPoint, const GfVec3d &direction)
 Sets the ray by specifying a starting point and a direction.
 
GF_API void SetEnds (const GfVec3d &startPoint, const GfVec3d &endPoint)
 Sets the ray by specifying a starting point and an ending point.
 
const GfVec3dGetStartPoint () const
 Returns the starting point of the segment.
 
const GfVec3dGetDirection () const
 Returns the direction vector of the segment.
 
GfVec3d GetPoint (double distance) const
 Returns the point that is distance units from the starting point along the direction vector, expressed in parametic distance.
 
GF_API GfRayTransform (const GfMatrix4d &matrix)
 Transforms the ray by the given matrix.
 
GF_API GfVec3d FindClosestPoint (const GfVec3d &point, double *rayDistance=NULL) const
 Returns the point on the ray that is closest to point.
 
bool operator== (const GfRay &r) const
 Component-wise equality test.
 
bool operator!= (const GfRay &r) const
 Component-wise inequality test.
 
Intersection methods.

The methods in this group intersect the ray with a geometric entity.

GF_API bool Intersect (const GfVec3d &p0, const GfVec3d &p1, const GfVec3d &p2, double *distance=NULL, GfVec3d *barycentricCoords=NULL, bool *frontFacing=NULL, double maxDist=std::numeric_limits< double >::infinity()) const
 Intersects the ray with the triangle formed by points p0, p1, and p2, returning true if it hits.
 
GF_API bool Intersect (const GfPlane &plane, double *distance=NULL, bool *frontFacing=NULL) const
 Intersects the ray with a plane, returning true if the ray is not parallel to the plane and the intersection is within the ray bounds.
 
GF_API bool Intersect (const GfRange3d &box, double *enterDistance=NULL, double *exitDistance=NULL) const
 Intersects the ray with an axis-aligned box, returning true if the ray intersects it at all within bounds.
 
GF_API bool Intersect (const GfBBox3d &box, double *enterDistance=NULL, double *exitDistance=NULL) const
 Intersects the ray with an oriented box, returning true if the ray intersects it at all within bounds.
 
GF_API bool Intersect (const GfVec3d &center, double radius, double *enterDistance=NULL, double *exitDistance=NULL) const
 Intersects the ray with a sphere, returning true if the ray intersects it at all within bounds.
 
GF_API bool Intersect (const GfVec3d &origin, const GfVec3d &axis, const double radius, double *enterDistance=NULL, double *exitDistance=NULL) const
 Intersects the ray with an infinite cylinder, with axis axis, centered at the origin, with radius radius.
 
GF_API bool Intersect (const GfVec3d &origin, const GfVec3d &axis, const double radius, const double height, double *enterDistance=NULL, double *exitDistance=NULL) const
 Intersects the ray with an infinite non-double cone, centered at origin, with axis axis, radius radius and apex at height.
 

Friends

GF_API friend bool GfFindClosestPoints (const GfRay &, const GfLine &, GfVec3d *, GfVec3d *, double *, double *)
 Computes the closest points between a ray and a line.
 
GF_API friend bool GfFindClosestPoints (const GfRay &, const GfLineSeg &, GfVec3d *, GfVec3d *, double *, double *)
 Computes the closest points between a ray and a line segment.
 

Detailed Description

Basic type: Ray used for intersection testing.

This class represents a three-dimensional ray in space, typically used for intersection testing. It consists of an origin and a direction.

Note that by default a GfRay does not normalize its direction vector to unit length.

Note for ray intersections, the start point is included in the computations, i.e., a distance of zero is defined to be intersecting.

Definition at line 44 of file ray.h.

Constructor & Destructor Documentation

◆ GfRay() [1/2]

GfRay ( )
inline

The default constructor leaves the ray parameters undefined.

Definition at line 49 of file ray.h.

◆ GfRay() [2/2]

GfRay ( const GfVec3d startPoint,
const GfVec3d direction 
)
inline

This constructor takes a starting point and a direction.

Definition at line 53 of file ray.h.

Member Function Documentation

◆ FindClosestPoint()

GF_API GfVec3d FindClosestPoint ( const GfVec3d point,
double *  rayDistance = NULL 
) const

Returns the point on the ray that is closest to point.

If rayDistance is not NULL, it will be set to the parametric distance along the ray of the closest point.

◆ GetDirection()

const GfVec3d & GetDirection ( ) const
inline

Returns the direction vector of the segment.

This is not guaranteed to be unit length.

Definition at line 73 of file ray.h.

◆ GetPoint()

GfVec3d GetPoint ( double  distance) const
inline

Returns the point that is distance units from the starting point along the direction vector, expressed in parametic distance.

Definition at line 79 of file ray.h.

◆ GetStartPoint()

const GfVec3d & GetStartPoint ( ) const
inline

Returns the starting point of the segment.

Definition at line 67 of file ray.h.

◆ Intersect() [1/7]

GF_API bool Intersect ( const GfBBox3d box,
double *  enterDistance = NULL,
double *  exitDistance = NULL 
) const

Intersects the ray with an oriented box, returning true if the ray intersects it at all within bounds.

If there is an intersection, this also returns the parametric distances to the two intersection points in enterDistance and exitDistance.

◆ Intersect() [2/7]

GF_API bool Intersect ( const GfPlane plane,
double *  distance = NULL,
bool *  frontFacing = NULL 
) const

Intersects the ray with a plane, returning true if the ray is not parallel to the plane and the intersection is within the ray bounds.

If there is an intersection, it also returns the parametric distance to the intersection point in distance and the front-facing flag in frontFacing, if they are not NULL. The front-facing flag is true if the intersection is on the side of the plane in which its normal points.

◆ Intersect() [3/7]

GF_API bool Intersect ( const GfRange3d box,
double *  enterDistance = NULL,
double *  exitDistance = NULL 
) const

Intersects the ray with an axis-aligned box, returning true if the ray intersects it at all within bounds.

If there is an intersection, this also returns the parametric distances to the two intersection points in enterDistance and exitDistance.

◆ Intersect() [4/7]

GF_API bool Intersect ( const GfVec3d center,
double  radius,
double *  enterDistance = NULL,
double *  exitDistance = NULL 
) const

Intersects the ray with a sphere, returning true if the ray intersects it at all within bounds.

If there is an intersection, returns the parametric distance to the two intersection points in enterDistance and exitDistance.

◆ Intersect() [5/7]

GF_API bool Intersect ( const GfVec3d origin,
const GfVec3d axis,
const double  radius,
const double  height,
double *  enterDistance = NULL,
double *  exitDistance = NULL 
) const

Intersects the ray with an infinite non-double cone, centered at origin, with axis axis, radius radius and apex at height.

Returns true if the ray intersects it at all within bounds. If there is an intersection, returns the parametric distance to the two intersection points in enterDistance and exitDistance.

Note this method does not validate whether the radius are height are valid.

◆ Intersect() [6/7]

GF_API bool Intersect ( const GfVec3d origin,
const GfVec3d axis,
const double  radius,
double *  enterDistance = NULL,
double *  exitDistance = NULL 
) const

Intersects the ray with an infinite cylinder, with axis axis, centered at the origin, with radius radius.

Returns true if the ray intersects it at all within bounds. If there is an intersection, returns the parametric distance to the two intersection points in enterDistance and exitDistance.

Note this method does not validate whether the radius is valid.

◆ Intersect() [7/7]

GF_API bool Intersect ( const GfVec3d p0,
const GfVec3d p1,
const GfVec3d p2,
double *  distance = NULL,
GfVec3d barycentricCoords = NULL,
bool *  frontFacing = NULL,
double  maxDist = std::numeric_limits< double >::infinity() 
) const

Intersects the ray with the triangle formed by points p0, p1, and p2, returning true if it hits.

If there is an intersection, it also returns the parametric distance to the intersection point in distance, the barycentric coordinates of the intersection point in barycentricCoords and the front-facing flag in frontFacing. The barycentric coordinates are defined with respect to the three vertices taken in order. The front-facing flag is true if the intersection hit the side of the triangle that is formed when the vertices are ordered counter-clockwise (right-hand rule). If any of the return pointers are NULL, the corresponding values are not returned.

If the distance to the intersection is greater than maxDist, then the method will return false.

Barycentric coordinates are defined to sum to 1 and satisfy this relationsip:

intersectionPoint = (barycentricCoords[0] * p0 +
barycentricCoords[1] * p1 +
barycentricCoords[2] * p2);

◆ operator!=()

bool operator!= ( const GfRay r) const
inline

Component-wise inequality test.

The starting points, directions, and lengths must match exactly for rays to be considered equal.

Definition at line 103 of file ray.h.

◆ operator==()

bool operator== ( const GfRay r) const
inline

Component-wise equality test.

The starting points, directions, and lengths must match exactly for rays to be considered equal.

Definition at line 96 of file ray.h.

◆ SetEnds()

GF_API void SetEnds ( const GfVec3d startPoint,
const GfVec3d endPoint 
)

Sets the ray by specifying a starting point and an ending point.

◆ SetPointAndDirection()

GF_API void SetPointAndDirection ( const GfVec3d startPoint,
const GfVec3d direction 
)

Sets the ray by specifying a starting point and a direction.

◆ Transform()

GF_API GfRay & Transform ( const GfMatrix4d matrix)

Transforms the ray by the given matrix.

Friends And Related Function Documentation

◆ GfFindClosestPoints [1/2]

GF_API friend bool GfFindClosestPoints ( const GfRay ,
const GfLine ,
GfVec3d ,
GfVec3d ,
double *  ,
double *   
)
friend

Computes the closest points between a ray and a line.

The two points are returned in rayPoint and linePoint. The parametric distance of each point on the lines is returned in rayDistance and lineDistance.

This returns false if the lines were close enough to parallel that no points could be computed; in this case, the other return values are undefined.

◆ GfFindClosestPoints [2/2]

GF_API friend bool GfFindClosestPoints ( const GfRay ,
const GfLineSeg ,
GfVec3d ,
GfVec3d ,
double *  ,
double *   
)
friend

Computes the closest points between a ray and a line segment.

The two points are returned in rayPoint and segPoint. The parametric distance of each point is returned in rayDistance and segDistance.

This returns false if the lines were close enough to parallel that no points could be computed; in this case, the other return values are undefined.


The documentation for this class was generated from the following file: