[All] Introduce Snapshot feature

[Lucas-TJ]

What is a Snapshot ?

A snapshot is an object that stores all information required to save the state of a simulation, so that it can be later restored.

Concept

General

A snapshot is a class structured like this :

• Data and Links are stored in dedicated structures called DataInfo and LinkInfo
• If the object is a node, then it creates a SnapshotNode is created. It contains data, links, components (SnapshotObject) and child nodes (also SnapshotNode instances).
• If the object is a component, a SnapshotObject is created. It contains only data and links, and is stored inside a SnapshotNode.

Once the snapshot has been built, it can be exported to the format chosen by the user. For example, calling saveSnapshot with the JSON exporter serializes the snapshot into a JSON file. Loading works the same way in reverse: the snapshot is first imported from the chosen format, then used to restore the simulation state.

Step-by-step

Structure of a Snapshot

public:
    struct DataInfo
    {
        std::string name;
        std::string type;
        std::string value;
    };

    struct LinkInfo
    {
        std::string name;
        std::string type;
        std::string value;
    };

    struct SnapshotObject
    {
        std::string m_name;
        std::vector<DataInfo> m_dataContainer;
        std::vector<LinkInfo> m_linkContainer;
        void* m_internalState { nullptr };

        SnapshotObject() = default;
        explicit SnapshotObject(const std::string& name) : m_name(name){}

        virtual ~SnapshotObject() = default;
    };

    struct SnapshotNode : public SnapshotObject
    {
        std::vector<SnapshotObject> components;
        std::vector<std::shared_ptr<SnapshotNode>> children;
        
        SnapshotNode() = default;
        SnapshotNode(const std::string& name) : SnapshotObject(name) {}
        SnapshotNode(const SnapshotObject& obj) : SnapshotObject(obj) {}

        ~SnapshotNode() noexcept = default;
    };

    std::shared_ptr<SnapshotNode> m_graphRoot { nullptr };

A Snapshot is organized as a graph. The root object, m_graphRoot, is the object that is exported to or imported from a file (or stored directly in memory). The graph is composed of nodes.

• A node corresponds to the struct SnapshotNode. Each node contains a name, a data container, a link container, a list of components, and a list of child nodes.
• A component corresponds to the struct SnapshotObject. Each component contains a name, a data container, and a link container.
• Data and links are represented in the same way: each entry stores its name, type, and value

For example,

{
    "name" : "root",

    "data" : [{},{}],
    "links" : [{},{}],
    
    "components" : [
        {
            "data" : [{},{}],
            "links" : [{},{}]
        },
        {
            "data" : [{},{}],
            "links" : [{},{}]
        }
    ],

    "children": []
}

Saving and loading snapshots rely on two visitors: SaveSnapshotVisitor and LoadSnapshotVisitor. These visitors traverse the scene graph to collect or restore data and links. Once collected, a snapshot can either be kept in memory or exported to a JSON file using SnapshotJSONExporter. The reverse process is used when loading a snapshot.

Save

Saving a snapshot relies on the SaveSnapshotVisitor, which traverses the scene graph. For each visited node or component, it calls:

Base::saveSnapshot(std::vector<std::shared_ptr<SnapshotNode>>& ).

Inside Base::saveSnapshot , the function

Base::createSnapshotObject(std::vector<std::shared_ptr<Snapshot::SnapshotNode>>&)

creates either a SnapshotObject or a SnapshotNode, depending on the type of the current object.

he snapshot object is then populated with:

• snapshotObject->m_name = this->getName() to store the object's name.
• saveDataIn(*snapshotObject) to serialize the object's data.
• saveLinkIn(*snapshotObject) to serialize the object's links.
• saveInternalStateIn(*snapshotObject) to serialize the object's Internal State.

Finally, the newly created SnapshotObject (or SnapshotNode) is inserted into the snapshot graph.

Load

Loading a snapshot relies on the LoadSnapshotVisitor, which traverses the scene graph and restores the saved state by calling:
Base::loadDataSnapshot(const std::shared_ptr<Snapshot::SnapshotObject>& snapshotObject)

Base::loadLinkSnapshot(const std::shared_ptr<Snapshot::SnapshotObject>& snapshotObject)

Base::loadInternalStateFrom(const Snapshot::SnapshotObject& snapshot)

loadDataSnapshot use : BaseData::read(const std::string& value) to restore data values from the snapshot.

loadLinkSnapshot use : BaseLink::readFromSnapshot(const std::string& value) to restore links from the snapshot.

SnapshotJSONExporter

SnapshotJSONExporter provides all the functions required to export a snapshot to JSON and import it back from a JSON file.

SnapshotManager

SnapshotManager stores and manages snapshots kept in memory.

---

By submitting this pull request, I acknowledge that
I have read, understand, and agree SOFA Developer Certificate of Origin (DCO).

---

Reviewers will merge this pull-request only if

• it builds with SUCCESS for all platforms on the CI.
• it does not generate new warnings.
• it does not generate new unit test failures.
• it does not generate new scene test failures.
• it does not break API compatibility.
• it is more than 1 week old (or has fast-merge label).

[alxbilger]

look if you can use sofa::helper::replaceAll instead to be more concise

[alxbilger]

Suggested change

	msg_error("findSnapshotObject") << "SnapshotObject "<< objectname << " not found";
	msg_error() << "SnapshotObject "<< objectname << " not found";

[alxbilger]

and same for all the msg_error in the same file

[alxbilger]

Use Allman style braces (valid for the whole PR)

[alxbilger]

again sofa::helper::replaceAll?

[alxbilger]

Suggested change

	std::vector<std::string> recentSnapshotFiles;
	std::map<std::string, std::shared_ptr<sofa::core::objectmodel::Snapshot>> recentSnapshots;
	std::vector<std::string> m_recentSnapshotFiles;
	std::map<std::string, std::shared_ptr<sofa::core::objectmodel::Snapshot>> m_recentSnapshots;

[alxbilger]

here you set the name of the component to pi, not the Data. But in the test you want to verify that the Data name is pi

[alxbilger]

Add a documentation please

[alxbilger]

add a documentation please

[alxbilger]

remove empty line between documentation and class declaration

[alxbilger]

use a consistant formatting: fileToString

[alxbilger]

if you only use static methods, I am not sure the non-static data members are used. So I would remove them.

Also, I am not sure about the design of the class. I don't think that this class manages anything. You seem to store all the data elsewhere.

[Lucas-TJ]

This class is here to store snapshots when I save in memory. I use it in SofaImGUI.
I will work on it again to make it clearer.