Skip to main content

pyVTTrac

Python Platforms License

Velocimetry by Template Tracking — a NumPy-first Python package with a native Fortran computational core (no Julia, no compiled-language runtime to install).

pyVTTrac conducts simple PIV-style (particle image velocimetry) template matching, applied repeatedly in a Lagrangian manner (as in PTV, particle tracking velocimetry) over a configurable number of steps. It's built for tracking coherent features — clouds, eddies, any translating pattern — in sequences of image-like 2-D data. Both forward and backward tracking are supported.

Upgrading from v1? The Julia backend and the old VTT/setup/trac API were replaced in v2.0.0. See docs/migration-v1-to-v2.md — a handful of algorithm bugs were fixed along the way, so results can legitimately change.

30-second quickstart

pip install pyVTTrac
import numpy as np
import pyvttrac as vt

# z: (nt, ny, nx) image-like data, e.g. satellite imagery, PIV frames, ...
z = np.load("images.npy").astype(np.float32)

# a regular grid of seed points to track
x0, y0 = vt.seed_grid(z.shape, spacing=8, margin=10)

res = vt.track(
    z, x0, y0, t0=0,
    template=(7, 7),              # (ny, nx) template size
    search_velocity=(2.0, 2.0),   # (vy, vx) search range, in pixels/frame
    nsteps=5,
)

print(f"tracked {res.ok.sum()} / {res.ok.size} points")
print(f"mean velocity: vx={np.nanmean(res.vx):.3f}, vy={np.nanmean(res.vy):.3f}")

# Need an xarray.Dataset or a tidy long-format table instead?
ds = res.to_xarray()       # requires: pip install "pyVTTrac[xarray]"
df = res.to_dataframe()    # requires: pip install "pyVTTrac[pandas]"

See docs/quickstart.md for a runnable, plottable version of this example (examples/quickstart.py), and docs/api.md for the full parameter reference and Status code table.

How it works

  • Scoring: template matching by sliding cross-correlation (method="xcor", the default — cov(x',y')/sig(x)/sig(y)) or normalized covariance (method="ncov"cov(x',y')/sig(x)^2), where x is the template and y is the slid target sub-image.
  • Subgrid refinement: an optional 5-point paraboloid (subgrid="paraboloid", the default) or Gaussian (subgrid="gaussian") fit around the score peak, or disable it entirely (subgrid=None) for integer-pixel tracking. Non-integer seed positions are read via bilinear interpolation either way.
  • Multi-step tracking: each seed is tracked for nsteps steps of step frames each (step can be negative, for backward tracking), carrying the previous step's velocity forward as the next search center.
  • Screening: min_score (first step vs. subsequent steps), an optional max_velocity_change trajectory-consistency check, an optional min_contrast template check, and an optional min_peak_prominence interior-peak check.
  • Missing data: mask (boolean, True = ignore) and/or missing_value (a sentinel in z); NaN in z is always treated as missing as well.
  • Coordinates: positions/velocities are index-based (grid spacing = 1) by default; pass a pyvttrac.Grid to work in physical units instead.

Performance

The Fortran core is called once per track() invocation (not once per tracking step), and OpenMP-parallelizes across seed points. On a benchmark (400×400×12 field, 7396 seeds, 5 steps), sequential tracking is faster than the Julia backend it replaces, and scales close to linearly with the workers parameter:

workers=1   0.145 s   (Julia v2.0.0 backend: 0.244 s)
workers=8   0.021 s
workers=-1  0.014 s   (all cores)

Reproduce with python tools/bench.py.

Installation

pip install pyVTTrac

Requires Python 3.10+ on Linux or macOS (Windows is not supported). Optional extras:

pip install "pyVTTrac[xarray]"   # for TrackResult.to_xarray()
pip install "pyVTTrac[pandas]"   # for TrackResult.to_dataframe()

Building from source needs a Fortran compiler (gfortran or equivalent); OpenMP is used automatically if available, but the package builds and runs fine without it. On macOS: brew install gcc.

Running the tests

git clone https://github.com/tsukada-cs/pyVTTrac.git
cd pyVTTrac
pip install -e ".[test]"
pytest

Related packages

  • VTTrac.jl by Taiga Tsukada — the Julia implementation this package was originally built on top of (up to v1), and whose v2.0.0 algorithm this package's Fortran core is a direct port of. It also serves as this package's reference implementation for golden-data testing (tools/gen_golden.jl).
  • VTTrac by Takeshi Horinouchi — the original implementation VTTrac.jl (and, transitively, pyVTTrac) is based on.

References

  • Horinouchi, T., S. Tsujino, M. Hayashi, U. Shimada, W. Yanase, A. Wada, and H. Yamada, 2023: Stationary and Transient Asymmetric Features in Tropical Cyclone Eye with Wavenumber-1 Instability: Case Study for Typhoon Haishen (2020) with Atmospheric Motion Vectors from 30-Second Imaging. Monthly Weather Review, 151, 253–273, https://doi.org/10.1175/MWR-D-22-0179.1.
  • Tsukada, T., T. Horinouchi, and S. Tsujino, 2024: Wind Distribution in the Eye of Tropical Cyclone Revealed by a Novel Atmospheric Motion Vector Derivation. JGR Atmospheres, 129, e2023JD040585, https://doi.org/10.1029/2023JD040585.

License

BSD 2-Clause License — see LICENSE.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyvttrac-2.1.0.tar.gz (323.5 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

pyvttrac-2.1.0-cp313-cp313-manylinux_2_28_x86_64.whl (1.2 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.28+ x86-64

pyvttrac-2.1.0-cp313-cp313-macosx_14_0_arm64.whl (992.9 kB view details)

Uploaded CPython 3.13macOS 14.0+ ARM64

pyvttrac-2.1.0-cp312-cp312-manylinux_2_28_x86_64.whl (1.2 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.28+ x86-64

pyvttrac-2.1.0-cp312-cp312-macosx_14_0_arm64.whl (993.0 kB view details)

Uploaded CPython 3.12macOS 14.0+ ARM64

pyvttrac-2.1.0-cp311-cp311-manylinux_2_28_x86_64.whl (1.2 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.28+ x86-64

pyvttrac-2.1.0-cp311-cp311-macosx_14_0_arm64.whl (992.3 kB view details)

Uploaded CPython 3.11macOS 14.0+ ARM64

pyvttrac-2.1.0-cp310-cp310-manylinux_2_28_x86_64.whl (1.2 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.28+ x86-64

pyvttrac-2.1.0-cp310-cp310-macosx_14_0_arm64.whl (991.8 kB view details)

Uploaded CPython 3.10macOS 14.0+ ARM64

File details

Details for the file pyvttrac-2.1.0.tar.gz.

File metadata

  • Download URL: pyvttrac-2.1.0.tar.gz
  • Upload date:
  • Size: 323.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pyvttrac-2.1.0.tar.gz
Algorithm Hash digest
SHA256 f8da36e49e7ced5759118fca2cbc182adea3bbb246d0775c90e602bec21f8fc6
MD5 c78d6e499c512b612e3be3c1fef7b5b7
BLAKE2b-256 0cf661e6a2247344f7856e96f4d9cafb4f0101adb8763f8392528e62033e7b3c

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyvttrac-2.1.0.tar.gz:

Publisher: wheels.yml on tsukada-cs/pyVTTrac

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyvttrac-2.1.0-cp313-cp313-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyvttrac-2.1.0-cp313-cp313-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 9e120add54c88fa953998d776f0f9c345f8c00e2a5f184edf85ee6538a7f9c9f
MD5 5a4f971f880b33276aca017bc4bfc0da
BLAKE2b-256 73686a42a924dc212629e2d0673df0e0e00287474cc21d441c6fbcc7fae696ba

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyvttrac-2.1.0-cp313-cp313-manylinux_2_28_x86_64.whl:

Publisher: wheels.yml on tsukada-cs/pyVTTrac

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyvttrac-2.1.0-cp313-cp313-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for pyvttrac-2.1.0-cp313-cp313-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 72b9542544db17c8cdd1c8c25d8f8cc40a2af0978f6d3e0dab30f3aac59750f4
MD5 da5b080b427786261b47653f138664b1
BLAKE2b-256 d107b35c7b624127f25b713ae8c552b433cd2673f17cb6830fd43756bd87aec9

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyvttrac-2.1.0-cp313-cp313-macosx_14_0_arm64.whl:

Publisher: wheels.yml on tsukada-cs/pyVTTrac

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyvttrac-2.1.0-cp312-cp312-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyvttrac-2.1.0-cp312-cp312-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 6da7eb1ebd28f8bacb682a91b3567526d7184673c62c8ba0ae60a90f5938b031
MD5 bc110a59ae5e338f162b328015341ffa
BLAKE2b-256 936f16a2b49bea0d110b0a0968d4dc4e264672f0fe5e8cb69ec665a4e4b85671

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyvttrac-2.1.0-cp312-cp312-manylinux_2_28_x86_64.whl:

Publisher: wheels.yml on tsukada-cs/pyVTTrac

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyvttrac-2.1.0-cp312-cp312-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for pyvttrac-2.1.0-cp312-cp312-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 8e7bd9971076674bca51fe94fb82e57bd40ad10220fed44f20614b8d549df6c2
MD5 4d095f4015c102176fc2c735e08ccbef
BLAKE2b-256 4e7ba006a2c3b7f8a7e6e387551eda9d61ded058b84318374678e748af710a8b

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyvttrac-2.1.0-cp312-cp312-macosx_14_0_arm64.whl:

Publisher: wheels.yml on tsukada-cs/pyVTTrac

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyvttrac-2.1.0-cp311-cp311-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyvttrac-2.1.0-cp311-cp311-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 ebd381abbf88a36ca711c592a30245a4106f8927047f921188e7bff35c55cca7
MD5 4719e7f3c217dfee2534d9eed5e35fc5
BLAKE2b-256 216867ea0c830cae806bdb0fdde85de2d7cb313bd6077b9c44ff7527752d35ce

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyvttrac-2.1.0-cp311-cp311-manylinux_2_28_x86_64.whl:

Publisher: wheels.yml on tsukada-cs/pyVTTrac

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyvttrac-2.1.0-cp311-cp311-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for pyvttrac-2.1.0-cp311-cp311-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 a26441e4f09bdd0f60483e0b0a4f4354a3eed25bffe2c3731a0ddc58a0a0ae17
MD5 2646467e3ef3a405d84dcd2a2da6477b
BLAKE2b-256 16301e016c2904533ca4144db31ee559d2fd375abc1568e4e71d0ddfcc09304a

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyvttrac-2.1.0-cp311-cp311-macosx_14_0_arm64.whl:

Publisher: wheels.yml on tsukada-cs/pyVTTrac

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyvttrac-2.1.0-cp310-cp310-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyvttrac-2.1.0-cp310-cp310-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 0c3b0660364847f8c680ad790fdd36945de033fc21bb3318d0c2e2e338d8d06e
MD5 236e8f6e051e02c340f8e5ee6ed39aa4
BLAKE2b-256 afb3c82ad54c4d4ab3524ef7ba18c7f34f4c042cbc67fc51f8c6795d64c32a46

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyvttrac-2.1.0-cp310-cp310-manylinux_2_28_x86_64.whl:

Publisher: wheels.yml on tsukada-cs/pyVTTrac

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyvttrac-2.1.0-cp310-cp310-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for pyvttrac-2.1.0-cp310-cp310-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 ba1a0cb7fc022c6148835faac0e39745855f5880cb4df692f65e2fb9dfa6cb11
MD5 a44dd01b0617936a14aea958f989fdc7
BLAKE2b-256 c3adb2d235c56cba147763ca77f6ffa49a9a14adb221d9db83c716a4f5f829c2

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyvttrac-2.1.0-cp310-cp310-macosx_14_0_arm64.whl:

Publisher: wheels.yml on tsukada-cs/pyVTTrac

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

2.2.0

9 files

This release

2.1.0 This release

9 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page