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: Optional[List] = 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: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], y: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], u: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], v: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[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: Optional[str] = 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: Optional[int] = None, cols: Optional[int] = 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: Optional[int] = None, cols: Optional[int] = None, delta_t: Optional[float] = 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: Optional[int] = None, cols: Optional[int] = None, delta_t: Optional[float] = 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: Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]) → Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[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: Optional[str] = None)

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: Optional[float] = None, contourLevels: Optional[List[float]] = 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: Optional[float] = 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

Created on Sun Macc_y 24 22:02:49 2015

@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: 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