Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add modelUpAxis and modelForwardAxis to tileset constructor #10439

Merged
merged 7 commits into from Jun 8, 2022

Conversation

ptrgags
Copy link
Contributor

@ptrgags ptrgags commented Jun 8, 2022

This PR adds two constructor options to allow the user more control over the orientation of glTF models in a tileset.

A common difficulty when making 3D Tiles for use in CesiumJS is determining which way to orient the data. CesiumJS makes some assumptions when loading glTF files (+y up because of the glTF specification). Though CesiumJS assumes individual models follow the glTF spec and have +z forward. Meanwhile, 3D Tiles often use earth-centered, earth-fixed (ECEF) coordinates, and +x is (perhaps arbitrarily) chosen as "forward".

Depending on the above, CesiumJS automatically applies rotations to bring the data into ECEF coordinates. This works nicely if the data is in glTF's coordinate space. However, if the positions are in a +z up coordinate system (e.g. a local east-north-up (ENU) coordinate system)), an extra matrix rotation must be baked into the data to cancel out the automatic correction. This is non-obvious and redundant.

This PR adds modelUpAxis and modelForwardAxis that let the user describe the coordinate system used by the glTF models.

Example use cases:

  • Local ENU coordinates:
    • positions in the glTF file: +x = east, +y = north, +z = up
    • modelUpAxis: Axis.Z
    • modelForwardAxis: Axis.X -- This may sound counterintuitive, but CesiumJS chooses +x forward. The model matrix (next step) will position and orient the coordinate system for a particular ENU frame.
    • when loading the tileset, use modelMatrix: Transforms.eastNorthUpToFixedFrame(...) to position the tileset as desired
    • CesiumJS skips the automatic correction since it is not needed (already in +z up, +x forward)
  • Existing 3D Tiles glTFs (default):
    • positions + matrix transform produce ECEF coordinates
    • glTF root matrix applies z-up to y-up rotation to cancel out CesiumJS's automatic correction
    • modelUpAxis: Axis.Y
    • modelForwardAxis: Axis.X (CesiumJS convention)
    • CesiumJS applies a y-up to z-up rotation automatically
  • glTF models added to a tileset
    • positions should follow the glTF conventions. +y up, +z forward
    • modelUpAxis: Axis.Y
    • modelForwardAxis: Axis.Z
    • CesiumJS applies both a z-forward to x-forward and y-up to z-up rotations.

Example ENU sandcastle -- Red = East, Green = North, Blue = Up

@cesium-concierge
Copy link

Thanks for the pull request @ptrgags!

  • ✔️ Signed CLA found.
  • CHANGES.md was not updated.
    • If this change updates the public API in any way, please add a bullet point to CHANGES.md.

Reviewers, don't forget to make sure that:

  • Cesium Viewer works.
  • Works in 2D/CV.

@lilleyse
Copy link
Contributor

lilleyse commented Jun 8, 2022

Looks great!

@lilleyse lilleyse merged commit d85ab90 into main Jun 8, 2022
@lilleyse lilleyse deleted the which-way-is-up branch June 8, 2022 20:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants