Copyright © 1988-2025 Tecplot, Inc. All rights reserved worldwide. See the complete legal notice in the copyright section of this document.

Table of Contents

XDB Workflows for CFD

FieldView is able to import as well as write XDB files. An XDB file can be managed just like any other dataset in FieldView, and can be manipulated in the following ways:

  1. Datasets can be scaled, rotated, translated, mirrored or rotationally duplicated

  2. Multiple copies of a surface can be created; each surface can be independently transformed, scaled and/or rotated

  3. 2D plots can be created on surfaces; surfaces can be probed

  4. XDB datasets can be appended and Dataset Comparison can be used (please refer to the Working with XDBs Tutorial in the User’s Guide)

  5. Linked Surface sweeps and Merged Transient sweeps can be performed

  6. Geometric functions "X", "Y" and "Z", etc., are always present in the data so need not (cannot) be selected for export. Quantities "I", "J", and "K" (for Structured cases) are not available for export when creating XDB files because they are reserved names in FieldView. They can however be exported by creating formulas, for example myI="I", myJ="J", myK="K".

  7. New XDB extracts can be created from XDB datasets (useful for limiting time ranges for example)

Note that Vector components do not need to be individually saved when creating XDB files. If a vector quantity is saved, all components of the vector are available for scalar coloring and thresholding.

To see how this is relevant to your workflows, consider a normal postprocessing session, illustrated in Figure 1. Typically, you read in a dataset and create several postprocessing objects (surfaces and rakes) to compose a visual representation of your CFD dataset. Next, you may create various images and animations for later review. You may also interrogate some of these surfaces to calculate things such as forces, loads, moments and heat fluxes.

xdb workflow step 01
Figure 1. Typical Postprocessing Work Session

After creating the postprocessing objects from your initial postprocessing session, you write and later import the XDB dataset containing your postprocessing objects.

xdb workflow step 02
Figure 2. Postprocessing with XDB Files

As noted above, an XDB dataset can be manipulated in the same was as any dataset, allowing you to create new representations of your postprocessing objects, and conduct quantitative postprocessing as well. This approach is particularly well suited to working with transient datasets, outlined in Figure 3 below. We recommend that you run FieldView in batch mode to create the XDB file for the entire transient run. This can be done by first reading a time step, and running FieldView interactively to create your postprocessing objects of interest. Then, in batch, you can use your RESTARTS with either a SCRIPT or an FVX script to create the XDB file.

xdb workflow step 03
Figure 3. Transient XDB Postprocessing

Once your XDB is written, you can import your XDB file interactively, to postprocess your results further.

xdb workflow step 04
Figure 4. Overall XDB Workflow

In the above image, we illustrate the flexibility of this XDB workflow approach. It is possible to run FieldView in batch creating an XDB file (in this case, xdb #2). This file, from a previous batch session, can be read interactively, and compared with a different XDB file (xdb #1). From these comparisons, it is possible to create a third XDB dataset (xdb #3), based on a numerical difference of the first two, which can then be further postprocessed.

An XDB file is imported from the Data Input menu, as shown in Figure 5. An XDB file may be imported using either the direct or client-server modes. XDB files can not be imported using parallel servers unless read via PFPR Partitioned File Parallel Reader (PFPR) layout files. However XDB files tend to be small and can be efficiently read without the need for parallel. This menu is also where you can select Local Parallel or your own custom server configuration as explained in the Set up a Server Configuration File section in the Installation Guide.

xdb import dialogs
Figure 5. XDB Import

The XDB reader has been extended in FieldView 19 to support the new XDB format introduced with XDBLib 2.0 (only supported on Linux64). XDBLib 2.0 is FieldView’s solution for in situ post-processing. It’s a library that allows solvers with native in situ post-processing and the ones instrumented for in situ thanks to libsim which writes directly to XDB extracts, without having to write full 3D datasets. This is particularly interesting for large and transient simulations, for which full 3D mesh and results are too large and take too long to process. If you’re interested into getting access to the XDBLib 2.0 library or in getting help in instrumenting your solver for in situ post-processing, please contact Tecplot, Inc.

There are essentially four types of XDB files:

  1. Steady state, which is a snapshot of all surfaces and rakes

  2. Surface sweep, containing a sweep of a coordinate, computational or iso-surface (and possibly other surfaces)

  3. Transient sweep, which is a sweep saving all time steps to a single file

  4. Transient sweep, saving each time step to a single file to create a series of files

Although information is available within the XDB files to describe what they were originally, all surfaces are stored as boundary types. A boundary type naming convention has been established to create some correspondence between the original surface type and its name within the XDB file. An illustration of the boundary type naming convention is shown in Figure 6. In general, the first part of the boundary type name corresponds to the type of surface it was originally derived from. The remaining part of the name attempts to provide additional context for that surface up to an 80 character limit.

baffles bnd panel
Figure 6. XDB Boundary Surfaces

Streamline, streakline or particle path data may also be present in XDB files. This type of data is read into FieldView as particle paths, and a separate step is required. The Particle Path input panel, when opened, automatically points to the XDB file which has already been read in. The Particle Path Data Input panel (see Figure 7. XDB Particle Path Data Input) can be used to read data directly or with a server.

Figure 7. XDB Particle Path Data Input

XDB particle paths data input

XDB particle path input data remote

If you attempt to read particle path data from an XDB file which does not have any, you will be prompted with the following error message:

xdb particle path input error
Figure 8. XDB Particle Path Data Input Error

In the case where an XDB file contains both streamlines or streaklines and particle path data, only the particle path is read since FieldView currently only supports one particle path per dataset.

Full FVX support has been provided to import XDB files. A sample FVX listing below illustrates the correct syntax.

    local dataset_1_info_table = read_dataset( {
        data_format = "xdb_import",
        input_parameters = {
            name = "/usr3/xdb/spitfire.xdb",
            options = {
                input_mode = "replace",
                boundary_only = "off"
            } -- options
        } -- input_parameters
    } ) -- read_dataset

    local particle_paths_1 = read_particle_paths(
	    {
            scalar_colormap = {
                name = "spectrum",
                invert = "off",
                filled_contour = "off",
            }, -- scalar_colormap
            ppath_func = "Duration",
            format = "xdb import",
            number_of_contours = 16,
            geometric_color = 4,
            line_type = "thin",
            scalar_range = {
                min = 0,
                local_min = 0,
                max = 0.2000000029802322,
                local_max = 0.2000000029802322,
                use_local = "off",
            }, -- scalar_range
            select_by = {
                initial_value_variable = "none",
                value_on_path_variable = "none",
                tags = "none",
            }, -- select_by
            visibility = "on",
            scalar_func = "none",
            dataset = 1,
            filename = "/usr3/xdb/spitfire.xdb",
        }
    ) -- particle_paths_1

Function Selection for XDB Export

Two methods have been available to specify the functions to be saved when exporting an XDB file via either the Write or Build mode. The first method lists the functions to be exported in a file called xdb_vars. A basic version of this file is included in the standard FieldView installation in the /fv/data subdirectory. Any modified version of this file, placed in a user’s HOME directory, would be used instead of the basic version of this file supplied with FieldView. As an alternative to using the xdb_vars file, FieldView checks for a file called root.xfn, which has a list of variable names, one per line, when saving an XDB file with the base name root. The root.xfn search path starts in the directory where the XDB file is being saved, then goes to the users HOME directory and finally looks in the FieldView installation area (/fv/data).

To simplify the task of selecting the functions to be saved when exporting an XDB, a GUI is provided, as shown in Figure 9.

Viewer XDB Export
Figure 9. Viewer XDB Export Panel

The QUANTITIES section of the Viewer XDB Export panel in Viewer XDB Write and Viewer XDB Build modes allows interactive function selection for XDB export. It lists all scalar and vector functions and formulas valid for the current dataset, excluding geometric functions ("X", "Y" and "Z", "Rcyl: \$(X^2+Y^2)^.5\$", …​through "atan(Y/Z)", as well as "I", "J", and "K" (for structured data.) Scalar functions are listed first, followed by vector functions. Scalar and vector functions are further broken up by categories. NOTE: The geometric functions are automatically available in the export, and quantities I, J, or K (for Structured data) can be exported if by creating formulas, for example, myI = "I", myJ = "J", myK = "K".

To simplify function selection when exporting an XDB file, functions in the QUANTITIES section of this GUI are pre-selected according to the following rules:

  • They have been used for a visualization object whose visibility is ON. In other words, if a function is in active use on any surface or rake for the current dataset, it will be pre-selected for XDB export.

  • The function is included in the xdb_vars file.

For certain visualization objects, functions in use are not pre-selected:

  • Scalar functions in use by 2D Plots are not pre-selected.

  • Vector functions that are only used for streamline or vortex core calculations are not pre-selected.

There are four buttons located immediately beneath the QUANTITIES section of this GUI. The Select All/Deselect All buttons allow you to change your current selected functions, selecting either all or none, respectively. If you choose the Select All button, you will see the following XDB Write Warning message. In general, the intent for XDB exports is that fewer functions are saved, containing only the functions of immediate interest.

XDB Write Warning
Figure 10. XDB Write Warning

Pressing the Open…​ button lets you browse to and open a previously created .xfn file. When this is done, any functions in the QUANTITIES list matching those in the .xfn file are pre-selected. This action will de-select anything that was already selected.

Pressing the Save…​ button opens a browser and lets you save a .xfn file, independently from the XDB export. This saved .xfn file can be re-used in a later session.

Functions can be selected interactively, overriding the pre-selection rules. Selecting a function by Left-Clicking M1 on it will select only that function and clear any pre-existing selections. To select more than one function, hold the Ctrl key down and Left-Click Ctrl+M1 on the desired functions. To select a range, Left-Click on the function at the top of the range, hold the Shift key and Left-Click M1+Shift+M1 on the function at the bottom of the range. You can also select a range of functions by Left-Clicking and Dragging M1+Drag.

The Viewer XDB Export panel has a checkbox to Maintain Thresholded Surfaces in Viewer XDB Write and Viewer XDB Build modes. When enabled, only the surface geometry visible after threshold clipping is output, potentially reducing file size substantially. This option can make extracts even smaller, allowing faster transfer and read operations for these files. It also reduces the memory required for loading them into FieldView or XDBview, pushing further the benefits of XDBs.

Thresholding includes:

  • Clipping by the selected threshold function, and

  • Min/max coordinate axis limiting (coordinate surfaces only).

Thresholded surfaces are exported with the tag [THR] embedded in the boundary surface name and include the following types:

  • Coordinate surfaces

  • Iso-surfaces

  • Boundary surfaces (unstructured datasets only)

Thresholding by the selected threshold function will be disregarded for computational surfaces or boundary surfaces of structured datasets when exported. However, they will continue to always clip by IJK coordinate axis limiting. If either surface types are present, visible and thresholded, complete unthresholded surfaces are exported and the following warning is issued:

XDB Write Warning: Computational or Boundary Surfaces of structured datasets have been detected and will not maintain thresholding on export.

Dynamic clipping has no effect on the exported XDB files.

To export the XDB file, press the OK button at the bottom left corner of the panel. When you export an XDB file, a .xfn file with the same name as the XDB file is written. If a .xfn file with the same name already exists, you will see the following overwrite confirmation:

XDB Function List Overwrite Confirmation
Figure 11. XDB Function List Overwrite Confirmation

In this way, you can choose to preserve or overwrite your existing .xfn file. After a selection has been made here, the XDB is exported.

If you choose not to export the XDB, you can push the Cancel button at the lower right corner of the Viewer XDB Export panel.

Important notes and limitations

Surface normals are always exported for all surfaces and can be used in subsequent calculations. The surface normal function, named "N", and its components (N.vector.x, N.vector.y, N.vector.z) are reserved names.

The limit on the functions exported to an XDB is 100. If you attempt to export more than 100 functions, you will be presented with a console warning advising you that you have exceeded this limit. At this point, an XDB file will be exported containing only the first 100 of all the functions selected.

XDB exports saved via SCRIPT commands will use either the xdb_vars or the .xfn method to specify the functions to export.

XDB Format

It is possible to write face-based results to XDB files for unstructured datasets only. This further enables quantitative postprocessing via XDB workflows - integrations performed on surfaces with face-based results in XDB files will match those reported by the finite-volume based CFD solver codes.

For transient cases, XDBs are saved using one file per time step, offering a 5X to 7X improvement to read a transient XDB export. Exported filenames contain the time step number embedded in the base name, as specified by the user, according to the following rules:

  • The .xdb extension (case insensitive) will be automatically appended to all XDB exports. If you have already specified the .xdb extension in the base name, it will not be redundantly added.

  • The time step number matches the integer for the TIME STEP as shown in the Transient Data Controls panel for the current dataset.

  • The time step number will be inserted in front of the first "." in the non-directory part of the specified filename. If the base name is specified as /opt/data/my.transient.export.xdb, then the name for the XDB for time step "10" will be /opt/data/my10.transient.export.xdb.

  • If the last character before the "." is a digit, we will insert a "_" in between this digit and the time step number. For example, if your specified XDB filename is F18.xdb, the name of the XDB for time step "12" will be F18_12.xdb.

When you specify an XDB filename for a transient case, either interactively or from a SCRIPT containing the XDB_ENABLE xdb_file_name and SWEEP TIME commands, you will see the following console printout:

XDB Extract data will be exported to xdb_file_name

XDB Extract filename is modified to include the time step number.

A complete restart is always written when an XDB is exported to allow the easy re-creation of the original set of visualization objects stored in the XDB. For transient XDBs, this complete restart will only be written once using the base name specified for the XDB and will not have the time step number included.

Transient XDBs include the solver solution time, enabling time synchronization between XDB files and particle path data. The PARTICLE SET format is used for transient streakline data to take advantage of the substantial performance benefits for this feature. Due to these format implementations, FieldView releases prior to 14 are unable to read the newer XDB files.

If particle path data is imported into FieldView along with steady or transient volume data, it will not be redundantly stored within XDB exports.

Encryption

For cases where XDB are used in a high performance extract based workflow and not shared with the outside, an encryption step can now be skipped at export by running FieldView with the environment variable FV_PROTO_QUICK_XDB set to any value. This will bring a speed up of about 20% for write and read operations. Having the environment variable set at read time is not needed to read unencrypted XDB files.

Known limitation: unencrypted XDB files are only compatible with FieldView 20 or higher. Attempting to read such an XDB file with an earlier version of FieldView or with XDBview2 will print the console message:

XDB file version is higher than expected (not supported)

FieldView Interface

Working with FieldView UGChapter 4 Fieldview Interface FOM SVG 28
Figure 12. FieldView Main Window

The FieldView interface (Figure 12) consists of a main Graphical User Interface (GUI). This interface allows you to quickly and easily access visualization tools and properties. The GUI consists of typical Windows-like pull-down menus as well as several toolbars. The toolbars contain shortcut buttons which either perform operations themselves or open interface panels. Highlights of this interface include:

  • Dockable Toolbars for customized GUI layout

  • Redundant access to common functionality and panels

  • Automatically saved preferences for the main window size & location of all panels

  • Interface starts up initially at full screen resolution

The FieldView interface is designed for a minimum screen resolution of 1280 by 1024 pixels. However, some laptop and projector displays have a shorter vertical resolution. Also, it is possible on some Windows systems to decrease the available vertical resolution through the use of a custom DPI setting to make system fonts easier to read. For these reasons, FieldView makes the tallest panels "scrollable" if it determines, at start-up, that they are too tall for the available screen space. The minimum vertical resolution for scrollable panels is 600 pixels.

Saved Preferences for the FieldView Interface

Saving the size and location of the main window, along with the location of the toolbars (and whether they are docked or not) is part of the broader functionality of saving preferences. This information is stored in FieldView.ini. Its location depends on the system where FieldView is being run.

On Linux/macOS,
/home/user/.config/Tecplot/FieldView.ini

On Windows,
C:\Users\user\AppData\Roaming\Tecplot\FieldView.ini

Note that the position of the file browsers, warning or error messages and confirmation pop-ups are not saved. Layouts are not saved as part of your FieldView preferences on exit. As a result, FieldView will start with a single window unless a Complete Restart with a multi-window layout is read at start-up.

FieldView Preference Override

In some cases, it may be desirable to turn off the default behavior which saves and restores user preferences, such as the GUI layout and last file locations browsed. This is controlled by setting the following environment variable: FV_NO_PREFERENCES

When this environment variable is set, the FieldView preference file (FieldView.ini) will neither be read on start up of nor written on exit from FieldView.

Multi-Window Operation

The FieldView graphics window can be split into more than one window. The basic GUI features for multi-windows are shown in Figure 13. Each window has the full functionality of interaction and transform control available within the full graphics window. Interactive mouse control, locked transforms, the click viewer, World, Dataset, Region, Surface, Plot and Light object transforms as well as Detach/Reset all work for the current window whether you have a single window or multi-window arrangement. The following attributes can be uniquely set for each window:

  • Background Color

  • Background Image and position

  • Outline set either ON or OFF

  • Axis Markers, set either ON or OFF

  • Rotation Increment

  • Scale Factor

  • Move Factor

  • Perspective, set either ON or OFF

  • Perspective Angle, when Perspective is ON

Working with FieldView UGChapter 4 Fieldview Interface FOM SVG 31
Figure 13. Getting to know multi-window operation

There is a toolbar within each window, fixed in the upper left corner. A Window Actions pulldown menu, accessible from either the vertical or horizontal split icons on the window toolbar, lets you create a new window by splitting the current one. Windows can be split repeatedly, either horizontally or vertically. When a window is split, the new window resulting from that action becomes the current window.

The toolbar for the current window is colored green and is highlighted with a green border. To make a different window current, Left-Click M1 anywhere in the window of interest.

Sashes are used to identify the borders separating each window. A handle located at the center of each sash can be used to interactively resize windows. Windows within the graphics window are interconnected. If a window is resized, any windows bordering it will also be resized, growing or shrinking to fully occupy the space defined by the graphics window.

Window Split Actions

When you start FieldView, the green toolbar in the upper left corner of your graphics window appears as illustrated in Figure 14. Clicking on either the vertical or horizontal split buttons gives you options for splitting the current window. Three distinct actions can be performed when a window is split: Copy, Instance or Empty. Copy and Instance perform specific operations with the visualization objects (surfaces and rakes) present in the window prior to splitting it.

Working with FieldView UGChapter 4 Fieldview Interface FOM SVG 34
Figure 14. The Window Toolbar and Action menus
Window Action: Copy

When Copy is selected from the Window Actions pulldown menu, a virtual representation for all of the datasets in current window is created. As part of the Copy action, the visualization objects for each dataset in the original window are re-created on virtual datasets in the new window produced by the split. These visualization objects are independent representations and can be displayed with different attributes than their original content. In Figure 15, we start (at left) with a coordinate plane colored with the scalar function Temperature, and a boundary surface with the display type Mesh. After a Vertical Split, Copy action, a new coordinate surface and a new boundary surface are created in window 2 at right. At this point, the scalar function for the coordinate surface in window 2 is changed from Temperature to Concentration.

Working with FieldView UGChapter 4 Fieldview Interface FOM SVG 36
Figure 15. Vertical Split, Copy action

Following a Copy action, it is possible to create new visualization objects in one window and not the other. It is also possible to save a Current Dataset Restart for the data in one window, make another window Current, and Open the Current Dataset Restart, creating the surfaces and rakes defined from the restart on the current dataset in the current window.

Window Action: Instance

When the Instance action is selected, a view-only representation of the visualization object(s) for all datasets in the original window is created in the new window Selecting any instanced visualization object by quick-picking in any window lets you modify it. Modifications, such as changing the scalar function or scalar range for example, are automatically propagated to all instances of that visualization object.

In Figure 16, we start (at left) with the same surfaces that were used in the Copy example above. After a Vertical Split, Instance action, the visualization objects are displayed in both windows. The view direction can be modified independently for each window, letting you view these visualization objects from different angles.

If you create a new surface or rake on any dataset in either window, an instance of that object is displayed in all windows which were created using the Instance action.

Working with FieldView UGChapter 4 Fieldview Interface FOM SVG 38
Figure 16. Vertical Split, Instance action
Window Action: Empty

When the Empty action is selected, a new window is created without any virtual copies of datasets or visualization objects, as shown in Figure 17. If the empty window remains current, any dataset when read in will be displayed in it. The contents of all other windows will remain undisturbed.

Working with FieldView UGChapter 4 Fieldview Interface FOM SVG 40
Figure 17. Vertical Split, Empty action

Maximizing, Restoring and Closing a Window

When multiple windows are present, it is sometimes useful to maximize one window temporarily. This can be done by pressing the maximize pane on the current window toolbar. When the current window is maximized, the button label changes to restore panes. Pressing restore panes restores the window to its original size and location.

To close the current window, press close pane on the window toolbar. Note that this icon does not control the visibility of the toolbar in the window. When a window is closed, all of the visualization objects (surfaces, rakes and annotations) in the closed window will be deleted. There is no undo operation to recover visualization objects from a closed window.

Showing/Hiding the Window Toolbar

The window toolbar is colored in green in the current window (see Figure 14) and beige in the non-current window(s). Its visibility can be controlled uniformly for all windows or individually for the current window. By default, the window toolbar is visible in all windows.