Gets the list of entities that are hit when a ray is fired at one or more entities.
Role: This API fires a ray at an array of entities from the given ray
point in the given ray direction with the given ray radius. It returns a list
that contains the n entities nearest the ray point (where n is the number of
hits recorded) and an array that holds the n parameter values of the points
along the ray. Only entities in the forward direction along the ray can be hit.
hits_wanted indicates the maximum number of hits to return. To return all hits,
specify hits_wanted as zero.
If ray_parameters is not NULL, it must point to an array of doubles large enough
to hold all of the returned parameters. When ray_parameters is specified as NULL,
an array large enough to hold the returned parameters is allocated and its
address is returned. The caller is responsible for deleting the array. When
several connected entities are wanted; e.g., all edges of a face, pick one
entity the face and the others are found by following the model pointers.
A face-ray intersection counts whether the ray enters or leaves the face. If the
ray hits the interior of a face at a point at least the length of the ray radius
from any edge or vertex of the face, it returns the face. If it hits an edge of
a face or passes within ray radius of the edge, it returns the edge. If it
passes within ray radius of a vertex, it returns the vertex.
To pick edges or vertices, it is often helpful to increase the ray radius, but
to pick a face, keep the ray radius small to avoid picking edges or vertices of
the face. If the ray lies in the surface (planar or ruled) of a face and crosses
the interior of the face, the edges or vertices of the face are returned.
If the ray hits an entity more than once, only the hit at the smallest ray
parameter is returned. A ray test applied to a body is made in the global space
of the body, and tests all faces, edges, and vertices of the lumps and wires of
the body in global body space.
This API fires a ray at a subset of the entities in a body; e.g., at a set of
faces already selected in some way. Ray tests applied to other entities (wires,
lumps, shells, subshells, faces, edges, or vertices) given directly in the array
of entities are made in the local space of the entity.
A call to this API will cause bounding boxes to be computed, causing a model
change and creating a bulletin board. To make the process read-only, call
api_note_state before the call to api_ray_test_ents.
Errors: Zero length ray_direction specified.
Ray radius less than SPAresabs.
Entity pointer in array is NULL.
Effect: Changes model
Journal: Available
Parameters:
ray_point
starting point of ray.
ray_direction
direction of the ray.
ray_radius
radius of ray.
hits_wanted
number of hits requested.
n_target_ents
number of target entities.
target_ents
array of target entities.
entities_hit
list of entities hit returned.
ray_parameters
parameters of the ray returned.
ao
ACIS options.
This object is included in the file: intrapi.hxx
Copyright (c) 1989-2007 by Spatial Corp. All rights reserved.