Spheric mirror distorter of fisheye projection is incorrect

[gwortheyastro]

Expected Behaviour

Stellarium should be able to warp the fisheye projection to an off-dome-axis projection using the [spheric_mirror] configuration parameters.

Actual Behaviour

The warping is geometrically incorrect, and therefore unusable in actual planetarium domes.

Steps to reproduce

It is helpful when comparing to turn the Alt-Az grid on and go to zenith. One must compare to a Stellarium version prior to 10.2 or the "Nightshade Legacy" fork. This Stellarium feature has been broken since then. See http://paulbourke.net/dome/stellarium/index.html

System

• Stellarium version: stellarium-0.20.4-win64
• Operating system: Windows10 (all OSs)
• Graphics Card: any
• Screen type (if applicable): any Resolution, HighDPI, scaling: any

[github-actions[bot]]

Thanks for adding your first issue to Stellarium. If you have questions, please do not hesitate to contact us.

[gzotti]

There are parameters in the config.ini file which should influence the distortion.

[gwortheyastro]

Yes, the config.ini parameters control the distorter. The issue is that the actual geometry of the distorter is incorrect, such that even an approximate mapping to a real dome is not possible, regardless of config file tweaks (I have a planetarium with a spheric mirror). One symptom is illustrated here, with Nightshade (an old Stellarium fork) and the current Stellarium 20.4.

If one increases the size of the mirror and lowers it (via config parameters) one should get a not-very-distorted fisheye view. Basically an oval. Certain features are essential. For example, the horizon must remain at the edge of the oval. The NSEW labels should also remain at the edge of the viewport. No combination of config parameters can make this happen for Stellarium 20.4.

Screenshots:

1. Nightshade fisheye
2. Nightshade with mirror blown up a bit and lowered, spheric distorter turned on.
3. Stellarium fisheye
4. Stellarium with mirror inflated a little and lowered, spheric distorter turned on. A few other parameters were tweaked to get a view that filled the screen. "Disk viewport" is turned on. You'll notice that the horizon does not appear at the top of the "jelly bean" shape, and the bottom edge is a frown instead of smile which would be appropriate for the actual requested geometr y .

[gzotti]

You obviously must move the view so that the sky fills the visible area. However without such a projecting system I cannot test the real view of such a system.

[alex-w]

@gzotti probably this issue related to founded typos in config parameters

[gwortheyastro]

@gzotti Yes, again. The sky is maximized in the screenshot. Truly, so much green grass should not be there, but that's a different undesirable effect. I was trying to show that the horizon should be a ring, always, even when distorted for a spheric mirror system.

If those replying are devs, there is a solution that bypasses having to model the distortions on the fly. A planetarium operator like me would use Paul Bourke's meshmapper program (http://paulbourke.net/dome/meshmapper/) to map the distortions, then use the xy-to-uv output file for the applications, such as, hopefully, Stellarium soon. The file format is super simple and described at this page, along with sample GL code to implement it: http://paulbourke.net/dataformats/meshwarp/

[gzotti]

As far as I know (this was from before 2010), the distorter code is at least influenced by Bourke's work (http://paulbourke.net/dome/stellarium/). It would be a matter for a developer with mirror/dome projection system to get that corrected again. Alexander just corrected some typos which have been in this code for many years, maybe this works better soon. Unfortunately the planetarium settings are largely undocumented. See Appendix D.1.21 in the User Guide. Any volunteers to fix these parameters and write clear instructions for the User Guide?

[alex-w]

This is screenshots from version 0.21.2 (max FOV in properties of projection is set on 180 degrees):

[alex-w]

@gwortheyastro please share your config.ini file

[alex-w]

@guillaumechereau could you look at this?

[guillaumechereau]

I'll check.

[guillaumechereau]

With the current master version, I can get something that looks OK, by setting fish-eye projection with a vertical offset:

I guess I'll need the config file to check what is going on.

[gzotti]

Looks "somewhat ok-ish". But the vertical viewport offset which is helpful on 2D screens to get more of the sky in wide-angle views should not be used (even suppressed?) in this planetarium context. I think currently the view angle is not wide enough. The planetarium mirror distortion should at least work for 4:3 and 16:9/16:10 projectors. (Must not clip image content on the left/right edges.) We could easily add another sub-panel to the config dialog to tweak the detailed settings for the ViewportEffect.

[guillaumechereau]

I guess I don't understand the math here. I thought the desired distortion is exactly the fish-eye with vertical offset.

[gwortheyastro]

@alex-w Eek, ok, I can share my config.ini. I might have tweaked stuff in the meantime. I mean, I tweaked /everything/, even though I am not clear on the intended meaning of some of the parameters.

Some things are clearly working well, such as "alpha" and "phi." A feature I absolutely love is the option to flip vertical and horizontal. The usual coordinate system has its origin at the center of the dome, and "up" is positive z. What's y and what's x is arbitrary, but Stellarium has apparently chosen the y-axis for placing the mirror and projector.

I would be happy to assist. I did manage to write a distorter for myself, in python, for the added complication of an oblate-spheroid mirror. For that, of course, I made my own choices on coordinate system and how to parameterize angles and offsets, and my solution probably lacks generality. But I did document my geometry.

I can't attach a "ini" file type in this forum, but here are the parameters in the spheric mirror section. I tried to get the projector to look "down" on the mirror so that the distortion should be quite minor. A horizon circle should map to a horizon oval in that case. I don't think I really succeeded.

[spheric_mirror] distorter_max_fov = 180 dome_radius = 3.9 flag_use_ext_framebuffer_object = false flip_horz = false flip_vert = false image_distance_div_height = 2.33 mirror_position_x = 0 mirror_position_y = 3.5 mirror_position_z = -0.3 mirror_radius = 0.47 projector_alpha = 0 projector_delta = 12.6 projector_gamma = 0.3 projector_phi = 0 projector_position_x = 0 projector_position_y = 1.5 projector_position_z = 0 texture_triangle_base_length = 8

p.s. thanks for your help, everybody. If this can get fixed lots of little planetariums all over the world will thank you.

[gwortheyastro]

The above is Paul Bourke's layout. It MAY have influenced the Stellarium implementation. For example, the "projector location" is a hypothetical focus point a few centimeters interior to the lens. The mirror location is the center point of the mirror.

[guillaumechereau]

I tried today to replace the current distortion code with the original one, and it seems to give better results. I still don't understand the code much, so I am not sure if the difference is due to a bug or to a change of the config parameters.

I'll try to sort it out tomorrow if I can.

[guillaumechereau]

I kept looking today but still not totally sure what is going on. I can pinpoint the commit where I think the difference starts: 720b1c45d8e. In this commit the parameters are changed and I think that is where the backward compatibility is broken. There is also a change of referential of the coordinates used, so maybe this was a bug in the code, but I cannot say for sure.

One thing I could do is revert the code to a state where it would work with the ini file given by @gwortheyastro, but without much understanding of the desired behavior it could breaks the code for other people.

By the way @gwortheyastro : have you tried to use the custom_distortion_file setting, where you can normally pass your own distortion grid?

[gzotti]

Phew, an issue from 2007? Do we have any documentation of these options? It looks very interesting, but without relevant hardware I never played with these settings. SUG Appendix D.1.21 needs a thorough revision, and the whole topic described in probably 1-2 pages.

[guillaumechereau]

The old options were:

projector_position_x/y/z
mirror_position_x/y/z
mirror_radius
dome_radius
zenith_y
scaling_factor
flip_horz
flip_vert

In the current code, scaling_factor has been replaced with: image_distance_div_height, zenith_t has been replaced with projector_delta, and we have two new options: projector_alpha and projector_phi.

Now the code is supposed to fallback to the old options in case we didn't specified image_distance_div_height and projector_delta, but it doesn't seem to work properly.

I am thinking maybe we could check if the old options are used, and in that case make the code behave like the original version (I think it mostly involves swapping the X and Y coordinates in the deformation function). This would solve the backward compatibility problem while maintaining the current behavior (correct or not) when we use the new options.

[axd1967]

You obviously must move the view so that the sky fills the visible area. However without such a projecting system I cannot test the real view of such a system.

Here you see an example of such a rotated view:

(from Paul Bourke's http://paulbourke.net/dome/domeinstall/)

[alex-w]

@guillaumechereau @gwortheyastro any news for it?

[guillaumechereau]

No news sorry. As I said previously, I can probably make a commit that revert to the original behavior, while trying to maintain the current behavior when the new options are used. Or we could just revert to the original behavior without regard to backward compatibility. The problem I have is that I am not sure if the old behavior makes more sense than the current one.

[alex-w]

I prefer to see original and current behavior when the new options are used. I don’t have hardware to check the projection. :(

[gwortheyastro]

Hello! I am here (after break) and I have a planetarium. I also have a working geometrical solution written in python if that is of use (it even has option for an oblate spheroid mirror). And I would be happy to, for example, write a manual page once I understand what's what. I am otherwise ignorant of github and the stellarium code base, alas.

As for "By the way @gwortheyastro : have you tried to use the custom_distortion_file setting, where you can normally pass your own distortion grid?" by @guillaumechereau , my reply is what? what? what? There is a custom_distortion_file ??? I'll go see if I can find that.

[gwortheyastro]

Briefly, (1) I could not find the custom_distortion_file option, either in the config.ini or in the various runtime menus. But if that exists, and if it is in the Paul Bourke format, and it successfully performs the fisheye --> distorted fisheye transformation, then my personal planetarium problem is solved because I have mapped my dome and saved it in this format. Furthermore, I think most small planetarium owners have done the same, and this would be a valid, permanent solution and you could snip out the on-the-fly distorter code altogether.

(2) Reverting to the "old" distorter should be fine. You won't make anybody mad, trust me.

[guillaumechereau]

@gwortheyastro: you can set the custom file in config.ini like that:

[spheric_mirror]
custom_distortion_file   = <path-to-my-file>

It should work even if the option is not there by default. I don't know Paul Bourke format, but based on the code in Stellarium the format used there seems to be a simple textual file of the form:

max_x max_y
x0 y0 r0 g0 b0
x1 y1 r1 g1 b1
...

[gwortheyastro]

Thank you! The format is very similar. It is written up here http://paulbourke.net/dataformats/meshwarp/

I'll test some 'translations' of my warpmesh files and I'll report back on progress.

Yours, Guy

[gwortheyastro]

Greetings. Although I think I understand the file format, I have to admit defeat.

There is an example of a simple custom_distortion_file at http://stellarium.sourceforge.net/wiki/index.php/Setting_up_your_own_dome_using_Stellarium%27s_spheric_mirror_distortion_feature

And I slightly modified the example there to exhibit no distortion (with a 1920x1080 viewport). The example becomes:

2 1 0 0 1 1 1 960 0 1 1 1 1920 0 1 1 1 0 1080 1 1 1 960 1080 1 1 1 1920 1080 1 1 1

But, alas, this produces the picture here, where the black lines are lines that I drew to indicate lines where the distortion changes slope. These lines intersect with screen coordinates (0,0) and (1920,1080)

Simplifying the custom_distortion_file to:

1 1 0 0 1 1 1 1920 0 1 1 1 0 1080 1 1 1 1920 1080 1 1 1

Does return to a regular fisheye.

So I'm pretty sure that the custom_distortion_file feature is bugged, too.

[alex-w]

@gwortheyastro could you test the latest release of Stellarium?