tecio.cli.tecaux#
Add, remove, or export dataset, zone, or variable level auxiliary data.
The Tecplot auxiliary data mechanism attaches arbitrary name=value metadata to a
dataset, a zone, or a variable (solver name, run date, units, a description, or any
other annotation that doesn’t belong in the numerical data itself). Managing this after
the fact ordinarily means writing a one-off script against the TecIO API. tecaux
does this from the command line, in a single read/write pass, in three mutually
exclusive modes:
By default (no
--strip/--export-json): merges new auxiliary entries (from-d/-z/-vand/or-j) into a copy of the input file. Every zone, variable, and existing sharing relationship is preserved exactly; an existing key with the same name is overwritten.--stripremoves every auxiliary entry at all three levels and writes the result to a new file, still preserving sharing.--export-jsonwrites every existing auxiliary entry to a JSON file, in the same format-jreads back – without touching the source file at all, unless combined with--strip.
- Usage:
tecaux [-h] [-d KEY=VALUE] ... [-z INDEX KEY=VALUE] ...
[-v INDEX_OR_NAME KEY=VALUE] ... [-j PATH] [-s] [--export-json]
[-o PATH] [-f] PATH
- Positional Arguments:
PATHPath to the input Tecplot file (
.plt,.szplt, or.dat).
- Options:
-d KEY=VALUE,--data KEY=VALUEA
name=valuepair to set as dataset-level auxiliary data. Repeat the flag for multiple pairs.-z INDEX KEY=VALUE,--zone INDEX KEY=VALUEA
name=valuepair to set as zone-level auxiliary data on the 0-based zoneINDEX, or on every zone ifINDEXis the literal wordall. Repeat the flag for multiple pairs and/or multiple zones; each occurrence takes exactly one zone and one pair, so-z 0 A=1 -z 0 B=2sets bothAandBon zone 0.-v INDEX_OR_NAME KEY=VALUE,--variable INDEX_OR_NAME KEY=VALUEA
name=valuepair to set as variable-level auxiliary data on the variable given by a 0-based index or a name (case-insensitive), r on every variable if the target is the literal wordall. Repeatable, same as-z.-j PATH,--json PATHLoad bulk auxiliary data from a JSON file (see format below). Applied before any
-d/-z/-vflags, which take precedence on a key collision.-s,--stripRemove all auxiliary data (dataset, zone, and variable levels) and write the result to
<stem>_no_aux<ext>(or-o’s path). Mutually exclusive with-d/-z/-v/-j. Combine with--export-jsonto keep a JSON copy of what was removed.--export-jsonWrite every existing auxiliary entry to
<stem>_aux.json, in the sameAUXDATASET/AUXZONE/AUXVARformat-jreads, without modifying the source file, unless combined with--strip. Mutually exclusive with-d/-z/-v/-j.-o PATH,--output PATHOutput file path. The extension controls the output format:
.szplt,.plt, or.dat. Defaults to<stem>_aux<ext>, or<stem>_no_aux<ext>with--strip. Not used by--export-jsonalone which always writes<stem>_aux.json, regardless of-o.-f,--forceOverwrite the output file(s) if they already exist. Without this flag the command exits with an error rather than silently clobbering an existing file.
- JSON Format:
{ "AUXDATASET": {"Solver": "MyCFD", "Version": "2.1"}, "AUXZONE": { "0": {"Description": "Wing"}, "all": {"Batch": "2024"} }, "AUXVAR": { "Pressure": {"Units": "Pa"}, "0": {"Source": "Experiment"} } }
All three top-level keys are optional, and match this library’s own attribute/method names for the same three levels exactly (
Write.auxdataset/add_auxdataset_dict,Write.auxvar/add_auxvar_dict;AUXZONEis the natural third member of that family even though zone-level aux has no “zone”-prefixed name internally.In
"AUXZONE"/"AUXVAR", a key is either a 0-based index, a variable name ("AUXVAR"only), or the literal string"all"meaning every zone/variable (the same three forms-z/-vaccept on the command line). Every JSON key must be a quoted string, including numeric indices ("0", not0).--export-jsonwrites this exact format back out, keyed by exact 0-based index (never"all", even if every zone happens to share identical aux content) and omitting any zone/variable/level with nothing to report.- Returns:
In the default mode, a new Tecplot file written to the output path with the requested auxiliary data merged in. With
--strip, a new Tecplot file with all auxiliary data removed. With--export-json, a JSON file of everything that was found (and the source file is untouched, unless--stripis also given). Exit code is0on success and non-zero if the input file cannot be read, a-z/-v/JSON target cannot be resolved,--strip/--export-jsonis combined with-d/-z/-v/-j, or an output file already exists and--forceis not set.
Examples
Tag a dataset with solver metadata (repeat the flag for multiple pairs):
$ tecaux -d Solver=MyCFD -d Version=2.1 flow.szplt
Two pairs on zone 0, one pair on zone 1:
$ tecaux -z 0 Description=Wing -z 0 Area=120sqm -z 1 Description=Fuselage \
flow.szplt
Annotate a single variable by name:
$ tecaux -v Pressure Units=Pa flow.szplt
Every zone at once, via the “all” target:
$ tecaux -z all RunDate=2024-01-15 flow.plt
Everything in one pass, written as a bash script would naturally lay it out:
$ tecaux --data Solver=MyCFD \
--data Version=2.1 \
--zone 0 Case=A \
--zone 0 Description=Wing \
--zone 1 Case=B \
--variable Pressure Units=Pa \
-o tagged.szplt flow.szplt
Bulk metadata from a file, with one CLI override on top:
$ tecaux -j metadata.json -d Version=2.2 flow.szplt
Back up everything currently on a file before editing it by hand, without touching the file itself:
$ tecaux --export-json flow.szplt # writes flow_aux.json
Sanitize a file for external sharing, discarding whatever aux data it had:
$ tecaux --strip flow.szplt # writes flow_no_aux.szplt
Sanitize a file but keep a record of what was removed, in case it’s needed later
(e.g. to reapply with -j after review):
$ tecaux --strip --export-json flow.szplt
# writes flow_no_aux.szplt and flow_aux.json
Call directly from a Python session:
from tecio.cli.tecaux import main as tecaux
tecaux(["-d", "Solver=MyCFD", "flow.szplt"])
See also
tecio.cli.tecfix- Rewrite a file with invalid variable arrays set to passive, using the same verbatim zone-copy approach.tecio.cli.teconvert- Convert between formats without modifying auxiliary data.
Functions
|
Add, remove, or export auxiliary data to a Tecplot file. |