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
 
// MRML includes
#include "vtkMRML.h"
class vtkCacheManager;
class vtkDataIOManager;
class vtkMRMLMessageCollection;
class vtkMRMLNode;
class vtkMRMLNodeFactory;
class vtkMRMLSceneViewNode;
class vtkMRMLStorableNode;
class vtkMRMLStorageNode;
class vtkMRMLSubjectHierarchyNode;
class vtkTagTable;
class vtkURIHandler;
 
// VTK includes
#include <vtkObject.h>
#include <vtkSmartPointer.h>
#include <vtkWeakPointer.h>
class vtkCallbackCommand;
class vtkCollection;
class vtkGeneralTransform;
class vtkImageData;
 
// STD includes
#include <list>
#include <map>
#include <random>
#include <set>
#include <string>
#include <vector>

//
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);
  void SetURL(const std::string& url) { return this->SetURL(url.c_str()); };

  const char* GetURL();

  void SetRootDirectory(const char* dir);

  const char* GetRootDirectory();

  int Connect(vtkMRMLMessageCollection* userMessages = nullptr);

  int Import(vtkMRMLMessageCollection* userMessages = nullptr);

  int Commit(const char* url = nullptr, vtkMRMLMessageCollection* userMessages = nullptr);

  void Clear(int removeSingletons = 0);

  void ResetNodes();

  vtkMRMLNode* CreateNodeByClass(const char* className);

  vtkMRMLNodeFactory* GetNodeFactory();

  void SetNodeFactory(vtkMRMLNodeFactory* factory);

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

  void RegisterNodeClass(vtkMRMLNode* node);

  void RegisterAbstractNodeClass(std::string className, std::string typeDisplayName);

  const char* GetClassNameByTag(const char* tagName);

  const char* GetTagByClassName(const char* className);

  std::string GetTypeDisplayNameByClassName(std::string 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);

  int GetNumberOfRegisteredAbstractNodeClasses();

  std::string GetNthRegisteredAbstractNodeClassName(int n);

  std::string GetNthRegisteredAbstractNodeTypeDisplayName(int n);

  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();

  void RemoveUnreferencedStorageNodes();

  void RemoveUnreferencedDisplayNodes();
 
  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(LoadFromXMLString, int);
  vtkGetMacro(LoadFromXMLString, int);

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

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

  const std::string& GetSceneXMLString();
 
  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, double progress = 0.0);
 
  enum SceneEventType
  {
    NodeAboutToBeAddedEvent = 0x2000,
    NodeAddedEvent,
    NodeAboutToBeRemovedEvent,
    NodeRemovedEvent,
    NodeClassRegisteredEvent,
 
    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 | ProgressEvent | 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(LastLoadedExtensions);
  vtkSetStringMacro(LastLoadedExtensions);

  vtkGetStringMacro(Version);
  vtkSetStringMacro(Version);

  vtkGetStringMacro(Extensions);
  vtkSetStringMacro(Extensions);

  static bool ParseVersion(const char* versionString, std::string& application, int& major, int& minor, int& patch, int& revision);

  void CopyRegisteredNodesToScene(vtkMRMLScene* scene);

  void CopySingletonNodesToScene(vtkMRMLScene* scene);

  void CopyDefaultNodesToScene(vtkMRMLScene* scene);

  bool GetModifiedSinceRead(vtkCollection* modifiedNodes = nullptr);

  vtkGetMacro(StoredTime, vtkMTimeType);

  bool GetStorableNodesModifiedSinceRead(vtkCollection* modifiedStorableNodes = nullptr);

  bool GetPrivateStorableNodesModifiedSinceRead(vtkCollection* modifiedStorableNodes = nullptr);

  void SetStorableNodesModifiedSinceRead();

  static void SetStorableNodesModifiedSinceRead(vtkCollection* storableNodes);

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

  std::string GetTemporaryBundleDirectory();

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

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

  static std::string UnpackSlicerDataBundle(const char* sdbFilePath, const char* temporaryDirectory, vtkMRMLMessageCollection* userMessages = nullptr);

  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);

  void RemoveInvalidNodeReferences(vtkCollection* checkNodes, const std::set<std::string>& validNodeIDs);

  static void SceneCallback(vtkObject* caller, unsigned long eid, void* clientData, void* callData);
  static void NodeFactoryEventCallback(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*);

  void UpdateNodeReferences(vtkCollection* checkNodes, double progressRangeStart, double progressRangeEnd, double& lastReportedProgress);

  bool WriteToMRBInternal(const char* filename, vtkImageData* thumbnail, vtkMRMLMessageCollection* userMessages);
  bool SaveSceneToSlicerDataBundleDirectoryInternal(const char* sdbDir,
                                                    vtkImageData* screenShot,
                                                    vtkMRMLMessageCollection* userMessages,
                                                    double progressRangeStart,
                                                    double progressRangeEnd);
 
  bool SaveStorableNodeToSlicerDataBundleDirectory(vtkMRMLStorableNode* storableNode,
                                                   std::string& dataDir,
                                                   std::map<vtkMRMLStorageNode*, std::vector<std::string>>& originalStorageNodeFileNames,
                                                   vtkMRMLMessageCollection* userMessages);

  bool GetPrivateStorableNodesDirectory(const std::string& url, std::string& privateDir);

  bool SavePrivateStorableNodes(const std::string& url, vtkMRMLMessageCollection* userMessages = nullptr);
 
  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;

  vtkSmartPointer<vtkMRMLNodeFactory> NodeFactory;
  vtkSmartPointer<vtkCallbackCommand> NodeFactoryCallback;
 
  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 SceneXMLString;
 
  int LoadFromXMLString;
 
  int SaveToXMLString;
 
  int ReadDataOnLoad;
 
  vtkMTimeType NodeIDsMTime;
 
  void RemoveAllNodes(bool removeSingletons);
 
  char* Version;
  char* Extensions;
 
  char* LastLoadedVersion;
  char* LastLoadedExtensions;
 
  vtkCallbackCommand* DeleteEventCallback;
 
  std::default_random_engine RandomGenerator;
 
private:
  vtkMRMLScene(const vtkMRMLScene&);   // Not implemented
  void operator=(const vtkMRMLScene&); // Not implemented

  int LoadIntoScene(vtkCollection* scene, vtkMRMLMessageCollection* userMessages = nullptr);

  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