Skip to content
On this page

Import and export scene data

Import scene data

Importing scene data is done by the ISceneImporter class. The file information is then stored in an IScene, where both the geometries, materials and textures of the imported file can be found.

cpp
void LoadScene( const char* readFrom )
{
    spSceneImporter importer = sg->CreateSceneImporter();
    spScene scene;

    // Set the path of the file to load
    importer->SetImportFilePath( readFrom );
    
    //Run scene importer
    auto importResult = importer->Run(); 
    if(Simplygon::Failed(importResult))
    {
        throw std::exception("Failed to load scene.");
    }
    scene = importer.GetScene()
    // do stuff with scene
}
csharp
void LoadScene( string readFrom )
{
    spSceneImporter importer = sg.CreateSceneImporter();
    spScene scene;

    // Set the path of the file to load
    importer.SetImportFilePath( readFrom );

    //Run scene importer
    var importResult = importer.Run();
    if (Simplygon.Simplygon.Failed(importResult))
    {
        throw new System.Exception("Failed to load scene.");
    }

    scene = importer.GetScene();
    // do stuff with scene
}
python
def LoadScene( readFrom ):
    importer = sg.CreateSceneImporter()
    scene = None
	
	# Set the path of the file to load
    importer.SetImportFilePath( readFrom )
    
    # Run scene importer
    importRestult = importer.Run()
    if Simplygon.Failed(importResult):
        raise Exception('Failed to load scene.')
    
    sgScene = sgSceneImporter.GetScene()
    # do stuff with scene

Export scene data

Exporting scene data is done by the ISceneExporter class. The file format is determined by the file name extension.

If the file name does not contain a known supported file extension (see list above) it will output the internal Simplygon binary scene dump format (same as if you export a file with .sg extension), which can then be read by the scene importer. This is useful for integrating the batch tool into your data pipeline or when requesting support, as it contains an exact representation of the Simplygon scene data.

cpp
void SaveScene( const char* fileName, spScene scene )
{
    spSceneExporter exporter = sg->CreateSceneExporter();
    exporter->SetScene( scene );
    exporter->SetExportFilePath( fileName );
    
    // For file formats that only supports a limited set of texture coordinate layers,
    // set the name of the primary layer to export
    exporter->SetPrimaryTexCoordName( "tex0" );

    // Some file formats support embedding texture and other data in the main scene file.
    // This flag controls if such data will be embedded or written to separate files
    exporter->SetReferenceExportMode( EReferenceExportMode::Embed );

    // Some file formats  support exporting cascaded scenes in the same file.
    // This flag controls if cascaded scenes will be written or ignored
    exporter->SetExportCascadedScenes( true );

    // Run scene exporter
    auto exportResult = exporter->Run();
    if (Simplygon::Failed(exportResult))
	{
		throw std::exception("Failed to save scene.");
	}
}
csharp
void SaveScene( string fileName, spScene scene )
{
    spSceneExporter exporter = sg.CreateSceneExporter();
    exporter.SetScene( scene );
    exporter.SetExportFilePath( fileName );
    
    // For file formats that only supports a limited set of texture coordinate layers,
    // set the name of the primary layer to export
    exporter.SetPrimaryTexCoordName( "tex0" );

    // Some file formats that support embedding texture and other data in the main scene
    // file, this flag controls if such data will be embedded or written to separate files
    exporter.SetReferenceExportMode(Simplygon.EReferenceExportMode.Embed);

    // Some file formats  support exporting cascaded scenes in the same file.
    // This flag controls if cascaded scenes will be written or ignored
    exporter.SetExportCascadedScenes( true );

    // Run scene exporter
    var exportRestult = exporter.Run();
    if (Simplygon.Simplygon.Failed(exportResult))
    {
        throw new System.Exception("Failed to save scene.");
    }
}
python
def SaveScene( fileName, scene ):
{
    exporter = sg.CreateSceneExporter()
    exporter.SetScene( scene )
    exporter.SetExportFilePath( fileName )
    
    # For file formats that only supports a limited set of texture coordinate layers,
    # set the name of the primary layer to export
    exporter.SetPrimaryTexCoordName( "tex0" )

    # Some file formats that support embedding texture and other data in the main scene
    # file, this flag controls if such data will be embedded or written to separate files
    exporter.SetReferenceExportMode(Simplygon.EReferenceExportMode_Embed)

    # Some file formats  support exporting cascaded scenes in the same file.
    # This flag controls if cascaded scenes will be written or ignored
    exporter.SetExportCascadedScenes( True );

    # Run scene exporter
    exportResult = exporter.Run()
    if Simplygon.Failed(exportResult):
        raise Exception('Failed to save scene.')
}

Embedding References

glTF and FBX Exporters allow users to set ReferenceExportMode setting. The setting control what should happen with texture references on export. See ReferenceExportMode

Cascaded scenes

You can output all cascaded scenes when exporting by setting the export cascaded scene flag with a call to SetExportCascadedScenes function. Note that all file format does not fully support cascaded scenes.

Deduplicate Vertices

For GTLF files user can set DeduplicateVerticesOnImport setting. The setting contorl merging of any vertices that contain exact same information. Currently only applicable for GTLF format.

File format specific options

FBX

You can control the exported FBX file format version by setting a global string setting "FBXFileExportVersion". The values for the version strings are listed in the FBX SDK "File version compatibility strings", for example "FBX201600" for file version 7.5 which guarantees compatibility with Autodesk 2016/2017/2018 products.

cpp
sg->SetGlobalStringSetting( "FBXFileExportVersion", "FBX201600" );
csharp
sg.SetGlobalStringSetting( "FBXFileExportVersion", "FBX201600" );
python
sg.SetGlobalStringSetting( "FBXFileExportVersion", "FBX201600" );

You can flatten the cascaded by calling SetFlattenCascadedScene. The method flatten the cascaded scene in a depth first order and remove name clashes by postfixing _LOD[Index] to object names.

Moreover you can call SetImportFilePath which will hint the exporter to merge the result of the processing into this file.

Limitations

Currently there are a number of limitations to features supported in the various file formats

FBX

  • Animations are not supported. See Tips And Tricks for a workaround.
  • Selection sets are not supported
  • There is limited support for blend modes and custom materials/shaders
  • Due to limitations in the FBX SDK, all importer & exporter calls will be limited to one concurrent thread
  • The FBX format can only contain one scene per file. Cascaded scene output will be converted into top-level nodes in the FBX scenes, one per cascaded scene in a depth-first pattern.
  • Transforms on the root FBX node will be emulated with an inserted node at the top of the Simplygon scene hierarchy

glTF

  • Different sampler wrap modes in S/T directions are not supported, S direction is used for both directions
  • Cascaded scenes are output as separate glTF scenes in a depth-first pattern, with the top level scene set as the default glTF scene.

Extensions

  • KHR_texture_transform is supported
  • KHR_materials_clearcoat is supported
  • KHR_materials_transmission is supported
  • Any other required extensions will result in an error
  • All other optional extensions are ignored

OBJ

  • Cascaded scenes are not supported
  • Bone data and skinned meshes are not supported

USD

  • Only the UsdPreviewSurface material model is supported
  • Blend shapes not supported

Tips and Tricks

FBX

  • Recover your animations by relinking animations from the original FBX file to the generated LOD FBX. This can be achieved using a DCC application e.g Blender.

File format specific limitations

There are few file format specific limitations described here.