Managing Asset Paths

Overview

  • SEQUOIA reads and writes large external data Assets (both point and mesh data) which are stored outside of the .SQ Document file.

  • SEQUOIA does not require a particular project folder structure - it can adapt to the user’s own folder organization.

  • Moving a whole project structure from one machine to another is supported, assuming some basic rules are followed.

Absolute vs. Relative Asset Paths

  • The SEQUOIA User Interface represents the file names of these external Assets as absolute paths.

  • However, to allow easier portability between computers and facilities, the .SQ Document will store both relative and absolute versions of all paths:

    • When an .SQ Document is being saved, every asset path will be converted to a relative path in relation to the location of the .SQ file.

    • The .SQ Document will store both the absolute and the relative path to the asset file.

    • When the SQ Document is loaded, the relative asset path will be expanded to an absolute path based on the current location of the .SQ file.

    • If the asset cannot be found at the expanded relative path, the absolute path stored in the Document will be used.

    • If neither location contains the asset, a file loading error will be reported by the respective object when it is updated.

Moving Assets Between Machines

  • Thanks to the above logic, it would be easy to move both the .SQ Documet and its referenced assets by simply copying the relevant portion of the folder structure while preserving the relative location of the files.

  • Let’s say the project structure looks like this:

    C:
    Project01
    Assets
    Points

    somepointsfile.e57

    somepointsfile.sprt

    Meshes

    somemesh.xmesh

    Documents

    myscene_v01.sq

    myscene_v02.sq

  • The Document myscene_v01.sq contains a Point Loader referencing “somepointsfile.e57”, and its cache file “somepointsfile.sprt” from path “C:\Project01\Assets\Points”.

  • When the Document is saved to “C:\Projects\Documents\myscene_v01.sq”, the asset paths are resolved to relative as “..\Assets\Points\somepointsfile.e57” and “..\Assets\Points\somepointsfile.sprt”, in addition to the absolute paths.

Renaming The Folders

  • Renaming the “Documents” folder to “Scenes” would not affect the loading because the relative asset paths would still resolve correctly.

  • Similarly, renaming the root folder from “Project01” to “ImportantProjectABC” would not affect the loading because the relative paths do not include it.

  • However, renaming the “Assets” folder to “Data” would break the loading because “Assets” is part of the relative path.

Moving The Document Within The Folder Structure

  • Thanks to the absolute asset paths stored in the Document, it is possible to move the .SQ file while keeping the rest in the same place.

  • Let’s say that the user decides to move the content of the “Documents” sub-folder to the “Project01” folder and delete the “Documents” sub-folder.

  • When the .SQ file is loaded, the relative asset paths will not resolve correctly because the file is one folder higher.

  • However, as long as the absolute paths to the assets are still valid, they will still be loaded correctly.

  • The user can then resave the .SQ file and the relative paths will be updated to take into account the new relationship of the Document vs. the Assets folder.

Moving The Files While Retaining Folder Structure

  • Let’s say that the user decides to pass the data to another user on a completely different machine by zipping up the Project01 folder.

    • The new user unzips the archive into the folder “D:\Work\Sequoia\”, producing “D:\Work\Sequoia\Project01\” with all relevant subfolders.

    • He then proceeds to open the the Document “myscene_v01.sq” in Sequoia.

    • SEQUOIA looks at the current folder of the scene which is now “D:\Work\Sequoia\Documents\”

    • It resolves the relative path “..\Assets\Points\somepointsfile.e57” to “D:\Work\Sequoia\Assets\Points\somepointsfile.e57”, and the .SPRT file the same way.

  • Let’s say that the Document “myscene_v02.sq” contained two Mesh Loaders - one reading the asset “somemesh.xmesh” from the “C:\Project01\Assets\Assets\Meshes\” folder, the other reading a file from a file server mapped to “Z:\Data\Meshes\anothermesh.obj”.

    • When the Document was saved, the first Mesh Loader’s path would be converted to a relative path “..\Assets\Meshes\somemesh.xmesh”.

    • But the second Mesh Loader’s path could not be resolved to a relative path on a Windows system because it is not rooted to a common root with the C:\ drive’s folders.

    • So when loading the Document from the new location, the absolute path to “Z:\Data\Meshes\anothermesh.obj” would be used.

    • If the new machine has the same file server mapped to the letter Z:\, the asset will be found and loaded. Otherwise, the asset will be reported as missing.

  • On Unix-based systems (like OSX), all drives have a single root, so the file server asset would be stored as a valid relative path in relation to the common root.