sbvtrans(1)

NAME

sbvtrans − translate a Starbase HPSBV archive to Personal Visualizer data formats.

SYNOPSIS

sbvtrans archive.sbv [ options ]

DESCRIPTION

The command sbvtrans translates Starbase graphics output into Personal Visualizer or Advanced Visualizer data files suitable for those products.

Archive files are the result of capturing Starbase output with the special Starbase-to-Visualizer (HPSBV) device driver included with the Starbase graphics library. When creating archives with the driver, it is recommended to use a .sbv extension (although it is not required).

Command options control the processing of information from the original archive. Since Starbase provides a unique graphics environment from the Personal Visualizer, not all information can be exchanged equally between the two. The command descriptions below explain current differences between the products and detail options for obtaining the closest possible translation of data.
One important difference between the environments is their choice of coordinate systems. Starbase employs a left-handed coordinate system, the Personal Visualizer a right-handed one. Data transformed by this translator may require a 180 degree rotation about the Y axis to appear oriented correctly in the new application.

The output of sbvtrans consists of at least two files. The first file is an importation script. This script works with the command language interpreter of the Personal Visualizer to simplify object file importation. An example below covers the basic usage of this script. Refer also to the Personal Visualizer’s "User’s Guide" for more information.

The second file is a Visualizer object data file (of possibly several object data files), signfied by an .obj extension. This plain text file contains the translatable Starbase geometry information, such as vertex points and polygon definitions. These files are imported either through use of the generated importation script or directly through the Advanced Visualizer data filter in the Manager (Object) section of the Personal Visualizer.

The following options are recognized by sbvtrans:

−n Include Starbase normals from archive data in the final object files, i.e., any vertex or facet normals. If both exist for a facet, vertex normals will be given priority. (The Personal Visualizer supports only vertex normals in its rendering model.)

This mode can not be used with −s option.

Default = Ignore any Starbase normals.

−s Attempt to create smooth objects by forcing vertex sharing of adjacent polygons. Faces which share the same logical point will have their facet normals averaged at that point, causing smooth shading across facet boundaries.

This mode can not be used with −n option.

Default = Use only archive definitions.

−e epsilon
Non-negative tolerence to consider adjacent points in the neighborhood of each other. This compensates for numerical precision errors generated by any Starbase processing. A value of zero means points much be exactly the same to be considered adjacent.

This option used only with the −s option.

Default = 0.0000

−c [ all ]
Center each output object at the origin (0, 0, 0). Objects which are not centered will exhibit scaling problems when imported into the Personal Visualizer. Centering repositions objects after local modeling transformations have been applied from the archive.

If all is specified, then all output objects in the archive are considered part of the same group and the entire group is repositioned around the origin.

Default = No centering applied.

−q Quiet processing. Translator does not print out status messages of archive translation.

Default = Verbose messages enabled.

−b Always create double-sided polygons in output objects. The number of sides a polygon displays is determined by the current state of cull (from the Starbase function hidden_surface) at the time it is placed in the archive. If cull is TRUE, then all polygons are single-sided. The Starbase default is FALSE, which means all polygons will have two faces.

This command option overrides any information in the archive.

Default = Use archive-based settings.

−d pathname
Specify a different pathname for object and script output.

Default = Current working directory.

−L Allow long file names to be generated for output files. If not allowed, sbvtrans attempts to generate unique file names for short file name systems.

Default = Short file names generated.

−f filename
Rename the target IMPORT script name. If not specified, sbvtrans generates a script based upon the archive name.

Default = archive_name.imp.

EXAMPLES

A simple archive containing information for one object can be translated by:

sbvtrans simple.sbv

The output files will be simple.imp (the IMPORT script) and simple.obj (the object data file). The object will appear faceted when imported into the Personal Visualizer.

More sophisticated archive translations may require translator options for better data organization. For example, an archive containing multiple object file definitions can be processed by:

sbvtrans parts.sbv -d /tmp/data -n -f brake

The resulting output files are all output into the directory /tmp/data. All objects include any original Starbase normals for shading calculations, and the final IMPORT script is created as /tmp/data/brake.

To execute the IMPORT script in the Personal Visualizer, enter command mode through the more button of the main menu. Once there, if the current mode is not in the the view manager, enter view to place it into the correct mode (the word view will show up next to the command line).

Set the command pathname to the directory where the IMPORT script resides using the option:

set path "/tmp/data" (Quotes necessary)

To execute the script, enter:

run script_name

COMMENTS

The Personal Visualizer does not check for object file replacement through the command mode. Files which exist in the current work area will be replaced without warning by those specified in the IMPORT script.

sbvtrans attempts to create unique object file names for every object created within a specific archive. File names, however, may not be unique from those which already exist in specific scenes and/or work areas.

To combine multiple objects in one archive file, refer to the gescape function, SBVESC_OBJ_NAME.

To translate an HPSBV archive file, the resulting output files may be equal to (or exceed, in some cases) the size of the original archive. If an archive occupies 100 blocks of system space, at least 100 addition blocks will be required to store the final IMPORT script and object files.

Archive files with .imp extensions will be overwritten by the final IMPORT script unless precautions are taken to specify a different destination directory or IMPORT script name. It is suggested that HPSBV users create their archives as archive.sbv.

IMPORT scripts contain full directory pathnames for all new Visualizer object files at the time of creation. Object files should not be relocated if an IMPORT script is to be used in the Personal Visualizer.

Data transferred from Starbase environments may require additional "retouching" in the Personal Visualizer’s model editor. Also, the current release of sbvtrans will not transfer color attribute information to the new environment, so measures should be taken to partition data from the driver for easy color specification in the Personal Visualizer.