Adds Mars ellipsoid and trackable rovers #12828

mzschwartz5 · 2025-08-22T00:33:22Z

Description

Sandcastle demo for Mars terrain. Showcases geological points of interest, and the ability to see a few rovers take their journeys from landing point to current point - defined in a CZML file, data and models from NASA.

Issue number and link

N/A

Testing plan

Make sure to include the CesiumGS default Ion access token when testing.

Review the new sandcastle example, CI-build link here
Make sure the title, description, and thumbnail are all correct.

Author checklist

I have submitted a Contributor License Agreement
I have added my name to CONTRIBUTORS.md
I have updated CHANGES.md with a short summary of my change
I have added or updated unit tests to ensure consistent code coverage
I have updated the inline documentation, and included code examples where relevant
I have performed a self-review of my code

github-actions · 2025-08-22T00:33:39Z

Thank you for the pull request, @mzschwartz5!

✅ We can confirm we have a CLA on file for you.

LisaBosCesium · 2025-08-22T18:26:55Z

@mzschwartz5 please share the sandcastle via https://sandcastle.cesium.com/ so reviewers without a local JS setup can view it.

javagl · 2025-08-22T20:47:29Z

^This happened in the meantime. More generally: Once there is that ✔️ for the build process, the sandcastle on a branch with the name my-example-branch is available at
https://ci-builds.cesium.com/cesium/my-example-branch/Apps/Sandcastle/index.html
(i.e. https://ci-builds.cesium.com/cesium/mars/Apps/Sandcastle/index.html here)

(I also tried to remember adding this link in the first post when applicable)

ggetz · 2025-08-26T18:10:40Z

(I also tried to remember adding this link in the first post when applicable)

Potential for automation via GitHub Actions?

ggetz

This is looking great so far!

I love that we're using models for both the rovers. Maybe consider using minimumPixelSize so that they are visible further away?

ggetz · 2025-08-26T18:17:59Z

packages/engine/Source/Core/Ellipsoid.js

@@ -254,6 +254,8 @@ Ellipsoid.MOON = Object.freeze(
  ),
 );

+Ellipsoid.MARS = Object.freeze(new Ellipsoid(3396190.0, 3396190.0, 3371726.0));


Just a reminder before this PR is merged: This property needs inline documentation, and the addition should be documented in CHANGES.md.

mzschwartz5 · 2025-08-26T18:23:53Z

This is looking great so far!

I love that we're using models for both the rovers. Maybe consider using minimumPixelSize so that they are visible further away?

Currently using a minimum pixel size of 64 (defined in the .czml file) but I can increase it! I think I've had general feedback about viewing the rovers from further out / at a scale that better matches the terrain resolution.

edit: I think it's actually the maximumScale that's the issue here. Set it to 1000, maybe need to increase.

LisaBosCesium · 2025-08-28T16:56:37Z

@mzschwartz5 here are my notes from our call:

Display instructions for rovers on the screen - eg double click, play animation controls to see rover movement
Adjust placement of labels on rovers - either hide when close to rover or move higher so doesn't block the rover
Adjust lighting/apearance and raise atmosphere and provide controls for the user to adjust
Include links to the overlay data sources (in the metadata?)
Nice to have - filter out the metadata fields populated only for the sake of the sandcastle
If needed add more comments to ensure devs understand the why of the code

mzschwartz5 · 2025-08-29T00:51:45Z

@LisaBosCesium Should all be addressed now (pushing changes momentarily). On the point of adjusting lighting, here are some before and after screen shots:

Globe view (before):

Globe view (after):

Feature view (before):

Feature view (after):

LisaBosCesium · 2025-08-29T16:27:29Z

@mzschwartz5 -

Nice!

The descriptions look great and I see you filtered out the info you used to position to camera, also good.
Adding green target when zoom to a feature or rover is a nice change.
Lighting looks really good.
Thank you to @dkbraig for reviewing the feature locations and catching some issues. You might already know about some comments that follow.

Requests:

What controls the order of the features on the drop down? Can we alphabetize if not a meaningful order I'm missing?
Labels and target don't appear when zoom to some features - Alba Mons, Elysium. Guessing these are the wrong location ones you already know about.
Also some issues with labels showing up for Perseverance and Curiosity. Maybe also a coordinates issue?
The Schiaperelli Crater appears to not be anchored to wherever it should be.
Can we add the Jezero Crater? Meant to ask this before, sorry. Is one that's mentioned a lot and for which we have high res data.
Please add the "Data attribution" link
We discussed adding an instructions text box on the page. I still think would be useful. Something like:
Use the "Fly to rover" and "Fly to landmark" drop downs to move the camera to the selected location.
After flying to a rover, doubleclick on the rover to zoom to a closer view of the model.
After flying to a rover, click the play button on the lower lefthand control for an animation of the path traveled by the rover.
Click the home icon in the upper right to return to the original view.

mzschwartz5 · 2025-08-29T16:37:26Z

@LisaBosCesium

What controls the order of the features on the drop down? Can we alphabetize if not a meaningful order I'm missing?

It's just the order I added them in, easy to rearrange. I can put them in alphabetical order.

Labels and target don't appear when zoom to some features - Alba Mons, Elysium.

Spin off of the same problem, yes - I'll fix it!

Also some issues with labels showing up for Perseverance and Curiosity. Maybe also a coordinates issue?

This is sort of intentional - we discussed having the labels for those disappear at close distances so that they wouldn't overlap the rover models. I can adjust the interval so they appear a little further out.

Can we add the Jezero Crater...

This is the Perseverance landing site. We have a landmark there by that name, as well as the ability to fly to the Perseverance rover. Would you prefer me to rename the landmark to Jezero Crater?

We discussed adding an instructions text box on the page...

Something beyond this? I made it so that when you fly to a rover, the nav help menu opens up - and I added two items to it for tracking and playing animation.

LisaBosCesium · 2025-08-29T17:26:41Z

@mzschwartz5 -

Re Jezero/Perseverance - Understood, but just as we label both Gale and Curiosity, we should label Jezero as well as Perseverance because some people will be looking for Jezero.

Re instructions - I'm so used to those default instructions they are literally invisible to me - didn't notice you'd added to them. OK, let's just keep this as is.

Also some issues with labels showing up for Perseverance and Curiosity. Maybe also a coordinates issue?

This is sort of intentional - we discussed having the labels for those disappear at close distances so that they wouldn't overlap the rover models. I can adjust the interval so they appear a little further out.

The behavior felt inconsistent when I was testing, but I don't think it's worth messing with more unless you've already made a change that feels like an improvement to you.

mzschwartz5 · 2025-08-29T17:30:24Z

I'm so used to those default instructions they are literally invisible to me

😂 I totally get it

jjspace

Overall the code seems fine. This is definitely a very lengthy sandcastle but I understand it's one that's more oriented at a "sales" perspective so that's ok.

Had a number of comments just using the sandcastle itself. Some are definitely optional, others I feel not so but feel free to push back on if they've already been discussed. Largely just ideas/suggestions

Marco mentioned this but at certain angles the camera "bounces" off the terrain much higher than I would expect.
(optional) Can we make the camera/animation tips only show up the first time? I don't need to see them every time I switch rovers
The highlight animation is cut off by the element bounds
- [image]
The clock keeps playing after leaving a rover, should it?
- Also why not just start the clock for people when zooming to a rover? we're already resetting the time to the start
Shadows don't turn off correctly when switching the rover "mid-flight"
- Counter point, why even enable shadows at all? Can we just turn them off completely?
- Repro:
  - Run sandcastle
  - Click Play on animation
  - Pick Curiosity
  - Pick Perseverance before getting to Curiosity
  - See shadows
"Spin on first load" is not working. This is because you're calling reset in the first menu item. That handler will always be called by default when first setting it up
The "Landing site" POIs overlap with the nearby crater names. Can we remove them? Or make them only appear much closer? Or maybe combine them like "Gale crater (Perseverance)"?
The order of POIs may not be the "best"? I realize they're alphabetical but I was first exploring them "top to bottom" and certain collections don't make sense (optional if it's already been decided)
- For example There's a POI between "Curiosity Landing Site" and "Gale crater". Going "top to bottom" makes the camera jump back and forth to the same spot even though it's right next to it. Same idea around the Perseverance
- It'd be nice to follow the POIs along the Martian Journey "in order"
(optional) It might help a lot to use optgroup elements to group things like "Craters" or "Rovers" or "Martian Journey stops"
Should all the positions be in a single menu list? (easier if using optgroups)
- With Menus you can't "re-select" the current selection. if you select a rover to see the path, then go to a POI, you can't jump back to the same rover. If they were one list it'd be easier to do that.
- The menu doesn't reset or change once leaving a POI. I don't think it needs to but it's a bit weird to zoom to a POI but still see it listing the rover you were just at
Did we look into keeping the camera facing somewhat down when using flyTo? It's a little odd to just stare at stars for some flights. If not possible then it's fine
(optional) is there any way to nicely cut out sections of the rover's path? It's not very interesting to see it just shake in one spot for may Sols because it didn't move much.
- Curiosity barely moves until Sol 300. Can we just start it further in their path?
- Perseverance also has a very long section it's "stationary" around the 250-300 sol mark. Honestly "max" speed of 604800x or whatever seems better than the current 100_000

jjspace · 2025-08-29T19:34:41Z

Apps/Sandcastle/gallery/Mars.jpg

Please shrink this waaaay down to match the other thumbnails. Should be ~250px in width

jjspace · 2025-08-29T19:36:59Z

packages/engine/Source/Core/Ellipsoid.js

@@ -254,6 +254,14 @@ Ellipsoid.MOON = Object.freeze(
  ),
 );

+/**
+ * An Ellipsoid instance initialized to a sphere with the mean radii of Mars.


Should we say where we sourced our value from? For the earth WGS84 is well known and clear. Just trying to get ahead of someone asking

jjspace · 2025-08-29T19:37:52Z

Apps/Sandcastle/gallery/Mars.html

+            scene.camera.flyTo(landmark);
+          };
+
+          const toolbarMenuEntries = [


If we're keeping 2 lists this should be renamed to make it clear in the code it's a different list than the first time this was declared.

mzschwartz5 · 2025-08-29T20:38:59Z

This is definitely a very lengthy sandcastle

Yes... definitely pulled as much as I could out into data, but it gets lengthier every time I revise upon feedback :)
Considering that, here's a list of the items you called out that I think definitely should be addressed, and are changes or fixes rather than additions:

"Spin on first load" is not working
Make camera face somewhat down when using flyTo - I vaguely recall reading somewhere that there's an option for this. I'm pretty sure.
The "Landing site" POIs overlap with the nearby crater names. - this has undergone some revision already, but I think this is OK to change. I agree it's not ideal.
Rover changes: starting off with a higher multiplier, potentially starting off mid path at more interesting points.
Shadow bug. (I don't think we should disable shadows entirely)

I think some of the other changes may be more trouble than they're worth / lengthen the sandcastle more (e.g. cutting out sections of rover data, first-time-only camera tips, optgroups and other menu shenanigans) or have already been discussed in other peoples' feedback (e.g. we do want the POIs in alphabetical order).

But on the whole, many of these are easy adjustments that will improve the experience.

Fixes spin-on-load, camera pitch while flying, label overlap, rover animation UX, and disables shadows.

mzschwartz5 force-pushed the mars branch from aace0dd to 3cf3c99 Compare August 22, 2025 00:34

Adds Mars ellipsoid and trackable rovers

64ec134

mzschwartz5 force-pushed the mars branch from 3cf3c99 to 64ec134 Compare August 22, 2025 00:41

mzschwartz5 added 2 commits August 22, 2025 13:32

Adds Mars points of interest and small camera tweaks

7a6ec49

Adds thumbnail for mars sandcastle

a4488e6

mzschwartz5 marked this pull request as ready for review August 22, 2025 17:41

ggetz requested changes Aug 26, 2025

View reviewed changes

ggetz assigned mzschwartz5 Aug 26, 2025

ggetz added the priority - next release label Aug 26, 2025

mzschwartz5 added 2 commits August 27, 2025 16:44

Mars sandcastle revamp

b628446

Polishes changes to Mars sandcastle

08a23c5

mzschwartz5 added 4 commits August 28, 2025 20:54

Refines mars sandcastle with more feedback

c8ae7b0

Minor fixes to mars sandcastle

88b56e0

Update Mars Ion asset ID

3a65ea0

Mars sandcastle code cleanup

9755e91

mzschwartz5 requested a review from jjspace August 29, 2025 15:33

mzschwartz5 added 2 commits August 29, 2025 13:02

Alphabetizes mars sandcastle points of interest

31c1305

Updates mars sandcastle ion asset ID and removes token

5979ae4

Adds Jezero Crater landmark to Mars sandcastle

212f7f5

jjspace reviewed Aug 29, 2025

View reviewed changes

More revisions to Mars Sandcastle

e5b89f1

Fixes spin-on-load, camera pitch while flying, label overlap, rover animation UX, and disables shadows.

Adds Mars ellipsoid and trackable rovers #12828

Are you sure you want to change the base?

Adds Mars ellipsoid and trackable rovers #12828

Uh oh!

Conversation

mzschwartz5 commented Aug 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Issue number and link

Testing plan

Author checklist

Uh oh!

github-actions bot commented Aug 22, 2025

Uh oh!

LisaBosCesium commented Aug 22, 2025

Uh oh!

javagl commented Aug 22, 2025

Uh oh!

ggetz commented Aug 26, 2025

Uh oh!

ggetz left a comment

Choose a reason for hiding this comment

Uh oh!

ggetz Aug 26, 2025

Choose a reason for hiding this comment

Uh oh!

mzschwartz5 commented Aug 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

LisaBosCesium commented Aug 28, 2025

Uh oh!

mzschwartz5 commented Aug 29, 2025

Uh oh!

LisaBosCesium commented Aug 29, 2025

Uh oh!

mzschwartz5 commented Aug 29, 2025

Uh oh!

LisaBosCesium commented Aug 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mzschwartz5 commented Aug 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jjspace left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jjspace Aug 29, 2025

Choose a reason for hiding this comment

Uh oh!

jjspace Aug 29, 2025

Choose a reason for hiding this comment

Uh oh!

jjspace Aug 29, 2025

Choose a reason for hiding this comment

Uh oh!

mzschwartz5 commented Aug 29, 2025

Uh oh!

Uh oh!

mzschwartz5 commented Aug 22, 2025 •

edited

Loading

mzschwartz5 commented Aug 26, 2025 •

edited

Loading

LisaBosCesium commented Aug 29, 2025 •

edited

Loading

mzschwartz5 commented Aug 29, 2025 •

edited

Loading

jjspace left a comment •

edited

Loading