Table of contents
CSPICE_VPRJPI calculates the vector in a specified plane that
maps under orthogonal projection to a specified vector in
another plane.
Given:
vin a double precision 3-vector.
help, vin
DOUBLE = Array[3]
projpl a SPICE plane structure, describing a SPICE plane that
represents the geometric plane containing 'vin'.
help, projpl
STRUCT = CSPICE_PLANE
The structure has the fields:
normal: [3-array double]
constant: [scalar double]
invpl a SPICE plane structure, describing a SPICE plane that
represents the geometric plane containing the inverse image of
'vin' under orthogonal projection onto 'projpl'.
help, invpl
STRUCT = CSPICE_PLANE
The structure has the fields:
normal: [3-array double]
constant: [scalar double]
the call:
cspice_vprjpi, vin, projpl, invpl, vout, found
returns:
vout the double precision 3-vector inverse orthogonal projection of
'vin'.
help, vout
DOUBLE = Array[3]
This is the vector lying in the plane 'invpl' whose orthogonal
projection onto the plane 'projpl' is 'vin'. 'vout' is valid
only when 'found' is true. Otherwise, 'vout' is undefined.
found a scalar boolean flag, indicating whether the inverse orthogonal
projection of 'vin' could be computed.
help, found
BOOLEAN = Scalar
'found' is true if so, false otherwise.
None.
Any numerical results shown for this example may differ between
platforms as the results depend on the SPICE kernels used as input
and the machine specific arithmetic implementation.
1) Suppose
vin = ( 0.0, 1.0, 0.0 ),
and that `projpl', the SPICE plane that represents the geometric
plane containing `vin', the has normal vector
projn = ( 0.0, 0.0, 1.0 ).
Also, let's suppose that `invpl' has normal vector and constant
invn = ( 0.0, 2.0, 2.0 )
invc = 4.0.
Then `vin' lies on the y-axis in the x-y plane, and we want to
find the vector `vout' lying in `invpl' such that the orthogonal
projection of `vout' the x-y plane is `vin'. Let the notation
< a, b > indicate the inner product of vectors a and b.
Since every point x in `invpl' satisfies the equation
< x, (0.0, 2.0, 2.0) > = 4.0,
we can verify by inspection that the vector
( 0.0, 1.0, 1.0 )
is in `invpl' and differs from `vin' by a multiple of `projn'. So
( 0.0, 1.0, 1.0 )
must be `vout'.
The following code example is used to find this result
using Icy.
Example code begins here.
PRO vprjpi_ex1
;;
;; Define a vector in plane1...
;;
vec = [ 0.d, 1.d, 0.d]
;;
;; Construct 2 planes. Define the normal vectors for both
;; planes and constant for the inverse plane.
;;
norm1 = [ 0.d, 0.d, 1.d]
norm2 = [ 0.d, 2.d, 2.d]
con2 = 4.0d
;;
;; Create the SPICE planes
;;
cspice_nvp2pl, norm1, vec, plane1
cspice_nvc2pl, norm2, con2, plane2
;;
;; Calculate the inverse projection to plane2.
;;
cspice_vprjpi, vec, plane1, plane2, vec_iproj, found
if ( found ) then begin
print, FORMAT='(A,3F12.6)', 'Found an inverse vector:', $
vec_iproj
endif else begin
print, 'Could not find the inverse vector.'
endelse
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
Found an inverse vector: 0.000000 1.000000 1.000000
Projecting a vector orthogonally onto a plane can be thought of
as finding the closest vector in the plane to the original vector.
This "closest vector" always exists; it may be coincident with the
original vector. Inverting an orthogonal projection means finding
the vector in a specified plane whose orthogonal projection onto
a second specified plane is a specified vector. The vector whose
projection is the specified vector is the inverse projection of
the specified vector, also called the "inverse image under
orthogonal projection" of the specified vector. This routine
finds the inverse orthogonal projection of a vector onto a plane.
Related routines are cspice_vprjp, which projects a vector onto a plane
orthogonally, and cspice_vproj, which projects a vector onto another
vector orthogonally.
1) If the normal vector of either input plane does not have unit
length (allowing for round-off error), the error
SPICE(NONUNITNORMAL) is signaled by a routine in the call tree
of this routine.
2) If the geometric planes defined by `projpl' and `invpl' are
orthogonal, or nearly so, the inverse orthogonal projection
of `vin' may be undefined or have magnitude too large to
represent with double precision numbers. In either such
case, `found' will be set to False.
3) Even when `found' is True, `vout' may be a vector of extremely
large magnitude, perhaps so large that it is impractical to
compute with it. It's up to you to make sure that this
situation does not occur in your application of this routine.
4) If any of the input arguments, `vin', `projpl' or `invpl', is
undefined, an error is signaled by the IDL error handling
system.
5) If any of the input arguments, `vin', `projpl' or `invpl', is
not of the expected type, or it does not have the expected
dimensions and size, an error is signaled by the Icy
interface.
6) If any of the output arguments, `vout' or `found', is not a
named variable, an error is signaled by the Icy interface.
None.
1) It is recommended that the input planes be created by one of
the Icy routines
cspice_nvc2pl ( Normal vector and constant to plane )
cspice_nvp2pl ( Normal vector and point to plane )
cspice_psv2pl ( Point and spanning vectors to plane )
In any case each input plane must have a unit length normal
vector and a plane constant consistent with the normal
vector.
ICY.REQ
[1] G. Thomas and R. Finney, "Calculus and Analytic Geometry,"
7th Edition, Addison Wesley, 1988.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.0.3, 10-AUG-2021 (JDR)
Edited the -Examples section to comply with NAIF standard. Added
example's problem statement and modified example code to parallel
other toolkit's documentation.
Added -Parameters, -Exceptions, -Files, -Restrictions,
-Literature_References and -Author_and_Institution sections, and
completed -Particulars section.
Removed reference to the routine's corresponding CSPICE header from
-Abstract section.
Added arguments' type and size information in the -I/O section.
-Icy Version 1.0.2, 23-NOV-2010 (EDW)
Edit to example code comments and 'vec' assignment eliminating typos.
-Icy Version 1.0.1, 02-MAY-2005 (EDW)
Corrected typo in description of 'found'.
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
vector projection onto plane inverted
|