VTKpytools/Bar2vtk

bar2vtk is a utility from the vtkpytools project for taking data in *bar files (velbar and stsbar) and loading it into a "blank" VTK Multiblock (VTM) file. In particular, it makes use of the barfiletools module in the vtkpytools project.

Documentation for bar2vtk can be found by running the --help flag, but this will also serve as a more detailed/verbose documentation page as well.

Functionality

Modes

bar2vtk has two primary modes; cli (short for command line interface) and toml. They have equal capabilities and can be called by bar2vtk cli and bar2vtk toml, respectively. The cli operates solely on the command line via standard flag and argument system. The toml system uses configuration files (in a toml format) to control the program instead.

Below is a equivalency table for cli flags/arguments vs toml config declarations. A more detailed description for each option is given in Options.

cli	toml	Description
[1st argument]	blankvtmfile = ' '	Path to the blank vtm file
[2nd argument]	barfiledir = ' '	Path to *bar files
[3rd argument]	timestep = ' '	Timesteps of data to be used
--velbar	velbar = [ ]	Explicitly specify velbar file to use
--stsbar	stsbar = [ ]	Explicitly specify stsbar file to use
--ascii	asciidata = [true/false]	Whether the *bar files are written in ASCII
--debug	debug = [true/false]	Add raw stsbar data to the file for debugging purposes
--velonly	velonly = [true/false]	Whether to only include data from velbar files
--outpath	outpath = ' '	Path that the resulting file should be output to
-f/--new-file-prefix	new-file-prefix = ' '	Prefix defined for the new file

Basic Usage

bar2vtk takes three primary arguments: blankvtmfile, barfiledir, and timestep. The utility will search the barfiledir for the appropriate *bar file(s) based on the timestep argument, and then load them onto the blankvtmfile.

blankvtmfile

Path to the VTM file that the data is loaded onto. Must match the "blank" VTM file format.

barfiledir

Path to directory where the *bar file(s) are located.

timestep

The timestep(s) of the *bar file(s) to be loaded. For time windows, a - is used to delimit between the beginning and ending timestep.

By default, the loaded VTM file will be output to the current directory and it's name will be [blankvtmfile]_[timestep].vtm. This can be changed using the utility options.

Example:

cli	toml
bar2vtk cli vtkFiles/example_blank.vtm data/ 10000	~> cat input.toml [arguments] asciidata = false barfiledir = './data' blankvtmfile = 'vtkFiles/example_blank.vtm' debug = false new_file_prefix = '' outpath = '' stsbar = [] timestep = '10000' ts0 = -1 velbar = [] velonly = false ~> bar2vtk toml input.toml

• Searches for {vel,sts}bar.10000 in ./data
• Outputs example_blank_10000.vtm to the vtkFiles/ directory

*bar File Searching

When searching for the *bar file(s) in barfiledir, bar2vtk uses a regex of ^{vel,sts}bar.*{timestep}(?![\d|-]).* to find them. For example, given timestep=200, this regex string will return the files velbar.200 or velbar.200.1, but not velbar.2000 or velbar.200-300.1. If the regex matches more than one file, it will return an error.

If setting the *bar file paths explicitly using --velbar and --stsbar, barfiledir will be ignored and no globing will occur.

Time Windows

Splitting time windows of the *bar files is done my specifying a timestep with a - to delimit the two timesteps. This will also require the --ts0 flag to define at what timestep the *bar files were reset at.

Example:

cli	toml
bar2vtk cli vtkFiles/example_blank.vtm data/ 10000-20000 --ts0 5000	~> cat input.toml [arguments] asciidata = false barfiledir = './data' blankvtmfile = 'vtkFiles/example_blank.vtm' debug = false new_file_prefix = '' outpath = '' stsbar = [] timestep = '10000-20000' ts0 = 5000 velbar = [] velonly = false ~> bar2vtk toml input.toml

• Searches for {vel,sts}bar.10000 and {vel,sts}bar.20000 in ./data
• Outputs example_blank_10000-20000.vtm to the vtkFiles/ directory

Options

--velbar and --stsbar

These flags allow for explicit setting the path(s) to the velbar and stsbar files. They can take a maximum of two arguments.

When given two paths, it will assume that a time window is to be created, with the first file corresponding to the first timestep in the timestep range.

Examples:

• bar2vtk [vtmfile] [dataPath] 10000 --velbar /data/path/velbar.file --stsbar /data/path/stsbar.file
  • Will use the files given to do a "single timestep" VTM creation
• bar2vtk [vtmfile] [dataPath] 10000-20000 --ts0=0 --velbar /data/path/velbar_first.file /data/path/velbar_second.file --stsbar /data/path/stsbar_first.file /data/path/stsbar_second.file
  • Will create a time step window using the /data/path/*bar_first.file files as timestep 10000 and /data/path/*bar_second.file as timestep 20000

--ascii

Ordinarily, the *bar files are assumed to be Fortran binary array files. Using this flag, the file(s) will instead be assumed to be space-delimited plain-text files (ie. ASCII files).

--debug

This flag will add in the raw values from the stsbar file, allowing for better debugging of the files if any strange data comes out from them.

--velonly

Will only load the velbar file(s) into the VTM file.

--vptpath

Path to vtkpytools in case of a desire to do custom testing with a separate module. Not generally recommended to use, mostly for testing/development purposes.

--outpath

Specify the path that the "loaded" VTM file is output to (instead of being saved to the current working directory by default).

-f/--new-file-prefix

Choosing a new file prefix for the "loaded" VTM file. By default, the name of the blank VTM file will be used with _[timestep] being appended to it. If this flag is given, then it's argument will be used as the file prefix.

Examples:

bar2vtk example_blank.vtm data/ 10000 -f otherprefix 
    # output file name is "otherprefix_10000.vtm"

toml Mode

There are only two options in toml mode; output a blank toml file:

   bar2vtk toml -b blank_toml_filename.toml 

or giving bar2vtk a filled out toml file to process:

   bar2vtk toml filled_toml_filename.toml 

Here's an example of a filled toml file:

[arguments]                                       
asciidata = false                                 
barfiledir = './BinaryBars'                       
blankvtmfile = '../meshFiles/CRS_4delta_12-30.vtm'
debug = false                                     
new_file_prefix = 'CRS_4delta_12-30_basestab'     
outpath = 'vtkFiles'                              
stsbar = []                                       
timestep = '1500-4500'                            
ts0 = 0                                           
velbar = []                                       
velonly = false 

See toml's website for documentation on what is possible with. For example, the # is used for comments, allowing you to make notes or skip over certain entries.