About the placement of CubeMapPanorama

CesiumJS
1

I have point clouds from a scanner along with camera positions, 6 cubemap face images, and a camera-to-world transformation matrix for each image. I’m trying to overlay the point cloud and panorama using Cesium’s CubeMapPanorama. I have two questions:

  1. sources: What coordinate system do the X/Y/Z axes in positiveX, negativeX, positiveY, negativeY, positiveZ, negativeZ refer to? ECEF? TEME (like SkyBox)? Or a local frame defined by transform?
  2. transform: What kind of matrix is expected here? What does it transform from and to?

I understand it’s similar to SkyBox, but I can’t find documentation on the face axes and transform specification, so my implementation is stuck. Any guidance would be appreciated.

2

I’m not deeply familiar with some aspects of the cube map panorama functionality that has recently been introduced. Maybe @Luke_McKinstry can provide additional details about the coordinate systems.

Until then:

The sources seem to refer to the local frame that is defined by the transform. There may be aspects on top of that, namely related to “axis conventions” - i.e. what is “up” in that local coordinate system? I also found it a bit difficult to “match” the observed behavior with what one could expect, but coordinate systems and axis conventions can always be a bit confusing.

About the transform itself:

transform: What kind of matrix is expected here? What does it transform from and to?

In contrast to what the documentation says, this should be a Matrix3 (and not a Matrix4 - already took a note to update the documentation).

And it indeed describes the rotation of the cube map around the viewer.

I created the following example, which might help to figure out some of the conventions and effects of these matrices:

Cesium Forum 45663 CubeMap.zip (61.0 KB)

This package contains…

  • a tileset with a unit cube, with detailed information about the face orientations
  • the “sides” of a cube map panorama
  • a Sandcastle for testing all this

When serving that data on localhost, the tileset will display this as shown here:

Cesium CubeMap Rotation

This screencap shows the effect of applying a rotation of 45° around Z to the cube map (in addition to the local frame transform - that may be a bit confusing, but it is mainly intended for demo purposes).

It should be possible to “match” the sides of the cube with the sides of the cube map (although I have not done this yet - it may involve swapping some positive/negative cube map images).

Maybe it helps for some first experiments.

3

Thanks @Chiiii for your question.

The CubeMapPanorama borrows its design from SkyBox.

The default orientation is defined using the True Equator Mean Equinox (TEME) axes, which is what SkyBox uses. If you supply a transform, that will be used instead to define the axes. For most cases, you will want to provide the following which defines a coordinate system at the location origin of the panorama, oriented north + down.

const modelMatrix = Cesium.Matrix4.getMatrix3(
  Cesium.Transforms.localFrameToFixedFrameGenerator("north", "down")(
    Cesium.Cartesian3.fromDegrees(longitude, latitude, height),
    Cesium.Ellipsoid.default
  ),
  new Cesium.Matrix3()
);

scene.primitives.add(new Cesium.CubeMapPanorama({
  sources : { ... }
  transform: modelMatrix,
}));

What kind of matrix is expected here?

We expect a Matrix3 here, the docs said Matrix4 but this will be corrected shortly. We really only car about the rotation to orient the cube map panorama correctly.

As a practical debugging tip, you may need to simply swap which cube face images you are passing to positiveX , negativeX , positiveY , negativeY , positiveZ , negativeZ.

Please let us know if we can provide further clarity as we want to make our documentation as robust as possible.