New functionality request: Spherical Mirror Projection

[ImmersiveTheatres]

Hello Celestia development community

I own and operate my own mobile planetarium business and Celestia 1.4.1 (spherical mirror projection version) has for many years been as important to me as Stellarium plus my catalogue of fulldome (360°) films.

In fact, many mobile planetarium operators like me have delighted audiences with Celestia 1.4.1 adapted for spherical mirror projection - immersing them with Celestia in 360°.

Spherical mirror projection is simply an inexpensive way of projecting in 360°. All you need is a projector, a spherical mirror and 'warping' of digital content so it looks correct on the dome (see diagram here).

The 1.4.1 spherical mirror version of Celestia was commissioned by mobile planetarium sales company Discovery Dome many years ago and made available free to its customers.

Of course 1.4.1 is very old now and no longer works with the latest operating systems (with OS X anyway, which is what I use). Plus it has always carried a number of bugs.

It would be wonderful if a spherical mirror projection option was incorporated into the current version of Celestia. This would make Celestia of great value and interest to the large and growing number of small and medium digital dome operators around the world.

Have you perhaps considered adding spherical mirror projection functionality, like Stellarium has done for many years now?

I'm not a programmer, but would love to help where I can. Please let me know if any developers would like to see a copy of the 1.4.1 spherical mirror version (I am a Discovery Dome sales agent, so I am allowed to share this version with you). Perhaps if you create a repository on here I can upload this version for those interested to examine? I have both Mac and Windows versions.

Also, Paul Bourke (the inventor of spherical mirror projection in 2005) is an academic who makes all the information and support you require as regards spherical mirror projection freely available on his website eg http://paulbourke.net/dome/stellarium/ He would be delighted to help you achieve spherical mirror projection in Celestia.

Please let me know if I can help in any other way?

By allowing Celestia to be projected in 360° inside digital planetariums, you will be introducing hundreds of thousands of people (mainly schoolchildren) to the magical universe of Celestia - and then operators like me will encourage these children to download Celestia at home for themselves (as we do with Stellarium).

Thanks very much.

Mario

[levinli303]

I have read the post on the forum, it is really a good idea to me to have it in the future. it would require quite some work as one would reckon.

it would be good if you can share the source code, with me and @375gnu via email, since it'd be more straightforward for us to incorporate existing code.

[ImmersiveTheatres]

Thank you for your interest in creating a version of Celestia for the dome @eyvallah and @375gnu . Please message me and I will share the warped version 1.4.1 with you.

[375gnu]

Hi @ImmersiveTheatres, please contact Discovery Dome and request source codes of their modified Celestia. As Celestia is licenced under terms of GPL2+ they must provide them to their customers. Without them it will be hard to reimplement this function.

[ImmersiveTheatres]

OK I have contacted Discovery Dome and they don't have the source code, so they referred me to Paul Bourke, who was originally commissioned to do the work.

Paul Bourke says he does not have the source code either, because he employed a programmer called Evan Hallein to create the dome version of Celestia 1.4.1.

I have managed to contact Even Hallein and he thinks he may no longer have the source code, but he will check when he returns from holiday in two weeks time.

I will follow up with him next month to try and obtain the source code.

[ImmersiveTheatres]

During my investigation, both Discovery Dome and Paul Bourke were delighted to hear the Celestia development team wishes to incorporate a spherical mirror option for Celestia.

In fact, Paul Bourke said that if we cannot obtain the original 1.4.1 source code: "...assuming Celestia already creates fisheye, then the warping is pretty straight forward. It is normally the fisheye bit that the harder part."

Discovery Dome said: "That would be cool to get Celestia up to date and warped (because WorldWide Telescope isn’t available for Mac). As for the source code ... probably would be better to start from scratch and use external warp meshes so we can go up to 4K, larger domes, etc…"

[LafuenteAstronomy]

You know honestly, it feels like we're getting support from official groups once again. That's really good to hear from you, ImmersiveTheaters!

[SevenSpheres]

You know honestly, it feels like we're getting support from official groups once again. That's really good to hear from you, ImmersiveTheaters!

Agreed, it really is!

I think it's also worth noting that, if Celestia does implement spherical mirror projection, its main competitor in that area would be WorldWide Telescope (as was mentioned above). What with programs like SpaceEngine, Celestia may not seem so great anymore, but Celestia is much better than WorldWide Telescope.

[ImmersiveTheatres]

GOOD NEWS! I have finally received the spherical mirror projection source code for Celestia ver. 1.4.1.

It can be downloaded here:

https://drive.google.com/open?id=1vpefaI36Paa8APKboBZXEj6zFKJLOMqc

It came with the following comment: There is a CGShader that does the majority of the work in converting the regular projection to a fisheye projection, and this is enabled by configuring a CFILES environment variable, but I’m sure the developers will be able to work out what is required by looking at the source code.

When the spherical mirror projection version of Celestia is released, it will be nice to include in the credits: Andrew Jameson, Systems & Software Engineer, Centre for Astrophysics & Supercomputing, Swinburne University of Technology

Finally, I'd like to be the first to volunteer to test spherical mirror projection beta versions in my mobile domes! :smile:

Mario

[levinli303]

@ImmersiveTheatres I looked at the source code and tried to port the difference over, here is what I got on my Mac, since I cannot run the dome version (32bit programs don't run on Catalina anymore), here is a demo video of how it is running, is this what it should be looking like?

https://drive.google.com/file/d/1Eefm9bgTUuuyZ4caFXTV9bJJk7qJxz9Z/view?usp=sharing

[ImmersiveTheatres]

@levinli303 Thank you for doing that! Yes, it looks correct in that it appears to be a perfect fisheye / fulldome / 360° projection. So it will look great in a dome through a fisheye lens projector.

Yet we need this fisheye / 360° projection to be warped for the spherical mirror. Only then will it work in most portable planetariums (that use affordable spherical mirror projection, not the very expensive fisheye lens projection).

See attached image.

The real-time warping is the challenge :-)

[levinli303]

hmm, maybe this part can be done with Quartz Composer? http://paulbourke.net/dome/warppatch/ from what I can see from the source code you provided, there is only fisheye.

[ImmersiveTheatres]

Celestia ver. 1.4.1 was spherical mirror warped (that's the code I managed to obtain above).

Are you saying the current version of Celestia cannot be warped? It would be best for warping to be functional both for Macs and Windows.

[levinli303]

from what I see in the source code you provided, it does not contain fisheye -> spherical mirror warping.

[ImmersiveTheatres]

That I don't understand, as I received those files from the university that warped ver 1.4.1 to work with the spherical mirror. If you wish, you can download both the Mac and Win versions of 1.4.1 (warped) here

[levinli303]

warping is not included in this source code, as far as I can tell. since my demo video basically includes all the rendering difference in the code you provided.

[ImmersiveTheatres]

OK I've written to the developer who supplied the code and will let you know what he says :-)

[ImmersiveTheatres]

Right, here is his comprehensive reply (which now makes sense I guess - although I have no idea why he didn't tell me this the first time! 😠 )

---

Hi Mario,

Thanks for your message, Yes, the Celestia developers have done all they could since we never implemented the warping algorithm directly into Celestia. Our solution was to:

1. Modify Celestia so that it rendered to a fisheye view in the centre of the primary computer display (you have these modifications now). 2. Develop a completely separate application (which we called ScreenCopy) to perform the warping from the primary display to a secondary display (which ran a projector). 3. ScreenCopy was a (Mac OSX only) application, built in X-code, that read the rendered OpenGL frame produced by Celestia from the graphics card and then warped it to the fish eye texture.

There are similar, now defunct, descriptions of this approach here: http://paulbourke.net/dome/warppatch.

It is important to note that ScreenCopy would actually warp any full screen application (e.g. a fisheye movie running in QuickTime, Stellarium or Celestia) from the primary display to the secondary display. When no application was running, it would even be able to “warp” the desktop of the primary computer display. Therefore it was never “linked to” or combined with Celestia in any way.

We did this so that that we could de-couple the warping function from the fisheye rendering software. This would then allow our ScreenCopy software to “warp” any other 3rd party software that could render a fisheye view without the need for:

1. Modification of the 3rd party software - saving time, effort and cost. 2. Ease of maintenance - since the provides of the 3rd party software could update their code without us also needing to do this. 3. No complaints and arguments regarding modification from the authors of the 3rd party software.

And so the software we developed to do this warping has not been publicly released. I hope this explains the situation clearly - please let me know if you have any further questions.

The techniques employed by ScreenCopy (special hooks into the OpenGL rendering pathways, etc) are no longer available on modern Mac operating systems - similar to Paul Bourke’s other “live warping” software I think.

If the developers want to add warping into Celestia then they would probably need to develop a new solution for it - either natively (Stellarium did this I think) or via an external application - obviously separate to Celestia, but perhaps more useful to the community.

Cheers,

Andrew

[ajameson]

Hi Mario,

Just to be clear - I did advise you of exactly this back in Jan 2020, namely:

I believe that the version of Celestia you might be referring to is version 1.4.0, which was modified for Fisheye projection, not spherical mirror projection. A completely separate software application was used to warp the fisheye image into spherical mirror image.

[ImmersiveTheatres]

Yes Andrew, but how come I have two versions of Celestia 1.4.1 (Mac and Win) - and they run warped for spherical mirror?

Are you saying you guys did not create this ready-to-run spherical mirror version?

On Fri, 2 Oct 2020 at 14:37, ajameson notifications@github.com wrote:

Hi Mario,

Just to be clear - I did advise you of exactly this back in Jan 2020, namely:

I believe that the version of Celestia you might be referring to is version 1.4.0, which was modified for Fisheye projection, not spherical mirror projection. A completely separate software application was used to warp the fisheye image into spherical mirror image.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/CelestiaProject/Celestia/issues/572#issuecomment-702738760, or unsubscribe https://github.com/notifications/unsubscribe-auth/AODE2D7AS2VTNVSY4A73HK3SIXJSLANCNFSM4J6KS2PQ .

[ajameson]

I'm not sure - none of our software was ever built or released for Windows, so it would seem that the copy you have came from somehwere else? This was happening back in 2006, so a fair bit of water has passed under the bridge since then.

We certainly tried integrating the warping software directly into Celestia during the early development and testing, but then that approach was discarded for the separate application warping I described above.

[ImmersiveTheatres]

My, this is turning out to be quite a mystery! 😃

Nevertheless thank you for all your help Andrew, and apologies I wrongly assumed you were behind the warped 1.4.1 version.

OK, back to the drawing board ... 🔎

[ImmersiveTheatres]

To all Celestia developers: in searching through my emails I've again come across these words of Paul Bourke's:

"But, assuming Celestia already creates fisheye, then the warping is pretty straight forward. It is normally the fisheye bit that the harder part"

So now that fisheye projection has been achieved (thanks to @levinli303 and @ajameson), I assume Paul Bourke's website has all the required info on how to implement warping for spherical mirror?

Or can this not be reverse engineered from ver. 1.4.1?

[levinli303]

for warping this part is missing in source code, so to tell from the header, this was done by Swinburne University of Technology

and these function implementation too. It's not easy to reverse engineer it (nor do I have the knowledge), it is better to have source code.

[ImmersiveTheatres]

I might be wrong @levinli303 , but I think what happened was Swinburne University did most of the original work (as described by @ajameson earlier), but did not make their warping method available publicly.

Then someone else took what Swinburne did, and added the spherical mirror warping - without updating the header. It seems they wanted to remain a mystery! 😃

Nevertheless this probably means - as Paul Bourke says above - the spherical mirror warping is not so difficult to implement (I know, I know, I'm not a programmer! 😄 . If you investigate http://paulbourke.net/ you'll see plenty of information on how to create spherical mirror warping code.

[ajameson]

@levinli303 - that is interesting, but I'm still not sure sure where those methods in CelestiaCore are from - they are not in the source code I have available that I provided to Mario. Perhaps you are dumping the binary objects from the compiled version Mario has? I wonder if his version was from the initial developement work we did with Celestia before the ScreenCopy approach was developed? I cannot be sure.

Regardess, the one remaining copy of the fisheye Celestia source code I have does not have any of these methods in it, so I'm not really able to help you here on this implementation.

[levinli303]

@ImmersiveTheatres I implemented warping, you should be able to see the result here

https://drive.google.com/file/d/1vcAYXfG5y8JkRBNziudzxylePAqJOXUc/view?usp=sharing

[ImmersiveTheatres]

WOW @levinli303 , that looks correct to me!! 😃

I will be in a dome next Friday, so I'd love to check it in the dome then if possible? Are you able to prepare a version for me to test?

This looks amazing, well done!! 🥳

PS - it will need to be a Mac version, if possible? Or even if it isn't a full Celestia programme, just a warped file sample that I can test to check the geometry is correct in the dome (it looks correct on the flat screen) :-)

[levinli303]

well this is implemented in celestia itself. so it will run on all platforms, including mobile platforms. I only got the rendering part working, warped mouse control is not there yet.

[levinli303]

@ImmersiveTheatres You can download this build to try out, should be fairly unstable. Since dome configuration might be different, you would need a mesh for the warping parameters. I used the one in the 1.4.1 version you provided as default (warp_xyuv.data). If you have a mesh file, you can replace the file in Celestia.app/Resources/CelestiaResources/warp/warp.map.

https://drive.google.com/file/d/1txLbdNG0Lhwk9wyOV8Se3EfF2X94FdjW/view?usp=sharing

for the mesh file format, see: http://paulbourke.net/dome/meshmapper/ or http://paulbourke.net/dataformats/meshwarp/

[ImmersiveTheatres]

Thank you for this, I'll download it and try it out tomorrow! 😊

On Sun, 4 Oct 2020 at 11:00, Levin Li notifications@github.com wrote:

@ImmersiveTheatres https://github.com/ImmersiveTheatres You can download this build to try out, should be fairly unstable. Since dome configuration might be different, you would need a mesh for the warping parameters. I used the one in the 1.4.1 version you provided as default (warp_xyuv.data). If you have a mesh file, you can replace the file in Celestia.app/Resources/CelestiaResources/warp/warp.map.

https://drive.google.com/file/d/1txLbdNG0Lhwk9wyOV8Se3EfF2X94FdjW/view?usp=sharing

for the mesh file format, see: http://paulbourke.net/dome/meshmapper/ or http://paulbourke.net/dataformats/meshwarp/

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/CelestiaProject/Celestia/issues/572#issuecomment-703231641, or unsubscribe https://github.com/notifications/unsubscribe-auth/AODE2D7INUCZ4VAAFVMOXWDSJBBSRANCNFSM4J6KS2PQ .

[ImmersiveTheatres]

@levinli303 THIS IS BRILLIANT! 😃

I'll have a chance to try it in the dome on the weekend, but the 1.4.1 warp mesh is looking fine on my laptop.

What would be REALLY useful is the Mac keyboard shortcuts. I've looked online but I can't find anything recent.

In particular I need the Mac shortcut to enter Full Screen please. This way I can use Keyboard Maestro to automate the launch process fully, and have Celestia open correctly in my secondary screen (the dome).

I'm no programmer, but am just curious: did you make the breakthrough by using the 1.4.1 code?

It's all looking so promising - I think we're practically there!! 🥳

[levinli303]

hmmm, I accidentally removed some of the default menu items, and that prevented some shortcuts. will add back toggle full screen and close window.

the version I provided has a small fov though, so it might behave strangely in many cases. This is done by looking at the code for the fisheye part. for the warping, I referred to the Paul's website mostly (and some decompilation from the binary...)

[ImmersiveTheatres]

GREAT NEWS! I tested the warped Celestia in a dome on the weekend and it's looking great to me 😃 Thank you for doing this.

I'm keen to put it through its paces to see if there are any bugs / issues - but I'm limited by the fact I don't have the latest Mac keyboard shortcuts. I can't seem to find them anywhere online. Do you have a link perhaps?

Thanks very much

[levinli303]

I think this https://github.com/CelestiaProject/Celestia/blob/master/controls.txt is for keyboard shortcuts.

[ImmersiveTheatres]

OK it looks like all the MAC keyboard commands are still the same, but one very important one is missing: Enter Full Screen

It used to be: Cmnd+F

[levinli303]

OK it looks like all the MAC keyboard commands are still the same, but one very important one is missing: Enter Full Screen

It used to be: Cmnd+F

I added back now in this commit. https://github.com/levinli303/CelestiaApp/commit/8a103d0a93a6721d1655ee0ea799baf4ac905bce

[ImmersiveTheatres]

Thanks - what does that mean though? That it will be included in the next release? Or is it possible to download the new version now?

[levinli303]

If you mean public release as a new version, this (shortcut) will be include in the next App Store release. But as the fisheye implementation is still a work in progress, next App Store release would not include fisheye.

[ImmersiveTheatres]

OK what I mean is : can I download a version with the Enter Full Screen keyboard command for MAC now - so that I can start using it in my planetarium shows?

On Fri, 16 Oct 2020 at 08:34, Levin Li notifications@github.com wrote:

If you mean public release as a new version, this will be include in the next App Store release. But as the fisheye implementation is still a work in progress, next App Store release would not include fisheye.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/CelestiaProject/Celestia/issues/572#issuecomment-709879673, or unsubscribe https://github.com/notifications/unsubscribe-auth/AODE2D33RORPDW35BUQT5ZTSK7ZQ5ANCNFSM4J6KS2PQ .

[levinli303]

if you need a version with it, I can compile one with it enabled.

[ImmersiveTheatres]

Yes please! :-)

On Fri, 16 Oct 2020 at 08:43, Levin Li notifications@github.com wrote:

if you need a version with it, I can compile one with it enabled.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/CelestiaProject/Celestia/issues/572#issuecomment-709883776, or unsubscribe https://github.com/notifications/unsubscribe-auth/AODE2D2JJCKIIP2M35Y3BYDSK72TLANCNFSM4J6KS2PQ .

[levinli303]

here it is, the fullscreen shortcut as for any other window on Mac, command + control + F https://drive.google.com/file/d/11qzDMotYqPh8SjeJCuwWHF9r31Mrdd_c/view?usp=sharing

[ImmersiveTheatres]

FABULOUS! Thank you :-)

A question and one more request please:

• where is the best place to find high resolution textures for this version (and are there instructions somewhere on how to introduce / include the new textures)?

• I keep mistakenly hitting the Fn + Down Arrow [intending to hit the Fn + Left / Right Arrow] - and the planet completely disappears ... and I need to locate it again. Is it possible to disable Fn + Down Arrow?

Fn + Up Arrow is disabled.

So I'm wondering if it's possible to disable Fn + Down Arrow too?

Thanks very much

[levinli303]

I think the Wiki covers a lot about customization https://en.wikibooks.org/wiki/Celestia

on my MacBook, pressing Fn+Down does not do anything.

[ImmersiveTheatres]

Thanks for the link.

On your MacBook, try giving the planet some rotation and then press Fn+Down ...

[levinli303]

I think this is by design, Fn+Down equals page down on extended keyboards, which trigger the back in history menu. avoid hitting it if you don't want this behavior.

[ImmersiveTheatres]

One thing I've just noticed is this version is not removing the Venus clouds to show the surface ie. the I key is not removing the clouds, the way it does for Earth.

[ImmersiveTheatres]

Also: 9 + G takes us to Pallas - not Pluto (?). Is that intentional?

[levinli303]

'i' disable cloud map rendering, probably Venus does not have a cloud map at all. and the 9th planet is not Pluto any more. clicking 9 will just select the ninth in the database, it happens to be Pallas. all intentional.

[ImmersiveTheatres]

I would suggest the Venus clouds are returned to what Celestia used to have ie. if you look at the texture folders, there are both surface textures and cloud textures for Venus. As an astronomy educator, I strongly encourage you to keep this functionality in, because it is a wonderful teaching tool (greenhouse effect, climate change, etc, etc).

An equally critical function for education purposes is to keep Pluto at G + 9. Pluto continues to play a major role in the teaching of the Solar System - because the very fact it has been designated a dwarf planet is an opportunity to teach how science is always progressing and improving our understanding of the Universe.

At any rate, it doesn't make sense to have Pallas at number 9 just because it is ninth in the database. Is Mercury first in the database and is Saturn sixth in the database? The reasoning is not consistent.

I think you'll find most astronomy educators around the world will agree with my suggestions above.

Thank you for all your hard work in support of astronomy education via the excellent teaching tool of Celestia! :-)