Given the path of a folder containing multiple Trex outputs (one .npz file per particle/individual), this function returns an object of class "tracklets", a list of tracklets (data frame) containing 7 elements classically used for further computations using MoveR package:
'maj.ax': the length of the major axis (i.e., the midline) for a particle over frame (i.e., length of the ellipse).
'angle': the particle's absolute angle in radians, orientation of the particle according to X-axis.
'min.ax': the length of the minor axis for a particle over frame (i.e., width of the ellipse), returns NA since it is not present in the TREX output.
'x.pos': x position of the particle's centroid.
'y.pos': y position of the particle's centroid.
'identity': the particle's identity given by the tracking software.
'frame': the video frame number at which the measurements has been made.
The function can also append all the others elements returned by the tracking software (see rawDat argument) Also, the function can flip y coordinates (see flipY argument).
Arguments
- trexPath
The path of the TRex output folder where .npz files are stored.
- flipY
A logical value (i.e., TRUE or FALSE) indicating whether the origin of y coordinates should be flipped. If TRUE, y coordinates are flipped to start on the bottom-left (default = FALSE).
- imgHeight
A numeric value expressed in pixels, the length of Y axis corresponding to the height of the image or video resolution (optional, only used when flipY = TRUE).
- rawDat
A logical value (i.e., TRUE or FALSE) indicating whether all other elements retrieved from the tracking output should appended to the tracklets data (see trex.run), Note that this may drastically increase the size of the object returned by the function (default = FALSE).
Value
An object of class "tracklets" containing a list of tracklets and their characteristics classically used for further computations. In case rawDat argument is TRUE, it also append all the others elements returned by the tracking software (for TRex it corresponds to several metrics see trex.run for more details). Also, by default the function returns y coordinates starting on the top-left.
References
Tristan Walter, Iain D Couzin (2021) TRex, a fast multi-animal tracking system with markerless identification, and 2D estimation of posture and visual fields eLife 10:e64000. trex.run
Examples
if (FALSE) {
# Download the first dataset from the sample data repository
Path2Data <- MoveR::DLsampleData(dataSet = 1, tracker = "TRex")
Path2Data
# Import the data as an object of class "tracklets"
# and flip Y coordinates to start on the bottom-left
Data <- MoveR::readTrex(Path2Data[[1]],
flipY = T,
imgHeight = 2160,
rawDat = F
)
str(Data)
}