AudiLabTr3: 3-D surface triangulation

Table of contents

1. Introduction

Tr3 is a home-grown programme for triangulating 3-D surfaces between serial-section contours. It takes a .tr3 plain-text model-definition file (as produced by Fie) as input and produces a VRML model file (.wrl, for use by Thrup’ny, for example); a finite-element model file (.sap) for use by SAP IV and our other modelling software; and JSON files for use by Thrwp’ny (example).

Tr3 is implemented in Fortran. It was originally developed under VMS, and later under Unix for Alpha, and is currently being developed under Debian GNU/Linux and (alas) Microsoft Windows; the binaries are available for downloading below. It can be used for any purpose as long as I am informed of its use. So far there is no documentation beyond what you're looking at.

2. Installation

2.1 Installation under MS Windows 95/98/NT

Either download the Tr3 executable for 32-bit Windows (about 1.6 Mbytes) or (if your computer is part of the McGill BME network) create a shortcut to the executable on probeShare. Follow the general instructions for installation of Dip software.

If you are using a copy of Tr3 installed on your local hard disk, then you must also provide the Glib library and two associated libraries. Download the following DLL files into the same directory that tr3.exe is in:

These libraries are used by the snake feature in Fie, and their presence is required by Tr3 because of Tr3's use of some Fie routines. Further information about these libraries (including their source code) can be found at the GTK+ Web site.

Tr3 also uses a statically linked copy of the GLE Tubing and Extrusion Library by Linas Vepstas.

2.2 Installation under GNU/Linux

If your computer is part of the McGill BME network, create a symbolic link (ln -s) to the executable on probeShare. Otherwise download the Tr3 executable from here:

To make Tr3 executable, open a terminal window (in some versions of Linux, by doing Applications ► Accessories ► Terminal), and do
cd Downloads
chmod u+x tr3
Alternatively, you can right-click on the file in a file-browsing window, select Properties and then the Permissions tab, and check the box Allow executing file as program.

You can run Tr3 by opening a terminal window and giving the command ./Downloads/tr3 or, if you have already cd'd into the Downloads directory, just ./tr3.

Tr3 uses version 6.2 of the Independent JPEG Group's JPEG library so you may need to install it (Debian package libjpeg62) if you don't have it (which may happen if you only have a later version installed).

You may need to look at the general instructions for installation of Dip software.

3. Usage

3.1 File and subset selection

When you first run Tr3 you are asked to select a .tr3 file. The menu usage is the same as for Fie's File ► Open.

Once the .tr3 file has been read in, you will be asked to select which subset you wish to process, if any subsets have been defined in the .tr3 file.

By default, Tr3's graphics are displayed on the screen. If you run Tr3 from the command line, you can optionally specify that Tr3 should plot its graphics to a file in one of a few formats. The command can take the following forms:
tr3 /plot (you will be asked to provide filename/dev=type)
tr3 /plot=filename (you will be asked to provide type)
tr3 /plot=filename/dev=type
The plotting device types are described in the Dip documentation under Specifying the output type.

3.2 Option menu

The next step is to select options, if desired.

The Verify option allows you to monitor and guide the triangulation process. This is done when you suspect that artefacts in the 3-D model (e.g., jaggedness) are caused by a poor triangulation. See below for details.

The Combine option is used to tell Tr3 to combine all triangles that have the same descriptive text into a single object, regardless of which line, join or cap they are derived from in Fie. This means that most viewers will render the entire object smoothly, rather than showing abrupt transitions between triangles derived from different lines, joins and caps. If this option is not selected, the default file name will include the text string _dbg (for ‘debug’).

The Generate clipped surfaces option tells Tr3 whether to attempt to generate surfaces indicating where x and y clipping have been enabled as a subset attribute in Fie. If the automatically generated surfaces are not successful, you may want to disable them here and create such surfaces manually.
The Generate clipped lines option tells Tr3 to create distinctive edges in the model where the clipping occurs.

The Generate internal nodes in caps option controls how Tr3 triangulates caps. It is unlikely that you'll need to worry about this.

The Surface smoothing option can enable Taubin iterative surface smoothing. You will be asked for the number of iterations to use. More iterations results in a smoother surface but the shape may be unacceptably deformed. This smoothing works best if the surfaces are already reasonably smooth, and in principle it is probably better to do your smoothing within Fie.

The Include marked voxels option controls whether Fie’s marked voxels are displayed in the 3-D model. This is seldom desired.

The Display model position & orientation option does not currently work with either Thrup’ny or Thrwp’ny.

The JSON output option controls whether the 3-D model is output in JSON format (as well as in VRML and SAP format). There are three possible settings:

The third option results in having every structure output twice, once with regular coloured triangles and once with orange back-facing triangles. This can be very useful for detected improperly reversed triangles.
If the JSON option is enabled, Tr3 creates an HTML file; a .jsonList file; and a set of .json files, one for each object. The files are written into a subdirectory named json, which must already have been created within the directory where the .tr3 file lives. To view the resulting model using Thrwp’ny, open the HTML file in your Web browser (example).
The Output high-plotting-level lines option tells Tr3 to create distinctive lines in the JSON model corresponding to edges with high plotting levels in Fad. This can be very useful in debugging a model for finite-element modelling or 3-D printing.

Once you have selected the desired options, click the bottom button to continue.

3.3 Name of output file

A default output file name will be suggested, based on the name of the .tr3 file and the name of the selected subset. The name may also contain _dbg, depending on the options chosen (see above).

Normally you should just accept the default name by hitting the Enter or Return key. The actual triangulation will then start. If your model is small, Tr3’s graphical output may flash past so quickly that you hardly see it. Tr3 should end with a message saying Done and an OK button.

3.4 Warnings

While Tr3 is running, it may produce warning messages. Make note of such messages and then click on OK (or press any key) to continue.

One such warning, at the end, may say No real elements, no .sap file created. This happens if no thicknesses or material properties are specified. This is normal for models that are used only for visualization and not for simulation.

3.5 Verifying and guiding the triangulation

Tr3 verification screen

If the Verify option is selected (see above) then Tr3 stops after triangulating each line pair, join and cap and allows you to accept or modify the result.

The image on the right shows a typical Tr3 verification screen. The upper left panel shows a line in two slices (black and red) and the triangles (green) that Tr3 has used to connect them. Below and on the right are side views of the two lines and the triangles. At the bottom are three lines of text:

The Skip function is seldom if ever required.

The Toggle alignment function controls whether Tr3 does a preliminary alignment of the two lines before trying to determine the optimal triangulation. The current state is displayed as either (aligned) or (unaligned) in the third line of text, and clicking the button reverses the state. Sometimes one or the other will give a better triangulation.

The Change cost function button is another way of affecting how the triangulation is done. Tr3 determines an optimal triangulation by minimizing a ‘cost’ (Funnell, 1984). For example, Tr3 may minimize the total surface area formed by the triangles between two lines.

There are several different cost functions available. Sometimes the triangulation can be improved by choosing one or the other.

3.6 Logging

Tr3 creates a log file called tr3_log.tmp in your home directory. As Tr3 is running, certain information is recorded in that file. It may be useful for debugging.

AudiLab AudiLab home page
R. Funnell
Last modified: 2017-08-15 08:09:46