merge: pull request #61 from brenocq/setup-api

brenocq · web-flow · commit 4dcaf035bad9 · 2025-02-08T20:33:41.000+01:00
Setup rotation API
diff --git a/implot3d.cpp b/implot3d.cpp
@@ -76,8 +76,6 @@ namespace ImPlot3D {
 ImPlot3DContext* GImPlot3D = nullptr;
 #endif
 
-static ImPlot3DQuat init_rotation = ImPlot3DQuat(-0.513269f, -0.212596f, -0.318184f, 0.76819f);
-
 ImPlot3DContext* CreateContext() {
     ImPlot3DContext* ctx = IM_NEW(ImPlot3DContext)();
     if (GImPlot3D == nullptr)
@@ -893,7 +891,7 @@ void ComputeActiveFaces(bool* active_faces, const ImPlot3DQuat& rotation, const
     };
 
     int num_deg = 0; // Check number of planes that are degenerate (seen as a line)
-    for (int i = 0; i < 3; ++i) {
+    for (int i = 0; i < 3; i++) {
         // Determine the active face based on the Z component
         if (fabs(rot_face_n[i].z) < 0.025) {
             // If aligned with the plane, choose the min face for bottom/left
@@ -1106,7 +1104,7 @@ void Locator_Default(ImPlot3DTicker& ticker, const ImPlot3DRange& range, float p
             }
             ticker.AddTick(major, true, true, formatter, formatter_data);
         }
-        for (int i = 1; i < nMinor; ++i) {
+        for (int i = 1; i < nMinor; i++) {
             double minor = major + i * interval / nMinor;
             if (range.Contains((float)minor)) {
                 ticker.AddTick(minor, false, true, formatter, formatter_data);
@@ -1124,7 +1122,7 @@ void Locator_Default(ImPlot3DTicker& ticker, const ImPlot3DRange& range, float p
 }
 
 void AddTicksCustom(const double* values, const char* const labels[], int n, ImPlot3DTicker& ticker, ImPlot3DFormatter formatter, void* data) {
-    for (int i = 0; i < n; ++i) {
+    for (int i = 0; i < n; i++) {
         if (labels != nullptr)
             ticker.AddTick(values[i], false, true, labels[i]);
         else
@@ -1315,7 +1313,7 @@ bool BeginPlot(const char* title_id, const ImVec2& size, ImPlot3DFlags flags) {
     plot.ID = ID;
     plot.JustCreated = just_created;
     if (just_created) {
-        plot.Rotation = init_rotation;
+        plot.Rotation = plot.InitialRotation;
         plot.FitThisFrame = true;
         for (int i = 0; i < 3; i++) {
             plot.Axes[i] = ImPlot3DAxis();
@@ -1327,6 +1325,7 @@ bool BeginPlot(const char* title_id, const ImVec2& size, ImPlot3DFlags flags) {
     plot.PreviousFlags = flags;
     plot.SetupLocked = false;
     plot.OpenContextThisFrame = false;
+    plot.RotationCond = ImPlot3DCond_None;
 
     // Populate title
     plot.SetTitle(title_id);
@@ -1356,9 +1355,8 @@ bool BeginPlot(const char* title_id, const ImVec2& size, ImPlot3DFlags flags) {
     plot.Items.Legend.Reset();
 
     // Reset axes
-    for (int i = 0; i < ImAxis3D_COUNT; ++i) {
+    for (int i = 0; i < ImAxis3D_COUNT; i++)
         plot.Axes[i].Reset();
-    }
 
     // Push frame rect clipping
     ImGui::PushClipRect(plot.FrameRect.Min, plot.FrameRect.Max, true);
@@ -1455,6 +1453,17 @@ void EndPlot() {
 // [SECTION] Setup
 //-----------------------------------------------------------------------------
 
+static const float ANIMATION_ANGULAR_VELOCITY = 2 * 3.1415f;
+
+float CalcAnimationTime(ImPlot3DQuat q0, ImPlot3DQuat q1) {
+    // Compute the angular distance between orientations
+    float dot_product = ImClamp(q0.Dot(q1), -1.0f, 1.0f);
+    float angle = 2.0f * acosf(fabsf(dot_product));
+
+    // Calculate animation time for constant the angular velocity
+    return angle / ANIMATION_ANGULAR_VELOCITY;
+}
+
 void SetupAxis(ImAxis3D idx, const char* label, ImPlot3DAxisFlags flags) {
     ImPlot3DContext& gp = *GImPlot3D;
     IM_ASSERT_USER_ERROR(gp.CurrentPlot != nullptr && !gp.CurrentPlot->SetupLocked,
@@ -1472,7 +1481,7 @@ void SetupAxis(ImAxis3D idx, const char* label, ImPlot3DAxisFlags flags) {
 void SetupAxisLimits(ImAxis3D idx, double min_lim, double max_lim, ImPlot3DCond cond) {
     ImPlot3DContext& gp = *GImPlot3D;
     IM_ASSERT_USER_ERROR(gp.CurrentPlot != nullptr && !gp.CurrentPlot->SetupLocked,
-                         "SetupAxisLimits() needs to be called after BeginPlot and before any setup locking functions (e.g. PlotX)!"); // get plot and axis
+                         "SetupAxisLimits() needs to be called after BeginPlot and before any setup locking functions (e.g. PlotX)!");
     ImPlot3DPlot& plot = *gp.CurrentPlot;
     ImPlot3DAxis& axis = plot.Axes[idx];
     if (!plot.Initialized || cond == ImPlot3DCond_Always) {
@@ -1531,6 +1540,51 @@ void SetupAxesLimits(double x_min, double x_max, double y_min, double y_max, dou
         GImPlot3D->CurrentPlot->FitThisFrame = false;
 }
 
+void SetupBoxRotation(float elevation, float azimuth, bool animate, ImPlot3DCond cond) {
+    // Convert angles from degrees to radians
+    float elev_rad = elevation * IM_PI / 180.0f;
+    float azim_rad = azimuth * IM_PI / 180.0f;
+
+    // Call quaternion SetupBoxRotation
+    SetupBoxRotation(ImPlot3DQuat::FromElAz(elev_rad, azim_rad), animate, cond);
+}
+
+void SetupBoxRotation(ImPlot3DQuat rotation, bool animate, ImPlot3DCond cond) {
+    ImPlot3DContext& gp = *GImPlot3D;
+    IM_ASSERT_USER_ERROR(gp.CurrentPlot != nullptr && !gp.CurrentPlot->SetupLocked,
+                         "SetupBoxRotation() needs to be called after BeginPlot and before any setup locking functions (e.g. PlotX)!");
+    ImPlot3DPlot& plot = *gp.CurrentPlot;
+
+    if (!plot.Initialized || cond == ImPlot3DCond_Always) {
+        if (!animate) {
+            plot.Rotation = rotation;
+            plot.AnimationTime = 0.0f; // Force any running rotation animation to stop
+        } else {
+            plot.RotationAnimationEnd = rotation;
+            plot.AnimationTime = CalcAnimationTime(plot.Rotation, plot.RotationAnimationEnd);
+        }
+        plot.RotationCond = cond;
+    }
+}
+
+void SetupBoxInitialRotation(float elevation, float azimuth) {
+    // Convert angles from degrees to radians
+    float elev_rad = elevation * IM_PI / 180.0f;
+    float azim_rad = azimuth * IM_PI / 180.0f;
+
+    // Call quaternion SetupBoxInitialRotation
+    SetupBoxInitialRotation(ImPlot3DQuat::FromElAz(elev_rad, azim_rad));
+}
+
+void SetupBoxInitialRotation(ImPlot3DQuat rotation) {
+    ImPlot3DContext& gp = *GImPlot3D;
+    IM_ASSERT_USER_ERROR(gp.CurrentPlot != nullptr && !gp.CurrentPlot->SetupLocked,
+                         "SetupBoxInitialRotation() needs to be called after BeginPlot and before any setup locking functions (e.g. PlotX)!");
+    ImPlot3DPlot& plot = *gp.CurrentPlot;
+
+    plot.InitialRotation = rotation;
+}
+
 void SetupBoxScale(float x, float y, float z) {
     ImPlot3DContext& gp = *GImPlot3D;
     IM_ASSERT_USER_ERROR(gp.CurrentPlot != nullptr && !gp.CurrentPlot->SetupLocked,
@@ -1795,7 +1849,6 @@ ImPlot3DRay NDCRayToPlotRay(const ImPlot3DRay& ray) {
 //-----------------------------------------------------------------------------
 
 static const float MOUSE_CURSOR_DRAG_THRESHOLD = 5.0f;
-static const float ANIMATION_ANGULAR_VELOCITY = 2 * 3.1415f;
 
 void HandleInput(ImPlot3DPlot& plot) {
     ImGuiIO& IO = ImGui::GetIO();
@@ -1962,12 +2015,12 @@ void HandleInput(ImPlot3DPlot& plot) {
         plot.ContextClick = false;
 
     // Handle reset rotation with left mouse double click
-    if (plot.Held && ImGui::IsMouseDoubleClicked(ImGuiMouseButton_Right)) {
+    if (plot.Held && ImGui::IsMouseDoubleClicked(ImGuiMouseButton_Right) && !plot.IsRotationLocked()) {
         plot.RotationAnimationEnd = plot.Rotation;
 
         // Calculate rotation to align the z-axis with the camera direction
         if (hovered_plane == -1) {
-            plot.RotationAnimationEnd = init_rotation;
+            plot.RotationAnimationEnd = plot.InitialRotation;
         } else {
             // Compute plane normal
             ImPlot3DPoint axis_normal = ImPlot3DPoint(0.0f, 0.0f, 0.0f);
@@ -2005,7 +2058,7 @@ void HandleInput(ImPlot3DPlot& plot) {
 
                 // Find the candidate with the maximum dot product
                 AxisAlignment* best_candidate = &candidates[0];
-                for (int i = 1; i < 4; ++i) {
+                for (int i = 1; i < 4; i++) {
                     if (candidates[i].dot > best_candidate->dot) {
                         best_candidate = &candidates[i];
                     }
@@ -2017,16 +2070,12 @@ void HandleInput(ImPlot3DPlot& plot) {
             }
         }
 
-        // Compute the angular distance between current and target rotation
-        float dot_product = ImClamp(plot.Rotation.Dot(plot.RotationAnimationEnd), -1.0f, 1.0f);
-        float angle = 2.0f * acosf(fabsf(dot_product));
-
-        // Calculate animation time for constant the angular velocity
-        plot.AnimationTime = angle / ANIMATION_ANGULAR_VELOCITY;
+        // Calculate animation time
+        plot.AnimationTime = CalcAnimationTime(plot.Rotation, plot.RotationAnimationEnd);
     }
 
     // Handle rotation with left mouse dragging
-    if (plot.Held && ImGui::IsMouseDown(ImGuiMouseButton_Right)) {
+    if (plot.Held && ImGui::IsMouseDown(ImGuiMouseButton_Right) && !plot.IsRotationLocked()) {
         ImVec2 delta(IO.MouseDelta.x, IO.MouseDelta.y);
 
         // Map delta to rotation angles (in radians)
@@ -2424,7 +2473,7 @@ ImPlot3DColormap AddColormap(const char* name, const ImVec4* colormap, int size,
     IM_ASSERT_USER_ERROR(gp.ColormapData.GetIndex(name) == -1, "The colormap name has already been used!");
     ImVector<ImU32> buffer;
     buffer.resize(size);
-    for (int i = 0; i < size; ++i)
+    for (int i = 0; i < size; i++)
         buffer[i] = ImGui::ColorConvertFloat4ToU32(colormap[i]);
     return gp.ColormapData.Append(name, buffer.Data, size, qual);
 }
@@ -2868,6 +2917,16 @@ ImPlot3DQuat ImPlot3DQuat::FromTwoVectors(const ImPlot3DPoint& v0, const ImPlot3
     return q;
 }
 
+ImPlot3DQuat ImPlot3DQuat::FromElAz(float elevation, float azimuth) {
+    // Create quaternions for azimuth and elevation
+    ImPlot3DQuat azimuth_quat(azimuth, ImPlot3DPoint(0.0f, 0.0f, 1.0f));     // Rotate around Z-axis
+    ImPlot3DQuat elevation_quat(elevation, ImPlot3DPoint(1.0f, 0.0f, 0.0f)); // Rotate around X-axis
+    ImPlot3DQuat zero_quat(-IM_PI / 2, ImPlot3DPoint(1.0f, 0.0f, 0.0f));     // Rotate to zero azimuth/elevation orientation
+
+    // Combine rotations
+    return elevation_quat * zero_quat * azimuth_quat;
+}
+
 float ImPlot3DQuat::Length() const {
     return ImSqrt(x * x + y * y + z * z + w * w);
 }
diff --git a/implot3d.h b/implot3d.h
@@ -373,10 +373,22 @@ IMPLOT3D_API void SetupAxisTicks(ImAxis3D axis, double v_min, double v_max, int
 // Sets the label and/or flags for primary X/Y/Z axes (shorthand for three calls to SetupAxis)
 IMPLOT3D_API void SetupAxes(const char* x_label, const char* y_label, const char* z_label, ImPlot3DAxisFlags x_flags = 0, ImPlot3DAxisFlags y_flags = 0, ImPlot3DAxisFlags z_flags = 0);
 
-// Sets the X/Y/Z axes range limits. If ImPlotCond_Always is used, the axes limits will be locked (shorthand for two calls to SetupAxisLimits)
+// Sets the X/Y/Z axes range limits. If ImPlot3DCond_Always is used, the axes limits will be locked (shorthand for two calls to SetupAxisLimits)
 IMPLOT3D_API void SetupAxesLimits(double x_min, double x_max, double y_min, double y_max, double z_min, double z_max, ImPlot3DCond cond = ImPlot3DCond_Once);
 
-// Sets the plot box X/Y/Z scale. A scale of 1.0 is the default. Values greater than 1.0 enlarge the plot, while values between 0.0 and 1.0 shrink it.
+// Sets the plot box rotation given the elevation and azimuth angles in degrees. If ImPlot3DCond_Always is used, the rotation will be locked
+IMPLOT3D_API void SetupBoxRotation(float elevation, float azimuth, bool animate = false, ImPlot3DCond cond = ImPlot3DCond_Once);
+
+// Sets the plot box rotation given a quaternion. If ImPlot3DCond_Always is used, the rotation will be locked
+IMPLOT3D_API void SetupBoxRotation(ImPlot3DQuat rotation, bool animate = false, ImPlot3DCond cond = ImPlot3DCond_Once);
+
+// Sets the plot box initial rotation given the elevation and azimuth angles in degrees. The initial rotation is the rotation the plot goes back to when a left mouse button double click happens
+IMPLOT3D_API void SetupBoxInitialRotation(float elevation, float azimuth);
+
+// Sets the plot box initial rotation given a quaternion. The initial rotation is the rotation the plot goes back to when a left mouse button double click happens
+IMPLOT3D_API void SetupBoxInitialRotation(ImPlot3DQuat rotation);
+
+// Sets the plot box X/Y/Z scale. A scale of 1.0 is the default. Values greater than 1.0 enlarge the plot, while values between 0.0 and 1.0 shrink it
 IMPLOT3D_API void SetupBoxScale(float x, float y, float z);
 
 IMPLOT3D_API void SetupLegend(ImPlot3DLocation location, ImPlot3DLegendFlags flags = 0);
@@ -393,7 +405,7 @@ IMPLOT3D_TMP void PlotTriangle(const char* label_id, const T* xs, const T* ys, c
 
 IMPLOT3D_TMP void PlotQuad(const char* label_id, const T* xs, const T* ys, const T* zs, int count, ImPlot3DQuadFlags flags = 0, int offset = 0, int stride = sizeof(T));
 
-// Plot the surface defined by a grid of vertices. The grid is defined by the x and y arrays, and the z array contains the height of each vertex. A total of x_count * y_count vertices are expected for each array. Leave #scale_min and #scale_max both at 0 for automatic color scaling, or set them to a predefined range.
+// Plot the surface defined by a grid of vertices. The grid is defined by the x and y arrays, and the z array contains the height of each vertex. A total of x_count * y_count vertices are expected for each array. Leave #scale_min and #scale_max both at 0 for automatic color scaling, or set them to a predefined range
 IMPLOT3D_TMP void PlotSurface(const char* label_id, const T* xs, const T* ys, const T* zs, int x_count, int y_count, double scale_min = 0.0, double scale_max = 0.0, ImPlot3DSurfaceFlags flags = 0, int offset = 0, int stride = sizeof(T));
 
 IMPLOT3D_API void PlotMesh(const char* label_id, const ImPlot3DPoint* vtx, const unsigned int* idx, int vtx_count, int idx_count, ImPlot3DMeshFlags flags = 0);
@@ -669,6 +681,9 @@ struct ImPlot3DQuat {
     // Set quaternion from two vectors
     IMPLOT3D_API static ImPlot3DQuat FromTwoVectors(const ImPlot3DPoint& v0, const ImPlot3DPoint& v1);
 
+    // Set quaternion given elevation and azimuth angles in radians
+    IMPLOT3D_API static ImPlot3DQuat FromElAz(float elevation, float azimuth);
+
     // Get quaternion length
     IMPLOT3D_API float Length() const;
 
diff --git a/implot3d_demo.cpp b/implot3d_demo.cpp
@@ -565,6 +565,52 @@ void DemoBoxScale() {
     }
 }
 
+void DemoBoxRotation() {
+    float origin[2] = {0.0f, 0.0f};
+    float axis[2] = {0.0f, 1.0f};
+
+    // Sliders for rotation angles
+    static float elevation = 45.0f;
+    static float azimuth = -135.0f;
+    static bool animate = false;
+    ImGui::Text("Rotation");
+    bool changed = false;
+    if (ImGui::SliderFloat("Elevation", &elevation, -90.0f, 90.0f, "%.1f degrees"))
+        changed = true;
+    if (ImGui::SliderFloat("Azimuth", &azimuth, -180.0f, 180.0f, "%.1f degrees"))
+        changed = true;
+    ImGui::Checkbox("Animate", &animate);
+
+    ImGui::Text("Initial Rotation");
+    ImGui::SameLine();
+    HelpMarker("The rotation will be reset to the initial rotation when you double right-click");
+    static float init_elevation = 45.0f;
+    static float init_azimuth = -135.0f;
+    ImGui::SliderFloat("Initial Elevation", &init_elevation, -90.0f, 90.0f, "%.1f degrees");
+    ImGui::SliderFloat("Initial Azimuth", &init_azimuth, -180.0f, 180.0f, "%.1f degrees");
+
+    if (ImPlot3D::BeginPlot("##BoxRotation")) {
+        ImPlot3D::SetupAxesLimits(-1, 1, -1, 1, -1, 1, ImPlot3DCond_Always);
+
+        // Set initial rotation
+        ImPlot3D::SetupBoxInitialRotation(init_elevation, init_azimuth);
+
+        // Set the rotation using the specified elevation and azimuth
+        if (changed)
+            ImPlot3D::SetupBoxRotation(elevation, azimuth, animate, ImPlot3DCond_Always);
+
+        // Plot axis lines
+        ImPlot3D::SetNextLineStyle(ImVec4(0.8f, 0.2f, 0.2f, 1));
+        ImPlot3D::PlotLine("X-Axis", axis, origin, origin, 2);
+        ImPlot3D::SetNextLineStyle(ImVec4(0.2f, 0.8f, 0.2f, 1));
+        ImPlot3D::PlotLine("Y-Axis", origin, axis, origin, 2);
+        ImPlot3D::SetNextLineStyle(ImVec4(0.2f, 0.2f, 0.8f, 1));
+        ImPlot3D::PlotLine("Z-Axis", origin, origin, axis, 2);
+
+        ImPlot3D::EndPlot();
+    }
+}
+
 void DemoTickLabels() {
     static bool custom_ticks = false;
     static bool custom_labels = true;
@@ -776,6 +822,7 @@ void ShowDemoWindow(bool* p_open) {
         }
         if (ImGui::BeginTabItem("Axes")) {
             DemoHeader("Box Scale", DemoBoxScale);
+            DemoHeader("Box Rotation", DemoBoxRotation);
             DemoHeader("Tick Labels", DemoTickLabels);
             ImGui::EndTabItem();
         }
diff --git a/implot3d_internal.h b/implot3d_internal.h
@@ -486,6 +486,7 @@ struct ImPlot3DAxis {
         ShowDefaultTicks = true;
         FitExtents.Min = HUGE_VAL;
         FitExtents.Max = -HUGE_VAL;
+        RangeCond = ImPlot3DCond_None;
         Ticker.Reset();
     }
 
@@ -552,7 +553,9 @@ struct ImPlot3DPlot {
     ImRect CanvasRect; // Frame rectangle reduced by padding
     ImRect PlotRect;   // Bounding rectangle for the actual plot area
     // Rotation & axes & box
-    ImPlot3DQuat Rotation;  // Current rotation quaternion
+    ImPlot3DQuat InitialRotation; // Initial rotation quaternion
+    ImPlot3DQuat Rotation;        // Current rotation quaternion
+    ImPlot3DCond RotationCond;
     ImPlot3DAxis Axes[3];   // X, Y, Z axes
     ImPlot3DPoint BoxScale; // Scale factor for plot box X, Y, Z axes
     // Animation
@@ -579,7 +582,9 @@ struct ImPlot3DPlot {
         PreviousFlags = Flags = ImPlot3DFlags_None;
         JustCreated = true;
         Initialized = false;
+        InitialRotation = ImPlot3DQuat(-0.513269f, -0.212596f, -0.318184f, 0.76819f);
         Rotation = ImPlot3DQuat(0.0f, 0.0f, 0.0f, 1.0f);
+        RotationCond = ImPlot3DCond_None;
         for (int i = 0; i < 3; i++)
             Axes[i] = ImPlot3DAxis();
         BoxScale = ImPlot3DPoint(1.0f, 1.0f, 1.0f);
@@ -602,6 +607,7 @@ struct ImPlot3DPlot {
     }
     inline bool HasTitle() const { return !Title.empty() && !ImPlot3D::ImHasFlag(Flags, ImPlot3DFlags_NoTitle); }
     inline const char* GetTitle() const { return Title.Buf.Data; }
+    inline bool IsRotationLocked() const { return RotationCond == ImPlot3DCond_Always; }
 
     void ExtendFit(const ImPlot3DPoint& point);
     ImPlot3DPoint RangeMin() const;
