tecio.cli.tec2mat#

Convert a Tecplot data file to a MATLAB .mat file.

MATLAB is widely used for engineering analysis and post-processing, but it cannot read Tecplot binary files directly, and the Tecplot ASCII format is awkward to parse on the MATLAB side. Moving data across normally requires a Tecplot license or a hand-written reader. tec2mat bridges this gap by reading any supported Tecplot format (.szplt, .plt, or .dat) and writing a single MATLAB .mat file via scipy.io.savemat(). Each input file maps to exactly one output file (flow.szplt -> flow.mat): every zone becomes a named struct, every variable is preserved at its native precision, and connectivity and metadata are retained so the dataset can be reconstructed in MATLAB without a Tecplot installation.

Usage:

tec2mat [-h] [-o PATH] [-f] [-c] [--oned-as {column,row}] PATH

Positional Arguments:

PATH: Path to the input Tecplot file (.plt, .szplt, or .dat) to convert.

Options:

-o PATH, --output PATH: Output file path. Defaults to the input file stem with a .mat extension in the same directory as the input file.
-f, --force: Overwrite the output file if it already exists. Without this flag the command exits with an error rather than silently clobbering an existing file.
-c, --compress: Compress the variable arrays inside the .mat file (passes do_compression=True to scipy.io.savemat()). Reduces file size at the cost of some write/read time.
--oned-as {column,row}: Orientation for one-dimensional arrays (finite-element nodal/cell vectors and the per-variable metadata arrays) in the .mat file. column (the default) writes N x 1 column vectors; row writes 1 x N. Has no effect on the two- and three-dimensional arrays of ordered zones.

Returns:

A single MATLAB .mat file written to the output path. Exit code is 0 on success and non-zero if the input file cannot be read or the output file already exists and --force is not set.

Output structure:

The .mat file contains one info struct describing the dataset and one zone_<n> struct per zone (1-based, matching MATLAB’s and Tecplot’s indexing):

info                      struct
  .title                  char
  .file_type              char    'FULL' | 'GRID' | 'SOLUTION'
  .num_zones              double
  .num_vars               double
  .var_names              cell    {'x', 'y', 'p'}   (real variable names)

zone_1                    struct
  .title                  char
  .zone_type              char    'ORDERED' | 'FETRIANGLE' | ...
  .solution_time          double
  .strand_id              double
  .I, .J, .K              double  (ordered zones)
  .num_nodes              double  (finite-element zones)
  .num_elements           double  (finite-element zones)
  .var_1 ... .var_N       array   one field per dataset variable
  .var_status             cell    'active' | 'passive' | 'shared'
  .var_locations          cell    'NODAL' | 'CELL_CENTERED' | ''
  .var_dtypes             cell    'FLOAT' | 'DOUBLE' | 'INT32' | ...
  .var_shared_from        array   1-based source zone, or 0 if not shared
  .node_map               array   (num_elements x nodes_per_cell), FE only

Variable arrays are stored at their on-disk NumPy dtype, so single/double/integer precision is preserved. The real variable names are kept only in info.var_names because they are frequently not valid MATLAB field names (e.g. "X [ft]"); the per-zone data is addressed by 1-based index (var_1 …) instead.

Passive and shared variables carry no data: their var_<k> field is an empty matrix []. A shared variable is therefore never duplicated on disk – the data lives in its source zone and var_shared_from records where, so the MATLAB user can dereference it (see the examples below).

Examples

Convert an SZL file to flow.mat:

$ tec2mat flow.szplt

Convert a PLT file with compression enabled:

$ tec2mat -c flow.plt

Convert to an explicit path, writing 1-D arrays as row vectors:

$ tec2mat -o /tmp/out.mat --oned-as row flow.dat

Call directly from a Python session:

import tecio.cli.tec2mat.main as tec2mat

tec2mat(["-c", "-o", "flow.mat", "flow.szplt"])

Load the result in MATLAB and read a variable directly:

d = load('flow.mat');
x = d.zone_1.var_1;        % first variable of the first zone
p = d.zone_1.var_3;        % third variable

Variables shared from another zone are stored once. Resolve them with a small helper that follows var_shared_from:

function v = tecvar(d, zoneIdx, varIdx)
    z = d.(sprintf('zone_%d', zoneIdx));
    src = z.var_shared_from(varIdx);
    if src == 0
        v = z.(sprintf('var_%d', varIdx));
    else
        v = d.(sprintf('zone_%d', src)).(sprintf('var_%d', varIdx));
    end
end