NearestPolygon3dFeature (Artisynth API documentation)

java.lang.Object
- maspack.collision.NearestPolygon3dFeature

public class NearestPolygon3dFeature
extends java.lang.Object

Given one more 3D planar polygons in a common plane, this class calculates and stores their nearest feature to a point. This will be either a vertex or an edge.

The method is used as follows:


 Point3d px;   // point to find nearest feature for
 Vector3d nrm; // normal of the plane containing the polygon
 double dtol;  // distance tolerance. polygon vertices whose distance to
               // a previous vertex is <= dotl will be ignored

 // to calculate nearest feature of a single polygon               
 NearestPolygon3dFeature nfeat = new NearestPolygon3dFeature();
 nfeat.init (px, nrm, dtol);
 for (each point p on the polygon) {
    nfeat.advance (p);
 }
 nfeat.close(); // call only if the polygon is closed

 // to calculate nearest feature for multiple polygons
 NearestPolygon3dFeature nfeat = new NearestPolygon3dFeature();
 nfeat.init (px, nrm, dtol);
 for (each polygon) {
    nfeat.restart(); // don't need to call if previous polygon was closed
    for (each point p on the polygon) {
       nfeat.advance (p);
    }
    nfeat.close(); // call only if the polygon is closed
 }

Once the calculation is done, information about the feature can be queried with the following methods:


 int numVertices();              // number of vertices defining the feature
 Point3d getVertext(int k);      // the k-th feature vertex
 Point3d getNearestPoint();      // nearest point on the polygon(s)
 double getDistance();           // distance to the feature
 boolean isOutside(boolean clockwise); // is the point outside the polygon

Constructor Summary

Constructors
Constructor and Description

NearestPolygon3dFeature()
Creates a new NearestPolygon3dFeature.

Constructors
Constructor and Description
`NearestPolygon3dFeature()` Creates a new NearestPolygon3dFeature.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`advance(Point3d pv)` Provides a new vertex for the current input polygon.
`void`	`close()` Closes off the current input polygon and calls `restart()`.
`double`	`getDistance()` Returns the distance to the nearest feature, or -1 if no feature has been determined yet.
`Point3d`	`getNearestPoint()` Returns the nearest point on the nearest fearure, or `null` if no feature has been determined yet.
`Point3d`	`getPoint()` Returns the reference point for which the nearest feature is determined.
`Point3d`	`getVertex(int idx)` Returns the `idx`-th polygon vertex associated with this feature.
`void`	`init(Point3d px, Vector3d nrm, double dtol)` Initializes this NearestPolygon3dFeature to input one or more polygons
`int`	`isOutside(boolean clockwise)` Determines if the reference point is ''outside'' its nearest feature, based on whether the polygons are assumed to be oriented clockwise or counter-clockwise.
`int`	`numVertices()` Returns the number of polygon vertices associated with this feature: 0: no feature is currently defined 1: feature is a single polygon vertex; no edges have been encountered 2: feature is an edge 3: feature is the vertex indexed by 1, with 0 and 2 indexing the previous and following vertices
`void`	`print(java.lang.String msg)` Prints out a description of this feature.
`void`	`restart()` Marks the start of a new polygon in the current sequence of input polygons.
`void`	`start()` Marks the start of a new sequence of input polygons.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - NearestPolygon3dFeature
```
public NearestPolygon3dFeature()
```
    Creates a new NearestPolygon3dFeature.
- Method Detail
  - init
```
public void init(Point3d px,
                 Vector3d nrm,
                 double dtol)
```
    Initializes this NearestPolygon3dFeature to input one or more polygons
    
    Parameters:
    
    px - point to compute nearest feature for
    
    nrm - normal of plane containing the polygons
    
    dtol - distance tolerance. Polygonal vertices whose distance to the previous vertex is <= dtol will be ignored.
  - numVertices
```
public int numVertices()
```
    Returns the number of polygon vertices associated with this feature:
    - 0: no feature is currently defined
    - 1: feature is a single polygon vertex; no edges have been encountered
    - 2: feature is an edge
    - 3: feature is the vertex indexed by 1, with 0 and 2 indexing the previous and following vertices
    Returns:
    
    number of feature vertices
  - getVertex
```
public Point3d getVertex(int idx)
```
    Returns the idx-th polygon vertex associated with this feature.
    
    Parameters:
    
    idx - vertex index. Should be less than the value returned by numVertices().
    
    Returns:
    
    idx-th polygon vertex. Value is a reference and should not be modified.
  - getPoint
```
public Point3d getPoint()
```
    Returns the reference point for which the nearest feature is determined.
    
    Returns:
    
    nearest feature reference point
  - getDistance
```
public double getDistance()
```
    Returns the distance to the nearest feature, or -1 if no feature has been determined yet.
    
    Returns:
    
    distance to the nearest feature.
  - getNearestPoint
```
public Point3d getNearestPoint()
```
    Returns the nearest point on the nearest fearure, or null if no feature has been determined yet.
    
    Returns:
    
    nearest point on the nearest feature
  - start
```
public void start()
```
    Marks the start of a new sequence of input polygons. Previous feature information is discarded.
  - restart
```
public void restart()
```
    Marks the start of a new polygon in the current sequence of input polygons. Previous feature information is kept. There is no need to call this method if the previous polygon was terminated using close().
  - isOutside
```
public int isOutside(boolean clockwise)
```
    Determines if the reference point is ''outside'' its nearest feature, based on whether the polygons are assumed to be oriented clockwise or counter-clockwise.
    
    Parameters:
    
    clockwise - if true, indicates that the polygons are oriented clockwise
    
    Returns:
    
    true if the reference point is outside its nearest feature
  - advance
```
public void advance(Point3d pv)
```
    Provides a new vertex for the current input polygon.
    
    Parameters:
    
    pv - position of the polygon vertex.
  - close
```
public void close()
```
    Closes off the current input polygon and calls restart().
  - print
```
public void print(java.lang.String msg)
```
    Prints out a description of this feature.
    
    Parameters:
    
    msg - optional message line

Class NearestPolygon3dFeature

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

NearestPolygon3dFeature

Method Detail

init

numVertices

getVertex

getPoint

getDistance

getNearestPoint

start

restart

isOutside

advance

close

print