1. Project Structure in Volinga Suite
Projects are the core organizational units in Volinga Suite (VS), providing a structured environment for managing all elements of a 3D Gaussian Splatting workflow. Each project is self-contained, ensuring efficient asset management and smooth collaboration within the production pipeline.
A Volinga Suite project consists of three essential components:
- Scenes (.vscene files): Define spatial arrangements of 3DGS assets, including transformations such as translation, rotation, and scale. Scenes also manage hierarchical relationships between elements.
- Assets (.nvol files): Represent individual 3D Gaussian Splatting elements. These can be placed, manipulated, and rendered within scenes.
- Datasets (folders): Store source data required for generating assets. Each dataset folder is named after the corresponding asset, ensuring clear traceability between raw data and processed elements.
📁 project
📄 project.volproj
📁 Scenes
- 📄 scene1.vscene
- 📄 scene2.vscene
- …
📁 Assets
📁 asset1
📄 asset1.nvol
📁 asset2
📄 asset2.nvol
📁 Datasets
- 📁 asset1
- 📁 asset2
Volinga Suite employs a hierarchical project structure, with a primary project file (.volproj) at the root level. This organization streamlines workflows by defining clear relationships between datasets, assets, and rendered scenes. Both .volproj and .vscene files are JSON-based, facilitating seamless integration into custom pipelines.
2. Getting Started with Volinga Suite
2.1. Welcome Window
When launching Volinga Suite, the Welcome Window provides quick access to your workflow. It includes a list of recently opened scenes and three primary options:
- New Project: Creates a fresh project with the appropriate folder structure.
- New Scene: Adds an empty scene to an existing project.
- New Asset: Initiates the creation of a new 3D Gaussian Splatting asset from source data.
2.2. Creating a New Project
To start a new project, specify a destination folder and project name. Once confirmed, the system automatically initializes a default empty scene called "main.vscene," providing a blank canvas for your work.
2.3. Creating a New Scene
The Blank Scene workflow allows you to create a new scene within an existing project. If no project is selected, a new one can be created. After naming the scene, Volinga Suite saves it as a .vscene file within your project structure.
2.4. Creating a New Asset
Assets serve as the fundamental building blocks of Volinga Suite. Creating a new asset involves generating an NVOL file, either by training a 3DGS model from media or converting existing 3DGS PLY files into NVOL format. The following section provides a detailed explanation of the asset creation process.
3. Asset Creation on Volinga Suite
When generating a new asset, you must first select the project where it will be stored. If a new project is required, the system will guide you through the project creation workflow. The Media Importer Wizard will then open, supporting the following data formats:
- Images (.png, .jpg, .jpeg) and Videos (.mp4, .mov): A minimum of 20 images or a video is required.
- OpenEXR files (.exr): Processed according to ACES 2065-1 specifications. For detailed instructions on working with EXR files, see.
6. Working with EXR Files for ACES Workflows
- 3DGS PLY files (.ply): These can be converted to NVOL format for direct use within Volinga Suite.
- COLMAP Model Import: Using the "Import COLMAP registration" button, an existing COLMAP model can be integrated.
3.1. Training Parameters
For assets requiring training, the following parameters can be configured:
- Camera Mode: Determines how camera intrinsics are calculated.
- Auto: Solves different intrinsics for each image.
- Single: Assumes a single camera source, leading to faster alignment.
- Iterations: Defines processing duration. Higher values generally improve quality, though improvements often plateau beyond 100,000 iterations.
- Checkpoint Iterations: Specifies checkpoint save frequency (e.g., a value of 7,000 saves a new model every 7,000 iterations).
- Overwrite Checkpoints: Saves storage by replacing previous checkpoints.
- Input Data Resolution Scaling: Options include Full, 75%, 50%, or 25%, balancing quality and performance.
- Use SSIM: Enhances detail but requires substantial GPU memory.
Adjusting the input resolution and enabling SSIM allows you to balance GPU memory usage and output quality. If your system meets the ideal requirements—specifically, with at least 24GB of VRAM—you can safely train on images up to 4K resolution using full resolution and SSIM without encountering performance issues.
Once parameters are set, you can begin training immediately or queue the job. "Begin training" will pause the job executing at the moment (if any), while "sending to queue" will add the job to the end of the queue. If there is no job in the queue, the asset will start processing. More details about how queues work on Volinga Suite are provided in the following section.
3.2 Job Queue Manager
The Job Queue Manager (JQM) allows monitoring and controlling asset processing tasks. It provides real-time progress updates, job prioritization, and log details, ensuring efficient processing management.
On the top part of the JQM, the list of jobs in the queue can be found. The jobs are executed by priority order, and only one job can be executed at the same time. Jobs can have the following status:
- Queued: Job is queued and waiting to be executed.
- Running: Job is being executed right now.
- Paused: Job started to execute but was paused by the user.
- Completed: Job has finished processing.
- Failed: An error occurred during job execution.
You can reprioritize jobs in the queue by selecting a job and clicking the "Change Priority" button. Assigning priority 1 to a job will immediately move it to the front of the queue and start its execution, pausing any job that is currently running.
Resuming a paused job will also start it immediately and move it to the top of the queue, interrupting any active job in progress.
Removing a job from the queue will delete it, while stopping a running job will cancel its execution and remove it from the list entirely.
Finally, the "Queue Job" button allows you to add a new job to the queue by launching the new asset creation workflow.
4. Editing Scenes in Main Window
The Main Window is where scenes are created and edited. The interface consists of:
- Viewport: Displays and manipulates 3DGS elements.
- Scene Outliner: Lists all elements and their hierarchical relationships.
- Properties Panel: Provides real-time editing options for selected elements.
When selecting an actor, a transform gizmo will appear, allowing you to manipulate its position, rotation, or scale. You can switch between different gizmo modes using the spacebar or the toolbar buttons located to the left of the viewport. Additionally, precise numerical adjustments to the actor's transform can be made via the Properties panel.
Actors can be nested hierarchically by dragging and dropping them within the Scene Outliner. You can also copy and paste actors into other parent actors. Operations such as copying, cutting, duplicating, or deleting a parent actor will automatically affect all of its child actors.
New actors can be added to a scene by dragging and dropping NVOL files directly into the viewport or by selecting the File > Import NVOL option. If an NVOL file from within the current project is imported, it will simply be added to the scene. However, importing an NVOL from outside the project will also copy it into the project's assets folder.
From the File > New menu, you can initiate workflows for creating new scenes or new assets. Additionally, complete scenes can be exported as NVOL collections by selecting File > Export as NVOLs Collection, which saves each actor’s transformations into a set of NVOL files. This feature is particularly useful when importing scenes created in Volinga Suite directly into the Volinga Plugin for Unreal Engine.
When your scene is finalized and you need to export multiple 3DGS elements while preserving the 3D structure of your scene, the "Export as NVOLs collection" feature (File > Export as NVOLs collection) is the ideal solution. These NVOL collections can subsequently be imported into Unreal Engine using the Volinga Plugin, maintaining the integrity of your original scene design.
5. Importing COLMAP Registration
When importing an existing COLMAP model into Volinga Suite, you'll need to provide the following files:
- Images File (*.bin or *.txt): The images.bin or images.txt file generated during COLMAP camera alignment that contains camera pose information.
- Cameras File (*.bin or *.txt): The cameras.bin or cameras.txt file from COLMAP camera alignment that defines intrinsic camera parameters.
- Points3D File (*.bin or *.txt): The points3d.bin or points3d.txt file containing the sparse point cloud generated during COLMAP camera alignment.
- Images Folder: The directory path containing all original images used to create the COLMAP model.
These files together provide the complete camera registration and sparse reconstruction data needed to properly initialize your 3D scene in Volinga Suite. By importing COLMAP models, you can also leverage camera alignments coming from other tools supporting COLMAP exports like Reality Capture or Metashape
7. Known Bugs and Limitations
Volinga Suite is currently in beta. We are actively working to introduce new features and resolve bugs promptly. The following limitations and known issues exist in the current release:
- Automatic updates are not yet supported. To update to a new version, users must manually uninstall the previous version before installing the latest release.
- Undo and redo actions are not currently implemented within Volinga Suite.
- Asset editing functionality is not yet available. We recommend using external tools, such as Supersplat, for asset modifications until this feature is supported directly within Volinga Suite.
- FQDN-formatted paths (fully qualified domain names) are not supported for asset generation. This limitation affects workflows involving shared network drives (e.g., Samba). We recommend using either local file paths or UNC-formatted network paths.
- When dragging an external NVOL file into the Main Window’s viewport, if an asset with the same name already exists within the project, the existing asset will be loaded instead of importing the new one.
- Occasionally, when initiating the "New Asset" workflow from the Main Window, the Asset Name prompt may appear behind the Main Window, requiring the user to manually bring it forward.
- In certain cases, if a training job is canceled during COLMAP's mapper phase, the associated RAM may not be properly released.
- Due to a known issue with the QT framework, uninstalling Volinga Suite may present some difficulties. To properly uninstall Volinga Suite, you can use the standard uninstallation method through the Programs and Features section in the Windows Control Panel, or alternatively, through the Apps & Features menu in Windows Settings by uninstalling the auxiliary application provided. This auxiliary application addresses the QT framework issue, and removing it will also fully uninstall Volinga Suite.
