----------------------------------------------------------------------
File Export Formats and Plug-In Translators

Last update: 24 July 1998

Confluent Technical Notes
Copyright (c) 1995-98 Confluent, Inc.  All rights reserved.
Suggestions or questions to 415-764-1000 or vthought@confluent.com.
----------------------------------------------------------------------

This technical note describes the Visual Thought file export and
plug-in translator technology.

The plug-in translator technology is the foundation for the large
number of export formats that are available in Visual Thought.  You
can give Visual Thought information about a file format, then
"plug-in" a translator from a format that Visual Thought knows about
to your requested file format, and the program will automatically and
transparently be able to export files in your new format.

Visual Thought will even automatically find multi-step translations;
if you tell Visual Thought about a TIFF-to-JPEG translator and a
JPEG-to-BMP translator, since Visual Thought knows how to generate
TIFF internally, it will then enable export of both the JPEG and BMP
formats.  Export of BMP files would then be accomplished in two
translation steps by generating a TIFF file, translating it to JPEG,
then translating to BMP.

Visual Thought also exports its own file format as text.  Since this
file format (Visual Thought Export, or VTX) contains all the object
information in a Visual Thought document, including the connectivity
between objects, you can define a translator to convert to any other
format requiring that semantic information.  For example, with the
appropriate translators, you can generate HTML for World Wide Web
pages, input files for CASE tools, simulators, or other graphics
packages, and even input files for your own proprietary programs.

A plug-in translator doesn't have to simply translate one file format
to another; it can be any program taking a file as input.  A simple
example would be a program that accepts GIF files and displays them.
Exporting using this "translator" would actually result in the display
of an image instead of mere generation of an image file.

As another example, suppose you want to use Visual Thought as a
graphical input preprocessor for a chemical process simulator.  You'd
like to draw a representation of your process in Visual Thought, click
a button, and have your simulator use Visual Thought's graphical
representation as input for a simulation.  This can be done by
defining a plug-in translator that accepts a VTX file as input,
reformats the information in a format your process simulator likes,
then runs the simulator with that information as input.


Predefined Export Formats
-------------------------
Visual Thought documents can be exported to graphics files with the
File->Export... menu item, which opens the Export file chooser.  The
export format is specified with the File Type menu in the Export file
chooser.  As distributed, Visual Thought provides the following export
formats in the File Type menu:

  Encapsulated PostScript (eps)
  EPS with bitmap preview (eps)
  EPS with TIFF preview (UNIX/Mac) (eps)
  EPS with TIFF preview (Windows) (eps)
  EPS with WMF preview (UNIX/Mac) (eps)
  EPS with WMF preview (Windows) (eps)
  FrameMaker Interchange Format (mif)
  Windows Metafile (wmf)
  Windows Enhanced Metafile (emf)
  Tagged Image File Format (tif)
  CompuServe GIF87a (gif)
  Visual Thought Export (vtx)
  FrameMaker (mif) [import by ref in FM5]
  NCSA HTTPd server-side imagemap (map)
  Spyglass client-side imagemap (map)
  HTML-ready client-side imagemap (map)
  GIF87a & HTML-ready imagemap (gif,map)
  Microsoft Windows Bitmap (bmp)
  CompuServe interlaced GIF89a (gif)
  JFIF-style JPEG (jpg)
  Macintosh PICT (pct)
  Portable Document Format (pdf)
  Portable Bitmap (ppm)
  Sun Raster (ras)
  Irix RGB (rgb)
  TrueVision Targa (tga)
  TIFF Compressed (tif)
  X11 Bitmap (xbm)
  X11 Pixmap (xpm)
  X11 Window Dump (xwd)

On UNIX, if only the first 12 of the above formats appear in the File
Type menu, the PATH environment variable may be truncated.  Contact
Confluent to obtain help fixing this problem.

The following export formats are automatically enabled if you have one
or more programs from the Island Graphics series and the directory
containing the Island executables is in your command search path:

  HP PCL (pcl)
  HP DeskJet (hpdj)
  HP PaintJet (hppj)
  Island Draw (vec)

The following export formats are also supported in the Visual Thought
distribution, but must be enabled by uncommenting entries in the
Translators configuration file (described below):

  AVS X Image (avs)
  Group 3 FAX (fax)
  CompuServe GIF89a (gif)
  Magick Image File Format (miff)
  MTV Raytracing (mtv)
  ZSoft PC Paintbrush (pcx)
  VICAR Image (vicar)


How Plug-In Translators Work
----------------------------
The plug-in translator technology in Visual Thought uses two
user-modifiable components:

 1. The system and user Translators configuration files
 2. A set of format translation programs

The Translators file defines the export formats that Visual Thought
can create (e.g., TIFF, GIF) and the translators used by Visual
Thought to convert native formats to export formats (e.g., convert_cf).

All defined formats that can be created via valid translators will
appear in the File Type menu in the Export file chooser.  A format may
be created by using more than one translator in a multi-step
translation.

Each translator uses an external program that reads a file with the
input format, performs translation, and writes a file with the output
format.  Any program used for translation must reside in the user's
command search path.  Translation programs supplied with the Visual
Thought distribution reside in one of the following locations
(assuming Visual Thought has been installed in the default location):

  UNIX:

    /usr/local/confluent/util-1.4/share/bin      (system-independent)
    /usr/local/confluent/util-1.4/<system>/bin   (system-dependent)

    These directories are added to the user's command search path by
    the vthought shell script.

  Windows:

    C:\Program Files\Confluent\Visual Thought 1.4\bin

    This directory is added to the user's command search path by the
    Visual Thought executable.

When Visual Thought is started, it reads the system version of the
Translators file from the following location:

  UNIX:

    /usr/local/confluent/vt-1.4/<system>/config

  Windows:

    C:\Program Files\Confluent\Visual Thought 1.4\config

<system> is one of the following, depending on your system:

  system          <system>
  ------          --------
  HP-UX 9.x/10.x  hpux-9
  Solaris 2.x     solaris-2
  SunOS 4.1.x     sunos-4.1

Visual Thought next reads the user version of the Translators file
from the following location:

  UNIX:

    ~/.vthought

  Windows:

    The first of the following directories that is available:

      %HOME%\.vthought
      %HOMEDRIVE%%HOMEPATH%\.vthought
      C:\Program Files\Confluent\Visual Thought 1.4\.vthought

Information defined by the user version supersedes that defined by the
system version.

When you use the Export file chooser, Visual Thought determines if the
format you wish to export is a native format.  If it is native, Visual
Thought writes the file directly.  The native formats are EPS, EPSI,
EPSTM, EPSTL, EPSWM, EPSWL, MIF, WMF, EMF, TIFF, GIF, and VTX.

When Visual Thought exports files in other formats, it first creates a
file in one of the native formats.  This file is then used as input to
the first of a sequence of one or more translators that convert the
native format to the desired export format.  The shortest possible
sequence of available translators will be used to create the desired
export format.

The Visual Thought distribution includes the ImageMagick convert
program for translating the native TIFF format to a wide variety of
other raster image formats.


How to Add Export Formats
-------------------------
To add export formats to Visual Thought, follow these simple steps:

 1. Modify the system or user Translators file to include new format
    and translator definitions.  The format of entries in the Translators
    file is described below.

 2. Add any translation programs referenced by your new translator
    definitions to a directory in your command search path.

 3. Debug your new entries by invoking Visual Thought with the
    following command-line option:

      -informtranslators

    This turns on error checking when Visual Thought parses the new
    Translators file.

As noted previously, a translator doesn't necessarily have to write an
output file.  It can be any program that simply takes input.  In this
case, the "format" output by the "translator" is simply a proxy that
is used for identification in the File Type menu in the Export file
chooser.  The format and translator definitions that reference "xdpy"
in the system Translators file comprise a very simple example of this
case.


Translators File Syntax
-----------------------
The Translators file must conform to the following syntax rules:

 1. Only printable ASCII characters are allowed
 2. Whitespace consists of one or more spaces and/or tabs
 3. Whitespace is ignored at the beginning of a line
 4. Whitespace delimits record fields
 5. Blank lines are ignored
 6. Lines beginning with "#" are ignored


Format Records
--------------
A format is defined with a format record, using the following syntax:

  format <id> <suffix> <description>
  format <id> <idlist> <description>

where:

  <id>          : format identifier
  <suffix>      = file name suffix for a single format (e.g., tif)
  <idlist>      = format <id> list for a multiple format (e.g., tiff+jpeg)
  <description> : format description

The <id> must be unique for each unique format.  If multiple formats
are defined with the same <id>, only the last one encountered is used.
The <id> cannot contain whitespace.

The <suffix> should be the standard suffix for this file type on your
system.  The <suffix> cannot contain whitespace.

A format with an <idlist> specifies a multiple format that exports
multiple single file formats.  The <idlist> contains the <id>
identifiers of the single formats, separated by "+".  They must match
the <id> identifiers for single formats defined elsewhere in this
Translators file.  No translator line is specified for a multiple
format.

The <description> is used to identify the format in the File Type menu
in the Export file chooser.  The <description> can contain whitespace
and consists of all characters after the whitespace following the
<suffix> or <idlist>.

For example, the following format records define TIFF, JPEG, and
multiple TIFF/JPEG formats:

  format tiff  tif   Tagged Image File Format (tif)
  format jpeg  jpg   JFIF-style JPEG (jpg)
  format tiff_jpeg  tiff+jpeg   TIFF & JPEG (tif,jpg)


Translator Records
------------------
A translator between two formats is defined with a translator record,
using the following syntax:

  translator <input> <output> <executable> <args>

where:

  <input>      : translator input format identifier
  <output>     : translator output format identifier
  <executable> : executable performing the translation (e.g., convert_cf)
  <args>       : arguments to <executable>

The <input> and <output> must match the <id> identifiers for formats
defined previously in this or a previously read Translators file.  The
combination of <input> and <output> must be unique for each unique
translator.  If multiple translators are defined with the same <input>
and <output>, only the last one encountered is used.  The <input> and
<output> cannot contain whitespace.

Whitespace may be included in the <executable> and <arg> fields by
enclosing the fields in double quotes (").

The <executable> string may be either a command name or the full path
to an executable.  Environment variables and the "~" symbol
(indicating a user's home directory) are evaluated in the string.  If
the string is a command name, the user's command search path is
searched to determine the full path.

If the <executable> string does not reference an available executable,
the associated translator is not defined and no warning message is
generated.  If you would like to be informed when translators are left
undefined for this reason, specify the "informtranslators" preference.
For more information, see the file note_preferences.txt.

The <args> may contain the strings "$INFILE" and "$OUTFILE", which are
replaced by the translator input and output file paths, respectively.

For example, suppose you have the following translation programs:

  tiff2jpeg <input> <output> - converts TIFF format to JPEG format
  jpeg2bmp  <input> <output> - converts JPEG format to BMP format

The following translator records define translators that would enable
both the JPEG and BMP export formats:

  translator tiff  jpeg  tiff2jpeg $INFILE $OUTFILE
  translator jpeg  bmp   jpeg2bmp  $INFILE $OUTFILE

To generate the file output.jpg in the JPEG export format, Visual
Thought performs the following steps:

 1. Generate the temporary file tmp.tif in the TIFF format.
 2. Execute tiff2jpeg to translate tmp.tif to output.jpg.

To generate the file output.bmp in the BMP export format, Visual
Thought performs the following steps:

 1. Generate the temporary file tmp.tif in the TIFF format.
 2. Execute tiff2jpeg to translate tmp.tif to tmp.jpg.
 3. Execute jpeg2bmp to translate tmp.jpg to output.bmp.
