API reference

This is a complete api reference to the PIVPy package.

The pivpy.io module

Contains functions for reading flow fields in various formats

pivpy.io.create_sample_Dataset(n_frames: int = 5, rows: int = 5, cols: int = 3, noise_sigma: float = 0.0) → Dataset

Creates a syntetic dataset

Parameters:

• n_frames – number of frames

• rows (int) – number of points along vertical coordinate, corresponds to ‘y’

• cols – number of grid points along horizontal coordinate, ‘x’

• grid – spacing between vectors in two directions (x,y)

• frame – frame number

• noise_sigma – strength of Gaussian noise to add

Returns:

PIVPy dataset

Return type:

dataset

Example

ds = create_sample_dataset(n_frames=3)

pivpy.io.create_sample_field(rows: int = 5, cols: int = 8, grid: List | None = None, frame: int = 0, noise_sigma: float = 1.0) → Dataset

Creates a sample Dataset for the tests.

Parameters:

• rows (int) – number of points along vertical coordinate, corresponds to ‘y’

• cols (int) – number of grid points along horizontal coordinate, ‘x’

• grid (int, int) – spacing between vectors in two directions (x,y)

• frame (int) – frame number

• noise_sigma (float) – strength of Gaussian noise to add

Returns:

dataset

Return type:

xarray.Dataset()

pivpy.io.create_uniform_strain()

creates constant strain field

pivpy.io.from_arrays(x: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], y: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], u: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], v: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], mask: array, frame: int = 0) → Dataset

creates a dataset from two-dimensional Numpy arrays of x,y,u,v and mask

Parameters:

• x (array) – x

• y (array) – y

• u (array) – u

• v (array) – v

• mask (array) – mask, all numpy arrays of the same shape

• frame (int) – frame number, default is 0

Returns:

xarray dataset with default attributes

Return type:

ds (xarray.Dataset)

Example

ds = io.from_arrays(x,y,u,v,mask,frame=0)

pivpy.io.from_df(df: DataFrame, frame: int = 0, filename: str | None = None) → Dataset

creates pivpy.Dataset from pandas DataFrame

Parameters:

• df (pd.DataFrame) – DataFrame with columns of x,y,u,v

• frame (int, optional) – frame number. Defaults to 0.

• filename (str, optional) – filename to add to the attributes. Defaults to None.

Returns:

pivpy.Dataset

Return type:

xr.Dataset

pivpy.io.get_units(filename)

given a full path name to the .vec file will return the names of length and velocity units fallback option is all None. Uses parse_header function, see below.

pivpy.io.load_davis8_txt(filename: Path, rows: int | None = None, cols: int | None = None, delta_t: float = 0.0, frame: int = 0) → Dataset

loads Davis8 old ASCII tables format

Parameters:

• filename (pathlib.Path) – Davis8 filename.txt

• rows (int, optional) – rows. Defaults to None.

• cols (int, optional) – cols. Defaults to None.

• delta_t (float, optional) – delta_t. Defaults to 0.0.

• frame (int, optional) – frame number. Defaults to 0.

Returns:

pivpy.Dataset

Return type:

xr.Dataset

pivpy.io.load_directory(path, basename='*', ext='*.vec')

Loads all the files with the chosen sextension in the directory into a single xarray Dataset with variables and units added as attributes

Input:

directory : path to the directory with .vec, .txt or .VC7 files, period . can be dropped

Output:

datasetxarray Dataset with dimensions: x,y,t and

dataset arrays of u,v, attributes of variables and units

See more: load_vec

pivpy.io.load_insight_vec_as_csv(filename, rows=rows, cols=cols)

Loads the VEC file (TECPLOT format by TSI Inc.), :param filename: file name, expected to have a header and 5 columns :param rows: number of rows and columns of a vector field, :param cols: number of rows and columns of a vector field, :param if None: :param None: :param then parse_header is called to infer the number: :param written in the header: :param DELTA_T: time interval (default is None) :param frame: frame or time marker (default is None)

Output:

dataset is a xAarray Dataset, see xarray for help

pivpy.io.load_openpiv_txt(filename: str, rows: int | None = None, cols: int | None = None, delta_t: float | None = None, frame: int = 0) → Dataset

loads OpenPIV txt file

Parameters:

• filename (str) – _description_

• rows (int, optional) – _description_. Defaults to None.

• cols (int, optional) – _description_. Defaults to None.

• delta_t (float, optional) – _description_. Defaults to None.

• frame (int, optional) – _description_. Defaults to 0.

Returns:

_description_

Return type:

xr.Dataset

pivpy.io.load_openpiv_txt_as_csv(filename: str, rows: int | None = None, cols: int | None = None, delta_t: float | None = None, frame: int = 0) → Dataset

loads OpenPIV txt file

Parameters:

• filename (str) – _description_

• rows (int, optional) – _description_. Defaults to None.

• cols (int, optional) – _description_. Defaults to None.

• delta_t (float, optional) – _description_. Defaults to None.

• frame (int, optional) – _description_. Defaults to 0.

Returns:

_description_

Return type:

xr.Dataset

pivpy.io.load_vc7(filename) or load_vc7(filename, frame=0)

Loads the vc7 file using Lavision lvreader package, :param filename: file name, pathlib.Path

Output:

dataset : xarray.Dataset

pivpy.io.load_vec(filename, rows=rows, cols=cols)

Loads the VEC file (TECPLOT format by TSI Inc.), OpenPIV VEC or TXT formats :param filename: file name, expected to have a header and 5 columns :param rows: number of rows and columns of a vector field, :param cols: number of rows and columns of a vector field, :param if None: :param None: :param then parse_header is called to infer the number: :param written in the header: :param DELTA_T: time interval (default is None) :param frame: frame or time marker (default is None)

Output:

dataset is a xAarray Dataset, see xarray for help

pivpy.io.parse_header(filename: Path) → Tuple[str, ...]

parses the header line in the file to obtain attributes

Parameters:

filename (pathlib.Path) – txt, vec file name

Returns:

variables: units : rows : cols : delta_t: frame : method :

Return type:

Tuple[str, …]

pivpy.io.set_default_attrs(dataset: Dataset) → Dataset

Defines default attributes:

# xr.DataSet.x.attrs[“units”] = POS_UNITS POS_UNITS: str = “pix” # or mm, m, after scaling

# None if not known, can become ‘sec’ or ‘msec’, ‘usec’ # the time units are for the sequence of PIV realizations # useful for animations of the DataSet and averaging # xr.DataSet.t.attrs[“units”] = TIME_UNITS TIME_UNITS: str = None

# after scaling can be m/s, mm/s, default is POS_UNITS # xr.DataSet.u.attrs[“units”] = VEL_UNITS VEL_UNITS: str = POS_UNITS

# attribute of the xr.DataSet, defines things for the # single flow realization, frame A -> DELTA_T -> frame B # xr.DataSet.attrs[“delta_t”] = DELTA_T DELTA_T: float = None # default is unknown, can be

pivpy.io.unsorted_unique(arr: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]

creates a sorted unique numpy array

The pivpy.graphics module

Various plots, mostly wraping xarray.plot

pivpy.graphics.animate(data: Dataset, arrowscale: int = 1, savepath: str | None = None, units: str = 'pix/dt')

animates flow fields in the data and saves to MP4 format

Parameters:

• data (xr.Dataset) – _description_

• arrowscale (int, optional) – _description_. Defaults to 1.

• savepath (str, optional) – _description_. Defaults to None.

Returns:

_description_

Return type:

_type_

pivpy.graphics.contour_plot(data: DataArray, threshold: float | None = None, contourLevels: List[float] | None = None, colorbar: bool = False, logscale: bool = False, aspectratio: str = 'equal', units: List[str] = [])

creates contour plot of xr.DataArray

Parameters:

• data (xr.DataArray) – _description_

• threshold (float, optional) – _description_. Defaults to None.

• contourLevels (List[float], optional) – _description_. Defaults to None.

• colorbar (bool, optional) – _description_. Defaults to False.

• logscale (bool, optional) – _description_. Defaults to False.

• aspectratio (str, optional) – _description_. Defaults to “equal”.

• units (List[str], optional) – _description_. Defaults to [].

Returns:

_description_

Return type:

_type_

pivpy.graphics.dataset_to_array(data: Dataset, t_index: int = 0)

converts xarray Dataset to array

pivpy.graphics.histogram(data, normed=False)

creates two histograms of two velocity components

Parameters:

• data (_type_) – _description_

• normed (bool, optional) – _description_. Defaults to False.

Returns:

_description_

Return type:

_type_

pivpy.graphics.quiver(data: DataArray, arrScale: float = 25.0, threshold: float | None = None, nthArr: int = 1, aspectratio: str = 'equal', colorbar: bool = False, colorbar_orient: str = 'vertical', units: List = [], streamlines: bool = False, cmap: str = 'RdBu', **kwargs)

creates quiver of xr.Dataset

Parameters:

• data (xr.DataArray) – _description_

• arrScale (float, optional) – _description_. Defaults to 25.0.

• threshold (float, optional) – _description_. Defaults to None.

• nthArr (int, optional) – _description_. Defaults to 1.

• aspectratio (str, optional) – _description_. Defaults to “equal”.

• colorbar (bool, optional) – _description_. Defaults to False.

• colorbar_orient (str, optional) – _description_. Defaults to “vertical”.

• units (List, optional) – _description_. Defaults to [].

• streamlines (bool, optional) – _description_. Defaults to False.

• cmap (str, optional) – matplotlib.colormap, e.g. ‘jet’, ‘hot’, ‘RdBu’, ‘Reds’

Returns:

_description_

Return type:

_type_

pivpy.graphics.showf(data, flow_property='ke', **kwargs)

shows data as quiver over a scalar background

Parameters:

• data (_type_) – _description_

• flow_property (str, optional) – _description_. Defaults to “ke”.

pivpy.graphics.showscal(data, flow_property='ke', **kwargs)

creates contour plot of some scalar field of a flow property

Parameters:

• data (_type_) – _description_

• flow_property (str, optional) – _description_. Defaults to “ke”.

Returns:

_description_

Return type:

_type_

The pivpy.pivpy module

This script extends the functionality of xarray.Dataset by adding a new accessor called piv. The accessor adds several properties and methods that are useful for working with particle image velocimetry (PIV) data. The properties include average, which returns the mean flow field, and delta_t, which returns the time step used in the PIV measurement. The methods include crop, which allows the user to crop the data by a given number of rows and columns from the boundaries, vec2scal, which converts vector data to scalar data, pan, which pans the data by a given number of pixels, and rotate, which rotates the data by a given angle.

@author: Ron, Alex

class pivpy.pivpy.PIVAccessor(xarray_obj)

extends xarray Dataset with PIVPy properties

acceleration()

calculates material derivative or acceleration of the data arracc_y (single frame)

Input:

xarray with the variables u,v and dimensions x,y

Output:

xarray with the estimated acceleration as a scalar field data[‘w’]

property average

Return the mean flow field .

crop(crop_vector=None)

crops xr.Dataset by some rows, cols from the boundaries

Parameters:

crop_vector (_type_, optional) – _description_. Defaults to None.

Returns:

_description_

Return type:

_type_

property delta_t

receives the delta_t from the set

divergence()

calculates divergence field

Returns:

xr.Dataset with the new property [“w”] = divergence

Return type:

self._obj

fill_nans(method: Literal['linear', 'nearest', 'cubic'] = 'nearest')

This method uses scipy.interpolate.griddata to interpolate missing data. :param src_data: Input data array. :type src_data: Any :param method: The method to use for interpolation in scipy.interpolate.griddata. :type method: {‘linear’, ‘nearest’, ‘cubic’}, optional

Returns:

An interpolated numpy.ndarray.

Return type:

numpy.ndarray

filterf(sigma: List[float] = [1.0, 1.0, 0], **kwargs)

Gaussian filtering of velocity

fluct()

returns fluctuations as a new dataset

kinetic_energy()

estimates turbulent kinetic energy

pan(shift_x=0.0, shift_y=0.0)

moves the field by shift_x,shift_y in the same units as x,y

quiver(**kwargs)

graphics.quiver() as a flow_property

reynolds_stress()

returns fluctuations as a new dataset

rms()

Root mean square

rotate(theta: float = 0.0)

rotates the data, but only for some x,y grids :param theta: degrees in the clockwise direction :type theta: float :param it can only work for the cases with equal size along: :param x and y:

Returns:

rotated object

set_delta_t(delta_t: float = 0.0)

sets delta_t attribute, float, default is 0.0

set_scale(scale: float = 1.0)

scales all variables by a sclar

showf(**kwargs)

method for graphics.showf

showscal(**kwargs)

method for graphics.showscal

strain()

calculates rate of strain of a two component field

Returns:

adds [“w”] = du_dx^2 + dv_dy^2 + 0.5*(du_dy+dv_dx)^2

Return type:

_type_

streamplot(**kwargs)

graphics.quiver(streamlines=True)

tke()

estimates turbulent kinetic energy

vec2scal(flow_property: str = 'curl')

creates a scalar flow property field

Parameters:

flow_property (str, optional) – one of the flow properties. Defaults to “curl”.

Returns:

_description_

Return type:

_type_

vorticity()

calculates vorticity of the data arracc_y (at one time instance) and adds it to the attributes

Input:

xarray with the variables u,v and dimensions x,y

Output:

xarray with the estimated vorticity as a scalar field with same dimensions