vcPackFolder

vcPackFolder allows you to pack files with a VCMX file and extract them. Files are contained in a folder that is mapped to a layout or component. Generally, you would map a temporary folder that you want to save with a VCMX file, and then extract the folder and its contents when you open the VCMX file. This allows you to share a layout or component that contains other files, for example a CSV file of robot position data.

Contents HideContents Show
  1. How It Works
    1. Step 1. Get the packing mechanism
    2. Step 2. Map a folder
    3. Step 3. Extract files
  2. Properties
  3. Methods

How It Works

You can pack any type of file but the file must be stored in a folder. The folder along with its files are packaged and saved with a VCMX file. When you open the VCMX file, the packed folder and files can be extracted to an existing or temporary folder. Extracted files are deleted when you clear the layout or delete the component from the 3D world.

Step 1. Get the packing mechanism

The packing mechanism is a vcPackFolder object.

Case 1. Components

To pack files with a component, get the PackFolder property of a vcComponent object.

from vcScript import *
 
comp = getComponent()
pf = comp.PackFolder

Case 2. Layouts

To pack files with a layout, use the vcApplication object to find or create a vcLayoutPackFolder object, and then get its PackFolder property.

from vcScript import *
 
app = getApplication()
 
pf_layout = None
for item in app.LayoutItems:
  if item.Type == VC_LAYOUTITEM_IT_LAYOUTPACKFOLDER:
    pf_layout = item
    break
 
if not pf_layout:
  pf_layout = app.createLayoutItem(VC_LAYOUTITEM_IT_LAYOUTPACKFOLDER)
pf = pf_layout.PackFolder

Step 2. Map a folder

The packing mechanism allows you to pack files in a mapped folder, including its subfolders. Generally, you would map a folder that is temporary or not directly accessed by a user. After you map a folder, save the layout or component.

Case 1. Map a temporary folder

In this case, a temporary folder is selected by the application. This is a safe option if you want to avoid mapping a folder that you want to keep on your computer. The application will also handle any conflicts with other instances of the component or layout.

from vcScript import *
 
comp = getComponent()
pf = comp.PackFolder
 
pf.mapFolder()
 
print pf.PackFolderLocalPath

Notes:

  • The temporary folder is created in AppData\Local\Temp.
  • The name of the folder in Temp is a unique id for your session.
  • The subfolder is the name of the component or layout.
  • Example file path of temporary folder C:\Users\%username%\AppData\Local\Temp\Instance_5952\NewComponent

Case 2. Map an existing folder

In this case, you are mapping an existing folder. You have two options: pack folder at the time of call, or wait until you to save the VCMX file.

from vcScript import *
 
comp = getComponent()
pf = comp.PackFolder
 
uri = r"C:\Users\Public\Pictures\Screenshots"
 
#packs at time of call
#pf.mapFolder(uri)
 
#packs when you save component
#pf.remapFolder(uri)
 
print pf.PackFolderLocalPath

Case 3. Map a different folder

In this case, you want to map a different folder. You should use caution to avoid deleting a mapped folder and its files.

One option is to remap a different folder and not affect the other folder.

from vcScript import *
 
comp = getComponent()
pf = comp.PackFolder
 
#mapped to wrong folder
uri = r"C:\Users\Public\Pictures\Screenshots"
pf.mapFolder(uri)
 
uri = r"C:\Users\Public\Pictures\Test"
 
#does not delete Screenshots folder nor override packed files at time of call
#mapped folder is changed to Test
#files from Test will not be packed until you save the component
pf.remapFolder(uri)
 
print pf.PackFolderLocalPath

Another option is to move files to a temporary folder and delete the other folder.

from vcScript import *
 
comp = getComponent()
pf = comp.PackFolder
 
#mapped to wrong folder
uri = r"C:\Users\Public\Pictures\Screenshots"
pf.mapFolder(uri)
 
#deletes Screenshots folder and moves files to temporary folder
pf.rollbackFolder()
pf.mapFolder()
 
print pf.PackFolderLocalPath

Another option is to delete a temporary folder and its files and remap a different folder.

from vcScript import *
 
comp = getComponent()
pf = comp.PackFolder
 
#mapped to wrong folder
uri = r"C:\Users\Public\Pictures\Screenshots"
pf.mapFolder(uri)
 
#delete folder and move files to temporary folder
pf.rollbackFolder()
pf.mapFolder()
 
uri = r"C:\Users\Public\Pictures\Test"
 
#deletes the temporary folder and its files
#mapped folder is changed to Test
pf.remapFolder(uri)
 
print pf.PackFolderLocalPath

Step 3. Extract files

After you have mapped a folder, you should modify your code to define how you want the files to be extracted when you open the VCMX file.

Case 1. Do not extract any files

In this case, the packed files are available but not extracted from the opened VCMX file. You would need to call the mapFolder() method to extract the files. In this case, it is good to know the state of the vcPackFolder object.

from vcScript import *
 
comp = getComponent()
pf = comp.PackFolder
 
#2 means folder is mapped
if pf.State == 2:
    print "A folder is mapped to component. Unpack the folder to extract its files."
 
#pf.mapFolder()

Case 2. Automatically extract files

In this case, the packed files are extracted when you open the VCMX file. Generally, you would extract the files to a temporary folder.

from vcScript import *
 
comp = getComponent()
pf = comp.PackFolder
 
#2 means folder is mapped
if pf.State == 2:
    print "A folder is mapped to component. Unpack the folder to extract its files."
 
#pf.mapFolder()

Properties

Name Type Access Description
PackFolderLocalPath String R Gets the file path of mapped folder.
State Enumeration R Gets the state of mapped folder.

0
Undefined, no folder is mapped.

1
Defined, but folder is not mapped.

2
Folder is mapped.

Methods

Name Return Type Parameters Description
mapFolder None [String uri] Maps a temporary folder generated by the application or an existing folder at the given uri which must be a file path.

Files will be packed/extracted at the time of call.
remapFolder None String uri Remaps a different folder.

This will not override the other folder until you save the VCMX file. Files in the other folder will also not be deleted unless they were contained in a temporary folder generated by the application.
rollbackFolder None None Removes mapping to folder.

Generally, this is used before you map a different folder.