Allow setting spherical screen radius

[svank]

With Helioprojective frames, you can use assume_spherical_screen to transform coordinates into another frame. The screen's center is configurable, but the radius is always such that the screen passes through the Sun. That's usually the right choice, but a user (i.e. me) might want to change the radius of the screen (with it then not passing through the Sun). This PR allows that. Delightfully, the spherical screen part of Helioprojective.make_3d is written in full generality, so all that's needed is an argument to assume_spherical_screen allowing a radius to be passed in.

It looks like there weren't any tests for assume_spherical_screen (though there was coverage through examples in the docs), so I added a one and exercise this option.

My use case here is making videos with WISPR on PSP, which involves compositing two images from the two imagers, which are taken at slightly different times and locations. It's a wide FOV that doesn't include the Sun, but the FOV is ~fixed in helioprojective coordinates. A spherical screen passing through the Sun starts to be uncomfortably close to PSP (perihelia near 10 R_sun, while traveling ~10 R_sun/day). Projecting the images onto that kinda-close screen to composite them adds a bit of jittery parallax for the stars, which makes videos look a bit jumpy. As an experiment, I'm instead projecting onto a screen at infinity, which has the stars move very smoothly and evenly through the FOV---in trade, the coronal structures should have a bit of parallax, but since they're large, diffuse, and evolving, it's less noticeable. (My only goal in this is pretty videos.)

[ayshih]

@svank: It sounds like you're setting the radius to something very large. If I actually finish #7115 to make a planar screen available, would that satisfy your use case?

[svank]

I think the planar screen wouldn't help, since it also (as implemented there) passes through the Sun, and my WISPR FOV goes from ~10 to 110 degrees of helioprojective longitude. So either the plane would be far away in the near-the-Sun side of the FOV but never actually touch the lines of sight on the far-from-the-Sun side, or it would be far away on the far-from-the-Sun side but much too close on the near-the-Sun side.

Though that got me thinking more, and I can get a screen at infinity without this PR by placing the "observer" location (the sphere center) lightyears away and in the right position so that the sphere passes through the Sun, right behind PSP, and then out to infinity:

     ___________      ___
    /           \      |
   /             \     m
  /               \    a
 /                 \   n
|                   |  y
|         ."observer"  
|                   |  l
|                   |  y
 \  \ FOV   ⁄      /   |
  \  \    ⁄       /    |
   \  \ ⁄        /     |
Sun *__+________/     ---
       PSP           

So I can fudge it without this PR, though it's not quite as clean as just having a really big sphere centered on my actual observer.

[wtbarnes]

Given how #7115 has now evolved, I think it would be preferable to make this change on that PR as an additional keyword argument to SphericalScreen. The test could be ported directly over and just modified to use SphericalScreen rather than assume_spherical_screen. Alternatively, we could merge that PR first and then alter this PR to accomodate the change in the API. Let's just merge #7115 first and then modify this PR to accommodate that change.

Sorry this has been tied up for so long @svank. We would really like to have this in v6.0.

[nabobalis]

Doc issues:

/home/runner/work/sunpy/sunpy/.tox/build_docs/lib/python3.12/site-packages/sunpy/coordinates/screens.py:docstring of sunpy.coordinates.screens.SphericalScreen:1: WARNING: py:class reference target not found: Unit('m')
/home/runner/work/sunpy/sunpy/.tox/build_docs/lib/python3.12/site-packages/sunpy/coordinates/screens.py:docstring of sunpy.coordinates.screens.SphericalScreen:1: WARNING: py:class reference target not found: Unit('m')
<unknown>:97: WARNING: py:obj reference target not found: sunpy.coordinates.Helioprojective.SphericalScreen

[wtbarnes]

Doc issues:

/home/runner/work/sunpy/sunpy/.tox/build_docs/lib/python3.12/site-packages/sunpy/coordinates/screens.py:docstring of sunpy.coordinates.screens.SphericalScreen:1: WARNING: py:class reference target not found: Unit('m')
/home/runner/work/sunpy/sunpy/.tox/build_docs/lib/python3.12/site-packages/sunpy/coordinates/screens.py:docstring of sunpy.coordinates.screens.SphericalScreen:1: WARNING: py:class reference target not found: Unit('m')
<unknown>:97: WARNING: py:obj reference target not found: sunpy.coordinates.Helioprojective.SphericalScreen

I fixed the last one, but am really confused by the first two. I assume this is coming from the unit annotation in the function signature, but I don't know why Sphinx wouldn't be able to find that target, especially since it seems to have no issue with it in PlanarScreen

[nabobalis]

Doc issues:

/home/runner/work/sunpy/sunpy/.tox/build_docs/lib/python3.12/site-packages/sunpy/coordinates/screens.py:docstring of sunpy.coordinates.screens.SphericalScreen:1: WARNING: py:class reference target not found: Unit('m')
/home/runner/work/sunpy/sunpy/.tox/build_docs/lib/python3.12/site-packages/sunpy/coordinates/screens.py:docstring of sunpy.coordinates.screens.SphericalScreen:1: WARNING: py:class reference target not found: Unit('m')
<unknown>:97: WARNING: py:obj reference target not found: sunpy.coordinates.Helioprojective.SphericalScreen

I fixed the last one, but am really confused by the first two. I assume this is coming from the unit annotation in the function signature, but I don't know why Sphinx wouldn't be able to find that target, especially since it seems to have no issue with it in PlanarScreen

I think it's best to add it the nitpicky file. We do this for a bunch of other units.

[wtbarnes]

@svank Could you have a quick look over this to make ensure it preserves the original intent of your PR?

[svank]

Yeah, a quick test shows I can do what I originally wanted with this PR. Thanks for pushing this all along!

[ayshih]

My only comment is to make the radius keyword keyword-only (i.e., stick a star before it)

[ayshih]

Also add "See Also" sections to each screen docstring that points at the other screen

[nabobalis]

Thank you again @svank!