pyVTTrac
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/tracAPI were replaced in v2.0.0. Seedocs/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), wherexis the template andyis 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
nstepssteps ofstepframes each (stepcan 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 optionalmax_velocity_changetrajectory-consistency check, an optionalmin_contrasttemplate check, and an optionalmin_peak_prominenceinterior-peak check. - Missing data:
mask(boolean,True= ignore) and/ormissing_value(a sentinel inz);NaNinzis always treated as missing as well. - Coordinates: positions/velocities are index-based (grid spacing = 1) by
default; pass a
pyvttrac.Gridto 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.jlby 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).VTTracby Takeshi Horinouchi — the original implementationVTTrac.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
Built Distributions
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
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
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f8da36e49e7ced5759118fca2cbc182adea3bbb246d0775c90e602bec21f8fc6
|
|
| MD5 |
c78d6e499c512b612e3be3c1fef7b5b7
|
|
| BLAKE2b-256 |
0cf661e6a2247344f7856e96f4d9cafb4f0101adb8763f8392528e62033e7b3c
|
Provenance
The following attestation bundles were made for pyvttrac-2.1.0.tar.gz:
Publisher:
wheels.yml on tsukada-cs/pyVTTrac
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
pyvttrac-2.1.0.tar.gz -
Subject digest:
f8da36e49e7ced5759118fca2cbc182adea3bbb246d0775c90e602bec21f8fc6 - Sigstore transparency entry: 2381806323
- Sigstore integration time:
-
Permalink:
tsukada-cs/pyVTTrac@188dca3a8e800a62000a8cfdb2cbfd73b59d6914 -
Branch / Tag:
refs/tags/v2.1.0 - Owner: https://github.com/tsukada-cs
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
wheels.yml@188dca3a8e800a62000a8cfdb2cbfd73b59d6914 -
Trigger Event:
push
-
Statement type:
File details
Details for the file pyvttrac-2.1.0-cp313-cp313-manylinux_2_28_x86_64.whl.
File metadata
- Download URL: pyvttrac-2.1.0-cp313-cp313-manylinux_2_28_x86_64.whl
- Upload date:
- Size: 1.2 MB
- Tags: CPython 3.13, manylinux: glibc 2.28+ x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
9e120add54c88fa953998d776f0f9c345f8c00e2a5f184edf85ee6538a7f9c9f
|
|
| MD5 |
5a4f971f880b33276aca017bc4bfc0da
|
|
| BLAKE2b-256 |
73686a42a924dc212629e2d0673df0e0e00287474cc21d441c6fbcc7fae696ba
|
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
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
pyvttrac-2.1.0-cp313-cp313-manylinux_2_28_x86_64.whl -
Subject digest:
9e120add54c88fa953998d776f0f9c345f8c00e2a5f184edf85ee6538a7f9c9f - Sigstore transparency entry: 2381806629
- Sigstore integration time:
-
Permalink:
tsukada-cs/pyVTTrac@188dca3a8e800a62000a8cfdb2cbfd73b59d6914 -
Branch / Tag:
refs/tags/v2.1.0 - Owner: https://github.com/tsukada-cs
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
wheels.yml@188dca3a8e800a62000a8cfdb2cbfd73b59d6914 -
Trigger Event:
push
-
Statement type:
File details
Details for the file pyvttrac-2.1.0-cp313-cp313-macosx_14_0_arm64.whl.
File metadata
- Download URL: pyvttrac-2.1.0-cp313-cp313-macosx_14_0_arm64.whl
- Upload date:
- Size: 992.9 kB
- Tags: CPython 3.13, macOS 14.0+ ARM64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
72b9542544db17c8cdd1c8c25d8f8cc40a2af0978f6d3e0dab30f3aac59750f4
|
|
| MD5 |
da5b080b427786261b47653f138664b1
|
|
| BLAKE2b-256 |
d107b35c7b624127f25b713ae8c552b433cd2673f17cb6830fd43756bd87aec9
|
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
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
pyvttrac-2.1.0-cp313-cp313-macosx_14_0_arm64.whl -
Subject digest:
72b9542544db17c8cdd1c8c25d8f8cc40a2af0978f6d3e0dab30f3aac59750f4 - Sigstore transparency entry: 2381806748
- Sigstore integration time:
-
Permalink:
tsukada-cs/pyVTTrac@188dca3a8e800a62000a8cfdb2cbfd73b59d6914 -
Branch / Tag:
refs/tags/v2.1.0 - Owner: https://github.com/tsukada-cs
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
wheels.yml@188dca3a8e800a62000a8cfdb2cbfd73b59d6914 -
Trigger Event:
push
-
Statement type:
File details
Details for the file pyvttrac-2.1.0-cp312-cp312-manylinux_2_28_x86_64.whl.
File metadata
- Download URL: pyvttrac-2.1.0-cp312-cp312-manylinux_2_28_x86_64.whl
- Upload date:
- Size: 1.2 MB
- Tags: CPython 3.12, manylinux: glibc 2.28+ x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6da7eb1ebd28f8bacb682a91b3567526d7184673c62c8ba0ae60a90f5938b031
|
|
| MD5 |
bc110a59ae5e338f162b328015341ffa
|
|
| BLAKE2b-256 |
936f16a2b49bea0d110b0a0968d4dc4e264672f0fe5e8cb69ec665a4e4b85671
|
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
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
pyvttrac-2.1.0-cp312-cp312-manylinux_2_28_x86_64.whl -
Subject digest:
6da7eb1ebd28f8bacb682a91b3567526d7184673c62c8ba0ae60a90f5938b031 - Sigstore transparency entry: 2381806462
- Sigstore integration time:
-
Permalink:
tsukada-cs/pyVTTrac@188dca3a8e800a62000a8cfdb2cbfd73b59d6914 -
Branch / Tag:
refs/tags/v2.1.0 - Owner: https://github.com/tsukada-cs
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
wheels.yml@188dca3a8e800a62000a8cfdb2cbfd73b59d6914 -
Trigger Event:
push
-
Statement type:
File details
Details for the file pyvttrac-2.1.0-cp312-cp312-macosx_14_0_arm64.whl.
File metadata
- Download URL: pyvttrac-2.1.0-cp312-cp312-macosx_14_0_arm64.whl
- Upload date:
- Size: 993.0 kB
- Tags: CPython 3.12, macOS 14.0+ ARM64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8e7bd9971076674bca51fe94fb82e57bd40ad10220fed44f20614b8d549df6c2
|
|
| MD5 |
4d095f4015c102176fc2c735e08ccbef
|
|
| BLAKE2b-256 |
4e7ba006a2c3b7f8a7e6e387551eda9d61ded058b84318374678e748af710a8b
|
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
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
pyvttrac-2.1.0-cp312-cp312-macosx_14_0_arm64.whl -
Subject digest:
8e7bd9971076674bca51fe94fb82e57bd40ad10220fed44f20614b8d549df6c2 - Sigstore transparency entry: 2381806369
- Sigstore integration time:
-
Permalink:
tsukada-cs/pyVTTrac@188dca3a8e800a62000a8cfdb2cbfd73b59d6914 -
Branch / Tag:
refs/tags/v2.1.0 - Owner: https://github.com/tsukada-cs
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
wheels.yml@188dca3a8e800a62000a8cfdb2cbfd73b59d6914 -
Trigger Event:
push
-
Statement type:
File details
Details for the file pyvttrac-2.1.0-cp311-cp311-manylinux_2_28_x86_64.whl.
File metadata
- Download URL: pyvttrac-2.1.0-cp311-cp311-manylinux_2_28_x86_64.whl
- Upload date:
- Size: 1.2 MB
- Tags: CPython 3.11, manylinux: glibc 2.28+ x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ebd381abbf88a36ca711c592a30245a4106f8927047f921188e7bff35c55cca7
|
|
| MD5 |
4719e7f3c217dfee2534d9eed5e35fc5
|
|
| BLAKE2b-256 |
216867ea0c830cae806bdb0fdde85de2d7cb313bd6077b9c44ff7527752d35ce
|
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
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
pyvttrac-2.1.0-cp311-cp311-manylinux_2_28_x86_64.whl -
Subject digest:
ebd381abbf88a36ca711c592a30245a4106f8927047f921188e7bff35c55cca7 - Sigstore transparency entry: 2381806831
- Sigstore integration time:
-
Permalink:
tsukada-cs/pyVTTrac@188dca3a8e800a62000a8cfdb2cbfd73b59d6914 -
Branch / Tag:
refs/tags/v2.1.0 - Owner: https://github.com/tsukada-cs
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
wheels.yml@188dca3a8e800a62000a8cfdb2cbfd73b59d6914 -
Trigger Event:
push
-
Statement type:
File details
Details for the file pyvttrac-2.1.0-cp311-cp311-macosx_14_0_arm64.whl.
File metadata
- Download URL: pyvttrac-2.1.0-cp311-cp311-macosx_14_0_arm64.whl
- Upload date:
- Size: 992.3 kB
- Tags: CPython 3.11, macOS 14.0+ ARM64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a26441e4f09bdd0f60483e0b0a4f4354a3eed25bffe2c3731a0ddc58a0a0ae17
|
|
| MD5 |
2646467e3ef3a405d84dcd2a2da6477b
|
|
| BLAKE2b-256 |
16301e016c2904533ca4144db31ee559d2fd375abc1568e4e71d0ddfcc09304a
|
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
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
pyvttrac-2.1.0-cp311-cp311-macosx_14_0_arm64.whl -
Subject digest:
a26441e4f09bdd0f60483e0b0a4f4354a3eed25bffe2c3731a0ddc58a0a0ae17 - Sigstore transparency entry: 2381806791
- Sigstore integration time:
-
Permalink:
tsukada-cs/pyVTTrac@188dca3a8e800a62000a8cfdb2cbfd73b59d6914 -
Branch / Tag:
refs/tags/v2.1.0 - Owner: https://github.com/tsukada-cs
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
wheels.yml@188dca3a8e800a62000a8cfdb2cbfd73b59d6914 -
Trigger Event:
push
-
Statement type:
File details
Details for the file pyvttrac-2.1.0-cp310-cp310-manylinux_2_28_x86_64.whl.
File metadata
- Download URL: pyvttrac-2.1.0-cp310-cp310-manylinux_2_28_x86_64.whl
- Upload date:
- Size: 1.2 MB
- Tags: CPython 3.10, manylinux: glibc 2.28+ x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
0c3b0660364847f8c680ad790fdd36945de033fc21bb3318d0c2e2e338d8d06e
|
|
| MD5 |
236e8f6e051e02c340f8e5ee6ed39aa4
|
|
| BLAKE2b-256 |
afb3c82ad54c4d4ab3524ef7ba18c7f34f4c042cbc67fc51f8c6795d64c32a46
|
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
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
pyvttrac-2.1.0-cp310-cp310-manylinux_2_28_x86_64.whl -
Subject digest:
0c3b0660364847f8c680ad790fdd36945de033fc21bb3318d0c2e2e338d8d06e - Sigstore transparency entry: 2381806552
- Sigstore integration time:
-
Permalink:
tsukada-cs/pyVTTrac@188dca3a8e800a62000a8cfdb2cbfd73b59d6914 -
Branch / Tag:
refs/tags/v2.1.0 - Owner: https://github.com/tsukada-cs
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
wheels.yml@188dca3a8e800a62000a8cfdb2cbfd73b59d6914 -
Trigger Event:
push
-
Statement type:
File details
Details for the file pyvttrac-2.1.0-cp310-cp310-macosx_14_0_arm64.whl.
File metadata
- Download URL: pyvttrac-2.1.0-cp310-cp310-macosx_14_0_arm64.whl
- Upload date:
- Size: 991.8 kB
- Tags: CPython 3.10, macOS 14.0+ ARM64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ba1a0cb7fc022c6148835faac0e39745855f5880cb4df692f65e2fb9dfa6cb11
|
|
| MD5 |
a44dd01b0617936a14aea958f989fdc7
|
|
| BLAKE2b-256 |
c3adb2d235c56cba147763ca77f6ffa49a9a14adb221d9db83c716a4f5f829c2
|
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
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
pyvttrac-2.1.0-cp310-cp310-macosx_14_0_arm64.whl -
Subject digest:
ba1a0cb7fc022c6148835faac0e39745855f5880cb4df692f65e2fb9dfa6cb11 - Sigstore transparency entry: 2381806684
- Sigstore integration time:
-
Permalink:
tsukada-cs/pyVTTrac@188dca3a8e800a62000a8cfdb2cbfd73b59d6914 -
Branch / Tag:
refs/tags/v2.1.0 - Owner: https://github.com/tsukada-cs
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
wheels.yml@188dca3a8e800a62000a8cfdb2cbfd73b59d6914 -
Trigger Event:
push
-
Statement type: