Index of Functions: A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X
vprjpi_c

 Procedure Abstract Required_Reading Keywords Brief_I/O Detailed_Input Detailed_Output Parameters Exceptions Files Particulars Examples Restrictions Literature_References Author_and_Institution Version Index_Entries

#### Procedure

```   vprjpi_c ( Vector projection onto plane, inverted )

void vprjpi_c ( ConstSpiceDouble    vin    [3],
ConstSpicePlane   * projpl,
ConstSpicePlane   * invpl,
SpiceDouble         vout   [3],
SpiceBoolean      * found       )

```

#### Abstract

```   Find the vector in a specified plane that maps to a specified
vector in another plane under orthogonal projection.
```

```   PLANES
```

#### Keywords

```   GEOMETRY
MATH
PLANE
VECTOR

```

#### Brief_I/O

```   VARIABLE  I/O  DESCRIPTION
--------  ---  --------------------------------------------------
vin        I   The projected vector.
projpl     I   Plane containing `vin'.
invpl      I   Plane containing inverse image of `vin'.
vout       O   Inverse projection of `vin'.
found      O   Flag indicating whether `vout' could be calculated.
```

#### Detailed_Input

```   vin,
projpl,
invpl       are, respectively, a 3-vector, a SPICE plane
containing the vector, and a SPICE plane
containing the inverse image of the vector under
orthogonal projection onto `projpl'.
```

#### Detailed_Output

```   vout        is the inverse orthogonal projection of `vin'. This
is the vector lying in the plane `invpl' whose
orthogonal projection onto the plane `projpl' is
`vin'. `vout' is valid only when `found' (defined below)
is SPICETRUE. Otherwise, `vout' is undefined.

found       indicates whether the inverse orthogonal projection
of `vin' could be computed. `found' is SPICETRUE if so,
SPICEFALSE otherwise.
```

#### Parameters

```   None.
```

#### Exceptions

```   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 SPICEFALSE.

3)  Even when `found' is SPICETRUE, `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.
```

#### Files

```   None.
```

#### Particulars

```   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 vprjp_c, which projects a vector onto a plane
orthogonally, and vproj_c, which projects a vector onto another
vector orthogonally.
```

#### Examples

```   1)   Suppose

vin    =  ( 0.0, 1.0, 0.0 ),

and that projpl 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.

To find this result using CSPICE, we can create the
SPICE planes projpl and invpl using the code fragment

nvp2pl_c  ( projn,  vin,  &projpl );
nvc2pl_c  ( invn,   invc, &invpl  );

and then perform the inverse projection using the call

vprjpi_c ( vin, &projpl, &invpl, vout );

vprjpi_c will return the value

vout = ( 0.0, 1.0, 1.0 );
```

#### Restrictions

```   1)  It is recommended that the input planes be created by one of
the CSPICE routines

nvc2pl_c ( Normal vector and constant to plane )
nvp2pl_c ( Normal vector and point to plane    )
psv2pl_c ( 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.
```

#### Literature_References

```   [1]  G. Thomas and R. Finney, "Calculus and Analytic Geometry,"
```

#### Author_and_Institution

```   N.J. Bachman        (JPL)
J. Diaz del Rio     (ODC Space)
```

#### Version

```   -CSPICE Version 1.1.1, 25-AUG-2021 (JDR) (NJB)

Edited the header to comply with NAIF standard.

Added entry #1 to -Exceptions section, and entry #1 to -Restrictions.

-CSPICE Version 1.1.0, 05-APR-2004 (NJB)

Computation of LIMIT was re-structured to avoid
run-time underflow warnings on some platforms.

-CSPICE Version 1.0.0, 05-MAR-1999 (NJB)
```

#### Index_Entries

```   vector projection onto plane inverted
```
`Fri Dec 31 18:41:15 2021`