PolyTrans-for-Director

PolyTrans-for-Adobe Director, 3D File Import Converters

This help file describes the PolyTrans import converters for Adobe Director.

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

The Xtra plug-ins works as follows: You are presented with a list box of import converters to select from. After clicking on the desired input 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 into the Director .w3d 3D file format. The final .w3d file will then be read into Director and displayed in the work area automatically. A number of processing options can be enabled which modify the 3D geometry before it is saved to the .w3d file.

NOTE: If you start the stand-alone PolyTrans or NuGraf stand-alone program first, prior to using PolyTrans-for-Director, 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 imported model in the stand-alone program prior to its export to .w3d file format.

As an alternative to using this Xtra plug-in, you can run the stand-alone PolyTrans or NuGraf software yourself and hand convert files from any input file format to the Shockwave .w3d file format. You can then manually insert the .w3d files into Director via its "Insert/Media Element/Shockwave 3D" menu item, or better yet, use the "File/Import menu" using the "Link to External File" sub-option so that the .w3d file is only virtually referenced as a cast member and not physically loaded.

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.


How The PolyTrans-for-Director Xtra Plug-in Works

Okino's PolyTrans-for-Director 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 Director, the file import process will appear to operate quite simply:

1. You select the "PolyTrans 3D Importers" plug-in from the "Xtras" menu inside Director.

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

3. You click on one of the import converters.

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

5. The "PolyTrans-for-Director" dialog box goes away and you are left with a new 3D member added to the current Director cast.

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 import conversion process is actually handled by the stand-alone Okino PolyTrans or NuGraf software, via its exposed PolyTrans!ProServer interface, under control of the Xtra plug-in within Director. The stand-alone software (run as a hidden COM server) converts your selected import file format to the Director .w3d file format, and then the .w3d file is linked or loaded into Director automatically.

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 3D Importers" plug-in from the "Xtras" menu inside Director. The "pt_dir.x32" Xtra plug-in is loaded into Director and then the PolyTrans-for-Director dialog box is shown. At this point the stand-alone Okino PolyTrans or NuGraf software package is executed in hidden PolyTrans!ProServer mode. The server will inform the PolyTrans-for-Director dialog box which import converters are available and these are listed on the list box. 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 Director.

2. You click on one of the import converters. This sends the selected import file 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 and not the Director Xtra.

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

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

5. And then the scene is exported to the Director .w3d file format. Control then passes back to the Director Xtra plug-in.

6. At this stage the exported .w3d file is imported into Director (or virtually linked) into a new Director cast member, using Lingo commands.

7. Finally, inside Director you can add behaviors and other Lingo commands to the scene. Once you are satisfied with the results you will normally publish a Shockwave-3D file.

8. At this stage you will take your published Shockwave-3D file and place it on a WEB site for distribution and viewing.


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.


W3D Import Conversion Options

W3D File Embedding Options (for Director Only)

These options control the import of the converted .w3d file as it is being imported into Adobe Director.

Cast Member Linking Method

Adobe Director is based on the concept of a movie containing one or more casts (like a group of human actors), and each cast having 1 to 32000 cast members. The cast members are 3D objects, text, bitmaps, etc. For the PolyTrans-for-Director importer, .w3d 3D assets are imported into "Shockwave-3D" compatible cast members.

The options shown on this portion of the dialog control how the .w3d file will be loaded into a new cast member:

Load and Embed .w3d File Into Cast Member

The converted .w3d file will be loaded and embedded directly into the cast member. Thus, no disk files will ever be associated with the new Shockwave-3D asset in the movie.

Virtually Link .w3d File on Disk to the Cast Member (Do Not Embed)

The converted .w3d file will be converted and saved to disk at the directory location shown on the dialog box ("Put .w3d files in this directory"). The new Shockwave-3D asset in the movie will link virtually to the .w3d file on disk. Thus, no .w3d file will be embedded into the movie. This is the default option. The default directory where the .w3d files will be stored is called "polytrans_created_w3d_files" and it is located in the Windows temporary working directory.


Troubleshooting the COM Communication Interface

Troubleshooting the PolyTrans-for-Director Plug-In

As shown in the "How the PolyTrans-for-Director Plug-In Works" section, PolyTrans-for-Director uses what is called a "COM" interface (previously known as OLE) to communicate between the dialog box you see inside Director and the PolyTrans import 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-Director is implemented as a small Xtra plug-in for Director. Once installed properly, the word "PolyTrans" will appear under the "Xtras" menu inside Director. If it does not appear then try these suggestions:

· 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-Director Xtra plug-in will not know how to start up the stand-alone software.

· Make sure that the files named pt_dir.x32 and pt_dir.hlp exist within the Adobe Director installation, in the "xtras\polytrans" folder. If not, run the PolyTrans-for-Director installer, if you have one.

· If the "PolyTrans for Director" dialog box appears to freeze while creating the list of import converters, 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-Director Xtra 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-Director Xtra 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 Director 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 pt32.exe, nugraf32.exe, pt64.exe or nugraf64.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.