AudiLabFie: Fabrication d’imagerie extraordinaire


Table of contents

1. Introduction

Fie is a programme for various image-editing and related tasks. Its main purpose these days is for 3-D segmentation.

1.1 3-D segmentation

The drawing operations in Fie can be used to trace structure outlines in stacks of images. The outlines are maintained in text files suitable for subsequent surface triangulation using Tr3, for either visualization or finite-element simulation.

The use of open contours (in addition to the usual closed contours) facilitates the controlled handling of complex structures with shared surfaces. An important feature is that one can specify that a line should start and/or finish at the start or finish of some other line. This provides a mechanism for specifying and ensuring topological continuity and integrity. This continuity is specified for a particular line within groups of slices, and is displayed graphically, so the user can visually verify connections. Since the connectivity often changes from slice to slice, a mechanism is provided to specify Joins across such divisions, and Caps can be defined to close the beginnings and ends of 3-D surfaces.

The alignment operations in Fie can be used to align histological serial sections for subsequent segmentation and 3-D reconstruction.

The .tr3 file produced by Fie can contain specifications for colours and transparency (for visualization), and also mechanical properties, boundary conditions and loads (for finite-element simulation), together with the basic geometry. The goal is that, if the image segmentation needs to be modified, a complete new model can be generated in one operation, without having to recreate all of the non-geometrical attributes.

Two different colours (an editing colour and a separate rendering colour) and a transparency can be specified for each line. Nodal boundary conditions (whether free or clamped) and applied pressure can be specified. Material properties for the 3-D surfaces can be specified for each line by reference to a list of material types, and specification of thickness.

A syntax is available for specifying the triangulation of subsets of a whole model, and for specifying different mesh resolutions for different parts of a model or for different versions of a model. Algorithms have been developed for resolving start-at/finish-at dependencies and detecting circular indeterminacy, and for detecting and removing duplicate nodes (essential to ensuring mechanical continuity for simulations).

Triangulated models are generated in both VRML and JSON formats (for interactive visualization) and SAP format (for finite-element simulation). The visualization models include labels with two levels of granularity, one well suited for debugging and the other for teaching purposes. The VRML files can be viewed using Thrup’ny or other VRML viewer. The JSON files are designed to be viewed using JavaScript and WebGL within a Web browser.

The finite-element model files can be converted to other formats using Fad.

1.2 Miscellaneous features

Additional features include:

1.3 Availability

Fie is implemented in Fortran. It was originally developed under VMS and later under Unix for Alpha. It is currently being developed under Debian GNU/Linux for x86 and x86_64, and (alas) under 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.

1.4 History

Fie has been evolving gradually since 1989. It was originally used for image viewing and editing. Around 1995 it absorbed features from Dig, a programme that I had been developing since 1976 for digitizing images and doing reconstruction from serial sections.

The ‘F’ originally stood for Fancy or Fortran or Funnell, depending on the phase of the moon and other factors; these days maybe it would stand for Funky. The ‘IE’ stood for Image Editor. These days we don't use Fie much for image editing, but more for creating 3-D models, so I came up with Fabrication d'imagerie extraordinaire as a new excuse for the name Fie.

1.5 Overview of documentation

Section 2 explains how to install the software. Section 3 gives some general information about the graphical user interface, file saving and automatic backups. Section 4 then presents the functions of every menu and submenu. Section 5 describes the detailed format of the .tr3 file produced by Fie; although much of the file is created and modified by Fie, there are some sections which still need to be created and edited directly by the user.

Section 6 presents an example to illustrate the use of Fie and Section 7 is a tutorial that is intended for self-teaching.

When new information is added to this documentation, it may be flagged as being new, like this.

2. Installation

2.1 Installation under Microsoft Windows

Either download the Fie executable for 32-bit Windows (about 1.5 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 Fie 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 fie.exe is in:

These libraries are used by the snake feature. Further information about these libraries (including their source code) can be found at the GTK+ Web site.

Fie has been used with MS Windows 95, 98, NT, 2000, XP, Vista, 7, 8 and 10.

Under Windows 7 and higher, some things act strangely and sometimes the programme fails to start. If it fails with a message that refers to a HOME environment variable, it means that you need to follow the instructions for setting up such a variable (see installation of Dip software as mentioned above). If other error messages occur upon startup, or if text messages overwrite one another, just try running Fie again.

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 Fie executable from here into a directory called Downloads in your home directory.

To make Fie executable, you can open a terminal window (in some versions of Linux, by doing Applications ► Accessories ► Terminal), and do
cd Downloads
chmod u+x fie
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.

Problems:

You can run Fie by opening a terminal window and giving the command ./Downloads/fie& or, if you have already cd'd into the Downloads directory, just ./fie&. The & causes Fie to run in the background so your terminal window can be used to do other things (e.g., to run Tr3) while Fie is still running. (By default, double-clicking on Fie in a directory listing probably won't work. An alternative is to set up a custom application launcher in the top panel of your Linux GUI, if there is such a panel.)

2.3 Window size

Fie will try to estimate how much screen space is available to it. You can use the function Set ► Dip device size to specify the window size by trial and error until the Fie window takes a little less than the whole vertical space available. Make sure you can see the Repaint button at the bottom of the screen, as shown below. The window size that is set in this way will also be used by other Dip software.

3. User interface

3.1 Layout

Interface

Fie has a menu-based graphical user interface. The interface is identical under different operating systems. As shown at right, the interface consists of

3.2 Menus

See the Dip documentation for a general discussion of how to use the menus. Note that every menu button has a shortcut key, indicated by underlining in the button label.

In some cases when a menu is displayed in Fie, you can either click on one of the menu items or click in one of the image windows. For example, when selecting a line for some purpose, you can either click on the appropriate button in the menu or click near the line within either the main image window or the overview window.

3.3 Versions of files

When Fie saves a file, if a file already exists with the same name then the old file is renamed by adding a version number. The version number is of the form #n# and is appended to the file name. For example, if three versions of the file test.tr3 exist, called test.tr3#1#, test.tr3#2# and test.tr3, when a new version is saved it will be called test.tr3 and the previous version will be renamed to test.tr3#3#.

If you ever need to recover an older version, just use your operating system to delete the later version (or rename it to something else if you're not sure) and then rename the version you want by removing the version number.

3.4 Automatic backups

As you are doing Draw operations (or Tailor ▶ Align operations) Fie will automatically back up the .tr3 file from time to time. The backup is done to a file called fie_tr3.tmp in your HOME directory. If something goes wrong during a session (e.g., Fie crashes or your computer crashes), or you accidentally quit without saving your latest changes, you can recover the contents of the last automatic backup:

  1. Move (or copy) the file fie_tr3.tmp from your HOME directory to the directory where your .tr3 file normally resides.
  2. Rename the last .tr3 file to something else.
  3. Rename fie_tr3.tmp to have the name of your normal .tr3 file.

The frequency with which automatic backups are done can be controlled by the Autobackup frequency item in the settings menu (which is available from within several menus). Specify how many interactive operations you want to have happen between backups.

4. Menus

The following summarizes the functionality of Fie, organised according to the items on the top-level menu (shown at right).

File includes file opening, saving, etc.

Set includes a number of settings. Other than font size, the important ones for most current uses are included at various places under Draw.

Focus allows the specification of focus regions for operations like filtering and statistics. Filter includes various image-processing operations.

Filter provides a number of image filters.

Paint provides some simple pixel-painting operations.

Draw provides a sophisticated set of drawing and segmentation operations.

Stats provides various kinds of statistics for pixels and clusters of pixels.

Tailor provides a number of image operations like resizing, reshaping, distortion removal and alignment.

Combine produces a combination image by combining selected images from a stack of images, using either average or maximum pixel values.

Surface generates a 3-D surface from a stack of images using a user-specified threshold and a marching-tetrahedra algorithm. The surface is output as a VRML file.

Quit just quits, after checking for any unsaved modifications, and with saving of session settings.

Note that all of the contour-tracing things are located under Draw, and the alignment tools for stacks of histological images are under Tailor.

4.1 File

4.1.1 Open

Fie can read in several different types of files, as described in the following subsections. When Open is selected from the File menu, Fie will display a list of recently opened files (if any). If the desired file appears on that list, select it. If not (or if no such list is available) click on Other or use the + shortcut key. Fie will then display a list of the subdirectories and files within some starting directory. (The particular starting directory used may depend on which files have been opened recently, on whether the HOME environment variable is defined, and on the phase of the moon.) Browse to find the file to be opened and click on it.

Currently (for historical reasons) Fie handles JPEG images differently from the way it handles other types of images. JPEG images can be handled only by opening a .tr3 file which includes a list of a set of JPEG images. For other types of images, open the image file itself; Fie will then automatically open the corresponding .tr3 file if it finds one with the same name as the image file.

For new datasets that we create ourselves, the format of choice is JPEG. It provides greater image compression and more flexibility.

4.1.1.1 JPEG (.jpg)

Fie can read both grey-scale and colour JPEG images. A 3-D stack consists of a set of image files, one image for each slice.

The images in a stack must all have the same numbers of rows and columns of pixels.

The usual practice is to have all of the image files in a subdirectory of the directory where the .tr3 file is. The name of that subdirectory, and the names of the image files, are specified in the SLICES section of the .tr3 file.

4.1.1.2 TIFF (.tif)

Fie can read several types of TIFF-encoded images: 8-bit grey-level or paletted, and 24-bit RGB, either uncompressed or with run-length-encoding compression.

A 3-D stack of TIFF-encoded images must be stored in a single multi-image TIFF file. The images must all have the same numbers of rows and columns of pixels, and must all be of the same type.

If the file name.tif is opened, then Fie will look for a file name.tr3 in the same directory, and open it if found.

4.1.1.3 Raw byte stream (.raw)

Fie can read images, or stacks of images, stored as raw byte streams.

If the file name.raw is opened, then Fie will look for a file name.fie in the same directory. This is an auxiliary plain-text file which provides the image size and other characteristics. It contains lines with the following syntax:

NPIXH nh nh = no. pixels horizontally
NPIXV nv nv = no. pixels vertically
NSLICE ns ns = no. slices in image stack
NBITS nb [nbu [{SWAP|NOSWAP}]] nb = no. bits/pixel = 8 or 16. If nb=16, then nbu = no. bits actually used/pixel = 8 or 16; and byte order is specified as either SWAP or NOSWAP. Default no. bits/pixel = 8. If no. bits/pixel = 16, default no. bits used/pixel = 16 and default byte order = NOSWAP.
TYPE t t = image type: GREY or RGB. Default = grey.

Any line which starts with a semicolon is interpreted as a comment.

Example. A stack of 8-bit grey images might have this .fie file:

;15516.fie
NPIXH 228
NPIXV 186
NSLICE 168
NBITS 8
TYPE GREY

If no .fie file is found, Fie will query the user for the image characteristics.

Fie will also look for a file name.tr3 in the same directory, and open it if found.

4.1.1.4 Density files (.den)

These are grey-level files as used in VolPack. The .den file format includes a header which specifies, among other things, the numbers of rows, columns and slices.

If the file name.den is opened, then Fie will look for a file name.tr3 in the same directory, and open it if found.

4.1.2 New

Fie can generate test images or new .tr3 files.

4.1.2.1 Image

Fie can generate test images and image stacks with user-specified size and various contents:

4.1.2.2 Tr3

Fie can generate a new .tr3 file corresponding to an existing set of .jpg or .png files. It will first ask to confirm that you have such a set of files. If you answer Yes, it will ask you to select the first file in the set, and then to select the last file in the set. All the files must be in the same directory. Fie assumes that the filenames of every file in the set consist of the same text followed by a sequence number (with leading zeros if required), e.g., cat01.jpg, cat02.jpg, … cat20.jpg. It asks what increment to use for the sequence numbers; the default is 1, but you could specify, e.g., 2 if you only wanted to use every second image, or if you only had cat02.jpg, cat04.jpg, etc.

If you specify the same file for the first and last image, Fie will reuse the same file for every slice, and will ask how many such slices you want.

Fie will then ask for the file path and name to use for the new .tr3 file. It will offer a default path and name based on the path and names of the image files.

Fie will then ask for the z coördinate to use for the first slice, and for the z spacing between slices. It will then ask for the x-y pixel size, which should be measured in the same units as the z coördinates. If you don't know the actual dimensions at this point, you can just accept the defaults and then adjust things later.

Finally, Fie will ask for your initials and a line of comment, and create the new .tr3 file. The file can now be opened using File ▶ Open.

4.1.3 Import

4.1.3.1 SurfDriver

Fie can import contours traced by SurfDriver. The contours must first have been Exported from SurfDriver to .txt files, and the corresponding set of image files used by SurfDriver must have been used to create a .tr3 file.

To export a set of contours from SurfDriver:

To import the contours, first use File ▶ Open to open the image stack. Then do File ▶ Import. You will then be asked for

You will then be asked to specify one or more .txt files. For each file you will be asked to specify a short Prefix text string to be used (combined with sequence numbers) in forming the contour names in Fie. Once the contours have been imported, you can use Edit attributes to change their attributes from the defaults assigned by Import.
4.1.3.2 MRP
0 13502 27000
[landmarks]

[nodes]
2.0781 2.3786 1.9818
2.0789 2.3786 1.9924
2.0753 2.3647 1.
…
2.4724 2.9489 2.3444
2.468 2.9474 2.3474
2.4756 2.9458 2.3422

[surface]
1 2 3
1 3 4
5 6 7
5 7 8
…
  

Fie can import .mrp files. This is a rather primitive surface-definition file format; an extract from an example file is shown on the right. Fie assumes that an image-stack file is available; the stack should be opened before doing the import. Landmarks are ignored. It is assumed that nodes come before triangles.

4.1.4 Save

Fie can save data in various formats:

See the descriptions above in the Open section for more details about some of the file formats.

When using Fie to do image segmentation, the only file that needs to be saved is the .tr3 file. The images themselves are not modified.

Saving a stack of images is a convenient way of converting the images to a different format, e.g., converting a TIFF or raw image stack to a set of JPEG images. When a stack of images is saved, they will not include any changes made to them within Fie.

4.2 Set

4.2.1 Zoom

Same as Zoom function within Draw.

4.2.2 Pan

Same as Pan function within Draw.

4.2.3 New image

Same as New image function within Draw.

4.2.4 Palette

Choose from several palette options.

For grey-scale images, the palette controls how the grey levels are displayed, possibly with colour. Normally one would choose either a grey-level palette (possibly specifying a gamma and thresholds) or a false-colour palette.

For full-colour (3 bytes/pixel, RGB) images, the grey-level mapping defined by the palette is applied to any pixel which is a shade of grey, i.e., for which the red, green and blue values are the same. This may be appropriate for images which are essentially grey-scale but have annotations in colour.

For paletted images (1 byte/pixel colour) the selected palette controls the mapping from the single-byte pixel value to colour. Currently this applies only to TIFF images which are paletted; such an image will set up its palette when it is read in.

4.2.4.1 Grey

grey-level palette, gamma = 1.0 The grey-level palette controls the mapping of 8-bit pixel values to displayed grey levels or colours. A submenu and thumbwheel are provided for adjusting the black level, white level, gamma, low (blue) threshold and high (yellow) threshold. The default palette just maps pixel values of 0-255 linearly to the same range of greys.

Black allows adjustment of the pixel value below which all values are displayed as completely black. By default the black level is 0.

White allows adjustment of the pixel value above which all values are displayed as completely white. By default the white level is 255 (i.e., the maximum pixel value).

grey-level palette, gamma = 0.5 grey-level palette, gamma = 1.5
γ=0.5 γ=1.5
Gamma is the exponent of a non-linear mapping from pixel value (v) to grey level (g): g = vγ. The default value of gamma (γ) is 1.0, corresponding to a linear mapping. Adjusting γ is sometimes useful to enhance contrast in grey-scale images. These examples show the grey-level palette with γ = 0.5 and 1.5.

Blue and Yellow correspond to two thresholds. Pixels are set to shades of blue if their values are less than the first threshold, and to shades of yellow if their grey-level values are greater than the second threshold. Such thresholds can be used to assist segmentation. The sample image shown here has the thresholds set to differentiate among bone, soft tissue and no tissue. As here, the distinction will generally be only approximate and in itself cannot provide accurate segmentation.

4.2.4.2 False colour
false-colour palette

False-colour palette ranging from black through blue, green and yellow to white. This palette provides monotonically increasing brightness. It can be used to enhance visual contrast and to make images prettier.

4.2.4.3 3-3-2
3-3-2 palette

RGB encoded with 3, 3 and 2 bits, respectively

4.2.4.4 5-6-5
5-6-5 palette

RGB encoded with ranges of 0 to 5, 6 and 5, respectively

4.2.4.5 RGB-CMY
rgb-cmy palette

Palette starting with black and white; then saturated red, green, blue, cyan, magenta and yellow; then six unsaturated colours having combinations of 0, 0.5 and 1 for r, g and b; then two greys; then 30 shades each for grey, red, green, blue, cyan, magenta, yellow and orange

4.2.4.6 B & w

Black and white

4.2.4.7 TIFF

Uses palette embedded in TIFF image (if any).

4.2.5 Pen

Pen size and shape for painting. Partially broken and not used much these days.

4.2.6 Cursor shape

The cursor shape for pointing can be either a crosshair (the default) or an arrow. The cursor for text input has a T shape.

4.2.7 Region of interest

Specify whether certain operations are to be applied to all of the image, to the visible part of the image, or to specified focus regions.

4.2.8 Window size

Set size of main image window within the overall Fie window.

4.2.9 Watch processing

Sets or unsets watch mode for watching the progress of certain operations.

4.2.10 Indirect input

Allows user to specify the name of a command file for executing scripts (currently broken)

4.2.11 Dip device size

Sets the vertical size (an integer number of pixels) of the overall Fie window. By default Fie will guess at an appropriate window size, but sometimes it will be too big or too small and will need to be set by trial and error. This setting is also used in Tr3, Fad and other Dip software.

4.2.12 Dip font size

Sets the font size (an integer) used in the interface. This setting is also used in Tr3, Fad and other Dip software.

4.3 Focus

Specify various ‘focus’ regions, which can be used to restrict the part(s) of the image involved in other operations

4.4 Filter

Apply various filtering operations

4.5 Paint

Things are painted into the image, actually changing the pixels. This is here for historical reasons, and for playing with algorithms, and isn't really very useful at the moment.

4.6 Draw

4.6.1 Introduction

Things are drawn over the image, not actually changing the pixel values in the underlying image. The x and y axes are the horizontal and vertical axes, respectively, in the main image window. The z axis extends through the stack of slices.

Draw interface with side views Draw interface with side views In addition to the main image window and the overview window, two additional windows appear. They are used for displaying side views of either the stack of images (as shown on the left) or the lines used to segment the images (as shown on the right).

If images are displayed in the side views, the x-z images are below the main image window and the z-y images are to the left. Left-clicking in such a sideview window causes the corresponding slice number and z coöordinate to be displayed. Right-clicking in the window causes Fie to jump to the slice corresponding to the z coördinate where the click occurred. Either left-clicking or right-clicking also causes either the x-z image or the z-y image to change to correspond to the x or y coöordinate where the click occurred.

If lines are displayed in the side views, they are in two windows below the main x-y image window: x-z on the left and z-y on the right. Left-clicking in such a sideview window causes the corresponding z coördinate to be displayed, along with the slice number and corresponding z coördinate of the nearest slice. Right-clicking in the window causes Fie to jump to the nearest slice that contains a line if that slice is reasonably near by, otherwise it jumps to the slice nearest to the z coördinate where the click occurred.

In Draw mode a scale bar is displayed in the main image window. The units used for this scale bar are specified in the XY_CALC command.

The image on the left shows how lines are displayed when not being edited. Their colours, the line thickness and the symbol sizes can all be controlled by the user. The first point of a line is indicated by a triangle pointing to the right and the last point of a line is indicated by a triangle pointing to the left . First and last points of lines which start at or finish at the ends of other lines are displayed as right-pointing and left-pointing 3-pointed stars (like dehydrated triangles). Other points are shown as squares. Connections due to start-at/finish-at commands are shown as thinner lines.

The image on the right shows how lines are displayed when being edited. All lines in the current slice are green, except for the currently active segment which is red. Lines in the previous and next slices are shown as thin lines. The user can control whether all lines in the previous and following slices are shown, or just the currently active line, or none at all; and can control the colours used.

The rest of this section describes the various items in the Draw menu.

4.6.2 Zoom image

Zoom in or out by factors of two, or specify an integer zoom factor. Zoom factors ≥ 1 correspond to magnifications. Negative zoom factors ≤ −1 correspond to reductions; e.g., −2 corresponds to a magnification of ½.

As seen in the examples above, when zoomed in, the original pixels are shown enlarged (rather than smoothly interpolated) so one doesn't lose sight of the resolution limitations of the data.

4.6.3 Pan image

If the image is larger than the displayed area, shift the display window by clicking in either the overview window or the main image window, at the point that you'd like to have centred in the display window.

One can also recentre the displayed area by right-clicking in either the overview window or in the main image window when the main Draw menu is active, but not when the Draw ▶ Edit lines menu is active. (In Edit lines mode, right-clicking is used to reposition nodes.)

4.6.4 New image

A 7-button navigation menu pops up, allowing selection of a new image from the stack of images.

4.6.5 Settings

Set various parameters. Many of the parameters are saved in a session-settings file when the user exits from the programme. The file is used to restore the settings when the programme is run again.


4.6.6 Show lines

This button can be used to quickly toggle on or off the display of lines in the main image window.

4.6.7 Copy lines

Copy lines to an internal clipboard

4.6.8 Paste lines

Paste lines from internal clipboard

4.6.9 Edit other

Choose to edit a number of different things, including caps, joins, labels, materials, attributes, etc., as shown in the menu on the right.

4.6.9.1 Edit caps

The first step in editing caps is to select which cap to edit, or select A (new) to create a new cap. In the list of existing caps, if a cap's name is preceded by {ext} it means that the cap is defined in an external file and cannot be edited (except by opening the external .tr3 file).

For the next step, a cap-editing menu appears. The first two entries are the usual Zoom and Pan operators, and the next entry is for editing the attributes of the cap. The (reverse cap) item is for reversing the orientation of a cap definition, and is seldom used. The (delete cap) item is for completely deleting the definition of this cap.

Initially a cap definition includes a single (undefined line) entry. Clicking on that button brings up a line-editing menu, and the (undefined line) text will ultimately be replaced by the name of a line (possibly with qualifiers). The (add new line) button is used for adding another (undefined line) menu entry, which in turn is used to bring up the line-editing menu.

The first item of the line-editing menu initially contains a plus sign (+). Clicking on the button changes it to a minus sign (-), indicating that the line will be traversed backward in forming the cap. The second menu item initially says (undefined line). Clicking on it brings up a menu from which a line may be selected; a line may also be selected by clicking on a line in the main image window. The button text then displays the name of the selected line.

The last four buttons in the line-editing menu permit you to move the line up or down in the list of lines making up the cap; to delete the line from the cap definition; or to quit and return to the cap-editing menu.

Buttons 3 and 4 initially say 0. and 1., respectively, and represent the fractional positions along the line at which the part to be included in the cap starts and finishes. Clicking on either button brings up a menu for specifying the fractional position. Clicking on Start or Finish sets the fractional position to 0. or 1., respectively. Clicking on Keyboard allows the fraction (from 0 to 1) to be typed in. The most common method of specifying a fractional position along a line is to select a point on the line by clicking in the main image window or by using the Prev and Next buttons, and then using the Select button.

4.6.9.2 Edit joins

The editing of Joins is not yet documented.

4.6.9.3 Edit labels

The editing of labels is not yet documented, but the menus should be fairly self-explanatory if you understand the syntax for labels.

4.6.9.4 Edit springs

The editing of springs is not yet documented, but the menus should be fairly self-explanatory if you understand the syntax for springs.

4.6.9.5 Edit concentrated loads

The editing of concentrated loads is not yet documented, but the menus should be fairly self-explanatory if you understand the syntax for concentrated loads.

4.6.9.6 Edit materials

The editing of Materials is not yet documented.

4.6.9.7 Edit attributes

Use this function to edit the attributes of either lines or slices.

4.6.9.8 Edit line attributes

You can choose to edit the attributes of either a single line or multiple lines.

If you choose to edit the attributes for a single line, a menu will appear which permits selection of one line. After you select the line, a menu will appear in which each button displays the current value of an attribute. Click on the appropriate button to change an attribute. Clicking on Copy attributes from another line will allow you to select some other line from which all attributes (except the name) will be copied to the line whose attributes are being edited. For some attributes (e.g., Open/Closed, Interpolation, Boundary conditions), a menu will appear for selecting the new attribute value. For other attributes a simple text prompt will appear asking for the new value.

If you choose to edit the attributes for multiple lines, a menu will appear which permits selection of the lines to be affected. After you select some lines, a menu will appear for editing only those attributes which can sensibly be applied to multiple lines. The attribute values will be preset to those for the first of the selected lines. The only attributes whose values will be transferred to the multiple lines are those whose menu buttons you use (whether or not you actually change their values).

4.6.9.8.1 External attribute

This attribute is set when the line is read in from either the main .tr3 file or an external file. This attribute cannot be set directly in this menu, but it can be set indirectly by using the Internalize lines function.

4.6.9.8.2 Open/Closed attribute

Clicking on the Open/Closed button will switch the Open/Closed attribute back and forth between open and closed.

4.6.9.8.3 Interpolation

The Interpolation button displays the current line type. Clicking on it brings up a menu for selecting the line type that is desired. In some cases Fie can try to convert the existing line data from the previous line type to the new one.

4.6.9.8.4 Colour

For the Colour attribute, a colour-selection tool will appear. Find and click on the desired editing colour (the colour used within Fie), then click outside the tool to make the selection. The colour-selection tool will then appear again, this time for selecting the rendering colour (the colour used for the 3-D models produced by Tr3).

4.6.9.8.5 Start-at and Finish-at attributes

For the start-at and finish-at attributes, each of the two menu buttons displays the word Dependent if there are any such conditions, and how many there are; or the word Independent if there are none. Clicking on the button causes a menu to be presented which displays the current start-at or finish-at specifications, and a A (new) button which can be used to create a new start-at or finish-at specification with default settings. Clicking on the button for an existing specification causes a menu to appear which displays the current settings. For example, the menu shown on the right corresponds to a connection to the finish-of the line wallextfr_001. By default the specification applies to all z’s, from −∞ to +∞. In the example on the right, the first four buttons indicate, for example, that the specification should be applied to the range –∞ < z ≤ 5. Clicking on button 1 or 4 permits specification of a new z value. Clicking on button 2 or 3 toggles between < and . Clicking on button 5 offers a choice of Start, Finish or Nearest. The Up and Down buttons move the current start-at or finish-at specification up or down in the original list; the specifications should be arranged in order of increasing z. The Delete button causes the current specification to be deleted.

4.6.9.8.6 Mesh resolution

The two mesh-resolution menu items permit setting of the x-y and z mesh resolutions.

4.6.9.9 Edit slice attributes

Choose whether to edit the attributes for one slice at a time, or for a range of slices: the current slice and all preceding ones, the current slice and all following ones, or all slices. If one slice at a time, the usual slice-choosing tool appears - use the tool to position yourself to the desired slice and then click outside the tool to make the selection. You will then be prompted for new attribute values for the slice: z value, slice name, rotation, and x and y offsets. The slice-choosing tool then appears again; either select a new slice, or select the same slice to quit.

If editing attributes for a range of slices, the values requested are a z scale factor and a z shift.

4.6.9.10 Edit subsets

The editing of subsets is not yet documented. The actual lines of a subset definition must be typed in, following the syntax defined below.

When a new subset is created, it will automatically include the line *: -off. That line should always be kept as the first line of the subset definition.

4.6.9.11 Edit external files

The editing of the names of ‘external files’ is not yet documented. External files are used when a set of images is to be segmented by more than one person at a time.

4.6.9.12 Edit scale factors for Tr3 files

Values for the x, y and z scale factors for Tr3 files are requested one at a time. By default, the y and z scale factors will have the same value as the x scale factor.

4.6.10 Jump to Fad location

This command causes Fie to jump to the slice and coordinates corresponding to the most recent Locate command in Fad.

4.6.11 Add line

Add a new line to an image or images. You are first asked to either specify an existing line definition or add a new one.

The line defining a particular structure should get a different name (i.e., become a different line) when the boundary of the structure changes its nature. For example:

If necessary, use New image to select a new image from the stack of images. If a line has been traced in the current image, it will be saved before moving to the newly selected image. Once at the new image, tracing can immediately begin for a new line with the same name, unless such a line already exists there.

Use Zoom image and Pan image as required.

The settings menu provides control over the smoothing algorithms used by the Smooth function described below. The first three buttons turn the three different kinds of smoothing on or off. The last three buttons set the parameters for the different kinds of smoothing.

You can use the following functions to create the new line:

For lines which are small and/or difficult, the line is best specified manually point by point.

For long stretches of clear boundaries, the autotrace function works well. It continues until it runs into the edge of the visible image, or until it runs into itself, or until it has generated too many points. Usually it will go too far, and it may also run off course. In either case the trim function can be used to cut off the unwanted part, and then the line tracing can be continued.

For closed regions with clear boundaries, the flood function works well.

The manual and automatic tracing methods can be mixed in any order, although the flood method is normally used by itself, and will overwrite any previous tracing.

The median-filter and smooth operations are particularly useful after the flood and autotrace functions, which tend to produce jagged curves and many more points than are required. The snake method of fitting (Edit linesLines ...Fit line using snake) may also be useful after tracing here.

4.6.12 Edit lines

Edit the existing lines in this image. Left-clicking within the image selects the closest point to be the active point. Right-clicking within the image repositions the currently active point.

4.6.13 Delete lines

Delete some or all of the lines in some or all slices.

4.6.14 Locate line

Determine which slices a particular line occurs in. If a line never appears and is never referenced, it can be marked for deletion.

4.6.15 Modify lines

Some functions repeated from Edit lines ▶ Line …

4.6.16 Transform z's

Apply scale factor and offset

4.6.17 Mark voxels

Reslice

An image stack is resliced perpendicular to the original plane of section, and x-z and z-y views are displayed. The side views are slices through a user-specified point. The user can select that point by right-clicking in any of the three image windows, or by using the menu.

Voxels can be ‘marked’, in which case they will be displayed in a distinctive colour. Once you exit from the Reslice mode the marked voxels can continue to be displayed in the main image window. One use for this is to help with the segmentation of structures which are difficult to visualise in the x-y images. Another use of this feature is to mark particular voxels for display as blocks in the VRML models produced by Tr3.

The remainder of this section explains the use of the menu.

4.7 Stats

Calculate density histograms

4.8 Tailor

4.9 Quit

5. Model-definition file

5.1 Introduction

The model definitions created by Fie are stored in plain-text files with the filename extension .tr3. These files are used by the Tr3 programme to create VRML and finite-element models.

A .tr3 file may contain the following sections:

Section END?* Notes
Comments No Any line starting with a semicolon is interpreted as a comment. Only the comments at the beginning of the file, before the first non-comment line, are preserved when Fie (or Tr3) saves a new version of the file. Whenever Fie (or Tr3) saves a revised version of the file, the user is asked for initials and a comment, which are added (with the current date) to the end of the initial comments.
LINES Yes See Lines
SCALE No See Scaling
XY_CALC No See Scaling
Z_CALC No See Scaling
SLICES Yes See Slices
JOINS Yes See Joins
CAPS Yes See Caps
SUBSETS Yes See Subsets
EXTERNAL Yes See External files
VOLUMES Yes See Volumes
MATERIALS Yes See Material properties
SPRINGS Yes See Springs
CONC_LOADS Yes See Concentrated loads
LABELS Yes See Labels
VIEWPOINTS Yes See Viewpoints
DATA Yes The actual x and y coördinates of lines are stored in this section.
IMAGES Yes Definitions of images sets. Seldom if ever used.
MARKED_VOXELS Yes Records marked voxels.
COSTS Yes Used by Tr3 to record cost functions chosen by user for triangulation. Normally not directly modified by the user.
GLOBAL_RANGES   Obsolete
MERGES   Obsolete

*Whether section must be terminated by an END record.

In the syntax specifications here, square brackets ([ ]) denote optional elements and { | } denotes alternative values. Roman (upright) characters denote actual strings to be used, while italic (slanted) characters denote values to be chosen by the user.

5.2 Lines

Within the LINES section of a .tr3 file, the syntax for a line definition is:

name: [qualifiers] descriptive_text

The possible qualifiers are:

-openclosed { OPEN | CLOSED }
-on  
-off  
-reverse  
-do_slices { ALL | FIRST | LAST | BOTH | ([zmin][,zmax]]) }
-colour ecolour[;rcolour]
-transparency transp
-boundary_condition {F | C[{S|F|B|N}[{F|L|B}]]}
-pressure press
-material itype
-thickness thick
-mtt itype thick [deprecated]
-m itype thick [deprecated]
-xyresolution ires_xy
-zresolution ires_z
-resolution ires_xy ires_z [deprecated]
-linetype { STRAIGHT | BEZIER | ELLIPTICAL | TUBING }
-start [([[=]zmin][, [=]zmax])] {START|FINISH|NEAREST} line_name
-finish [([[=]zmin][, [=]zmax])] {START|FINISH|NEAREST} line_name
-url URL

The attributes are discussed in more detail below. All qualifier names may be abbreviated to any unambiguous degree. In fact, they can all be abbreviated to a single character except -openclosed, -on and -off, which require at least two characters.

5.2.1 Basic attributes

5.2.2 Model-creation attributes

5.2.3 Visualization-related attributes

5.2.4 Simulation-related attributes

5.2.5 Examples

incus1: -op CL -c yellow;bone -r 100 1 -m 1 .04 ;Incus top
Example incus1 demonstrates a closed line which will be shown as yellow in Fie and rendered as bone coloured in the 3-D models; which is to be triangulated using every slice at 100 elements/diameter; and which consists of material type 1 with a thickness of 0.04.

tm_inf: -op OP -c green;white -t .5 -r 50 2 -m 4 .001 -s f annlig -f s manub ;TM
Example tm_inf demonstrates an open line which will be shown as green in Fie, but in the VRML model as translucent white with a transparency of 0.5; it is to be triangulated using only every second slice at 50 elements/diameter; it consists of material type 4 with a thickness of 0.001; and it starts at the finish of line annlig and finishes at the start of line manub.

5.3 Slices

The first line of the SLICES section may be of the form

IMAGE_PATH path

path can be used to specify where to find the image files if they are not in the same directory as the .tr3 file. It will be prefixed to the image names before the path of the .tr3 file is prefixed, so it will specify a path relative to the path of the .tr3 file. (Neither the image-path name nor the path of the .tr3 file will be used if the image name itself contains a path specification.) The image-path name should not include leading or trailing path delimiters; it will be system independent if it does not include any path delimiters, i.e., it specifies only a single directory name. This path is used only when there is a separate image file for each slice. The usual method is to put all of the image files into a subdirectory of the directory where the .tr3 file is, and then give the subdirectory name as the path.

The rest of the SLICES section consists of records of the form

i, name, [z, [rotate, offsetx, offsety]]

There should be one record for each image (slice). i is the slice sequence number. name is a descriptive name for the slice (or an actual file name when the slices are stored as separate files). z is the z coördinate for the slice. rotate, offsetx and offsety optionally specify the offset and orientation required to align the image with the rest of the stack (usually for histological images).

5.4 Joins

As a structure subdivides from slice to slice, or becomes connected to other structures, multiple line names must be used for the same structure. The Join mechanism is provided to specify how triangulation should be done across such changes of line name. The syntax for Joins allows concatenation of multiple lines; forward or backward traversal of lines; and incorporation of only the first or last point of a line. The syntax permits transitions between Closed and Open lines. Joins can either inherit properties from the lines which constitute them, or take on new properties.

Within the JOINS section of a .tr3 file, the syntax for a Join definition is:

name: [qualifiers] [-]i1[{>|<}] [-]i2[{>|<}] … to [-]j1[{>|<}] [-]j2[{>|<}] … [;description]

i1, i2, etc., are the names of the lines to be concatenated in order to form multiline 1. j1, j2, etc., are the names of the lines to be concatenated in order to form multiline 2. A surface is triangulated between multiline 1 and multiline 2.

A minus sign (-) before a line name means that that line is to be traversed backwards when being concatenated to its multiline.

The symbol > after a line name means that only the first node of that line is used. The symbol < after a line name means that only the last node of that line is used.

The following attributes (qualifiers) can be defined for Joins. Their meanings are the same as for line attributes.

Attributes which are not explicitly specified for the Join are inherited from the first component of its multiline 1.

Example. If you had a structure defined by two open lines, bone_ant_50 and bone_post_50, from slices 50 to 79, and then at slice 80 they combined into a single closed line, bone_80, you could define the join between them as

bone_50: bone_ant_50 bone_post_50 to bone_80 ;Bone

If you wanted to specify a distinctive colour for the triangles corresponding to the join, you could use, for example,

bone_50: -c red bone_ant_50 bone_post_50 to bone_80 ;Bone

5.5 Caps

Within the CAPS section of a .tr3 file, the syntax for a Cap definition is:

name: {HEAD|TAIL} [qualifiers] [-]i1[{>|<}] [-]i2[{>|<}] … [;description]

HEAD means that the cap is to created at the first slice for which all of the component lines are present. TAIL means that the cap is to created at the last slice for which all of the component lines are present.

i1, i2, etc., are the names of the lines to be concatenated in order to form the cap. A flat surface is triangulated within the resulting multiline.

A minus sign (-) before a line name means that that line is to be traversed backwards when being concatenated to the multiline.

The symbol > after a line name means that only the first node of that line is used. The symbol < after a line name means that only the last node of that line is used.

The following attributes (qualifiers) can be defined for Caps. Their meanings are the same as for line attributes.

Attributes which are not explicitly specified for the Cap are inherited from the first component of its multiline.

Example. If you had a structure defined by two open lines, bone_ant_50 and bone_post_50, from slices 50 to 79, you could a define a cap at slice 50 as

bone: HEAD bone_ant_50 bone_post_50 ;Bone
or a cap at slice 79 as
bone: TAIL bone_ant_50 bone_post_50 ;Bone

5.6 Volumes

The syntax for the VOLUMES section of a .tr3 file is the following:

VOLUMES
volname1
[-]i1[{>|<}] [-]i2[{>|<}] …
[-]i1[{>|<}] [-]i2[{>|<}] …
End of volume
volname2
[-]i1[{>|<}] [-]i2[{>|<}] …
[-]i1[{>|<}] [-]i2[{>|<}] …
End of volume
End of volumes

i1, i2, etc., are the names of the lines to be concatenated in order to form a closed multiline. These closed multilines should be specified in the order in which they are encountered in processing from the first slice to the last.

The syntax for specifying a multiline is the same as for Joins and Caps. A minus sign (-) before a line name means that that line is to be traversed backwards when being concatenated to the multiline. The symbol > after a line name means that only the first node of that line is used; the symbol < after a line name means that only the last node of that line is used.

The purpose of this section is to produce surface model definitions suitable for use by volume-mesh generators. This section has essentially been superseded by the use of the Volume qualifier for subsets.

5.7 Subsets

The syntax of the SUBSETS section of a .tr3 file is the following:

SUBSETS
subsetname1 [VOLUME] [MIRROR]
subsetrecord1a
subsetrecord1b
End of subset
subsetname2 [VOLUME] [MIRROR]
subsetrecord2a
subsetrecord2b
End of subset
End of subsets

The optional VOLUME qualifier is intended to result in the output of the model in file formats for use by volume-mesh generators. (Currently no such formats are output because a separate application, sap2gmsh, is used to convert .sap files to Gmsh format.) This qualifier should be used only for a subset which defines a single, simple closed surface.

The optional MIRROR qualifier causes the model to be flipped to become a mirror image: the z coördinates are all multiplied by –1 and the node numbering is reversed in each triangle.

The syntax for each subset record is one of the following:

linename: [qualifiers] descriptive_text
(cap) capname: [qualifiers] descriptive_text
(join) joinname: [qualifiers] descriptive_text
(label) labelname: { -on | -off }
(spring) springname: { -on | -off }
(concload) loadname: { -on | -off }
(vol) volname: { -on | -off }
(clip) { xmin val | xmax val | xrange val1 val2 | ymin val | ymax val | yrange val1 val2 | zmin val | zmax val | zrange val1 val2 }
(rot) θx θy θz
(tran) tx ty tz
@[-]subsetname
SUBSETS
SUBSET Bone
*: -off
bone*: -on -c red
(join) bone1: -off
(join) bone2: -on
End of subset
End of subsets

Each line, cap and join name field can contain any number of the wildcard characters * and ?. The * matches any number of characters, including zero characters, and the ? matches exactly one character. For example, inc?_*med_* would match incA_antmed_050, incB_postmed_100, etc. This works best if lines are named systematically.

Any of the line, cap and join attributes which are specified here will over-ride those specified in the original line, cap and join definitions. In the case of -reverse used for caps and joins in a subset definition, it will cause the current setting to be flipped.

The (label), (spring), (concload) and (vol) lines are used to turn specified labels, springs, concentrated loads and volumes on or off.

The (clip) line is used to exclude ranges of x and y, or slices based on their z values, from the 3-D model. For example, (clip) zmin 5. would cause all slices with z less than 5. to be dropped; (clip) zmax 10. would cause all slices with z greater than 10. to be dropped; and (clip) zrange 5. 10. would result in keeping only slices with 5. ≤ z ≤ 10.

The (rot) and (tran) lines are used to apply specified rotations and translations to the overall model.

The @ line is used to include another subset within this subset. Subsets can be nested to any depth; that is, the included subset can itself include other subsets. The optional - (minus sign) can be used to reverse the numbering of all of the triangles in the included subset.

The usual practice is to begin each subset definition with *: -off (i.e., turn off all lines) and then turn on the desired lines, turn caps and joins on or off as required, etc. When some other subset is included using an @ line, the *: -off line of the included subset is ignored (to avoid turning off the lines that have already been turned on in the subset requesting the inclusion).

As an example, the SUBSET definition shown on the right would suppress all lines and then reactivate (and turn red) all those whose names start with ‘bone’. It would also turn off Join bone1 and replace it with join bone2 (which presumably would initially have been defined with -off.

5.8 Material properties

Within the MATERIALS section of a .tr3 file, the syntax for a record is:

nmat ym pr den descriptive_text

nmat is a sequence number for the material type, normally starting at 1 and incremented for each material type. ym is the Young's modulus, pr is Poisson's ratio, and den is the mass density of the material. The value of Young's modulus may be expressed with a metric suffix (with no space); for example, 2G or 2.G for 2 GPa, or 1.5M for 1.5 MPa.

Everything after the density value is taken as descriptive text.

If no material properties are defined, then no .sap finite-element model will be generated by Tr3.

5.9 Springs

Within the SPRINGS section of a .tr3 file, the syntax for a record is:

{D|R} stiffness node0 node1 [node2 [node3 [node4]]]

If the first item in the spring definition is D then the spring is a translational one (e.g., N/m); if it's an R then the spring is a rotational one (e.g., N/rad). stiffness is the actual stiffness of the spring. The rest of the record defines from 2 to 5 nodes.

Each node is defined by a line name, an optional z value, and an optional fraction f from 0 to 1:

line[([z][,f])]
If z is undefined, it is taken to be the z of the first slice in which the line appears. The fraction f represents a fractional arc length along the line, from 0 at the start to 1 at the end. If f is undefined, it is taken to be 0.

The spring will be attached to the model at node 0. The direction of the spring is determined by the position(s) of the other nodes, as described in the following table. The notation Vmn indicates a vector from node m to node n.

No. other nodes Direction of spring
1 parallel to V01
2 parallel to V12
3 perpendicular to the plane formed by V12 and V13
4 perpendicular to the plane formed by V12 and V34

Note that the length of the spring doesn’t matter.

5.10 Concentrated loads

Within the CONC_LOADS section of a .tr3 file, the syntax for a record is:

{F|M} load node0 node1 [node2 [node3 [node4]]]

If the first item in the concentrated-load definition is F then the load is a force (e.g., N); if it's M then the load is a moment (torque, e.g., N m). load is the actual value of the load.

The nodes are defined in the same way as for springs. The load will be applied to the model at node 0 and the direction of the load is determined in the same way as for springs.

5.11 Labels

Within the LABELS section of a .tr3 file, the syntax for a record is:

label_text [-size size] [-colour colour] [-family family] node0 [node1]

label_text is the text that will be displayed as the label. If the text contains any space characters, it should be enclosed in double quotation marks, e.g., "Label 1".

size is the font size used for the label, measured in the same units as the model. If unspecified, the default value is 1. If the specified size is negative, no text will be displayed and the label may be interpreted as a pin head.

colour is the colour used for the text of the label, specified by name. If unspecified, the default value depends on the browser. The colour names available are the same as those offered by menu as line, join and cap colours.

family specifies the font family to be used for the label. It can specify the name of any font on the user's computer, but the only values guaranteed to work are the generic values SERIF, SANS and TYPEWRITER. If unspecified, the default value is SERIF.

The label (in particular, at least in some viewers, the lower left corner of the first character of the label's text) will be located at node 0, and the label will be attached to the model by a line running to node 1, if defined.

If the font size is negative then the label itself will not appear. It may be rendered as a pin head in some viewers.

5.12 Viewpoints

Within the VIEWPOINTS section of a .tr3 file, the syntax for a record is one of the following:

name XYZ rotx roty rotz description
name AA posx posy posz axisx axisy axisz angle description
(reldist) relative_distance

The xyz option defines a viewpoint corresponding to what one sees in Fad after the specified x, y and z rotations (in that order). In other words, one can use the rotation angles displayed in Fad in order to re-create a view from the same direction. If one is starting from an orientation in Thrup’ny, one can use View ▶ Display current orientation to display the rotation angles, apply them in the order z, y and x in Fad using the interactive rotation tool, and then use the angles displayed by Fad.

The aa option defines a viewpoint using the same method used by VRML itself. The required parameters can be determined by requesting Tr3 to include code in the VRML file which causes the current position (posx posy posz) and orientation (axisx axisy axisz angle) of the viewpoint to be continuously displayed. (This display doesn't work in Thrup’ny.)

Whether or not any viewpoints are defined in the .tr3 file, six standard viewpoints are generated, in both directions along each of the x, y and z axes.

A (reldist) line defines the relative distance from the centre of the model to any xyz-type viewpoint and to the six standard viewpoints along the axes. The actual distance is the relative distance multiplied by an estimate of the size of the model. The default value for the relative distance is 2.

5.13 Scaling

5.13.1 Introduction to scaling in Fie

Fie needs to handle two different ways of thinking about x, y and z coördinates. On the one hand, line nodes need to be positioned with respect to pixel positions (columns and rows) within images and with respect to slice numbers within a stack of images. On the other hand, the x, y and z coördinates of the final model normally need to be expressed in real-world coördinates, e.g., millimetres.

There are two ways to manage Fie's scaling between the real-world x, y and z coördinates of a model and the row, column and slice positions:

  1. store x, y and z coördinates internally as real-world coördinates and use XY_CALC and Z_CALC parameters to map the real-world coördinates to pixel positions and slice numbers when displaying lines; or
  2. store x and y coördinates internally in units of pixels, and z coördinates as multiples of the pixel size, and use SCALE parameters to convert to real-world coördinates when creating the final triangulated models.
If the x and y coördinates are not expressed in the same units as the z coördinates, then the side views of the traced contours will not be scaled properly.

5.13.2 XY_CALC and Z_CALC

5.13.2.1 XY_CALC
XY_CALC
[-u unitux [uy [ox [oy]]]

ux and uy are scaling parameters (in units/pixel). ox and oy are offsets (in pixels). These parameters are used by Fie to transform real-world x and y coördinates in the .tr3 file to match the images. The z coördinates of the slices are assumed to be given using the same real-world coördinates.

The directive XY_CALC is on one line and the parameter values are on the next line.

By default, ux and uy are 1., and ox and oy are 0., implying that the x and y coördinates in the .tr3 file, and presumably also the z coördinates, are measured in pixels. If the z coördinates were measured in, say, mm, then ux and uy would normally specify the pixel size in mm.

If uy is not specified, it is assumed to be the same as ux, i.e., the x and y units are assumed to be the same.

The -u parameter is an optional name for the units, e.g., -u m for metres, or -u um for micrometres.

Example. If you had images with a pixel size of 0.5 mm, then you might use the following:

XY_CALC
-u mm 0.5
5.13.2.2 Z_CALC
Z_CALC
z1 dz

z1 is the z coördinate for the first image of a stack of images, measured in the same units as used for x and y. dz indicates the nominal spacing between slices.

The directive Z_CALC is on one line and the parameter values are on the next line.

Note that these parameters are just used to guess an appropriate z coördinate for a slice which has not yet had a z coördinate assigned, and to assign slice numbers to contours read from an old .tr3 file which does not contain explicit slice-number/z-coördinate information.

5.13.2.3 Changing from pixels to units

If a .tr3 file currently uses pixels for its coördinates and you want to start using real-world coördinates, do the following:

5.13.3 SCALE

SCALE
sx [sy sz]

These scaling parameters are not actually used within Fie. Tr3 uses them to scale the x, y and z coördinates that it reads from the .tr3 file.

Normally only sx needs to be specified, and sy and sz will be taken to be the same as sx. By default, sx = 1.

The directive SCALE is on one line and the parameter values are on the next line.

One use for these parameters is to produce real-world coördinates in the VRML and SAP files produced by Tr3 when the coördinates in the .tr3 file are expressed in pixels.

Example. If you had images with a pixel size of 0.5 mm, then you might use the following:

SCALE
0.5

The SCALE parameters could also be used to convert from one set of units to another, say from mm in the .tr3 file to m in the VRML and SAP files.

6. Example

On the right is a partial screenshot that includes 3 of Fie's windows. Click on the screenshot for a larger version.

The main window shows part of slice 127 from magnetic-resonance microscopy dataset 516871 for a cat middle ear. The data are courtesy of Drs. O.W. Henson, Jr. and Miriam M. Henson (UNC) and the CIVM (Duke University). The image shown is a small part of the original MR image.

Below the main image window are x-z and z-y views showing a selected subset of the lines that have been created by the user. The lines shown in the side views correspond to parts of the eardrum, malleus, tensor tympani muscle and stapes.

Each line in the image is represented by a set of vertices. The first vertex of a line is represented by a rightward-pointing triangle; the last vertex is represented by a leftward-pointing triangle; and the others are represented by squares. The straight-line segments between the vertices of a line are relatively thick. When a line is specified as starting at, or finishing at, some other line, then that connection is drawn as a thin straight-line segment.

In the centre of the image are seen a part of the malleus bone (yellow) and the tensor tympani muscle (red) attached to it. Notice that the shared surface between the two is represented as a separate line. These lines could be defined as shown in the following table: mallmuscinf and mallmuscsup represent the inferior (lower) and superior (upper) lines defining the part of the malleus to which the muscle is attached, and ttymp represents the tensor tympani muscle. The lines mallmuscsup and ttymp are both defined as starting at the finish of mallmuscinf and finishing at the start of mallmuscinf. Note that the bone has a material type of 1 while the muscle has a material type of 2.

mallmuscinf: -op OP -c yellow;bone -xyr 100 -mat 1 Malleus
mallmuscsup: -op OP -c yellow;bone -xyr 100 -mat 1 -s f mallmuscinf -f s mallmuscinf Malleus
ttymp: -op OP -c red;muscle -xyr 100 -mat 2 -s f mallmuscinf -f s mallmuscinf Tensor tympani

7. Tutorial

This section is intended to lead a new user through a logical succession of tasks. It is assumed that you have already read at least the first few sections of the Introduction; the section on the User interface; and the introduction to the section on Draw. In addition, it is strongly suggested that, as you go through the tutorial, you follow the provided links to the detailed documentation.

For now, at least, this section focusses on working with stacks of images like X-ray CT scans, MR scans, serial-section histology or optical-sectioning microscopy.

7.1 General notes

7.2 Getting a dataset into Fie

7.2.1 Importing a stack of images into Fie

Fie’s favourite way of dealing with stacks of images is as collections of JPEG or PNG files. Every file in the collection must be of the same type (e.g., 8-bit grey-scale or 24-bit colour) and have the same number of pixels. The file names should follow the rules mentioned above (General notes) and each file name should end in the sequence number of the image, with leading zeroes if appropriate (e.g., 001, 002, …, 150).

For playing with, you can download 16885.zip. Unzip the files into some directory. There will be a directory 16885/ containing a 00readme.txt file and a jpg/ subdirectory containing 340 image files corresponding to the human-ear magnetic-resonance microscopy (MRM) dataset 16885 from the lab of Drs. O.W. Henson, Jr. and Miriam M. Henson. The 00readme.txt file contains the voxel size for the dataset.

To create a new .tr3 file for a set of images, start by clicking on File and then New and then Tr3 file. You will be asked whether you have a set of .jpg or .png files. If you click on No the operation will be cancelled. For this tutorial, click on Yes. You will now see a menu for browsing, and a message telling you to Specify first image file. Unless the file already appears in the menu, browse to find it. Once you have selected the first image in your series, you will be asked to Specify last image file. Browse and select the last image in your series. Fie will try to determine the number of digits in the sequence numbers incorporated in the file names, and will offer a chance to correct it. For the 16885 images, it will ask No. digits [3] ?; just accept the default value of 3. Fie will then display the sequence numbers of the first and last images and ask for the increment between images; the default value is 1, which you should just accept for the 16885 images.

You will next be asked for a file name for your new .tr3 file. A default path and file name will be offered based on where the images are located. It's advisable to keep the images in a separate subdirectory. For example, for the 16885 sample dataset, the default path and file name might be d:\Users\username\Henson\human\16885\jpg\16885_. You probably want to have the .tr3 file in the directory in which the jpg\ subdirectory is located, that is, in the 16885\ directory, not in the jpg\ directory itself. You probably also want to remove the underscore character (_) at the end of the default name. The final path and file name might be d:\Users\username\Henson\human\16885\16885, corresponding to a file name of 16885.tr3. You don't need to specify the .tr3.

Next you will be asked for the z value for the first slice (or image). Usually this would correspond to the slice thickness. For the sample dataset the slice thickness is 78.125 μm, so you would specify 78.125 here. The next two questions ask for the z spacing between slices and the x-y pixel size; for the sample dataset you would specify 78.125 for both. The next question asks for the units being used for the sizes; for the sample dataset you would specify um (for μm). The following three questions ask for x, y and z scale factors; normally you should accept the default values of 1. Finally, you will be asked for your initials and for an optional comment.

Now you need to open your new .tr3 file by following the instructions below.

7.2.2 Working with an existing .tr3 file

This section assumes that you already have a .tr3 file and the corresponding stack of images. Look at the previous section if that's not the case.

If your images are in either JPEG or PNG format, you need to tell Fie to open the .tr3 file. If the images are in the form of a TIFF or raw stack, you need to tell Fie to open the stack file.

Start by clicking on File and then Open. The first time you work with a dataset in Fie, you need to browse to find it. Click on the + Other menu button. The first button in the next menu will be A <other> and will display what Fie considers to be the current directory. You can navigate from there by using the B <up> button or by clicking on one of the buttons indicating a subdirectory. (Each button in a file-selection menu contains, after its shortcut key, either d for directory or f for file.) Use the buttons at the bottom of the menu to scroll up and down as required.

If you want to go directly to some other directory (or don't recognize what directory you're in) click on the A <other> button. You will then be asked to type in the name of a directory, e.g., /home or C:\users. You can then start browsing from there.

Once you're looking at the right directory, click on the button corresponding to the desired .tr3, .tif or .raw file.

Next time you run Fie, the most recently opened file will be at the top of a list of all of your previously opened files, so you don't need to browse for it again.

Once you have opened a .tr3 file, most of the time you will want to go into Draw mode. Click on Draw in the main Fie menu.

7.3 Browsing among images

Many Fie menus include a common set of four buttons, for zooming, panning, moving among images and adjusting various settings. Note the easy-to-remember shortcut keys, which correspond to four keys in the upper left corner of many keyboards. The exclamation point is for how much zoom! you want; the at sign is for where you want to be at; the number sign is for which image number you want; and the dollar sign is for $ettings. See the detailed descriptions in the Menus documentation.

When you open a .tr3 file for the first time, you will see some or all of the first image in the stack, at 100% scaling. To look at the other images, click on the # New image. Use the 7-button navigation menu to move back and forth in the stack.

If the images are large, then at 100% scaling you may see only part of the image; you can zoom out to see more of the image. If the images are quite small, they may take up only a small area of the screen; you can zoom in to make them bigger or to focus on a small area. To zoom in or out, use the ! Zoom button. If you are viewing less than the whole image, the Overview window will show you which part you are viewing.

If you are looking at only part of an image (because you have zoomed in) you can choose which part to look at by using the @ Pan button.

The next time you use Fie to look at the same dataset, it will start at the image that you were looking at last time, and with the same zoom and pan settings.

7.4 Adding a line

Region to add line for

If you have not already done so, click on Draw in the main Fie menu. In the 16885 dataset, go to slice 213 and find the dark region below and to the left of the centre of the image, as shown at the right. Click on Add line. If lines already exist in this .tr3 file, a list of them will appear as a menu, with A (new) at the top of the list. If no lines exist yet, only the A (new) button will appear. Click on it and then on /OK.

When the menu for specifying line attributes appears, click on Name =. A prompt will appear near the bottom of the window, asking for the name of the new line to be added. It is best to name lines systematically. For this exercise, name the line test1_213 (because the line appears first in slice 213).

For this exercise you should use the Open/Closed button to change the line from open to closed.

The X-Y mesh resolution can be left at its default value of zero for now. It will be considered later in the part of the tutorial dealing with finite-element simulation.

Click on /OK to continue. Later you can change these attributes, or set other attributes, by doing Edit other ► Attributes ► Edit line attributes ► 1 line .

There are three different methods available for adding the points that define a line: manual, autotrace and flood. The manual method is the most straightforward but also the most tedious. The autotrace and flood methods can greatly speed things up – when they're successful. They work best for structures with good contrast.

7.4.1 Manual method

Manually added line

To add points to a new line manually, simply left-click in the image window. The prompt near the bottom of the screen will show the number of the point to be added next. At any time the last point in the line can be deleted using the Delete last pt button.

By convention, objects should be outlined counterclockwise and holes should be outlined clockwise.

The image on the right shows a typical manually added line.

7.4.2 Autotrace

Autotraced line

The Autotrace function will attempt to trace a boundary automatically. It will use the current last point as its starting point; if no points have been added yet it will ask for a starting point. It will ask you to point to a point that lies in the direction in which it should go. It will then attempt to trace a boundary that has properties similar to the boundary defined by the two points that it has been given to start with. It will continue tracing until it hits the edge of the visible image or until it runs into itself. Often it will trace successfully for a while and then go off course. In that case the Trim tail function can be used to delete all of the points following a point that you specify. You can then add some points manually and perhaps try autotracing again.

The image on the right shows the result of autotracing this region with one manually selected starting point and selection of the direction in which to start. In this particular case it worked well, with no trimming or other fiddling required.

7.4.3 Flood

Result of flood fill

The Flood function traces a line around a closed region based on a range of pixel intensities. This method cannot be combined with the manual and autotrace methods. Adjust the thresholds in case the line isn't quite right (or is terribly wrong). Click on Quit when the line is satisfactory (or as satisfactory as it's going to get). If the line is mostly acceptable but part is not, the Cut function can be used to remove that part by pointing to each end of it.

The image on the right shows the result of flood-filling this region.

7.4.4 Doing multiple images

Go to slice 214, do Add and select test1_213 from the list of lines, and then trace the outline of the same structure. You're using the same line name, test1_213, because Tr3's default action is to create a triangulated surface for a line that appears with the same name in multiple slices.

The thin orange line that you see in edit-lines mode represents the contour that you segmented in slice 213. If you go back to slice 213, you'll see a thin magenta line representing the contour segmented in slice 214. You can change the colours that are used for displaying the lines in the previous and next slices.

When a line has been satisfactorily traced in one image, it is often useful to immediately use the # New image button to advance to another image, rather than doing Quit. This way a line can be added to multiple slices without having to specify the line name each time. The flood method works particularly effectively this way because it automatically attempts to use the same location and intensity range for the next slice.

Often you will not need to segment structures in every slice. If, for example, every fifth slice is enough to provide the desired amount of detail, then it is convenient to set the ‘big step’ setting to 5 and then use the >> to move from slice to slice.

When a line is segmented in multiple slices, the starting points should be consistently positioned from slice to slice, because when Tr3 creates triangles between slices it always starts by connecting the starting points. If you always use flood fill, the starting points will generally be well aligned automatically. If you use manual tracing or autotracing, you need to make sure that you position the starting points consistently. If the starting points are not well aligned, the triangulation produced by Tr3 will be of poor quality. The starting points can be changed later using Edit lines ► Lines ... ► Change start pt.

For the purposes of this tutorial, once you've segmented the structure in two slices you're ready to save your work and create a model.

7.5 Saving your work

As soon as you have done any work that is worth saving, go to the main Fie menu and do File ► Save ► Tr3. Each time you save, you will be asked to type in a comment about what you've done. Entering a few words here may help in recovering from problems later. The first time you save, you will also be asked to type in your initials, which will be saved along with your comments. .tr3 file, Fie will create a numbered backup version.

7.6 Creating and viewing a 3-D model

To create a 3-D surface model from the line(s) that you have created in two or more slices, save your work in Fie and then use the Tr3 programme. You do not need to exit from Fie before running Tr3. Initially you can ignore all of the options that Tr3 offers, and don't worry about the message saying No real elements, no .sap file created.

Once Tr3 has created a .wrl (VRML) file for your model, use the Thrup’ny programme to view the file. If you have used the default settings in Tr3, the file name of the .wrl file will include _dbg (for ‘debug’ mode) and the labels that Thrup’ny displays in pointing mode will be the line, join and cap names that were used in Fie.

In the rest of the tutorial, whenever you try something new you should save your work, run Tr3, and use Thrup'ny to see the results of what you've done.

7.7 Editing a line

7.7.1 Manual editing

Once a line has been added, it can be manually edited by clicking on Edit lines.

Note that the Undo facility is extremely primitive. It can only be used to undo the positioning of a single point, and only if undone immediately. The best protection against errors is to save frequently.

7.7.2 Cleaning up

The Autotrace and Flood methods often produce excessive numbers of points and very jagged lines. The Median filter and Smooth functions can be used to clean things up somewhat. The more powerful Snake function can also be used for this (see Fitting a line below).

When using the Manual method, it is sometimes useful to manually specify only a small number of points and then use the Smooth or Resample function to interpolate additional points.

7.8 Fitting a line

An existing line can also be refined using the semi-automatic line-fitting functions. The snake method is especially useful. There are several ways of taking advantage of it:

Invoke the snake method by doing Edit lines then Line ... then Fit line using snake. Choose the line to be fitted from the menu that appears. A menu then appears that offers a number of settings that can be adjusted. See the detailed documentation for how to use the various adjustments.

The actual fitting is done by using the the Slither ahead button. If the results of that slithering are bad, use either Undo & slither again or Restore original line to back up and try again.

If the snake algorithm is having trouble getting part of the line to fit the desired boundary, then Manual adjustment can be used to help it along. The functions are similar to those for manually editing lines.

Once you are satisfied with the fit, or have given up, click on Quit. In the menu that then appears, you can choose to keep the results of the fitting and go directly to another slice. This allows efficient fitting of the same line in a number of slices after having added it using, say, the flood method. If the line that you were fitting does not already appear in the new slice, the line will be pasted into the new slice, ready for fitting. This allows efficient addition of a line to a number of slices without having to do an explicit Add line for each slice. Whether it's better to do a series of floods followed by a series of snakes, or just do a series of snakes, depends on the nature of the data and on personal preference.

When fitting an open (as opposed to closed) line in a sequence of images, it is often useful to do a manual adjustment of the first and last points before slithering in each new image. When you click on Manual adjustment the first point in the line will be the active point. You can reposition it by right-clicking, then use Previous point to move to the last point in the line and reposition it. Then click on Quit and try slithering.

7.9 Adding a cap

When a closed line is triangulated in Tr3, a hole will be left at the first slice and at the last slice. To close the hole you can use a cap. Add a cap in slice 213 for the line that you have added in slices 213 and 214.

To add a cap, do Edit other ► Edit caps and select A (new). In the menu that pops up, click on E (undefined line). In the next menu that pops up, click on 2 (undefined line) then select the line that you want to cap, either by clicking on it in the image window or by selecting it from the list of lines that appears. Click on /OK. The top-most menu will now display the name of the selected line where it used to say ‘(undefined line)’. Select Quit.

By default the cap will be put at the ‘head’ of the structure, that is, at the first slice in which the line appears. You can put the cap at the last slice in which the line appears by selecting A (edit attributes) ► Z = Head and then selecting Tail.

Notice the message at the bottom of the window that says Cap (unnamed). The cap must be given a name for it to become active. Select Name = and type in a name. If you just type @ a name will be assigned automatically, which is usually the best option. This should be done after specifying whether the cap will be at the head or tail because the automatic name will include either ‘_head’ or ‘_tail’.

Caps (and also joins) inherit attributes from the lines that make them up so normally you don't need to specify their colours, material properties, etc.

7.10 Adding a join

Regions to create join for

By default, Tr3 generates triangles only between lines with the same name. If, for example, a structure is defined by a single line in some slices but by two lines in other slices, then the lines will need to have different names, and therefore Tr3 by default will not generate triangles to join them together. To tell Tr3 to do so, you must define a join between the last slice in which the structure has one configuration and the first slice in which it has a different configuration.

In the 16885 dataset, go to slice 215. The structure that you have segmented in slices 213 and 214 has almost split into two separate regions, as shown at the right.
Structure defined by 2 lines Structure defined by 1 lines

Add line test1_213 in slice 215 using Flood with a Fill level = 130 and Fill tolerance = 80. This should create a single line around the structure. (As often happens, it is difficult to decide on the exact slice at which a structure goes from being one region to two regions, or vice versa.) Smooth the line.

In slices 216 and 217, add lines test2a_216 and test2b_216 for the two separate regions. They should again be Closed lines.
Creation of a join, step 1

Position yourself to view slice 215 and then do Edit other ► Edit joins. Select A (new). You will see that lines from two different slices are displayed: those from slice 215 in dark green and those from slice 216 in dark magenta. The menu that pops up has three sections. The first section consists of buttons for edit attributes and delete join. The other two sections are separated by a dummy button labelled ---- to ----. Each of the two sections has a button (add new line) and a list of lines that initially just has one entry, labelled undefined line. There is also a button for specifying the z values of the slices involved in the join; to begin with you can ignore this.
Creation of a join, step 2

To define a line that's involved in the first part of the join (slice 215), select F (undefined line). In the menu that pops up, select 2 (undefined line) and then select the desired line (test1_213 in this case), either by clicking in the image or by selecting it from the list that appears. Similarly, to define a line that's involved in the second part of the join (slice 216), select J (undefined line) and specify the line. To define the second line that's involved in the second part of the join, select the (add new line) button after the ---- to ---- button and then specify the line. Because of the direction in which the lines are traversed, this example will work better if you specify line test2b_216 first and then line test2a_216. Note that the selected lines are now displayed in light green and light magenta, and with larger symbols, as in the image to the right.
Traversal of lines

If we leave the join definition as it is, then Tr3 will start at the first point of the first line in the first slice (displayed in green) and at the first point of the first line in the second slice (displayed in magenta), and in the slice with two lines (here it is the one displayed in magenta) Tr3 will continue from the last point of the first line to the first point of the second line. This is illustrated by the dashed lines in the figure at the right. (In Fie the starting and ending points to be used by Tr3 for the join are indicated by right-pointing and left-pointing 3-pointed stars.)

In general, and in the example shown here, these different starting points will not work well together and something needs to be changed. This could be done by using Edit lines ► Line … ► Change start pt to change the lines' actual starting points. However, this will often have undesirable effects elsewhere. A better way is to modify the join definition itself, which is what we'll do here.

In our example, we'll use the starting point of the line in the first slice as it is but make changes in the second slice. First, select the first line in the second part of the join menu (i.e., the button that says test2b_216) and then select button 3, which initially displays the value 0. You are now prompted to specify the desired Start position for this line. Usually this is done by clicking on a point in the image and using the Select button. The next step is to specify the End position for the line by selecting the button 4. You can again explicitly select a point. However, if you want Tr3 to trace all the way around the line and back to where it started, which is what is needed here, select the Wrap button. (If you specify the same point as where you started, it will just stop there and not trace around the curve at all. Using Wrap will specify a position just slightly before the first point, causing it to trace all the way around.) The buttons 3 and 4 now display values between 0 and 1 that correspond to fractions of the distance from the start of the line to the end of the line, unless Wrap is used for the end position. When Wrap is used, a value of −1 will be displayed as a flag. Creation of a join, step 2

After performing the same operation for the second line in the second slice of our example, the result is as shown in the image at the right. Note the display (for the magenta lines) of the newly defined starting and ending points by superimposed left-pointing and right-pointing 3-pointed stars.

The join is not quite finished; if you generate a model now, you'll see a triangular gap in the surface. In order to close the loop in the second slice, it is necessary to jump from the end of the second line back to the start of the first line. Use the (add new line) button and add the first line again. Then select its menu entry and use buttons 3 and 4 to set both the start and end positions of this third instance of the line to the start position of the first instance of the line, by selecting the point highlighted by 3-pointed stars. Join definition

The complete join definition should look something like the one at the right.

Similar to what you saw for your caps, there is a message at the bottom of the window that says Join (unnamed). The join must be given a name for it to become active. Select Name = and type in a name. If you just type @ a name will be assigned automatically, which is usually the best option. The automatic name will be the name of the first line in the second part of the join.
3-D join

The final join should look something like the image at the right. (You can click on the image to view the VRML file.)

To make it easier to debug problems with joins, you can use the (edit attributes) button in the join menu to specify a distinctive colour in which the join will appear in the 3-D model created by Tr3. When you want to set the colour back to its default value, select Unspecify attributes in that menu.

Important things to remember about joins:

To reiterate why joins are necessary: if in one slice a line corresponds to something different from what it corresponds to in another slice, then it should be given different names in the two slices, and a join should be created. For example, if a line corresponds to one branch of a branching structure in one slice and to the combined branches in another slice, as in the example above, then different line names should be used. Or if a line corresponds to all of a structure in one slice but only part of the structure in another slice, then different line names should be used. The lines should be named systematically.

7.11 Creating a finite-element model

This section is important if you want to learn how to run finite-element simulations with a model. Parts of it are also useful if you want to learn how to prepare a model for 3-D printing. Otherwise just skip this section. (For the purposes of 3-D printing, you can ignore the stuff about material properties, mesh resolution, thickness, boundary conditions and pressure; and in the Using Fad with Gmsh section you don't need to run Gmsh, nor to run Fad the second time.)

Starting from the lines created above, add the line test1_213 in two earlier slices (211 and 212) and add the lines test2a_216 and test2b_216 in two following slices (217 and 218). Line test1_213 should be renamed to test1_211 to continue following the recommended naming conventions; this can be done using Draw ► Edit other ► Edit attributes ► Edit line attributes.

Make sure you have a head cap (but not a tail cap) for test1_211 and tail caps (but not head caps) for test2a_216 and test2b_216.

Add material properties by doing Edit other ► Edit materials. Select (new) and use the menu to specify the desired properties (e.g., Young's modulus = 20.M, Poisson's ratio = 0.3, mass density = 1000.) and a descriptive text. (The units are not specified but will be assumed by the finite-element solver to be consistent. If your mesh coordinates are specified in mm or μm, for example, the units for other quantities must be adjusted accordingly.)

Edit the attributes for the three lines, setting the x-y mesh resolution to 25; the Material type to 1 (the one that you just defined); and the Thickness to 1 (which is an arbitrary value that will not be used. You may need to specify a higher x-y mesh resolution if you have segmented more than just the test lines. PostView output

Edit the attributes of cap test2a_216_tail, setting the Boundary condition to Clamped.

Edit the attributes of cap test2b_216_tail, setting the Pressure to 1 (another arbitrary and unused value).

Save the .tr3 file and run Tr3, generating a model for a subset containing just the test lines. If you've specified the material type and thickness, you should get both a .wrl file and a .sap file. Follow the instructions at Installation to install the Fad programme and then follow the instructions at Using Fad with Gmsh, reading the .sap file and checking it for correctness. At the end, export an FEBio file from Fad. (Just type Enter in response to the question about rigid elements.) Specify a pressure of 100k when asked.)

Run FEBio on the .feb file exported from Fad. The ultimate output in PostView should be something like the figure at the right.

7.12 Splitting to create open lines

Line to be split

In the next few sections you will see how to use open lines to create a shared surface between two structures.

Histological image
showing incus and ligament Between slices 250 and 261, the incus (one of the three small bones in the middle ear) is connected to the posterior incudal ligament, which is connected in turn to the wall of the middle-ear air cavity. The histological image on the left shows these structures more clearly. The ligament is barely distinguishable from bone in the MRM images.

The ligament actually extends from slice 249 to about slice 264. We shall concentrate here on slices 254 to 261 for simplicity.

Go to slice 254 and find the part of the image shown at the right. Create a closed line with the starting point at the position shown in the figure. (In a case like this, no automatic method is going to work so you'll have to segment manually.) Call the line osinc_254, based on ‘os’ for bone, ‘inc’ for incus and slice number 254. Create a similar line with the same name in slice 261 and in however many lines you feel like in between.
Line to be split

To permit the creation of an explicit shared surface between the bone and the ligament, you can now split the single closed line osinc_254 into three open lines. This needs to be done in two steps.

Step 1: Do Edit lines ► Line ► Split line. Select osinc_254 as the line to be split into 2 parts. For part 1, click on (new) and create a new line called osinc_med_254 (the medial side of the incus). Use Copy attributes from another line to copy the attributes of osinc_254, then change Open/Closed from closed to open. Click on OK. For part 2, create another new open line called osinc_lat_254 (for the lateral side of the incus). In the next menu select All slices. You will now be presented one by one with the slices in which osinc_254 occurs. In each slice, select the point on osinc_254 where the ligament surface meets the bone on the left and select Point to part 1.

Step 2: Use Split line again to split osinc_lat_254 into osinc_pil_254 (new) and osinc_lat_254 (existing). The result should look something like the figure on the right.

If you want to see what your model looks like so far, you may want to skip forward to the section on subsets before returning to the section below on connecting open lines.

7.13 Connecting open lines

Start-at/Finish-at

The three open lines created in the previous section need to be connected together in order to recover a closed boundary for the incus. This is done by using the start-at and finish-at features in Fie. For example, do Edit other ► Edit attributes ► Edit line attributes ► 1 line and select line osinc_pil_254. In the Attributes menu select Start-at and then select (new). A new menu item B will appear – click on it and a new menu will appear. Menu button 6 will contain the name of some default line – click on the button, select line osinc_med_254 and click on OK. The triangle at the start of line osinc_pil_254 will change shape and a thin line will appear connecting it to the finish of line osinc_med_254.

Similarly, specify that osinc_pil_254 should finish at the start of osinc_lat_254 and that osinc_lat_254 should finish at the start of osinc_med_254. The results should look something like the figure on the right.

Sometimes a line will need to start or finish on one line in some slices but on a different line in some other slices. This is controlled using the first four menu items, as described above.

7.14 Creating structures with a shared surface

Segmentation of ligament

We now want to add some open lines to represent the posterior incudal ligament and its connection to the cavity wall. In slice 254, the segmentation should look something like the figure at the right. The white lines correspond to the medial and lateral surfaces of the ligament and could be named ligpilmed_254 and ligpillat_254. Note that their orientations (top to bottom for the one on the left, right to left for the one on the right) are appropriate for a counterclockwise boundary for the ligament.

The lower beige line corresponds to the part of the wall of the air-filled middle-ear cavity where the posterior incudal ligament is attached, and could be named cav_pil_254. Note that its orientation (top right to bottom left) corresponds to a clockwise boundary for the cavity.

It is probably easiest to manually segment one line at a time from slice 254 to slice 261 using Draw ► Add line and stepping from slice to slice. Segment the lines in the same slices in which you segmented line osinc_254.

As above, the different open lines need to be connected together. In the figure on the right, the ligament lines are specified as starting and finishing at the starts and finishes of the incus and cavity-wall lines. One could equally well decide to have the cavity-wall line, for example, start and finish at the ends of the ligament lines.

7.15 Creating caps with open lines

Cap definition with open lines

If you want to create a 3-D model of the ligament, you need to create caps on both ends. In this case, each cap definition will consist of several lines. The figure on the right shows the definition for a cap for the ligament. Note that the lines corresponding to the incus and the cavity wall both have a minus sign in front of the line name. This is because they must be traversed backward when being used for the ligament boundary. The line corresponding to the incus would of course be traversed forward when creating a cap for the incus. A good practice is for the names of shared lines to include indications of both structures that they belong to, with the one that their direction corresponds to coming first. For example, the name osinc_pil_254 has the incus first and then the ligament, because its direction corresponds to its use in the incus. Line traversed backwards in cap definition

The figure on the left shows what the menu looks like when specifying line cav_pil_254, for example, as part of the cap. Menu item 1 contains a minus sign. Menu item 3 specifies that the traversal of the line should start at the finish, and menu item 4 specifies that the traversal should finish at the start.

7.16 Creating a 3-D model with a subset

Subset definition

If you want Tr3 to create a model that contains only certain lines, you can create a subset. Do Draw ► Edit other ► Subsets, select New, and give the new subset a name. In the menu that appears, select (add new line) to add a line to the subset definition and then enter the desired text. In the simplest case, such a line will consist of a line name, a colon and a space, and the text -on to specify that the line is to be included in the subset. If lines are named systematically, then wildcards can be used to make it easier to define subsets. The figure on the right shows what the subset definition would look like for the posterior incudal ligament.

In the subset definition you can also override line attributes like colour, transparency, etc., using the attribute syntax. For example, if you wish to generate a finite-element model, but material types and thicknesses have not been specified as attributes of the lines involved, they can be added in the subset definition, as shown in the figure on the right. For this ligament subset, when creating a finite-element model it is necessary to correct for the fact that the incus and cavity-wall lines are backward, as mentioned in the previous section. This can be done by adding -reverse (or just -rev) to the specifications for both osinc_pil_254 and cav_pil_254 in the subset definition.

To also change the colour and x-y mesh resolution for all of the lines in the subset, the following line could be added:
*: -c red -xyr 150

Once you have defined one or more subsets, PIL model when you run Tr3 it will display a list of the available subsets, and the name of the selected subset will be included in the names of the model files created by Tr3. The animation on the right shows the model produced by the pil subset above.

To do a finite-element simulation of a system that includes more than one structure, you can create a subset for each structure, process surface models to create a volume mesh for each structure, and then combine the volume meshes with Fad. Any shared surfaces among the structures will be fully connected in the combined model.

Caps and joins will only be generated by Tr3 for a subset if all of the lines they require are included in the subset definition. Sometimes a line is needed in one slice for a cap or a join, but simply adding that line to the subset definition would result in the unwanted creation of the corresponding surface in the model by Tr3. A solution is to use the do_slices line attribute to specify that the line is to be included in the subset only in the first or last slice in which it appears.

8. Tips and tricks

8.1 Creating a join for a hole

Lines involved in a hole

An example of a place that a join is required is when a hole appears in a structure.

The figure on the right shows the lines involved at the beginning of a hole in a structure, as displayed while defining a join. The green line and vector indicate a counterclockwise line with a deep indentation, before the hole has closed. The magenta lines and vectors represent lines in the next slice, after the hole has closed. The line forming the hole itself (item 2 in the figure) has been traced clockwise, while the line around the outside (items 1 and 3) has been traced counterclockwise. Join definition for a hole In the second part of the join (magenta), the outside line is traced about halfway around (segment 1), then a jump is made to the inside line, which is traced all the way around (segment 2), then a jump is made back to the outside line and it is traced to its end (segment 3). The figure on the left shows what the corresponding join definition might look like, with segments 1, 2 and 3 defined by items I, J and K. The details would be different, of course, if the starting points of the lines were in different locations.

8.2 Renaming a line in some slices

If you have already segmented a line with the same name (say body2_020) across multiple slices and then realize that you need to give the line different names in different slices, do the following. Position yourself at the slice in which the line body2_020 should start having a new name, and use the command Draw ► Edit lines ► Lines ► Rename line. When asked for the line to be renamed, select the line body2_020. When asked for the line having new name, select (new) from the menu and create a new line (similar to what you do when you add a new line). Remember the recommendation that each line name should include the slice number in which that line first appears. Then, in this case, select the menu item This slice and following slices.

If you want to change the name of a line in all the slices in which it appears, just use Edit other ► Edit attributes ► Edit line attributes to change its name attribute.

8.3 Unexpected lines

If you see a thin line with no points in slices where you don't expect it (or an unexpected surface in your model), reread the section on start-at specifications, particularly the part about lines having both -start and -finish specifications. You may need to specify a z range.

8.4 Creating smooth surfaces

Applying the line-smoothing operation (Smooth ► Line ► Spline fitting) to a manually traced or edited line can make the line nice and smooth in each slice, but it may make the resulting 3-D surface less smooth from slice to slice, because the smoothing is done independently in each slice. The Smooth ► Surface across slices operations can be used to produce smooth surfaces but are best used after the surface is already reasonably smooth, and the resulting lines should be carefully compared with the corresponding images to make sure that they still match.

8.5 Restoring an old version of a line

Suppose you have revised a line and then realize that you want to restore the line as it was in a previous version of your .tr3 file. The following is one way to do so.

  1. Open an appropriate old version of your .tr3 file in Fie. (You will need to make a copy of the file, with the extension .tr3, or temporarily rename it to remove the version number.) Do Draw ► Delete lines and delete all lines in all slices, except the line that you want to restore. Save the .tr3 file.
  2. Use your operating-system tools to rename the newly saved .tr3 file to something different, say lineToBeRestored.txt. Remove the version number from the name of the previous version, so it becomes the latest version again.
  3. Open lineToBeRestored.txt in a text editor. Delete everything up to and including the line that says DATA. Then delete the END line at the end of the DATA section and everything that follows. (That will include the MARKED_VOXELS and COSTS sections.) Save the file.
  4. Open the latest version of your .tr3 file in Fie. Use Edit line attributes to change the name of the line that you want to restore. Then use Edit lines ► Lines … ► Duplicate line to duplicate the line to be restored into a new line with the old line name. Save the .tr3 file.
  5. Open the latest .tr3 file in a text editor. It is preferable to use a text editor that saves the original version of the edited file; otherwise, make a copy of the file yourself before editing.) Go to the END line at the end of the DATA section. Insert the contents of lineToBeRestored.txt just before the END line. Save the .tr3 file.
  6. Open the latest .tr3 file in Fie. You should see both the old and new versions of the line that has been restored. You can give them different colours to facilitate comparison. Delete the unwanted version.

8.6 Side views

Mark voxels

By default, Fie displays side views that display lines that you have created. These side views are particularly useful for seeing the range of slices that a line appears in, and for checking the alignment of starting points. You can control which lines are displayed.

You can also have side views that display orthogonal cuts through the image stack. You can toggle between the two modes using Settings ► Sideview: lines or Images.

Another way of seeing images as side views is to use the Mark voxels feature.

8.7 Triangulation problems

If your triangulated surface looks strange, use Thrup’ny to identify which lines, joins or caps are causing the problems, and then use the Verify option in Tr3 to see what’s happening.

The Verify option can also be used to correct certain kinds of problems using the Toggle alignment of centres and Change cost function tools.

8.8 Dramatic changes

When the shape of a structure changes dramatically from one slice to the next and you can’t get a good triangulation, you may want to start a new line and then create a join. It may make sense to join only part of one line to the other line, and to then use a cap to complete the 3-D surface.

8.9 Too many nodes

If you get a message from Tr3 that there are too many nodes, you’ll have to reduce the number. The maximum number is very generous, so you really do have too many, especially for finite-element analysis.

The number of nodes can be reduced by smoothing using splines. Alternatively, if you’re using the snake fitting, you can specify the desired node spacing to be > 1.

8.10 Tubing

Pelvic arteries

Structures like blood vessels and nerves can often be conveniently modelled using the tubing line type. Typically the structure will be represented in each slice by just two points, defining the centre and the radius. Tubing-type lines are very easy to smooth across slices by using Smooth points across slices for the Start point (which defines the centre of the tube) and for Radius 1.


AudiLab AudiLab home page
R. Funnell
Last modified: 2018-11-29 17:33:04