Try It! Packaging a Sample World

on this page: defaults | directory structure | mappings | directory index | trusted references

After you've read some of the background material on CosmoPackage, try experimenting with this sample set of files to see how you can set various options and what happens during packaging. For complete information, be sure to read all the Help cards listed at the end of this section.

The sample files are located in this directory:

/usr/share/Insight/library/SGI_bookshelves/Help/books/CosmoCreate_UG/Tutorial/samplePackage

This directory contains the following files and subdirectories:

Note to Cosmo Create users: The .wrl suffix is for files created in Cosmo Worlds. The .jpg suffix indicates an image file in JPEG format. If you do not have Cosmo Worlds installed, .wrl files will be treated as "black boxes"; they will be copied as is and will not be processed (their references will not be discovered and they will not be converted to standard VRML).

Using the Default Values

First, try running CosmoPackage using the default settings. Use the file sample.htm as the root file of your package. This file contains links to office.wrl, map.wrl, and the otherClients/ directory. The map.wrl file uses the GoggleEyes.jpg texture from the textures/ directory.

By default, when a file refers to a directory, CosmoPackage packages the index.html file within that directory, if there is one. See Referring to a Directory Index. In the example, the file index.html contains links to the other three .wrl files in the otherClients/ directory.

Follow these steps to package sample.htm:

  1. Open sample.htm and choose File > Package.

  2. Choose a package directory. For example, type myPkgDir in the text box and click OK.

    The file sample.htm is added as the root of this package.

  3. Click the Discover button. CosmoPackage looks for all files linked to the root file and adds them to the package.

  4. Click the Package button. CosmoPackage creates the package containing the necessary files.

  5. Click Preview to test out the links in your package.

  6. Click Save. The package is saved in the directory /myPkgDir/stage in your working directory.

Now examine the contents of the stage/ directory. You'll see that it looks like this:

Important things to notice at this point are:

Maintaining Your Directory Structure

If you have a lot of files that are carefully arranged into logical subdirectories, you may not want your package to have a completely flat file structure. Follow these steps to preserve a hierarchical file structure:

  1. Click Restart.

  2. Click the Mappings tab. Then click the Hierarchical check box.

  3. Click Discover.

  4. Click Package.

  5. Click Save.

Now check the contents of /workingDirectory/myPkgDir/stage. You'll find the usr/ subdirectory, and if you dig deep enough, you'll finally find the contents of your package in the following directory:

/workingDirectory/myPkgDir/stage/usr/share/Insight/library/SGI_bookshelves/Help/books/
          CosmoCreate_UG/Tutorial/samplePackage

Clearly, you need a way to shorten this path! The answer is to add a custom mapping, as described in the following section.

Directory Mappings

Follow these steps to map files from your original working directories to the package directory.

  1. Click Restart.

  2. Click the Mappings tab. Be sure the Hierarchical box is still checked.

  3. Click the Add button. In the Map From field, specify (all on one line):

    file:/usr/share/Insight/library/SGI_bookshelves/Help/books/
              CosmoCreate_UG/Tutorial/samplePackage/

    Be sure to include the file:/ specification at the beginning.


    In the Map To field, specify

    .

    (to indicate the stage/ directory)


  4. Click Discover.

  5. Click Package.

  6. Click Save.

Now, you have a short, readable path to your files, and your original directory structure is maintained (with the otherClients/ and textures/ directories as part of your package):

Referring to a Directory Index (index.html)

This example illustrates another technique you may find useful. The sample.htm file contains a link to the otherClients/ directory. By default, the index.html file is packaged when an HTML link specifies a directory. In the example provided, the index.html file, in turn, contains references to all the files in that subdirectory, which causes them to be pulled recursively into the package.

You can also specify another filename for the packager to use when it receives a directory reference. If you want CosmoPackage to use a filename other than index.html when it encounters a directory reference, add that name to the Directory panel in CosmoPackage.

Trusted References

In some cases, you know that certain files will already be placed on the server, and you don't want them included in your package. This is where trusted references are useful.

To test their use, assume that all textures are currently placed on the server in a specified location. To omit the textures from your package, follow these steps:

  1. Click Restart.

  2. Click the Trusted References tab.

  3. Click Add.

  4. Type the path of the trusted reference (all on one line):


    file:/usr/share/Insight/library/SGI_bookshelves/Help/books/
              CosmoCreate_UG/Tutorial/samplePackage/textures/


    Be sure to include the file:/ specification at the beginning of the trusted reference.

  5. Click Discover.

  6. Click Package.

  7. Click Save.

Now, if you examine the contents of the package directory, you'll notice that the textures are missing, since you've assumed that they are already on the server. CosmoPackage did not follow any links to the textures/ directory.

Tip: If your files contain relative references, such as ../textures, you also need to specify ../textures as a trusted reference.

Jump to: