VTT(z; t=nothing, mask=nothing, zmiss=nothing, fmiss=-999.0, imiss=-999)

Sets data for tracking (you need to set parameters separately with setup).

Arguments

• z::AbstractArray{Float32,3}: Array of image-like data (in dimensions [time, y, x]), with at least 2 time steps. z[i] contains i-th image data.
• t::Union{AbstractVector{Float64}, Nothing}=nothing: Times at which the images are for. Defaults to 0:size(z,1)-1.
• mask::Union{Array{Bool,3}, Nothing}=nothing: Mask to ignore when calculating score (true positions are ignored).
• zmiss::Union{Real, Nothing}=nothing: Missing value used in z.
• fmiss::Real=-999.0: Missing value to be set for Real.
• imiss::Integer=-999: Missing value to be set for Integer.

setup(o, nsx, nsy, vxhw, vyhw, [ixhw, iyhw, subgrid, subgrid_gaus,
    itstep, ntrac, score_method, Sth0, Sth1, vxch, vych,
    peak_inside, peak_inside_th, Cth, use_init_temp, min_samples])

Setup for tracking.

Arguments

• o::VTT: The object.
• nsx::Integer, nsy::Integer: Subimage x & y sizes (x:1st, y:2nd dim).
• vxhw::Union{Real, Nothing}, vyhw::Union{Real, Nothing}: (either v[xy]hw or i[xy]hw are MANDATORY). the dimensions along which to perform the computation. search velocity range half sizes to set i[xy]hw. Seach at least to cover +-v?hw around the first guess or previous step. (the result can be outside the range.)
• ixhw::Union{Integer, Nothing}, iyhw::Union{Integer, Nothing}: (either v[xy]hw or i[xy]hw are MANDATORY) Max displacement fro template match (can be set indirecly through v[xy]hw).
• subgrid::Bool=true: Whether to conduct subgrid tracking.
• subgrid_gaus::Bool=true: Whether subgrid peak finding is by gaussian.
• itstep::Integer=1: Step of t's used (skip if >1).
• ntrac::Integer=2: Max tracking times from initial loc.
• score_method::String="xcor": "xcor" for cross-correlation, "ncov" for normalized covariance.
• Sth0::Real=0.8: The minimum score required for the 1st tracking.
• Sth1::Real=0.7: The minimum score required for subsequent tracking.
• vxch::Union{Real, Nothing}=nothing: If non-nothing, the max tolerant vx change between two consecutive tracking. Screening by velocity change is only active when both vxch and vych are set (both non-nothing and positive).
• vych::Union{Real, Nothing}=nothing: If non-nothing, the max tolerant vy change between two consecutive tracking. See vxch.
• peak_inside_th::Union{Real, Nothing}=nothing: If non-nothing, an initial template is used only when it is peaked (max or min) inside, exceeding the max or min along the sides by the ratio specified by its value.
• Cth::Union{Real, Nothing}=nothing: If non-nothing, an initial template is used only when it has a difference in max and min greater than its value.
• min_samples::Integer=1: Minimum number of visible values to calculate score when chk_mask is true.

set_ixyhw_from_v(o, vxhw, vyhw)

Sets the tracking parameters i[xy]hw from velocities (v[xy]hw).

Arguments

• o::VTT: The object.
• vxhw::Real: The range over which vx is searched around initial guess.
• vyhw::Real: The range over which vy is searched around initial guess.

set_ixyhw_directly(o, ixhw, iyhw)

Sets the tracking parameters i[xy]hw.

Arguments

• o::VTT: The object.
• ixhw::Integer: The range over which next x is searched around initial guess.
• iyhw::Integer: The range over which next y is searched around initial guess.

trac(o, tid, x, y[, vxg, vyg, out_subimage, out_score_ary])

Conduct tracking.

Arguments

• o::VTT: The tracking object.
• tid::Array{Integer,Any}: Tracking initial time indices.
• x::Array{Float64,Any}: Tracking initial template-center x location (index-based; non-integer for subgrid).
• y::Array{Float64,Any}: Tracking initial template-center y location (index-based; non-integer for subgrid).
• vxg::Array{Float64,Any}=nothing: First guess of vx (to search around it). Can be 0.
• vyg::Array{Float64,Any}=nothing: First guess of vy (to search around it). Can be 0.
• out_subimage::Bool=false: Whether output subimages.
• out_score_ary::Bool=false: Whether output score arrays.
• to_missing::Bool=true: Whether output missing values as missing.

Returns

• count::Vector{Integer}: [len] The number of valid trajectory points for each initial template, including the initial one (so it ranges 0:ntrac+1; e.g. ntrac+1 means every step succeeded).
• status::Vector{Integer}: [len] The reason tracking stopped for each initial template (0 if it completed ntrac steps without stopping early). One of:
  • 0: completed successfully (or not yet stopped)
  • 1/5: the start/end tid for a step was out of range
  • 2: the template subimage could not be read (out of bounds, or missing/masked data)
  • 3: the template subimage failed the Cth contrast check
  • 4: the template subimage failed the chk_peak_inside check
  • 6: the sliding score could not be computed (out of bounds, or missing/masked data)
  • 7: no valid score peak, or the peak was on the edge of the search window
  • 8: the peak score was below Sth0 (1st step) or Sth1 (subsequent steps)
  • 9: the velocity change along the trajectory exceeded vxch/vych
• tid::Matrix{Float64}: [ntrac+1, len] time index of the trajectories (tid0 and subsequent ones).
• x::Matrix{Float64}: [ntrac+1, len] x locations of the trajectories (x0 and derived ones).
• y::Matrix{Float64}: [ntrac+1, len] y locations of trajectories (x0 and derived ones).
• vx::Matrix{Float64}: [ntrac, len] Derived x-velocity.
• vy::Matrix{Float64}: [ntrac, len] Derived y-velocity.
• score::Matrix{Float64}: [ntrac, len] Scores along the trajectory (max values, possibly at subgrid).
• zss::Array{Float32,4}: [ntrac+1, nsy, nsx, len] optional, if non-nothing (Diagnosis output if wanted) The subimages along the track.
• score_ary::Array{Float64,4}: [ntrac, 2iyhw+1, 2ixhw+1, len] optional, if non-nothing (Diagnosis output if wanted) The entire scores.