Projection Radius calculation in PointPerspective

[nova461]

ISIS version(s) affected: 8.3.0

Description
I am not a programmer but I have been trying to understand the PointPerspective mapping. I had the same question as the 2020 issue #3873 (units of DIST and reference from the surface or center). That issue was apparently closed with the finding that the documentation was correct and the distance was from the center, and the current documentation reflects that: "Distance from the center of the target in kilometers: value should be greater than the target radius."

Trying to confirm this for myself in the code, I see the following (PointPerspective.cpp::77):

      // Get the distance above planet center (the point of perspective from
      // the center of planet), and calculate P
      m_distance = mapGroup["Distance"];
      m_distance *= 1000.;

      m_P = 1.0 + (m_distance / m_equatorialRadius);

So m_P is effectively (m_distance + m_equatorialRadius)/m_equatorialRadius, which suggests that the input is the distance from the surface (or, at least, the equator). Again, I am not a programmer...I am assuming that mapGroup["Distance"] is returning the DIST input.

Importantly, while inspecting the code and checking the use of m_P, I noticed line 161:

  bool PointPerspective::SetGround(const double lat, const double lon) {
    // Convert longitude to radians & clean up
    double projectionRadius = m_equatorialRadius*sqrt((m_P+1)/(m_P+1));

I suspect that (m_P+1)/(m_P+1) is a bug; this logic always sets projectionRadius == m_equatorialRadius. Elsewhere in the file we have logic that looks more functional (line 326):

  bool PointPerspective::XYRange(double &minX, double &maxX, double &minY, double &maxY) {

    double projectionRadius = m_equatorialRadius*sqrt((m_P-1.0)/(m_P+1.0));

How to reproduce
Reported from documentation and code inspection; no MWE available.

Possible Solution
Doc update and correction of line 161.

[acpaquette]

@nova461 Thank you for the extremely detailed issue and explanation. Just to confirm, the fix for line 161 would be to update the calculation to (m_P-1.0)/(m_P+1.0) correct?

[nova461]

@acpaquette well...I suspect that to be the proper fix, but I confess that I haven't fully grokked the intent of that calculation. What we can say for sure, though, is that (m_P+1)/(m_P+1) is a useless statement...