Add terrain to the skymap.
Summary
Adds the ability for a user to add a customized terrain overlay (i.e. trees and buildings etc that surround his telescope site) to the KStars SkyMap.
This would allow the user to predict when astronomical targets rise and fall relative to those obstructions. It will also (in the future) make creating sky-lines the scheduler might use.
Details
The user is responsible for creating a partially-transparent image, that is overlayed onto the SkyMap. This image should have transparent regions that the user creates to let the SkyMap show through, and opaque regions representing the trees, buildings, landscape around the telescope. There's a particular format required, and this is a significant effort. There are many resources on the web that explain how this is done for Stellarium. The details of image creation are the same. The details of how it loads into KStars are different. For example: https://www.youtube.com/watch?v=flwllEQTfVw
Initially the user captures a full sphere equirectangular projection image from approximately the same point-of-view as his/her telescope. This kind of image can be captured with the Google Camera App, or the Google YouTube App on iPhone, or likely many other camera apps. The user then needs to edit the resulting image so that the sky is erased/transparent, and save it as a PNG. Finally the user needs to determine where North is in the image, so it can eventually be aligned with the SkyMap. One all that is done, the skymap can simulate the local sky view including the local terrain. For example, see this screenshot: https://photos.app.goo.gl/PqkF2mjczoD1QZon9
Once the image is created, there's a configuration menu where the user can ask KStars to load the image, and set some other parameters. See: https://photos.app.goo.gl/Vt9RR8YA3WPSqBm57 Note that the azimuth correction value (in degrees) allows the user to rotate the view so north in the SkyMap is aligned with north in the image.
The implementation is complete in that testers can try this out.
User interface
The UI is complete, but basic. It would be great to have a library of sample terrain images. I have prepared one--a panorama of Mars. This is not included with this MR, but can follow soon, with a little advice of how to add such a data file.
Currently the controls are in the main configure KStars menu, in a new tab titled terrain: Here's a view of those controls https://photos.app.goo.gl/Vt9RR8YA3WPSqBm57
There's also a keyboard shortcut (control-shift-T) and a Menu->View item for toggling the terrain overlay on and off.
Graphics
I worked on speeding up the rendering (which is currently all CPU, not GPU) so that it can be used on Raspberry Pi 4, these speedups trade off with image quality, but the resulting image is acceptable in my opinion. Right now, it is limited by KStars rendering, which is not supported by the GPU. Fixing that is out of the scope of this MR.
Speed
It's workable on the Raspberry Pi 4 (while panning) and fine on faster machines. Of course, once you have the view, there's no speed issue (it doesn't re-compute the rendering unnecessarily as the sky moves west). Overall, I measure <100ms rendering time for a 1000x800 KStars window (it gets slower as the window grows) or <250ms for a 1900x960 window, when using the speedup parameter = 4. The actual redraw time is much longer, not limited by this rendering code, but rather by the non-GPU image display.
Live Testing
If you want to test, but don't have or can't make a photosphere, you can download a png file from this folder: https://drive.google.com/drive/folders/1BXHzbF9JIyhE2IZd0V8mpgZJiwNkU4i1?usp=sharing The curiosity*.png files are different resolution versions of a NASA/JPL panorama from Mars I modified, and are Courtesy NASA/JPL-Caltech. SideByRoses is the view from my telescope (use the azimuth adjustment of 10 degrees to align it with my north).
However, I'd encourage you to watch the video and make your own, to experience "the whole package".
FWIW, I've tested with 2 captured photospheres, both full spheres. One made with the google camera app on a Pixel 3 camera, and one made with the Google YouTube App on an iPhone. The other image tested was the NASA/JPL panorama. In all cases, I edited the end result in Photoshop, saving as PNG.