ImGuizmo Documentation

ImGuizmo is a collection of Dear ImGui-based widgets designed for 3D manipulation and specialized editing tasks. Each widget is provided as a standalone .h/.cpp pair for independent use, or can be used as part of a unified static library built via CMake.

Available widgets include:

• ImViewGizmo: For manipulating view orientation.
• ImGuizmo: For manipulating 4x4 float matrices (rotation, translation, and scale).
• ImSequencer: A timeline sequencer for editing frame start/end ranges across multiple events.
• GraphEditor: A node graph editor featuring connections and a delegate system for custom node rendering.
• ImVectorEditor: A 2D vector geometry path editor supporting pen tools, anchor/handle editing, and host-provided transforms.

You can install ImGuizmo using the vcpkg package manager. For detailed integration steps, refer to the vcpkg-example/ directory in the repository.

vcpkg install imguizmo

If you are using the VSCode CMake Tools extension, you can automate the vcpkg integration by adding the toolchain file path to your .vscode/settings.json.

To ensure compatibility across different machines, it is recommended to use an environment variable (like VCPKG_ROOT) with variable substitution instead of a hardcoded absolute path.

{
    "cmake.configureArgs": [
        "-DCMAKE_TOOLCHAIN_FILE={$env:VCPKG_ROOT}\\scripts\\buildsystems\\vcpkg.cmake"
    ]
}

To install ImGuizmo and its dependencies, use the vcpkg toolchain file during the CMake configuration step. This requires that both cmake and vcpkg are already installed on your system. Providing the toolchain file allows CMake to detect the vcpkg.json manifest file, which triggers the automatic download and compilation of all required dependencies.

mkdir build
cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=C:/dev/vcpkg/scripts/buildsystem/vcpkg.cmake

To use ImGuizmo, you must call ImGuizmo::BeginFrame() once per frame. This should be done immediately after your ImGui new frame call (e.g., ImGui_XXXX_NewFrame()).

ImGuizmo::BeginFrame();

The ImGuizmo::Manipulate function draws and handles a gizmo for a specific matrix.

Key Details:

• Matrix Input/Output: The matrix parameter is both an input (defines where the gizmo is drawn) and an output (updated when the user interacts with it).
• Coordinate Systems: Supports both left-handed and right-handed coordinate systems, as well as both finite and infinite far plane projection matrices.
• Snapping: The snap parameter accepts a float[3] for translation snapping, or a single float for rotation (in degrees) or scale snapping.

Enums:

• OPERATION: TRANSLATE, ROTATE, SCALE
• MODE: LOCAL, WORLD

Signature:

void Manipulate(const float* view, const float* projection, OPERATION operation, MODE mode, float* matrix, float* deltaMatrix = 0, float* snap = 0);

Use ImGuizmo::DrawCube to render a cube where face colors correspond to face normals. This is intended for debugging and testing purposes.

void DrawCube(const float* view, const float* projection, float* matrix);

Use these functions to determine how the user is interacting with the gizmo:

• IsOver(): Returns true if the mouse cursor is currently over any gizmo control (axis, plane, or screen component).
• IsUsing(): Returns true if the mouse is over the gizmo OR if the gizmo is currently being actively moved/manipulated.

The ImVectorEditor::Config struct allows you to customize the editor's appearance, input handling, and coordinate system. Key configuration areas include:

• Canvas & Tools: Set canvasSize and the active tool (Tool::Select or Tool::Pen).
• Transform: Provide a Transform object to handle pan, zoom, and object-level transformations (rotation, scale, translation).
• Style: Customize colors (e.g., pathColor, anchorColor, handleColor), thicknesses, and shapes (ControlPointShape).
• Behavior: Toggle showGrid, allowKeyboardShortcuts, or set readOnly mode.
• Callbacks: Provide a Delegate* to receive BeginEdit and EndEdit notifications.