High level document RFC

[slimbuck]

Background

SuperSplat has grown to include many settings which are currently not stored between editing sessions. This introduces friction for users who edit scenes over multiple sittings.

Fixing this will require us to introduce a document storage format for saving the editor state between sessions.

This feature has already been requested by users, see #236.

The document will store the following types of data:

• The splat objects, including their state (deleted, selected, frozen), color tinting, transform
• The list of camera poses
• Viewport settings
• Export and import settings
• Other future settings

The document will primarily be stored and loaded from the user's local hard drive (and perhaps optionally browser local storage) much the way PLY files are currently handled.

Ideally the document would be stored in a user-accessible way:

• A PLY file for each splat object (as binary data)
• A single JSON blob for everything else (as text data)

Alternatives

We have a few options with regards to how we would package such data.

1. Create a custom binary file format and store everything together

This would likely be the least effort solution.

Cons: Users would have no access to the data outside of SuperSplat.

2. Store the document in separate files

This might be possible using the browser's File System API. User would grant SuperSplat access to a folder at load and save time.

Pros: files placed nicely on disk would allow very nice user access

Cons: File System API is not supported in Safari and even Chrome users are shown "scare screens" when requesting read/write access to folders. Also we will have no ability to associate a file type with SuperSplat PWA.

3. Zip files into one archive

This could result in useful user-side disk space saving.

Cons: It might not be possible to stream data to a multi-file zip target in which case memory requirement at save time is doubled.

[willeastcott]

Should there be global settings (persisting regardless of what scene is loaded) and project specific settings? Or should all settings be tied to a specific project?

What should the project file extension be? .ssplat maybe?

I would probably go with a ZIP format containing a .json and .ply and rename it to .ssplat. If a user really needed to access the contents, they could rename to .zip and extract. But generally, that should not be needed by a typical user.

[simonbethke]

Maybe there could be the option to zip-files, but at the same time allow to load the files unzipped.
If its a zip-file, its your 3rd option. However, in that 3rd option you woudl have a json-file or something that holds the semantic state. If that file was outside the zip, it could still be loaded either alongside with the respective ply-files or entirely standalone which would make the editor show a bounding-box instead of the splat file. So the user can load the splat-data afterwards (and also only the objects he needs)

[slimbuck]

I forgot to mention that it is possible to store FileSystemAPI handles to files and directories in IndexDb (see here) which can then be used across browser sessions.

This could be useful for re-opening recently used documents.

[simonbethke]

Afaik, using the indexDB is a pain. I would prefer that the editor knows from its local storage at which disk-locations I stored the files locally so it can provide a recent-files list.

[slimbuck]

Should there be global settings (persisting regardless of what scene is loaded) and project specific settings? Or should all settings be tied to a specific project?

I thought initially we would just store everything in the document itself, nice and simple. But actually when we add support for custom key bindings, for example, a user wouldn't want to have to configure that per document.

(A user would probably also not want to have to configure key bindings per browser install either, but I'm not sure how we can address that without an online user login).

[slimbuck]

The best we can do right now is support import/export of editor settings JSON.

[simonbethke]

Yea, use localStorage to store the settings within the browser and enable export import to move them from one browser to the other.

[slimbuck]

One of the tricky aspects of designing a document format is that we must try to prepare for it evolving over time. We can't afford to make breaking changes to the format and render old files unusable.

The usual way to address this is with file versioning and I guess we'll have to do the same.

Ideally the document loading process will have a migrate step which has transforms to go from version a to b (and b to c, c to d, etc).

Presumably this will only apply to the JSON details, not the raw PLY files.

[simonbethke]

Yea, I think so too. I already implemented this once for supersplat but I think I never pushed anything related... or maybe I did. I implemented that in the context of storing state within the browser

[simonbethke]

I wonder if it is a good idea to prespecify this overhead ahead of having plenty of these issues or if it might be better to start with something like just telling the user what has been loaded and what hasn't.
The severity heavily depends on what it is about. Most important is to include the version number even in the very first files. And tbh, I wouldn't track a version for the format itself. Just use the version of supersplat.

[slimbuck]

I implemented a zip archiver which is able to stream files out without requiring all the contents to be in memory first.

I tested an output file with zip -T which reported no errors. So this seems like a valid approach for constructing a document archive.

The ongoing work is at https://github.com/playcanvas/supersplat/compare/main...slimbuck:supersplat:doc-dev?expand=1.