 |
PK_CURVE_find_vectors_o_t |
|
struct PK_CURVE_find_vectors_o_s
{
int o_t_version; --- option structure version
int n_measurements; --- number of measurements
--- (1)
double *measurements; --- values of the measurements
--- (0.5)
PK_measure_t measurement_method; --- what 'measurements' measure
--- (PK_measure_chord_ratio_c)
PK_ERROR_on_fail_t error_on_failure; --- when to return error
--- indicating failure.
--- (PK_ERROR_on_fail_no_c)
};
typedef struct PK_CURVE_find_vectors_o_s PK_CURVE_find_vectors_o_t;
This structure holds controls for PK_CURVE_find_vectors
Used in:
PK_CURVE_find_vectors
The option structure allows the caller to control how the position vectors
on the curve are determined.
Notation: The "start point" of the curve is the position vector corresponding
to evaluating the curve at the lower boundary of the supplied
interval 't_int'.
The "end point" of the curve is the position vector corresponding
to evaluating the curve at the upper boundary of the supplied
interval 't_int'.
The "bounded length" of the curve is the length of the curve measured
along the curve from the start point to the end point.
n_measurements:
---------------
The number of values supplied in 'measurements'.
measurements:
-------------
The values supplied are either distances or ratios of distances measured in
3-space. If they are distance measurements they may neither be negative nor
exceed the length of their reference object ( see below ). If they are ratios
they may neither be negative nor greater than 1.
measurement_method:
-------------------
This enum determines what the values in 'measurements' represent.
'measurement_method' can be set to one of:
PK_measure_distance_c
All values in 'measurements' are distances measured along the curve from
the start point.
For each distance in 'measurements' a position vector will be returned
such that the distance along the curve from the start point to the
position vector equals the given distance.
Note that no position vector will be returned for values in
'measurements' that are negative or larger than the bounded length of the
curve.
PK_measure_distance_ratio_c
All values in 'measurements' are ratios of distances measured along the
curve from the start point to the bounded length of the curve.
For each ratio of distances in 'measurements' a position vector will be
returned such that the ratio of the distance along the curve from the
start point to the position vector to the bounded length of the curve
equals the given ratio.
Note that no position vector will be returned for values in
'measurements' that are negative or larger than 1.
PK_measure_chord_c
The chord is the straight line from the start point to the end point.
All values in 'measurements' are distances measured along the chord
from the start point.
For each distance in 'measurements' all position vectors on the curve
that satisfy the following condition will be returned:
they lie
i) on the curve between the start and end points
AND
ii) in the plane which is orthogonal to the chord and which is
located at the given distance from the start point.
Note that there may be several position vectors returned for each value
in 'measurements'.
Furthermore, no position vector will be returned for values in
'measurements' that are negative or larger than the length of the
chord.
PK_measure_chord_ratio_c
The chord is the straight line from the start point to the end point.
All values in 'measurements' are ratios of distances measured along the
chord from the start point to the bounded length of the chord.
For each ratio in 'measurements' all position vectors on the curve
that satisfy the following condition will be returned:
they lie
i) on the curve between the start and end points
AND
ii) in the plane which is orthogonal to the chord and which is
located at a distance from the start point such that the ratio
of this distance to the bounded length of the chord equals the
given ratio.
Note that there may be several position vectors returned for each value
in 'measurements'.
Furthermore, no position vector will be returned for values in
'measurements' that are negative or larger than 1.
PK_measure_2_chords_ratio_c
Let P be any point on the curve. Let A be the length of the chord from
the start point to P, and let B be the length of the chord from P to
the end point.
All values in 'measurements' are ratios A / ( A + B ).
For each ratio in 'measurements' all position vectors S on the curve
that satisfy the following condition will be returned:
i) S lies on the curve between the start and end points
AND
ii) the ratio of the lengths of the chord from the start point
to S to the bounded length of the two chords from the start
point to S and from S to the end point is equal to the given
ratio.
Note that there may be several position vectors returned for each value
in 'measurements'.
Furthermore, no position vector will be returned for values in
'measurements' that are negative or larger than 1.
In general the computational cost of the methods involving chord measurements
is lower than the methods involving true curve lengths or ratios of such.
error_on_failure:
-----------------
This enum determines when the error PK_ERROR_cant_get_vectors will be
returned. It can be set to:
PK_ERROR_on_fail_any_c
The error PK_ERROR_cant_get_vectors will be returned unless the
operation is successful for all values in 'measurements'.
PK_ERROR_on_fail_all_c
The error PK_ERROR_cant_get_vectors will be returned if the
operation is successful for none of the values in 'measurements'.
PK_ERROR_on_fail_no_c
The error PK_ERROR_cant_get_vectors will not be returned.