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. vt.concat_bidirectional() stitches a forward and a backward run from the same starting point into one trajectory.
  • 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.2.0.tar.gz (333.3 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.2.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.2.0-cp313-cp313-macosx_14_0_arm64.whl (997.0 kB view details)

Uploaded CPython 3.13macOS 14.0+ ARM64

pyvttrac-2.2.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.2.0-cp312-cp312-macosx_14_0_arm64.whl (997.0 kB view details)

Uploaded CPython 3.12macOS 14.0+ ARM64

pyvttrac-2.2.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.2.0-cp311-cp311-macosx_14_0_arm64.whl (996.4 kB view details)

Uploaded CPython 3.11macOS 14.0+ ARM64

pyvttrac-2.2.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.2.0-cp310-cp310-macosx_14_0_arm64.whl (995.9 kB view details)

Uploaded CPython 3.10macOS 14.0+ ARM64

File details

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

File metadata

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

File hashes

Hashes for pyvttrac-2.2.0.tar.gz
Algorithm Hash digest
SHA256 969a036b4f8939f152c3c9c8d62c35a258c27c8c61e0fa484068a9cb3e4fd243
MD5 7f023a7273f769dfe5203a9e03989fed
BLAKE2b-256 8c6e42e4289659792a95a3db4979ef55d1936a116253a89499554ae1bd1f13a2

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyvttrac-2.2.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.2.0-cp313-cp313-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyvttrac-2.2.0-cp313-cp313-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 9a70608ef670d8ed245263a96425744bd7da00172363c1be7c55575ec4ededeb
MD5 e316d056782752f3523ddcfe2a9f50d2
BLAKE2b-256 edc30d7c2657f8bde1895dd18b60d74df00358236fbba2473205bd5fdc348780

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyvttrac-2.2.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.2.0-cp313-cp313-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for pyvttrac-2.2.0-cp313-cp313-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 f95386a7af1a6142c04496d6f27e2860a81a98358c3216b9c1f6d7d83b200be8
MD5 1b410f022b25a86f5a176bc28f6289de
BLAKE2b-256 c476c908ba9ab02e0a81fd76c4f96beddfafe271dd846d3022f87bfc4b31a58b

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyvttrac-2.2.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.2.0-cp312-cp312-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyvttrac-2.2.0-cp312-cp312-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 fd998d898b226802782d1121ed78bfa2f7144b635e166e32f147b29ae9772c77
MD5 5b852fe8d47eac7aaed6551baf13bb19
BLAKE2b-256 821e97859d442fcae824e418e774c2b54c204b76951df21757b4a5369c753b7f

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyvttrac-2.2.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.2.0-cp312-cp312-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for pyvttrac-2.2.0-cp312-cp312-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 814497f3199226e0e1b847afe8b8770163ce9032dd228c64e32b6a1b6949aa1c
MD5 57e02437e7964ac2fdc0c1e2a279fa8e
BLAKE2b-256 3a75ff807bf2e1853a2691c322d1f0c2ba9744753d0d6391bd095ea1c31c395d

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyvttrac-2.2.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.2.0-cp311-cp311-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyvttrac-2.2.0-cp311-cp311-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 bf45b8cfb2ff8c792c4f18f8a4dee69faf5b635a6b7b2004196ee3cdf93e85cf
MD5 af7a83e22c877ba6ef5ecb209f58b96f
BLAKE2b-256 f21091713c0c9c5e034a2c957918ef1c3bae3ed4c3a2bb3e4282e0e80f3a2cab

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyvttrac-2.2.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.2.0-cp311-cp311-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for pyvttrac-2.2.0-cp311-cp311-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 a4e303488e4e07724cdb9298d93481f0a17e9146fd4f8154a2ca2c66a4607fcc
MD5 1008b65df90a7e880f796b1cedda5990
BLAKE2b-256 92de3313c34a952c684f3722a34a44667cd45a8ad89a2829b2d36df9f014e0fc

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyvttrac-2.2.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.2.0-cp310-cp310-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyvttrac-2.2.0-cp310-cp310-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 80f67b14a47d0c2141bd799f96fd8cbeebd4df5a646edc1c8058bd6e5bb7e924
MD5 7f985251dda92ecddc225af08270a2f1
BLAKE2b-256 59bfa2ba528c299135730229e96b6db90e3657c3b1b6a00aa33cd9558f4add29

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyvttrac-2.2.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.2.0-cp310-cp310-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for pyvttrac-2.2.0-cp310-cp310-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 d682a6989f5ecb8fc46b0d0e5b5b58ee65675b802855103286323c4cf0fbb159
MD5 5825e8ae0e531031b9568e3fc5fcc579
BLAKE2b-256 01ec5875751868682dc3a3535354cc3ce3aca4e311c2d513eacb4e1736d861e6

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyvttrac-2.2.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

This release

2.2.0 This release

9 files

2.1.0

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