Add support for camera reference frames to support camera yaw in certain situations (#4088)

* proof of concept change for fixing camera yaw rotation being ignored Signed-off-by: hultonha <hultonha@amazon.co.uk> * updates to fully support camera roll Signed-off-by: hultonha <hultonha@amazon.co.uk> * small fixes for PR Signed-off-by: hultonha <hultonha@amazon.co.uk> * undo changes in EditorCameraComponent Signed-off-by: hultonha <hultonha@amazon.co.uk> * add test to verify interaction between editor viewport view entity change and modular camera controller Signed-off-by: hultonha <hultonha@amazon.co.uk> * add additional tests for updated camera behaviors Signed-off-by: hultonha <hultonha@amazon.co.uk> * revert change to Camera Gem Output Name Signed-off-by: hultonha <hultonha@amazon.co.uk> * move location of new files Signed-off-by: hultonha <hultonha@amazon.co.uk> * fix tab/spaces issue Signed-off-by: hultonha <hultonha@amazon.co.uk> * remove static from potentially unused functions Signed-off-by: hultonha <hultonha@amazon.co.uk> * set camera lib name in CMakeLists.txt file Signed-off-by: hultonha <hultonha@amazon.co.uk> * cosmetic CMakeLists.txt change Signed-off-by: hultonha <hultonha@amazon.co.uk>
2021-09-22 09:08:24 +01:00
parent 2c55ad5379
commit b865d2aec1
12 changed files with 418 additions and 36 deletions
@@ -254,4 +254,35 @@ if(PAL_TRAIT_BUILD_TESTS_SUPPORTED)
    ly_add_googletest(
        NAME Legacy::EditorLib.Tests
    )
+
+    ly_add_target(
+        NAME EditorLib.Camera.Tests ${PAL_TRAIT_TEST_TARGET_TYPE}
+        NAMESPACE Legacy
+        FILES_CMAKE
+            Lib/Tests/Camera/editor_lib_camera_test_files.cmake
+        INCLUDE_DIRECTORIES
+            PRIVATE
+                .
+        BUILD_DEPENDENCIES
+            PRIVATE
+                AZ::AzCore
+                AZ::AzTest
+                AZ::AzToolsFramework
+                AZ::AzTestShared
+                Legacy::EditorLib
+                Gem::Camera.Editor
+                Gem::AtomToolsFramework.Static
+        RUNTIME_DEPENDENCIES
+            Legacy::EditorLib
+    )
+
+    ly_add_source_properties(
+        SOURCES Lib/Tests/Camera/test_EditorCamera.cpp
+        PROPERTY COMPILE_DEFINITIONS 
+        VALUES CAMERA_EDITOR_MODULE="$<TARGET_FILE_BASE_NAME:Camera.Editor>"
+    )
+
+    ly_add_googletest(
+        NAME Legacy::EditorLib.Camera.Tests
+    )
 endif()
@@ -9,6 +9,7 @@
 #include <EditorModularViewportCameraComposer.h>

 #include <AtomToolsFramework/Viewport/ModularViewportCameraControllerRequestBus.h>
+#include <AzCore/Component/TransformBus.h>
 #include <AzCore/std/smart_ptr/make_shared.h>
 #include <AzFramework/Render/IntersectorInterface.h>
 #include <AzToolsFramework/Viewport/ViewportMessages.h>
@@ -34,10 +35,12 @@ namespace SandboxEditor
        : m_viewportId(viewportId)
    {
        EditorModularViewportCameraComposerNotificationBus::Handler::BusConnect(viewportId);
+        Camera::EditorCameraNotificationBus::Handler::BusConnect();
    }

    EditorModularViewportCameraComposer::~EditorModularViewportCameraComposer()
    {
+        Camera::EditorCameraNotificationBus::Handler::BusDisconnect();
        EditorModularViewportCameraComposerNotificationBus::Handler::BusDisconnect();
    }

@@ -283,4 +286,22 @@ namespace SandboxEditor
        m_orbitCamera->SetOrbitInputChannelId(SandboxEditor::CameraOrbitChannelId());
        m_orbitDollyMoveCamera->SetDollyInputChannelId(SandboxEditor::CameraOrbitDollyChannelId());
    }
+
+    void EditorModularViewportCameraComposer::OnViewportViewEntityChanged(const AZ::EntityId& viewEntityId)
+    {
+        if (viewEntityId.IsValid())
+        {
+            AZ::Transform worldFromLocal = AZ::Transform::CreateIdentity();
+            AZ::TransformBus::EventResult(worldFromLocal, viewEntityId, &AZ::TransformBus::Events::GetWorldTM);
+
+            AtomToolsFramework::ModularViewportCameraControllerRequestBus::Event(
+                m_viewportId, &AtomToolsFramework::ModularViewportCameraControllerRequestBus::Events::SetReferenceFrame,
+                worldFromLocal);
+        }
+        else
+        {
+            AtomToolsFramework::ModularViewportCameraControllerRequestBus::Event(
+                m_viewportId, &AtomToolsFramework::ModularViewportCameraControllerRequestBus::Events::ClearReferenceFrame);
+        }
+    }
 } // namespace SandboxEditor
@@ -10,13 +10,16 @@

 #include <AtomToolsFramework/Viewport/ModularViewportCameraController.h>
 #include <AzFramework/Viewport/CameraInput.h>
+#include <AzToolsFramework/API/EditorCameraBus.h>
 #include <EditorModularViewportCameraComposerBus.h>
 #include <SandboxAPI.h>

 namespace SandboxEditor
 {
    //! Type responsible for building the editor's modular viewport camera controller.
-    class EditorModularViewportCameraComposer : private EditorModularViewportCameraComposerNotificationBus::Handler
+    class EditorModularViewportCameraComposer
+        : private EditorModularViewportCameraComposerNotificationBus::Handler
+        , private Camera::EditorCameraNotificationBus::Handler
    {
    public:
        SANDBOX_API explicit EditorModularViewportCameraComposer(AzFramework::ViewportId viewportId);
@@ -32,6 +35,9 @@ namespace SandboxEditor
        // EditorModularViewportCameraComposerNotificationBus overrides ...
        void OnEditorModularViewportCameraComposerSettingsChanged() override;

+        // EditorCameraNotificationBus overrides ...
+        void OnViewportViewEntityChanged(const AZ::EntityId& viewEntityId) override;
+
        AZStd::shared_ptr<AzFramework::RotateCameraInput> m_firstPersonRotateCamera;
        AZStd::shared_ptr<AzFramework::PanCameraInput> m_firstPersonPanCamera;
        AZStd::shared_ptr<AzFramework::TranslateCameraInput> m_firstPersonTranslateCamera;
@@ -0,0 +1,11 @@
+#
+# Copyright (c) Contributors to the Open 3D Engine Project.
+# For complete copyright and license terms please see the LICENSE at the root of this distribution.
+#
+# SPDX-License-Identifier: Apache-2.0 OR MIT
+#
+#
+
+set(FILES
+    test_EditorCamera.cpp
+)
@@ -0,0 +1,225 @@
+/*
+ * Copyright (c) Contributors to the Open 3D Engine Project.
+ * For complete copyright and license terms please see the LICENSE at the root of this distribution.
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ *
+ */
+
+#include <AZTestShared/Math/MathTestHelpers.h>
+#include <AtomToolsFramework/Viewport/ModularViewportCameraController.h>
+#include <AzCore/UnitTest/TestTypes.h>
+#include <AzFramework/Viewport/ViewportControllerList.h>
+#include <AzTest/GemTestEnvironment.h>
+#include <AzToolsFramework/API/EditorCameraBus.h>
+#include <AzToolsFramework/ToolsComponents/TransformComponent.h>
+#include <EditorModularViewportCameraComposer.h>
+
+namespace UnitTest
+{
+    class EditorCameraTestEnvironment : public AZ::Test::GemTestEnvironment
+    {
+        // AZ::Test::GemTestEnvironment overrides ...
+        void AddGemsAndComponents() override;
+    };
+
+    void EditorCameraTestEnvironment::AddGemsAndComponents()
+    {
+        AddDynamicModulePaths({ CAMERA_EDITOR_MODULE });
+        AddComponentDescriptors({ AzToolsFramework::Components::TransformComponent::CreateDescriptor() });
+    }
+
+    class EditorCameraFixture : public ::testing::Test
+    {
+    public:
+        AtomToolsFramework::ModularCameraViewportContext* m_cameraViewportContextView = nullptr;
+        AZStd::unique_ptr<SandboxEditor::EditorModularViewportCameraComposer> m_editorModularViewportCameraComposer;
+        AZStd::unique_ptr<AZ::DynamicModuleHandle> m_editorLibHandle;
+        AzFramework::ViewportControllerListPtr m_controllerList;
+        AZStd::unique_ptr<AZ::Entity> m_entity;
+
+        static const AzFramework::ViewportId TestViewportId;
+
+        void SetUp() override
+        {
+            m_editorLibHandle = AZ::DynamicModuleHandle::Create("EditorLib");
+            [[maybe_unused]] const bool loaded = m_editorLibHandle->Load(true);
+            AZ_Assert(loaded, "EditorLib could not be loaded");
+
+            m_controllerList = AZStd::make_shared<AzFramework::ViewportControllerList>();
+            m_controllerList->RegisterViewportContext(TestViewportId);
+
+            m_entity = AZStd::make_unique<AZ::Entity>();
+            m_entity->Init();
+            m_entity->CreateComponent<AzToolsFramework::Components::TransformComponent>();
+            m_entity->Activate();
+
+            m_editorModularViewportCameraComposer = AZStd::make_unique<SandboxEditor::EditorModularViewportCameraComposer>(TestViewportId);
+
+            auto controller = m_editorModularViewportCameraComposer->CreateModularViewportCameraController();
+            // set some overrides for the test
+            controller->SetCameraViewportContextBuilderCallback(
+                [this](AZStd::unique_ptr<AtomToolsFramework::ModularCameraViewportContext>& cameraViewportContext) mutable
+                {
+                    cameraViewportContext = AZStd::make_unique<AtomToolsFramework::PlaceholderModularCameraViewportContextImpl>();
+                    m_cameraViewportContextView = cameraViewportContext.get();
+                });
+
+            m_controllerList->Add(controller);
+        }
+
+        void TearDown() override
+        {
+            m_editorModularViewportCameraComposer.reset();
+            m_cameraViewportContextView = nullptr;
+            m_entity.reset();
+            m_editorLibHandle = {};
+        }
+    };
+
+    const AzFramework::ViewportId EditorCameraFixture::TestViewportId = AzFramework::ViewportId(1337);
+
+    TEST_F(EditorCameraFixture, ModularViewportCameraControllerReferenceFrameUpdatedWhenViewportEntityisChanged)
+    {
+        // Given
+        const auto entityTransform = AZ::Transform::CreateFromQuaternionAndTranslation(
+            AZ::Quaternion::CreateRotationX(AZ::DegToRad(90.0f)), AZ::Vector3(10.0f, 5.0f, -2.0f));
+        AZ::TransformBus::Event(m_entity->GetId(), &AZ::TransformBus::Events::SetWorldTM, entityTransform);
+
+        // When
+        // imitate viewport entity changing
+        Camera::EditorCameraNotificationBus::Broadcast(
+            &Camera::EditorCameraNotificationBus::Events::OnViewportViewEntityChanged, m_entity->GetId());
+
+        // ensure the viewport updates after the viewport view entity change
+        const float deltaTime = 1.0f / 60.0f;
+        m_controllerList->UpdateViewport({ TestViewportId, AzFramework::FloatSeconds(deltaTime), AZ::ScriptTimePoint() });
+
+        // retrieve updated camera transform
+        const AZ::Transform cameraTransform = m_cameraViewportContextView->GetCameraTransform();
+
+        // Then
+        // camera transform matches that of the entity
+        EXPECT_THAT(cameraTransform, IsClose(entityTransform));
+    }
+
+    TEST_F(EditorCameraFixture, ReferenceFrameRemainsIdentityAfterExternalCameraTransformChangeWhenNotSet)
+    {
+        // Given
+        m_cameraViewportContextView->SetCameraTransform(AZ::Transform::CreateTranslation(AZ::Vector3(10.0f, 20.0f, 30.0f)));
+
+        // When
+        AZ::Transform referenceFrame = AZ::Transform::CreateTranslation(AZ::Vector3(1.0f, 2.0f, 3.0f));
+        AtomToolsFramework::ModularViewportCameraControllerRequestBus::EventResult(
+            referenceFrame, TestViewportId, &AtomToolsFramework::ModularViewportCameraControllerRequestBus::Events::GetReferenceFrame);
+
+        // Then
+        // reference frame is still the identity
+        EXPECT_THAT(referenceFrame, IsClose(AZ::Transform::CreateIdentity()));
+    }
+
+    TEST_F(EditorCameraFixture, ExternalCameraTransformChangeWhenReferenceFrameIsSetUpdatesReferenceFrame)
+    {
+        // Given
+        const AZ::Transform referenceFrame = AZ::Transform::CreateFromQuaternionAndTranslation(
+            AZ::Quaternion::CreateRotationX(AZ::DegToRad(90.0f)), AZ::Vector3(1.0f, 2.0f, 3.0f));
+        AtomToolsFramework::ModularViewportCameraControllerRequestBus::Event(
+            TestViewportId, &AtomToolsFramework::ModularViewportCameraControllerRequestBus::Events::SetReferenceFrame, referenceFrame);
+
+        const AZ::Transform nextTransform = AZ::Transform::CreateTranslation(AZ::Vector3(10.0f, 20.0f, 30.0f));
+        m_cameraViewportContextView->SetCameraTransform(nextTransform);
+
+        // When
+        AZ::Transform currentReferenceFrame = AZ::Transform::CreateTranslation(AZ::Vector3(1.0f, 2.0f, 3.0f));
+        AtomToolsFramework::ModularViewportCameraControllerRequestBus::EventResult(
+            currentReferenceFrame, TestViewportId,
+            &AtomToolsFramework::ModularViewportCameraControllerRequestBus::Events::GetReferenceFrame);
+
+        // Then
+        EXPECT_THAT(currentReferenceFrame, IsClose(nextTransform));
+    }
+
+    TEST_F(EditorCameraFixture, ReferenceFrameReturnedToIdentityAfterClear)
+    {
+        // Given
+        const AZ::Transform referenceFrame = AZ::Transform::CreateFromQuaternionAndTranslation(
+            AZ::Quaternion::CreateRotationX(AZ::DegToRad(90.0f)), AZ::Vector3(1.0f, 2.0f, 3.0f));
+        AtomToolsFramework::ModularViewportCameraControllerRequestBus::Event(
+            TestViewportId, &AtomToolsFramework::ModularViewportCameraControllerRequestBus::Events::SetReferenceFrame, referenceFrame);
+
+        // When
+        AtomToolsFramework::ModularViewportCameraControllerRequestBus::Event(
+            TestViewportId, &AtomToolsFramework::ModularViewportCameraControllerRequestBus::Events::ClearReferenceFrame);
+
+        AZ::Transform currentReferenceFrame = AZ::Transform::CreateTranslation(AZ::Vector3(1.0f, 2.0f, 3.0f));
+        AtomToolsFramework::ModularViewportCameraControllerRequestBus::EventResult(
+            currentReferenceFrame, TestViewportId,
+            &AtomToolsFramework::ModularViewportCameraControllerRequestBus::Events::GetReferenceFrame);
+
+        // Then
+        EXPECT_THAT(currentReferenceFrame, IsClose(AZ::Transform::CreateIdentity()));
+    }
+
+    TEST_F(EditorCameraFixture, InterpolateToTransform)
+    {
+        // When
+        AZ::Transform transformToInterpolateTo = AZ::Transform::CreateFromQuaternionAndTranslation(
+            AZ::Quaternion::CreateRotationZ(AZ::DegToRad(90.0f)), AZ::Vector3(20.0f, 40.0f, 60.0f));
+        AtomToolsFramework::ModularViewportCameraControllerRequestBus::Event(
+            TestViewportId, &AtomToolsFramework::ModularViewportCameraControllerRequestBus::Events::InterpolateToTransform,
+            transformToInterpolateTo, 0.0f);
+
+        // simulate interpolation
+        m_controllerList->UpdateViewport({ TestViewportId, AzFramework::FloatSeconds(0.5f), AZ::ScriptTimePoint() });
+        m_controllerList->UpdateViewport({ TestViewportId, AzFramework::FloatSeconds(0.5f), AZ::ScriptTimePoint() });
+
+        const auto finalTransform = m_cameraViewportContextView->GetCameraTransform();
+
+        // Then
+        EXPECT_THAT(finalTransform, IsClose(transformToInterpolateTo));
+    }
+
+    TEST_F(EditorCameraFixture, InterpolateToTransformWithReferenceSpaceSet)
+    {
+        // Given
+        const AZ::Transform referenceFrame = AZ::Transform::CreateFromQuaternionAndTranslation(
+            AZ::Quaternion::CreateRotationX(AZ::DegToRad(90.0f)), AZ::Vector3(1.0f, 2.0f, 3.0f));
+        AtomToolsFramework::ModularViewportCameraControllerRequestBus::Event(
+            TestViewportId, &AtomToolsFramework::ModularViewportCameraControllerRequestBus::Events::SetReferenceFrame, referenceFrame);
+
+        AZ::Transform transformToInterpolateTo = AZ::Transform::CreateFromQuaternionAndTranslation(
+            AZ::Quaternion::CreateRotationZ(AZ::DegToRad(90.0f)), AZ::Vector3(20.0f, 40.0f, 60.0f));
+
+        // When
+        AtomToolsFramework::ModularViewportCameraControllerRequestBus::Event(
+            TestViewportId, &AtomToolsFramework::ModularViewportCameraControllerRequestBus::Events::InterpolateToTransform,
+            transformToInterpolateTo, 0.0f);
+
+        // simulate interpolation
+        m_controllerList->UpdateViewport({ TestViewportId, AzFramework::FloatSeconds(0.5f), AZ::ScriptTimePoint() });
+        m_controllerList->UpdateViewport({ TestViewportId, AzFramework::FloatSeconds(0.5f), AZ::ScriptTimePoint() });
+
+        AZ::Transform currentReferenceFrame = AZ::Transform::CreateTranslation(AZ::Vector3(1.0f, 2.0f, 3.0f));
+        AtomToolsFramework::ModularViewportCameraControllerRequestBus::EventResult(
+            currentReferenceFrame, TestViewportId,
+            &AtomToolsFramework::ModularViewportCameraControllerRequestBus::Events::GetReferenceFrame);
+
+        const auto finalTransform = m_cameraViewportContextView->GetCameraTransform();
+
+        // Then
+        EXPECT_THAT(finalTransform, IsClose(transformToInterpolateTo));
+        EXPECT_THAT(currentReferenceFrame, IsClose(AZ::Transform::CreateIdentity()));
+    }
+} // namespace UnitTest
+
+// required to support running integration tests with the Camera Gem
+AZTEST_EXPORT int AZ_UNIT_TEST_HOOK_NAME(int argc, char** argv)
+{
+    ::testing::InitGoogleMock(&argc, argv);
+    AZ::Test::printUnusedParametersWarning(argc, argv);
+    AZ::Test::addTestEnvironments({ new UnitTest::EditorCameraTestEnvironment() });
+    int result = RUN_ALL_TESTS();
+    return result;
+}
+
+IMPLEMENT_TEST_EXECUTABLE_MAIN();
@@ -58,28 +58,6 @@ namespace UnitTest
        return true;
    }

-    class TestModularCameraViewportContextImpl : public AtomToolsFramework::ModularCameraViewportContext
-    {
-    public:
-        AZ::Transform GetCameraTransform() const override
-        {
-            return m_cameraTransform;
-        }
-
-        void SetCameraTransform(const AZ::Transform& transform) override
-        {
-            m_cameraTransform = transform;
-        }
-
-        void ConnectViewMatrixChangedHandler(AZ::RPI::ViewportContext::MatrixChangedEvent::Handler&) override
-        {
-            // noop
-        }
-
-    private:
-        AZ::Transform m_cameraTransform = AZ::Transform::CreateIdentity();
-    };
-
    class ModularViewportCameraControllerFixture : public AllocatorsTestFixture
    {
    public:
@@ -146,7 +124,7 @@ namespace UnitTest
            controller->SetCameraViewportContextBuilderCallback(
                [this](AZStd::unique_ptr<AtomToolsFramework::ModularCameraViewportContext>& cameraViewportContext)
                {
-                    cameraViewportContext = AZStd::make_unique<TestModularCameraViewportContextImpl>();
+                    cameraViewportContext = AZStd::make_unique<AtomToolsFramework::PlaceholderModularCameraViewportContextImpl>();
                    m_cameraViewportContextView = cameraViewportContext.get();
                });

@@ -3642,7 +3642,7 @@ namespace AzToolsFramework
        }
    }

-    void EditorTransformComponentSelection::OnViewportViewEntityChanged(const AZ::EntityId& newViewId)
+    void EditorTransformComponentSelection::OnViewportViewEntityChanged(const AZ::EntityId& viewEntityId)
    {
        AZ_PROFILE_FUNCTION(AzToolsFramework);

@@ -3650,12 +3650,12 @@ namespace AzToolsFramework
        // match the editor camera translation/orientation), record the entity id if we have
        // a manipulator tracking it (entity id exists in m_entityIdManipulator lookups)
        // and remove it when recreating manipulators (see InitializeManipulators)
-        if (newViewId.IsValid())
+        if (viewEntityId.IsValid())
        {
-            const auto entityIdLookupIt = m_entityIdManipulators.m_lookups.find(newViewId);
+            const auto entityIdLookupIt = m_entityIdManipulators.m_lookups.find(viewEntityId);
            if (entityIdLookupIt != m_entityIdManipulators.m_lookups.end())
            {
-                m_editorCameraComponentEntityId = newViewId;
+                m_editorCameraComponentEntityId = viewEntityId;
                RegenerateManipulators();
            }
        }
@@ -270,7 +270,7 @@ namespace AzToolsFramework
        void OnTransformChanged(const AZ::Transform& localTM, const AZ::Transform& worldTM) override;

        // Camera::EditorCameraNotificationBus overrides ...
-        void OnViewportViewEntityChanged(const AZ::EntityId& newViewId) override;
+        void OnViewportViewEntityChanged(const AZ::EntityId& viewEntityId) override;

        // EditorContextVisibilityNotificationBus overrides ...
        void OnEntityVisibilityChanged(bool visibility) override;
@@ -116,11 +116,18 @@ namespace AtomToolsFramework
        // ModularViewportCameraControllerRequestBus overrides ...
        void InterpolateToTransform(const AZ::Transform& worldFromLocal, float lookAtDistance) override;
        AZStd::optional<AZ::Vector3> LookAtAfterInterpolation() const override;
+        AZ::Transform GetReferenceFrame() const override;
+        void SetReferenceFrame(const AZ::Transform& worldFromLocal) override;
+        void ClearReferenceFrame() override;

    private:
        // AzFramework::ViewportDebugDisplayEventBus overrides ...
        void DisplayViewport(const AzFramework::ViewportInfo& viewportInfo, AzFramework::DebugDisplayRequests& debugDisplay) override;

+        //! Update the reference frame after a change has been made to the camera
+        //! view without updating the internal camera via user input.
+        void RefreshReferenceFrame();
+
        //! The current mode the camera controller is in.
        enum class CameraMode
        {
@@ -139,6 +146,8 @@ namespace AtomToolsFramework

        AzFramework::Camera m_camera; //!< The current camera state (pitch/yaw/position/look-distance).
        AzFramework::Camera m_targetCamera; //!< The target (next) camera state that m_camera is catching up to.
+        AzFramework::Camera m_previousCamera; //!< The state of the camera from the previous frame.
+        AZStd::optional<AzFramework::Camera> m_storedCamera; //!< A potentially stored camera for when a custom reference frame is set.
        AzFramework::CameraSystem m_cameraSystem; //!< The camera system responsible for managing all CameraInputs.
        AzFramework::CameraProps m_cameraProps; //!< Camera properties to control rotate and translate smoothness.
        CameraControllerPriorityFn m_priorityFn; //!< Controls at what priority the camera controller should respond to events.
@@ -147,6 +156,7 @@ namespace AtomToolsFramework
        CameraMode m_cameraMode = CameraMode::Control; //!< The current mode the camera is operating in.
        AZStd::optional<AZ::Vector3> m_lookAtAfterInterpolation; //!< The look at point after an interpolation has finished.
                                                                 //!< Will be cleared when the view changes (camera looks away).
+        AZ::Transform m_referenceFrameOverride = AZ::Transform::CreateIdentity(); //!<
        //! Flag to prevent circular updates of the camera transform (while the viewport transform is being updated internally).
        bool m_updatingTransformInternally = false;
        //! Listen for camera view changes outside of the camera controller.
@@ -154,4 +164,17 @@ namespace AtomToolsFramework
        //! The current instance of the modular camera viewport context.
        AZStd::unique_ptr<ModularCameraViewportContext> m_modularCameraViewportContext;
    };
+
+    //! Placeholder implementation for ModularCameraViewportContext (useful for verifying the interface).
+    class PlaceholderModularCameraViewportContextImpl : public AtomToolsFramework::ModularCameraViewportContext
+    {
+    public:
+        AZ::Transform GetCameraTransform() const override;
+        void SetCameraTransform(const AZ::Transform& transform) override;
+        void ConnectViewMatrixChangedHandler(AZ::RPI::ViewportContext::MatrixChangedEvent::Handler& handler) override;
+
+    private:
+        AZ::Transform m_cameraTransform = AZ::Transform::CreateIdentity();
+        AZ::RPI::ViewportContext::MatrixChangedEvent m_viewMatrixChangedEvent;
+    };
 } // namespace AtomToolsFramework
@@ -35,6 +35,16 @@ namespace AtomToolsFramework
        //! Look at point after an interpolation has finished and no translation has occurred.
        virtual AZStd::optional<AZ::Vector3> LookAtAfterInterpolation() const = 0;

+        //! Return the current reference frame.
+        //! @note If a reference frame has not been set or a frame has been cleared, this is just the identity.
+        virtual AZ::Transform GetReferenceFrame() const = 0;
+
+        //! Set a new reference frame other than the identity for the camera controller.
+        virtual void SetReferenceFrame(const AZ::Transform& worldFromLocal) = 0;
+
+        //! Clear the current reference frame to restore the identity.
+        virtual void ClearReferenceFrame() = 0;
+
    protected:
        ~ModularViewportCameraControllerRequests() = default;
    };
@@ -30,6 +30,18 @@ namespace AtomToolsFramework
        "");
    AZ_CVAR(float, ed_cameraSystemOrbitPointSize, 0.1f, nullptr, AZ::ConsoleFunctorFlags::Null, "");

+    AZ::Transform TransformFromMatrix4x4(const AZ::Matrix4x4& matrix)
+    {
+        const auto rotation = AZ::Matrix3x3::CreateFromMatrix4x4(matrix);
+        const auto translation = matrix.GetTranslation();
+        return AZ::Transform::CreateFromMatrix3x3AndTranslation(rotation, translation);
+    }
+
+    AZ::Matrix4x4 Matrix4x4FromTransform(const AZ::Transform& transform)
+    {
+        return AZ::Matrix4x4::CreateFromQuaternionAndTranslation(transform.GetRotation(), transform.GetTranslation());
+    }
+
    // debug
    void DrawPreviewAxis(AzFramework::DebugDisplayRequests& display, const AZ::Transform& transform, const float axisLength)
    {
@@ -167,11 +179,19 @@ namespace AtomToolsFramework
        controller->SetupCameraControllerPriority(m_priorityFn);
        controller->SetupCameraControllerViewportContext(m_modularCameraViewportContext);

-        auto handleCameraChange = [this](const AZ::Matrix4x4&)
+        auto handleCameraChange = [this]([[maybe_unused]] const AZ::Matrix4x4& cameraView)
        {
            // ignore these updates if the camera is being updated internally
            if (!m_updatingTransformInternally)
            {
+                if (m_storedCamera.has_value())
+                {
+                    // if an external change occurs ensure we update the stored reference frame if one is set
+                    RefreshReferenceFrame();
+                    return;
+                }
+
+                m_previousCamera = m_targetCamera;
                UpdateCameraFromTransform(m_targetCamera, m_modularCameraViewportContext->GetCameraTransform());
                m_camera = m_targetCamera;
            }
@@ -231,7 +251,7 @@ namespace AtomToolsFramework
                }
            }

-            m_modularCameraViewportContext->SetCameraTransform(m_camera.Transform());
+            m_modularCameraViewportContext->SetCameraTransform(m_referenceFrameOverride * m_camera.Transform());
        }
        else if (m_cameraMode == CameraMode::Animation)
        {
@@ -240,6 +260,8 @@ namespace AtomToolsFramework
                return t * t * t * (t * (t * 6.0f - 15.0f) + 10.0f);
            };

+            m_cameraAnimation.m_time = AZ::GetClamp(m_cameraAnimation.m_time + event.m_deltaTime.count(), 0.0f, 1.0f);
+
            const auto& [transformStart, transformEnd, animationTime] = m_cameraAnimation;

            const float transitionTime = smootherStepFn(animationTime);
@@ -253,14 +275,13 @@ namespace AtomToolsFramework
            m_camera.m_lookAt = current.GetTranslation();
            m_targetCamera = m_camera;

+            m_modularCameraViewportContext->SetCameraTransform(current);
+
            if (animationTime >= 1.0f)
            {
                m_cameraMode = CameraMode::Control;
+                RefreshReferenceFrame();
            }
-
-            m_cameraAnimation.m_time = AZ::GetClamp(animationTime + event.m_deltaTime.count(), 0.0f, 1.0f);
-
-            m_modularCameraViewportContext->SetCameraTransform(current);
        }

        m_updatingTransformInternally = false;
@@ -280,7 +301,7 @@ namespace AtomToolsFramework
    void ModularViewportCameraControllerInstance::InterpolateToTransform(const AZ::Transform& worldFromLocal, const float lookAtDistance)
    {
        m_cameraMode = CameraMode::Animation;
-        m_cameraAnimation = CameraAnimation{ m_camera.Transform(), worldFromLocal, 0.0f };
+        m_cameraAnimation = CameraAnimation{ m_referenceFrameOverride * m_camera.Transform(), worldFromLocal, 0.0f };
        m_lookAtAfterInterpolation = worldFromLocal.GetTranslation() + worldFromLocal.GetBasisY() * lookAtDistance;
    }

@@ -288,4 +309,59 @@ namespace AtomToolsFramework
    {
        return m_lookAtAfterInterpolation;
    }
+
+    AZ::Transform ModularViewportCameraControllerInstance::GetReferenceFrame() const
+    {
+        return m_referenceFrameOverride;
+    }
+
+    void ModularViewportCameraControllerInstance::SetReferenceFrame(const AZ::Transform& worldFromLocal)
+    {
+        if (!m_storedCamera.has_value())
+        {
+            m_storedCamera = m_previousCamera;
+        }
+
+        m_referenceFrameOverride = worldFromLocal;
+        m_targetCamera.m_pitch = 0.0f;
+        m_targetCamera.m_yaw = 0.0f;
+        m_targetCamera.m_lookAt = AZ::Vector3::CreateZero();
+        m_targetCamera.m_lookDist = 0.0f;
+        m_camera = m_targetCamera;
+    }
+
+    void ModularViewportCameraControllerInstance::ClearReferenceFrame()
+    {
+        m_referenceFrameOverride = AZ::Transform::CreateIdentity();
+
+        if (m_storedCamera.has_value())
+        {
+            m_targetCamera = m_storedCamera.value();
+            m_camera = m_targetCamera;
+        }
+
+        m_storedCamera.reset();
+    }
+
+    void ModularViewportCameraControllerInstance::RefreshReferenceFrame()
+    {
+        m_referenceFrameOverride = m_modularCameraViewportContext->GetCameraTransform() * m_camera.Transform().GetInverse();
+    }
+
+    AZ::Transform PlaceholderModularCameraViewportContextImpl::GetCameraTransform() const
+    {
+        return m_cameraTransform;
+    }
+
+    void PlaceholderModularCameraViewportContextImpl::SetCameraTransform(const AZ::Transform& transform)
+    {
+        m_cameraTransform = transform;
+        m_viewMatrixChangedEvent.Signal(AzFramework::CameraViewFromCameraTransform(Matrix4x4FromTransform(transform)));
+    }
+
+    void PlaceholderModularCameraViewportContextImpl::ConnectViewMatrixChangedHandler(
+        AZ::RPI::ViewportContext::MatrixChangedEvent::Handler& handler)
+    {
+        handler.Connect(m_viewMatrixChangedEvent);
+    }
 } // namespace AtomToolsFramework
@@ -57,6 +57,7 @@ if (PAL_TRAIT_BUILD_HOST_TOOLS)
            PRIVATE
                AZ::AzToolsFramework
                Gem::Camera.Static
+                Gem::AtomToolsFramework.Static
        RUNTIME_DEPENDENCIES
            Legacy::EditorCommon
    )