PolyTrans-for-Softimage Plug-in System

PolyTrans-for-Softimage Native Plug-In System

This help file describes the PolyTrans converters for use internally within Softimage.

PolyTrans-for-Softimage is a native plug-in for Softimage which allows all of the supported Okino import and export converters to be accessed directly from within the Softimage user interface. It is based around Okino's PolyTrans!ProServer technology.

If you wish to convert data between 3ds Max, Maya and Softimage then use the PolyTrans-for-3ds Max and PolyTrans-for-Maya plug-in systems to read/write Softimage files or Okino .bdf files via their native PolyTrans converters.

PolyTrans-for-Softimage works as follows:

1. You access the PolyTrans-for-Softimage user interface by selecting "PolyTrans Import…" from the File/Import menu of XSI, or "PolyTrans Export…" from the File/Export menu.

2. You are then presented with a list box of import and export converters to select from (see the user interface snapshot image below).

3. After clicking on the desired file format, and selecting the desired 3D file on disk, the stand-alone PolyTrans (or NuGraf) program will be executed in the background (hidden) to convert your selected file to/from the desired destination 3D file format (via a COM interface). A number of processing options can be enabled which modify the 3D geometry while it is being processed. The data transfer between Softimage and PolyTrans/NuGraf is handled transparently in the background by dotXSI files written to the Windows TEMP directory (hence, you will need empty space on that disk drive).

NOTE: If you start the stand-alone PolyTrans or NuGraf stand-alone program first, prior to using PolyTrans-for-Softimage, then you will see the 3D files being converted in the stand-alone program's user interface rather than it being hidden during the conversion process. This is useful if the conversion process does not proceed as you wish, in which case you can see the model in the stand-alone program prior to its transfer to/from Softimage.

Alternative dotXSI Conversion Pipeline:

As an alternative to using this plug-in, you can run the stand-alone PolyTrans or NuGraf software yourself and hand convert files between any Okino supported file format and the Softimage dotXSI format. Inside Softimage you can then import/export dotXSI files via the File/Import/dotXSI and File/Export/dotXSI menus. Both methods will produce the exact same results, although the PolyTrans-for-Softimage plug-in is more convenient to use.

If you need to import a lot of files into Softimage, then the suggested method is to use the "3D batch converter" within the stand-alone Okino PolyTrans or NuGraf software to convert the source files to the Softimage dotXSI file format. You can then "drag and drop" these dotXSI files onto the view windows of the Softimage user interface to easily load them.

Copyright (c) Okino Computer Graphics, Inc.

For updates please visit the Okino WEB site at http://www.okino.com or email to support@okino.com.


PolyTrans-for-Softimage Plug-In Installation

PolyTrans-for-Softimage Plug-in Installation Process

PolyTrans-for-Softimage consists of at least two major components:

1. You need to install the stand-alone PolyTrans or NuGraf software (which usually resides in the "c:\program files\polytrans" or "c:\program files\nugraf" directories).

2. You need to install the PolyTrans-for-Softimage plug-in modules underneath the Softimage installation.

3. You optionally need to install the special native plug-in modules to 3ds Max, Maya and/or Macromedia Director.

Fortunately all these installations can be accomplished by running two major installers.

Automatic Installation Instructions:

· Step One: Run the NuGraf or PolyTrans stand-alone installers. Follow the prompts. When done, enter your assigned serial numbers. Run this program at least once in order to register its COM server interface.

· Step Two: Run the Okino plug-in super installer. Select from which plug-ins you wish to install, most notably the native PolyTrans-for-Softimage plug-in. Tell the installer where your copy of Softimage is installed, if it could not determine this itself.

· Step Three: Reboot your machine in order to propagate the changes to the global PATH environment variable.

Manual Installation Instructions for the PolyTrans-for-Softimage Plug-In

1. Locate your Softimage installation directory.

2. Create two sub-directories called "addons" and then "addons/polytrans" under the main Softimage installation directory.

3. Copy the files "install.bat", "install.vbs" and "pt_xsi.dll" to the "addons/polytrans" sub-directory.

4. Start up Softimage and make the script editor visible by pressing this button located in the lower right corner of the Softimage user interface: . Select the "File/Open" on the script editor and navigate to the "addons/polytrans" sub-directory. Load up the install.vbs script file. Press the "Run" button located at the top of the Softimage script editor. Exit the dialog box when done. This will install new menu items into the Softimage user interface.

5. Or, navigate to the "addons/polytrans" sub-directory and type "xsi -script .\install.vbs -continue" on a DOS command line.

If the plug-in is working properly then you will find new menu entries in the File/Import and File/Export menus of Softimage, named "PolyTrans Import…" and "PolyTrans Export…". Pressing either one will cause the PolyTrans-for-Softimage user interface to appear within Softimage.

How to Manually Remove PolyTrans-for-Softimage

1. Locate your Softimage installation directory and then the "addons/polytrans" sub-directory.

2. Delete all files in that directory.

3. From within Softimage select the "View/Custom Toolbars/Customize" menu item.

4. Click on the "PolyTrans Export…" entry in the list and then press the "Remove Command" button.

5. Click on the "PolyTrans Import…" entry in the list and then press the "Remove Command" button.


How The PolyTrans-for-Softimage Plug-in Works

Okino's PolyTrans-for-Softimage works very differently, behind the scenes, than any other current Okino product. Internally it is highly dependent upon Microsoft's "COM" client/server technology (previously known as OLE).

Internally, within Softimage, the file process will appear to operate quite simply:

To import a file into Softimage via a PolyTrans import converter:

1. You select "PolyTrans Import" from the "File/Import" menu inside Softimage.

2. The "PolyTrans-for-Softimage" dialog box and list box appears.

3. You press the "Import" tab located above the list box.

4. You click on one of the import converters and select the desired file to load.

5. Several status dialog boxes appear while the file is being imported.

6. The "PolyTrans-for-Softimage" dialog box goes away and you are left with the imported file.

To export a file from Softimage to a PolyTrans export converter:

1. You load up Softimage with the desired scene to be exported.

2. You select "PolyTrans Export" from the "File/Export" menu inside Softimage.

3. The "PolyTrans-for-Softimage" dialog box and list box appears.

4. You press the "Export" tab located above the list box.

5. You click on one of the export converters and specify the desired filename to save.

6. Several status dialog boxes appear while the file is being exported.

7. The "PolyTrans-for-Softimage" dialog box goes away.

However, in the background, the process is actually more complex. Understanding this process will help you comprehend the overall conversion pipeline. The key point to consider is that the conversion processes are actually handled by the stand-alone Okino PolyTrans or NuGraf software, via its exposed PolyTrans!ProServer interface, under control of the plug-in within Softimage, and not within Softimage itself

During an export from Softimage, a dotXSI file is temporarily written to the Windows TEMP directory. This file is then read into the stand-alone PolyTrans or NuGraf software (run as a hidden COM server) and it is converted to the desired destination file format. This process is made transparent to you.

During an import to Softimage, the stand-alone PolyTrans or NuGraf software (run as a hidden COM server) imports the desired source 3D file and writes it out to a temporary dotXSI file in the Windows TEMP directory. This intermediate file is then read into Softimage where it is displayed. This process is made transparent to you.

Detailed Explanation of Importing Files into Softimage via PolyTrans-for-Softimage

Referring to the numbers shown in the image above, the actual process which occurs during an import operation is as follows:

1. You select the "PolyTrans Import" from the "File/Import" menu inside Softimage. The "pt_xsi.dll" plug-in is loaded into Softimage and then the PolyTrans-for-Softimage user interface is shown. At this point the stand-alone Okino PolyTrans or NuGraf software package is executed, in hidden PolyTrans!ProServer mode. The server will then inform PolyTrans-for-Softimage which import converters are available and they are placed onto the list box. NOTE: If you want to make the hidden PolyTrans!ProServer become visible, execute the stand-alone PolyTrans or NuGraf software from the START menu, as you would normally do -- this will make the user interface appear and still allow the program to run as a server to Softimage.

2. You click on one of the import converters. This sends the selected import filename and file format to the stand-alone PolyTrans or NuGraf software, via its PolyTrans!ProServer interface. Control is now in the hands of the PolyTrans!ProServer server and not Softimage.

3. The stand-alone PolyTrans or NuGraf software loads up the desired import file.

4. Then it performs optional scene resizing, optimization, reduction, etc.

5. The scene is exported from the stand-alone PolyTrans/NuGraf COM server to the dotXSI file format. The file is placed in the Windows TEMP directory with the same name as the desired file to convert. Control then passes back to the PolyTrans-for-Softimage plug-in.

6. At this stage the temporary dotXSI file (located in the Windows TEMP directory) is imported into Softimage via a script command at which point the data appears in the Softimage user interface windows. The temporary dotXSI file is deleted.

7. At this stage you can then save the data, as it appears within Softimage, to the native Softimage .scn file format.

Detailed Explanation of Exporting Files from Softimage via PolyTrans-for-Softimage

Referring to the numbers shown in the image above, the actual process which occurs during an export operation is as follows:

1. You populate the Softimage with 3D geometry and scene data.

2. You select the "PolyTrans Export" from the "File/Export" menu inside Softimage. The "pt_xsi.dll" plug-in is loaded into Softimage and then the PolyTrans-for-Softimage user interface is shown. At this point the stand-alone Okino PolyTrans or NuGraf software package is executed, in hidden mode as a COM server. The COM server will then inform PolyTrans-for-Softimage which export converters are available and they are placed onto the list box. NOTE: If you want to make the hidden COM server become visible, execute the stand-alone PolyTrans or NuGraf software from the START menu, as you would normally do -- this will make the user interface appear and still allow the program to run as a COM server to Softimage.

3. You click on one of the export converters. PolyTrans-for-Softimage will then ask Softimage (via a script command) to write out the current scene data to a temporary dotXSI file located in the Windows TEMP directory.

4. The COM server is sent the name of the newly written intermediate dotXSI file (located in the Windows TEMP directory), the desired export filename and file format. Control is now in the hands of the COM server and not Softimage.

5. The stand-alone PolyTrans or NuGraf software imports the temporary dotXSI file into its user interface. The intermediate dotXSI file is deleted.

6. Then it performs optional scene resizing, optimization, reduction, etc. on the imported data prior to re-export.

7. The scene is exported from the stand-alone PolyTrans/NuGraf COM server to the desired destination file format. Control then passes back to the PolyTrans-for-Softimage plug-in.


Geometry Processing Functions

Geometry Processing Options

While the 3D data is passing between the PolyTrans import/export converters and the host program’s database a number of powerful geometry and scene processing operations can be applied to all the data:

This dialog box basically allows automated access to the stand-alone PolyTrans geometry processing functions but without having to work within the stand-alone PolyTrans program itself.

Alternatively, you could import a file into the stand-alone PolyTrans, perform the processing operations by hand, then export out a file format best supported by the host program of this COM client plug-in module.

Resize Model to the Viewport Extents

If this checkbox is enabled (check-marked) then the camera is resized to encompass the entire model.

Add Lights to Scene if None

If this checkbox is enabled (check-marked) then 2 point light sources will be added to the final scene. The lights are added in the front-left and front-right quadrants.

Perform "Polygon Processing" On Model Before Exporting

If this checkbox is enabled (check-marked) then the converter will apply processing functions to the polygon data. Press the "Options" button to access the full list of processing options.

These polygon processing functions allow polygon vertices to be welded together, normals unified, auto-smoothing to be performed, redundant coordinates to be deleted and triangles merged back into n-sided polygons. For a technical description of each polygon processing function, press the Help button shown on that dialog box.

Compress Children Objects of Grouping Nodes to Single Object

This is a most useful batch conversion processing function, in particular when you are converting from a CAD-based file format (such as IGES, SolidWorks, Solid Edge, etc) and need to create the dotXSI file with the least number of objects and an optimum hierarchy. This function collects together all objects situated under a "yellow" or "red" folder in PolyTrans/NuGraf (grouping nodes) into a single object. This can greatly reduce the number of objects in a scene prior to re-export. This is particularly true for CAD data which is often broken down into smaller sub-components (called faces) rather than transferred as whole objects. For a technical description of this function, press the Help button shown on its option dialog box.

Hierarchy Optimizer # 1 and Hierarchy Optimizer # 2

These options provide methods to remove redundant hierarchy nodes from the current scene. In most cases you will not need to enable these options because (1) they are provided on some of the import converters already, or (2) they are provided in the "Compress Children Objects of Grouping Nodes to Single Object" option dialog box too, (3) most scenes don't need to have their nodal hierarchy optimized. Usually VRML and DirectX imports benefit from enabling these options.

Optimzier # 1 removes runs of empty folders, as well as folders with no children.

Optimizer # 2 is simpler, deleting empty folders which only have 1 geometry object in them. The second optimizer is useful if you batch import a file and find that there are a number of yellow folders (one per imported file) with one a single object in each folder.

Perform "Polygon Reduction" On Each Model

If this checkbox is enabled (check-marked) then the converter will apply the global polygon reduction algorithm to the imported polygons just prior to the start of the dotXSI file export process. The algorithm allows the number of polygons in the scene to be greatly reduced. For a technical description of this function, press the Help button shown on its option dialog box.

Apply Global Transformation to Exported Geometry

If this checkbox is enabled then a general purpose 4x4 transformation matrix will be applied to each exported scene, with specific limitations. This option will allow you to, for example, rotate all the exported scenes 90 degrees around one axis, or scale all the scenes uniformly by a specific amount. For a technical description of this function, press the Help button shown on its option dialog box.

Create Backup File When Writing the Intermediate Temporary File

This option allows the program to create a backup file if a file is about to be overwritten with a new version. For example, if the program is about to output a new file called "file.xsi" which already exists on disk then the program will first rename the current version to "file.bak" before writing the new version. If backup copies of the file already exist from previous executions of the translator program then the backup file extension will use sequential numbers (for example, "file.bk1", "file.bk2"). Thus, successive backups will use the file extensions: .bak, .bk2,. bk3, etc. If this option is not checkmarked then no backup files will be made.

Modify Polygon Triangulation Options

Pressing this button will display the global options will control polygon triangulation. In those cases when a N-sided polygon must be converted to triangles, up to 3 different triangulation routines can be enabled inside the core Okino software. For a technical description of this function, press the Help button shown on its option dialog box.

Modify Texture File Search Paths Directories

Pressing this button will display the file search paths dialog box. If you want to inform the core Okino software where your bitmap images are located (for automatic bitmap conversion), then press this button and add another file search path in the first tabbed dialog panel.


Troubleshooting the COM Communication Interface

Troubleshooting the PolyTrans-for-Softimage Plug-In

As shown in the "How the PolyTrans-for-Softimage Plug-In Works" section, PolyTrans-for-Softimage uses what is called a "COM" interface (previously known as OLE) to communicate between the dialog box you see inside Softimage and the PolyTrans converters located in the main PolyTrans home directory (or the NuGraf home directory if you own that variation of the product). This interface is implemented by the PolyTrans!ProServer add-in module to Okino's stand-alone PolyTrans and NuGraf programs.

PolyTrans-for-Softimage is implemented as a small proxy plug-in for Softimage. Once installed properly the entries "PolyTrans Import…" and "PolyTrans Export…" will appear in the "File/Import" and "File/Export" menus inside Softimage. If these do not appear then try these suggestions:

· Follow the automatic or manual installation instructions.

· Run the stand-alone PolyTrans or NuGraf software, which ever one you purchased, at least once. This will ensure that the PolyTrans!ProServer add-in module is initialized and registered with Windows. If you do not do this then the PolyTrans-for-Softimage plug-in will not know how to start up the stand-alone software.

· If the "PolyTrans-for-Softimage" dialog box appears to freeze while creating the list of import or export converters then make sure the files named ui_dcom.dll and ui_dcom.rti are located in the "vcplugin" directory of the main PolyTrans or NuGraf home directories. This is the PolyTrans!ProServer side of this COM interface.

· Make sure you have the stand-alone PolyTrans or NuGraf software installed on your computer. You will only have one of these installed. These are often installed to "c:\program files\polytrans" or "c:\program files\nugraf".

· Make sure you have acquired the newest PolyTrans or NuGraf software to be used with the special PolyTrans-for-Softimage plug-in. If you installed them at the same time from CD, or an update, then this should not cause problems. However, if you acquired the PolyTrans-for-Softimage plug-in at a much later date than the stand-alone PolyTrans or NuGraf software CD/update, then there might be chance there the two are incompatible. In such rare cases simply ask Okino for their latest patch-level upgrade.

· Make sure there are no rogue NuGraf or PolyTrans stand-alone tasks hidden in the background. The dialog box inside Softimage communicates using the PolyTrans!ProServer interface with the stand-alone PolyTrans or NuGraf program (depending on which on you purchased). You will need to abort one of these tasks. You can access Task Manager by pressing Ctrl-Alt-DEL or by right clicking on the task bar and selecting "Task Manager". Inside task manager look for a process called nugraf32.exe or pt32.exe ("NuGraf" or "PolyTrans"). Press the corresponding "End Task" or "End Process" button.


"Server Not Respondong" Dialog Box

"Server Not Responding" Dialog Box

As explained in the "How the COM Client Plug-In Works" section, this plug-in system uses Microsoft Windows's "COM" technology to communicate commands between a running copy of the plug-in host’s application and a running (hidden background) copy of Okino's PolyTrans or NuGraf stand-alone software and its PolyTrans!ProServer interface (which acts as the COM server).

If this dialog box appears, most times you will be able to press "Restart Server" and have any intermediate problems go away (or try "Retry Operation" first and then "Restart Server" second).

Microsoft's COM technology is not a bullet proof communication system and depends heavily on the "server" process being available when commanded. This may not always occur and hence this section of the online help describes how to solve cases where the Okino converter server is not immediately available when requested by the host application’s plug-in.

In terms of the image shown in the "How the COM Client Plug-In Works" section, the left portion is the COM client (the plug-in into the host application) and the right portion is the PolyTrans!ProServer converter server (the stand-alone Okino PolyTrans or NuGraf software). If the COM server (right side) fails for any reason or becomes slow, the COM client (left side) will appear to hang or will report COM errors. The operation can be restarted when and if the following dialog box appears within Director:

Retry Operation

There are some cases where the embedded plug-in within the host application asks the COM converter server to perform an operation but it is busy doing other tasks. If this occurs, press the "Retry Operation" button. It will try to contact the COM server once again for it to re-try the operation. If this does not work, press the "Restart Server" button.

Restart Server

You will probably find that this is the best button to press in many cases. If the COM converter server has become unstable, hung or unresponsive then press the "Restart Server" button. Internally it will terminate the COM server process (pt32.exe, nugraf32.exe, pt64.exe or nugraf64.exe). It will then restart the COM converter server from scratch and re-submit the last operation request. Should this fail as well, cancel the current conversion operation and try again. Alternatively if this does not work then perform the conversion to/from the host application’s primary file format inside the stand-alone PolyTrans or NuGraf software yourself without the help of this COM client plug-in.

Cancel Operation

If all else fails, or you simply want to cancel the current conversion operation, then press this button. It will immediately abort the conversion process. Note, however, that the COM converter server may still be in an unstable state for the next conversion, in which case you can press the "Restart Server" button to synchronize everything again.

Help

This displays the help you are currently reading.

Last Reported Error

This displays the last error reported by the COM converter server. The cause of the problem will be reflected by this error message.