Scripting: CopyExtFilesIntoProject

CopyExtFilesIntoProject

Introduced

v1.0

Description

Copies all external files used by the current scene into the current project or any given project. This command can be used to centralize all external files used by a scene, so the scene is self-contained in the project. In other words you can zip the project and extract it on another machine and all external files (like pictures, audio, etc.) will be there and valid.

Files are copied into their corresponding directories (for example, a picture is copied into the Pictures directory).

Scripting Syntax

CopyExtFilesIntoProject( SceneFileName, [Overwrite], [Models], [UpdateSourcePaths], [Files], [IgnoreFilesFromRefModel] );

Parameters

Parameter	Type	Description
SceneFileName	String	Full path name of the scene, or the the project path of the destination.
Overwrite	Boolean	True to overwrite the file if it exists Default Value: False
Models	String	If a list of models is specified, only files that relate to these models will be copied. Default Value: Selected objects
UpdateSourcePaths	Boolean	If true, all sources objects that have files that have been copied will be updated in the scene. This way the scene will use the new files copied to the current project, so they will be relative paths to the current project. If false, the files are copied locally but the scene still use the files where they were before they were copied. This is true when using a SaveAs command. Default Value: True
Files	String	With this argument you can specify which files are to be copied. When this argument is not empty the Models argument is ignored. The files can be either the resolved path or the GUID of the file path. Using a GUID will be more performant. Many files can be specified, they need to be separated by a semi-colon (;).
IgnoreFilesFromRefModel	Boolean	The files that are used by objects in a referenced model cannot be changed because the data is really in the original model, not in the scene. Each time you load a scene, any models referenced in that scene are imported from the original location. So because of that you may want to ignore copying these files for efficiency. Note: If this parameter is false, the files that are used by the referenced models will be copied but the object owner of the path will not be changed because the objects are locked. Default Value: True

Examples

1. JScript Example

/*
        This example shows how to use CopyExtFilesIntoProject command to copy the 
        external files used by a scene to a new destination.
*/
NewScene( "", false );
Application.LogMessage ( "Current project: " + Application.ActiveProject );
var sPathNewProject = XSIUtils.BuildPath(
        Application.InstallationPath( siFactoryPath ), 
        "Data", "NewProject"
);
Application.CreateProject( sPathNewProject );
var sPathScn = XSIUtils.BuildPath(
        Application.InstallationPath( siProjectPath ),
        "Scenes", "Texturing", "Head.scn"
);
// Load a scene with textures
OpenScene( sPathScn, false );
var oScene = Application.ActiveProject.ActiveScene;
// Now copy all files in the new project, by setting the last argument to false 
// the source path is not updated but the file is copied.
var oImageSource = oScene.ImageClips(0).Source;
Application.LogMessage( "Before: " + oImageSource.Parameters("FileName").Value );
CopyExtFilesIntoProject( sPathNewProject, true, null, false );
Application.LogMessage( "After: " + oScene.ImageClips(0).Source.Parameters("FileName").Value );
// Now do the same but set the last argument to true, so we change the source
Application.LogMessage( "Before: " + oScene.ImageClips(0).Source.Parameters("FileName").Value );
CopyExtFilesIntoProject( sPathNewProject, true, null, true )
Application.LogMessage( "After: " + oScene.ImageClips(0).Source.Parameters("FileName").Value );
Application.LogMessage ( "Current project: " + Application.ActiveProject);
// Expected results (note that your_current_project_path will not change): 
// INFO : Current project: $XSI_HOME\Data\XSI_SAMPLES
// INFO : Before: $XSI_HOME/Application/rsrc/noIcon.pic
// INFO : After: $XSI_HOME/Application/rsrc/noIcon.pic
// INFO : Before: $XSI_HOME/Application/rsrc/noIcon.pic
// INFO : After: $XSI_HOME/Application/rsrc/noIcon.pic
// INFO : Current project: $XSI_HOME\Data\XSI_SAMPLES

2. Python Example

#
#     This example shows how to use CopyExtFilesIntoProject command to copy some 
#     specific files. This example is theorical because we copy some files that
#     are already under the pro7ject.
#
from win32com.client import constants as c
app = Application
sFactory = app.InstallationPath( c.siFactoryPath )
sProject = app.InstallationPath( c.siProjectPath )
sScene2Open = XSIUtils.BuildPath( sProject, "Scenes", "Texturing", "Head.scn" )
app.OpenScene( sScene2Open, 0, 0 )
# Note that the files are separated by a semi-colon
sFile1 = XSIUtils.BuildPath( sProject, "Pictures", "Checks.pic" )
sFile2 = XSIUtils.BuildPath( sFactory, "Application", "rsrc", "noIcon.pic" )
sFiles = sFile1 + ";" + sFile2
app.CopyExtFilesIntoProject( sProject, 1, "", 0, sFiles, 1 )