Working With SEQUOIA Documents

The SEQUOIA Multi-Document Interface

• SEQUOIA implements a new breed of multi-document User Interface. It lets you
  • Edit one Document using an arbitrary number of views and control panels,
  • Clone a Document to create a branch and make experiment with its settings without affecting the source Document,
  • Edit any number of unrelated Documents at the same time, including working in parallel and sharing the data cache and some controls like camera navigation, camera animation, bookmarks etc.
  • Switch Panels according to the current Document, or lock some Panels to specific Documents
• You can also launch multiple instances of the SEQUOIA application to work independently on multiple Documents without sharing any data or controls - only Bookmarks and Camera Animation keyframes can be dragged and dropped between SEQUOIA instances.

The SEQUOIA Document

• “Document” is the term used to describe a SEQUOIA scene. SEQUOIA Documents can exist in memory or on disk.
• When SEQUOIA is launched, a new empty “Untitled” Document will be created and can be populated with objects.
• A Document can be closed manually via
  • The File > CLOSE Document > ... menu.
  • The Viewport Options menu > Clode Document > ... menu.
• Documents are never closed automatically, except when closing the SEQIOIA application.
  • For example, closing a Viewport Panel showing the content of a Document does not remove the Document from memory.
  • A new Viewport can be opened or an existing Viewport could be switched to show the content at the existing Document again.

The Active Document

• While there can be multiple open Documents at any given time, only one of these Documents will be considered the Active Document.
• The activation of a Document is performed by selecting a Viewport associated with that Document
  • The Active Viewport will show a border with the same color as the associated Document.

Viewports And Documents

• The Viewport panel is a “window” into a Document’s world.
• Each Viewport can be associated with a Document, but a Document can exist even if no Viewport exists to look into it.
• By default, a single viewport will exist when SEQUOIA is started, representing the default Untitled Document.
• The creation of a new Document via File > New or File > Clone will automatically create a new Viewport to look at its content.
• The creation of a new Viewport via Panels > VIEWPORT - Create New Panel menu item will not create a new Document
  • It will create a new panel docked to the side of the existing Viewport panel.
  • It will set the new Viewport to display the content of the Active Document.

Automatic Document Colors

• Every Document will be assigned a color to make it easier to distinguish between all open Documents at a glance, especially when working with two or more Documents at the same time.
• The colors are assigned according to a pre-defined scheme.
  • The first 10 colors to use are currently declared in the file Sequoia_colors.json .
  • The same colors will be reused for the next 10 documents.
• The Document color shows up in the upper left corner Options Menu icon of a Viewport, as well as on the Viewport icon on the tab.
• When a Viewport is selected, the Document color is also used to draw an outline border around the viewport to denote that it is the active viewport (and thus the Active Document).

• In the above screenshot, two Documents were created - “Untitled” (green) and “Untitled 2” (orange).
• The green Document is the Active one.
• Switching to the orange tab would make Document “Untitled 2” the Active Document.

Document-Aware Panels

• Most panels in the SEQUOIA User Interface are Document-Aware.
• Document-Aware Panels will display a list of all open Documents in memory in their Options Menu just like the Viewports, but with the addition of a default “Active Document” option.

• Any Document-Aware panels that are set to “Active Document” will automatically switch to display relevant data from the Active Document.

For example,

• Two Documents are opened
• A Point Loader is selected in the first Document
• A Mesher is selected in the second Document
• Switching the Active Document between the first and second Document will update the content of the Object Properties panel to show either the Point Loader or the Mesher.

• Switching the Object Properties panel to a specific Document entry via the menu will lock the panel to that Document regardless of what the Active Document is.

In the above example,

• Lock the Object Properties panel to the Document with the Point Loader
• Switching to the Document with the Mesher will still display the Point Loader’s properties in the Object Properties panel.
• Now you could open a new Object Properties panel using the Panels>OBJECT PROPERTIES - Create New Panel menu.
• Dock it to the side of the first Object Properties panel
• Lock it to the second Document
• Now you can display the Mesher properties from the second Document side-by-side with the Point Loader’s properties from the First document, regardless of which Document is the Active one!

Loading Documents

• If the Active Document is Untitled and completely empty and unmodified, using File > Open... to load an existing .SQ file from disk will replace the Untitled Document with the content from disk.
• If the Active Document has been modified or saved to disk, using File > Open... to load an existing .SQ file from disk will create a new Document and associated Viewport which will be docked as a tab of the existing Viewport panel.

Saving Documents

• The Active Document can be saved to an .SQ file on disk using the
  • File > SAVE Document menu item or by pressing CTRL+S - if the Document is Untitled, a file save dialog will open, otherwise the existing file will be overwritten.
  • File > SAVE Document AS... menu item - a file save dialog will open even if the document already has a name.
• The .SQ file uses the SQLite database format and only stores the node graph (scene objects) without their data.

For example,

• A Document contains a Point Loader pointing at an external point data file, and a Mesher object creating geometry from the Point Loader’s data.
• Saving the Document will only save the Point Loader’s and Mesher’s properties and their relationship
• Their respective point data and mesh data will not be stored explicitly in the Document.
• When the Document is loaded again, the point data will be restored from the referenced disk file, and the mesh data will have to be recomputed.