// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \title Virtual Assistant
    \ingroup quick3d-examples
    \example virtualassistant
    \examplecategory {3D}
    \brief Qt Quick application that presents a 3D model of a virtual assistant with dynamic animations created using QML and timelines.
    \meta {tag} {quick,quick3D}

    \image VirtualAssistantHome.png

    The \e{Virtual Assistant} example demonstrates how to bring a 3D model of a virtual assistant
    to life through timeline animations, increasing user engagement and interaction.

    \section1 Importing 3D Model

    To load the model in \QDS, it is enough to import the .gltf file to the project. \QDS
    then automatically creates a QML file that represents the object. It also generates the
    necessary assets. Without \QDS, you must manually run the \l{Balsam Asset Import Tool}{Balsam} tool.
    In this example, the generated QML file was modified to introduce the states,
    animations, and additional invisible models that allow picking specific parts of the
    Virtual Assistant.

    \section1 Preparing Scene Environment

    The scene uses HDR images to create a skybox and to provide natural lighting.

    \quotefromfile virtualassistant/content/Screen01.ui.qml
    \skipto environment
    \printuntil vignetteRadius
    \printuntil }

    \section1 Camera Options

    Camera properties can be changed from the  Settings panel. You can
    manipulate the field of view (FOV) and skybox rotation using sliders. The checkbox enables an
    \l OrbitCameraController that allows you to also interactively change camera position and
    rotation.

    \section1 Animations

    The animations are created using multiple \l {Timeline} timelines and \l {Keyframe} keyframes.
    Each \l {Timeline} is connected with a different state of the Virtual Assistant. When the state
    changes, the connected animations start playing immediately. At the end of each animation, the
    object returns to the default state and restores the default values, such as position and
    rotation of the model \l {Node} {nodes}. The animations change the properties values of the
    nodes in our skeleton and modify the weight of different \l {MorphTarget} {morph targets} to
    animate the face elements (eyes, mouth).

    Use the buttons on the Animations panel to run the animations. You also click on specific
    model elements like hands, lower body, and face to activate animation related to that part
    of the model.

    \section2 Skeleton Animations
    \list
        \li Entry animation
        \li Exit animation
        \li Exploring scene animation
        \li Backflip animation
        \li Low body bouncing animation
        \li Right and left hand waving animation
    \endlist
    \section2 Morph Target Animations
    \list
        \li Face animations (Happy and Sad)
    \endlist

    Sample implementation of the waving animation on the model's left hand:

    \snippet virtualassistant/asset_imports/Quick3DAssets/VirtualAssistant/VirtualAssistant.qml wavingAnim
*/