vtkMRMLScene.h

Go to the documentation of this file.

/*=auto=========================================================================

Portions (c) Copyright 2005 Brigham and Women's Hospital (BWH) All Rights Reserved.

See COPYRIGHT.txt
or http://www.slicer.org/copyright/copyright.txt for details.

Program:   3D Slicer
Module:    $RCSfile: vtkMRMLScene.h,v $
Date:      $Date: 2006/03/17 15:10:09 $
Version:   $Revision: 1.18 $

=========================================================================auto=*/

#ifndef __vtkMRMLScene_h
#define __vtkMRMLScene_h

#define CURRENT_MRML_VERSION "Slicer4.4.0"

// MRML includes
#include "vtkMRML.h"

// VTK includes
#include <vtkObject.h>
#include <vtkSmartPointer.h>
#include <vtkWeakPointer.h>

// STD includes
#include <list>
#include <map>
#include <random>
#include <set>
#include <string>
#include <vector>

class vtkCacheManager;
class vtkDataIOManager;
class vtkTagTable;

class vtkCallbackCommand;
class vtkCollection;
class vtkGeneralTransform;
class vtkImageData;
class vtkURIHandler;
class vtkMRMLMessageCollection;
class vtkMRMLNode;
class vtkMRMLSceneViewNode;
class vtkMRMLSubjectHierarchyNode;
class vtkMRMLStorableNode;
class vtkMRMLStorageNode;

//
class VTK_MRML_EXPORT vtkMRMLScene : public vtkObject
{
  friend class vtkMRMLSceneViewNode;

public:
  static vtkMRMLScene *New();
  vtkTypeMacro(vtkMRMLScene, vtkObject);
  void PrintSelf(ostream& os, vtkIndent indent) override;

  void SetURL(const char *url);

  const char *GetURL();

  void SetRootDirectory(const char *dir);

  const char *GetRootDirectory();

  int Connect();

  int Import();

  int Commit(const char* url=nullptr);

  void Clear(int removeSingletons=0);

  void ResetNodes();

  vtkMRMLNode* CreateNodeByClass(const char* className);

  void RegisterNodeClass(vtkMRMLNode* node, const char* tagName);

  void RegisterNodeClass(vtkMRMLNode* node);

  const char* GetClassNameByTag(const char *tagName);

  const char* GetTagByClassName(const char *className);

  void AddDefaultNode(vtkMRMLNode* node);
  vtkMRMLNode* GetDefaultNodeByClass(const char* className);

  void RemoveAllDefaultNodes();

  vtkCollection* GetNodes();

  vtkMRMLNode* AddNode(vtkMRMLNode *nodeToAdd);

  vtkMRMLNode* AddNewNodeByClass(std::string className, std::string nodeBaseName = "");

  vtkMRMLNode* AddNewNodeByClassWithID(std::string className, std::string nodeBaseName, std::string nodeID);

  vtkMRMLNode* CopyNode(vtkMRMLNode *n);

  void NodeAdded(vtkMRMLNode *n);
  void NodeAdded() {this->NodeAdded(nullptr);}

  void RemoveNode(vtkMRMLNode *n);

  int IsNodePresent(vtkMRMLNode *n);

  void InitTraversal();

  vtkMRMLNode *GetNextNode();

  vtkMRMLNode *GetNextNodeByClass(const char* className);

  vtkCollection *GetNodesByName(const char* name);
  vtkMRMLNode *GetFirstNodeByName(const char* name);

  vtkMRMLNode *GetFirstNode(const char* byName = nullptr, const char* byClass = nullptr,
                            const int* byHideFromEditors = nullptr,
                            bool exactNameMatch = true);

  vtkMRMLNode *GetNodeByID(const char* name);
  vtkMRMLNode *GetNodeByID(std::string name);

  vtkCollection *GetNodesByClassByName(const char* className, const char* name);

  int GetNumberOfNodes();

  vtkMRMLNode* GetNthNode(int n);

  vtkMRMLNode* GetNthNodeByClass(int n, const char* className );
  vtkMRMLNode* GetFirstNodeByClass(const char* className);

  int GetNumberOfNodesByClass(const char* className);

  int GetNodesByClass(const char *className, std::vector<vtkMRMLNode *> &nodes);

  vtkCollection* GetNodesByClass(const char *className);

  vtkMRMLNode* GetSingletonNode(const char* singletonTag, const char* className);

  vtkMRMLNode* GetSingletonNode(vtkMRMLNode* n);

  std::list<std::string> GetNodeClassesList();

  int GetNumberOfRegisteredNodeClasses();
  vtkMRMLNode * GetNthRegisteredNodeClass(int n);

  bool IsNodeClassRegistered(const std::string& className);

  std::string GenerateUniqueName(const std::string& baseName);

  const char* GetUniqueNameByString(const char* baseName);

  vtkMRMLNode* InsertAfterNode(vtkMRMLNode *item, vtkMRMLNode *newItem);
  vtkMRMLNode* InsertBeforeNode(vtkMRMLNode *item, vtkMRMLNode *newItem);

  void SetUndoOn() {UndoFlag=true;}
  void SetUndoOff() {UndoFlag=false;}
  bool GetUndoFlag() {return UndoFlag;}
  void SetUndoFlag(bool flag) {UndoFlag = flag;}

  void Undo();

  void Redo();

  void ClearUndoStack();

  void ClearRedoStack();

  int GetNumberOfUndoLevels() {return static_cast<int>(this->UndoStack.size());}

  int GetNumberOfRedoLevels() {return static_cast<int>(this->RedoStack.size());}

  void SaveStateForUndo();

  void SaveStateForUndo(vtkMRMLNode *node);

  void SaveStateForUndo(vtkCollection *nodes);
  void SaveStateForUndo(std::vector<vtkMRMLNode *> nodes);

  void AddReferencedNodeID(const char *id, vtkMRMLNode *refrencingNode);
  bool IsNodeReferencingNodeID(vtkMRMLNode* referencingNode, const char* id);

  int GetNumberOfNodeReferences();
  vtkMRMLNode* GetNthReferencingNode(int n);
  const char* GetNthReferencedID(int n);

  void RemoveReferencedNodeID(const char *id, vtkMRMLNode *refrencingNode);

  void RemoveNodeReferences(vtkMRMLNode *node);

  void RemoveReferencesToNode(vtkMRMLNode *node);

  void UpdateNodeReferences(vtkCollection* checkNodes=nullptr);

  void CopyNodeReferences(vtkMRMLScene *scene);

  void CopyNodeChangedIDs(vtkMRMLScene *scene);

  void UpdateNodeChangedIDs();

  void RemoveUnusedNodeReferences();

  bool IsReservedID(const std::string& id);

  void AddReservedID(const char *id);

  void RemoveReservedIDs();

  const char* GetChangedID(const char* id);

  vtkCollection* GetReferencedNodes(vtkMRMLNode *node, bool recursive=true);

  void GetReferencingNodes(vtkMRMLNode* referencedNode, std::vector<vtkMRMLNode *> &referencingNodes);

  void GetReferencedSubScene(vtkMRMLNode *node, vtkMRMLScene* newScene);

  int IsFilePathRelative(const char * filepath);

  vtkSetMacro(ErrorCode,unsigned long);
  vtkGetMacro(ErrorCode,unsigned long);

  vtkSetMacro(LoadFromXMLString,int);
  vtkGetMacro(LoadFromXMLString,int);

  vtkSetMacro(SaveToXMLString,int);
  vtkGetMacro(SaveToXMLString,int);

  vtkSetMacro(ReadDataOnLoad,int);
  vtkGetMacro(ReadDataOnLoad,int);

  void SetErrorMessage(const std::string &error);
  std::string GetErrorMessage();

  void SetSceneXMLString(const std::string &xmlString);

  const std::string& GetSceneXMLString();

  void SetErrorMessage(const char * message);

  vtkMRMLSubjectHierarchyNode* GetSubjectHierarchyNode();

  vtkGetObjectMacro(CacheManager, vtkCacheManager);
  virtual void SetCacheManager(vtkCacheManager*);
  vtkGetObjectMacro(DataIOManager, vtkDataIOManager);
  virtual void SetDataIOManager(vtkDataIOManager*);
  vtkGetObjectMacro(URIHandlerCollection, vtkCollection);
  virtual void SetURIHandlerCollection(vtkCollection*);
  vtkGetObjectMacro(UserTagTable, vtkTagTable);
  virtual void SetUserTagTable(vtkTagTable*);

  vtkURIHandler *FindURIHandler(const char *URI);
  vtkURIHandler *FindURIHandlerByName (const char *name);
  void AddURIHandler(vtkURIHandler *handler);

  enum StateType
    {
    BatchProcessState = 0x0001,
    CloseState = 0x0002 | BatchProcessState,
    ImportState = 0x0004 | BatchProcessState,
    RestoreState = 0x0008 | BatchProcessState,
    SaveState = 0x0010,
    UndoState = 0x0020,
    RedoState = 0x0040,
    };

  int GetStates()const;

  inline bool IsBatchProcessing()const;
  inline bool IsClosing()const;
  inline bool IsImporting()const;
  inline bool IsRestoring()const;
  inline bool IsUndoing()const;
  inline bool IsRedoing()const;

  void StartState(unsigned long state, int anticipatedMaxProgress = 0);

  void EndState(unsigned long state);

  void ProgressState(unsigned long state, int progress = 0);

  enum SceneEventType
    {
    NodeAboutToBeAddedEvent = 0x2000,
    NodeAddedEvent,
    NodeAboutToBeRemovedEvent,
    NodeRemovedEvent,

    NewSceneEvent = 66030,
    MetadataAddedEvent = 66032, // ### Slicer 4.5: Simplify - Do not explicitly set for backward compat. See issue #3472
    ImportProgressFeedbackEvent,
    SaveProgressFeedbackEvent,

    StateEvent = 0x2000, 
    StartEvent = 0x0100,
    EndEvent = 0x0200,
    ProgressEvent = 0x0400,

    StartBatchProcessEvent = StateEvent | StartEvent | BatchProcessState,
    EndBatchProcessEvent = StateEvent | EndEvent | BatchProcessState,
    ProgressBatchProcessEvent = StateEvent | ProgressEvent | BatchProcessState,

    StartCloseEvent = StateEvent | StartEvent | CloseState,
    EndCloseEvent = StateEvent | EndEvent | CloseState,
    ProgressCloseEvent = StateEvent | ProgressEvent | CloseState,

    StartImportEvent = StateEvent | StartEvent | ImportState,
    EndImportEvent = StateEvent | EndEvent | ImportState,
    ProgressImportEvent = StateEvent | EndEvent | ImportState,

    StartRestoreEvent = StateEvent | StartEvent | RestoreState,
    EndRestoreEvent = StateEvent | EndEvent | RestoreState,
    ProgressRestoreEvent = StateEvent | ProgressEvent | RestoreState,

    StartSaveEvent = StateEvent | StartEvent | SaveState,
    EndSaveEvent = StateEvent | EndEvent | SaveState,
    ProgressSaveEvent = StateEvent | ProgressEvent | SaveState,

    StartUndoEvent = StateEvent | StartEvent | UndoState,
    EndUndoEvent = StateEvent | EndEvent | UndoState,
    ProgressUndoEvent = StateEvent | ProgressEvent | UndoState,

    StartRedoEvent = StateEvent | StartEvent | RedoState,
    EndRedoEvent = StateEvent | EndEvent | RedoState,
    ProgressRedoEvent = StateEvent | ProgressEvent | RedoState,

    };

  vtkGetStringMacro(LastLoadedVersion);
  vtkSetStringMacro(LastLoadedVersion);

  vtkGetStringMacro(Version);
  vtkSetStringMacro(Version);

  void CopyRegisteredNodesToScene(vtkMRMLScene *scene);

  void CopySingletonNodesToScene(vtkMRMLScene *scene);

  void CopyDefaultNodesToScene(vtkMRMLScene *scene);

  bool GetModifiedSinceRead();

  bool GetStorableNodesModifiedSinceRead(vtkCollection* modifiedStorableNodes = nullptr);

  void SetStorableNodesModifiedSinceRead();

  static void SetStorableNodesModifiedSinceRead(vtkCollection* storableNodes);

  void SetMaximumNumberOfSavedUndoStates(int stackSize);
  vtkGetMacro(MaximumNumberOfSavedUndoStates, int);

  bool WriteToMRB(const char* filename, vtkImageData* thumbnail=nullptr, vtkMRMLMessageCollection* userMessages=nullptr);

  bool ReadFromMRB(const char* fullName, bool clear=false);

  static std::string UnpackSlicerDataBundle(const char* sdbFilePath, const char* temporaryDirectory);

  bool SaveSceneToSlicerDataBundleDirectory(const char* sdbDir, vtkImageData* thumbnail=nullptr, vtkMRMLMessageCollection* userMessages=nullptr);

  void SaveSceneScreenshot(vtkImageData* thumbnail);

  static std::string PercentEncode(std::string s);

  static std::string CreateUniqueFileName(const std::string& filename, const std::string& knownExtension = "");

protected:

  typedef std::map< std::string, std::set<std::string> > NodeReferencesType;

  vtkMRMLScene();
  ~vtkMRMLScene() override;

  void PushIntoUndoStack();
  void PushIntoRedoStack();

  void CopyNodeInUndoStack(vtkMRMLNode *node);
  void CopyNodeInRedoStack(vtkMRMLNode *node);

  vtkMRMLNode* AddNodeNoNotify(vtkMRMLNode *n);

  void AddReferencedNodes(vtkMRMLNode *node, vtkCollection *refNodes, bool recursive=true);

  static void SceneCallback(vtkObject *caller, unsigned long eid, void *clientData, void *callData);

  std::string GenerateUniqueID(vtkMRMLNode* node);
  std::string GenerateUniqueID(const std::string& baseID);
  int GetUniqueIDIndex(const std::string& baseID);
  std::string BuildID(const std::string& baseID, int idIndex)const;

  std::string GenerateUniqueName(vtkMRMLNode* node);

  int GetUniqueNameIndex(const std::string& baseName);

  std::string BuildName(const std::string& baseName, int nameIndex)const;

  void UpdateNodeIDs();

  void AddNodeID(vtkMRMLNode *node);

  void RemoveNodeID(char *nodeID);

  void ClearNodeIDs();

  NodeReferencesType::iterator FindNodeReference(const char* referencedId, vtkMRMLNode* referencingNode);

  void TrimUndoStack();

  void ReserveNodeReferenceIDs(vtkMRMLNode* node);

  void GetNodeReferenceIDsFromUndoStack(std::set<std::string>& referenceIDs) const;

  bool IsNodeIDReservedByUndo(const std::string id) const;

  virtual void SetSubjectHierarchyNode(vtkMRMLSubjectHierarchyNode*);

  bool SaveStorableNodeToSlicerDataBundleDirectory(vtkMRMLStorableNode* storableNode, std::string& dataDir,
    std::map<vtkMRMLStorageNode*, std::vector<std::string> > &originalStorageNodeFileNames, vtkMRMLMessageCollection* userMessages);

  vtkCollection*  Nodes;

  vtkWeakPointer<vtkMRMLSubjectHierarchyNode> SubjectHierarchyNode;

  vtkCacheManager *  CacheManager;
  vtkDataIOManager * DataIOManager;
  vtkCollection *    URIHandlerCollection;
  vtkTagTable *      UserTagTable;

  std::vector<unsigned long> States;

  int  MaximumNumberOfSavedUndoStates;
  bool UndoFlag;

  std::list< vtkCollection* >  UndoStack;
  std::list< vtkCollection* >  RedoStack;

  std::string                 URL;
  std::string                 RootDirectory;

  std::map<std::string, int> UniqueIDs;
  std::map<std::string, int> UniqueNames;
  std::set<std::string>   ReservedIDs;

  std::vector< vtkMRMLNode* > RegisteredNodeClasses;
  std::vector< std::string >  RegisteredNodeTags;

  NodeReferencesType NodeReferences; // ReferencedIDs (string), ReferencingNodes (node pointer)
  std::map< std::string, std::string > ReferencedIDChanges;
  std::map< std::string, vtkSmartPointer<vtkMRMLNode> > NodeIDs;

  // Stores default nodes. If a class is created or reset (using CreateNodeByClass or Clear) and
  // a default node is defined for it then the content of the default node will be used to initialize
  // the class. It is useful for overriding default values that are set in a node's constructor.
  std::map< std::string, vtkSmartPointer<vtkMRMLNode> > DefaultNodes;

  std::string ErrorMessage;

  std::string SceneXMLString;

  int LoadFromXMLString;

  int SaveToXMLString;

  int ReadDataOnLoad;

  vtkMTimeType  NodeIDsMTime;

  void RemoveAllNodes(bool removeSingletons);

  char * Version;
  char * LastLoadedVersion;

  vtkCallbackCommand *DeleteEventCallback;

  std::default_random_engine RandomGenerator;

private:

  vtkMRMLScene(const vtkMRMLScene&);   // Not implemented
  void operator=(const vtkMRMLScene&); // Not implemented

  int LoadIntoScene(vtkCollection* scene);

  unsigned long ErrorCode;

  vtkTimeStamp StoredTime;
};

//------------------------------------------------------------------------------
bool vtkMRMLScene::IsBatchProcessing()const
{
  return (this->GetStates() & vtkMRMLScene::BatchProcessState)
         == vtkMRMLScene::BatchProcessState;
}

//------------------------------------------------------------------------------
bool vtkMRMLScene::IsClosing()const
{
  return (this->GetStates() & vtkMRMLScene::CloseState)
         == vtkMRMLScene::CloseState;
}

//------------------------------------------------------------------------------
bool vtkMRMLScene::IsImporting()const
{
  return (this->GetStates() & vtkMRMLScene::ImportState)
         == vtkMRMLScene::ImportState;
}

//------------------------------------------------------------------------------
bool vtkMRMLScene::IsRestoring()const
{
  return (this->GetStates() & vtkMRMLScene::RestoreState)
         == vtkMRMLScene::RestoreState;
}

//------------------------------------------------------------------------------
bool vtkMRMLScene::IsUndoing()const
{
  return (this->GetStates() & vtkMRMLScene::UndoState)
    == vtkMRMLScene::UndoState;
}

//------------------------------------------------------------------------------
bool vtkMRMLScene::IsRedoing()const
{
  return (this->GetStates() & vtkMRMLScene::RedoState)
    == vtkMRMLScene::RedoState;
}

#endif