trackter (version 0.1.1)

fin.kin: Tracking of fin-like extensions of body contours

Description

Estimates the amplitudes of regions along a body contour that are protruding. Useful in computing paired-fin amplitudes from contour data produced from kin.simple and kin.search. Also computes a smoothed midline based on the body outline with the fin region removed.

Usage

fin.kin(
  x,
  fin.pos = NULL,
  smooth.n = 50,
  tip.ang = 10,
  smoothing = "loess",
  x.bins = 0.2,
  ml.smooth = 0.25
)

Arguments

x

a data frame or matrix with 'x' and 'y' data as columns.

fin.pos

numeric, a vector of length 2 indicating the start and end of the contour region that contains the fins of interest as a proportion of the body length.

smooth.n

numeric, the number of smoothing operations undertaken by coo_smooth on the contour described by 'x'.

tip.ang

the minimum angle, in degrees, that defines tip of each fin. See Details.

smoothing

character, the midline smoothing method, either 'loess' or 'spline'.

x.bins

numeric, when less than or equal to 1, the proportion of contour coordinates to sample for midline estimation. If greater than 1, the absolute number of equally spaced x values from which to compute the midline. See Details.

ml.smooth

numeric the smoothing value for the midline. If smoothing is set to 'loess', passed to 'span' value for loess. If smoothing is set to 'spline', passed to 'spar' value for smooth.spline

Value

A list with the following components:

body a data table consisting of x,y coordinates of the body contour

fin a data table describing the contour of the fins consisting of the following:

• x,y coordinates within the range of fin.pos

• 'ang': the angle formed by each coordinate and its adjacent points.

• 'fin': fin side, 'L' or 'R'

• 'y.pred': predicted y values according to lm() from start to end of fins.

fin.pts a data table describing fin position consisting of the following:

• x,y coordinates of the fin tips, start, and end within the range of fin.pos.

• 'ang': the angle formed by the coordinates and their adjacent points.

• 'pos': description of the coordinates' positions, 'start', 'end' or 'tip'.

comp a data table describing the composite contour of the body minus the fins.

• x,y coordinates of the body except the range of x values within fin.pos. These values take on a straight line described by the prediction of lm() based on the start and end of the fin. See Details.

midline a data table describing the estimated

• 'x': the mean x position within the bin.

• 'x.bin': the x bin in cut notation.

• 'y.m': the y midpoint at the bind and mean x value.

• 'ml.pred': the y midline value according to the smoothing parameters.

Details

The algorithm assumes a left-right orientation, i.e., the head of the contour is left. If otherwise oriented, contour can be flipped with coo_flipx and coo_flipy after converting contour to class coo.

tip.angle is used to define the tip of the fin, assuming that the tip of the fin is pointed and, for a sufficiently smoothed fin contour, will have contour edges that form the highest angles within the fin region defined by fin.pos. Low values of smooth.n ($<$5) should be avoided if the contour is jagged, perhaps due to digitization.

In addition to fin amplitude and contour extraction, also produces a composite contour of the body minus the fin area described by fin.pos. Fin contours are replaced by a simple linear prediction constructed from the coordinates of the first and last values covered by fin.pos. The result is a straight line between the start and end of each fin. From this composite body contour, a midline prediction is made based on the method indicated by smoothing and number of points indicated by x.bins.

x.bins controls the bin size of x values used to estimate the midline. From these bins, mean x and the range of y is calculated. The midpoint at each mean x is then calculated from the mid point of y. When less then 1, x.bins values approaching 1 may result in poor a midline as x values on one side of the contour may not have corresponding identical values on the other. Values closer to 0 will result in fewer points but a more robust midline. Higher smooth.n values will also result in a more robust midline estimation (but also a loss of contour information).

See Also

kin.simple, kin.LDA, kin.search, efourier, coo_angle_edges, coo_smooth, loess, smooth.spline

Examples

# NOT RUN {
###plot pectoral-fin amplitudes of a swimming sunfish
# }
# NOT RUN {
require(ggplot2)

#download example avi video
f <- "https://github.com/ckenaley/exampledata/blob/master/sunfish_pect.avi?raw=true"
download.file(f,"sunfish.avi")

#extract images with ffmpeg opereations and reduce them to 600 px wide with a filter
filt.red <- " -vf scale=600:-1 " #filter
vid.to.images2(vid.path="sunfish.avi",filt = filt.red) #extract

#number of frames
fr <- length(list.files("images"))
#extract contours and other data
kin <- kin.simple(image.dir = "images",frames=c(1:fr),thr=0.9,ant.per = 0.25)
#fin amplitudes by frame with data.table
fin.pos <- c(0.25,.5)
fin.dat <- kin$cont[, { f <- fin.kin(data.frame(x=x,y=y),fin.pos =fin.pos);
list(amp=f$amp$amp,fin=f$amp$fin,amp.bl=f$amp$amp.bl)},by=list(frame)]
p <- ggplot(dat=fin.dat,aes(x=frame,y=amp,col=fin))+geom_line()+theme_classic(15)
print(p)


## plot body and fin contours of frame 1
cont <- data.frame(x=kin$cont[frame==2,list(x,y)]$x,y=kin$cont[frame==2,list(y)]$y)
fins <- fin.kin(cont,fin.pos =fin.pos,x.bins=100)

#plot body contour and fins 
p <- qplot(data=fins$body,x=x,y=y)+geom_point(data=fins$fin,aes(x,y),col="red",size=3)
p+geom_point(data=fins$fin.pts,aes(x,y,shape=pos))+xlim(c(0,kin$dim[1]))+ylim(c(0,kin$dim[2]))

#plot body contour minus fins and the body midline
p <- qplot(data=fins$comp,x=x,y=y)+geom_point(data=fins$midline,aes(x,ml.pred),col="red",size=2)
p+xlim(c(0,kin$dim[1]))+ylim(c(0,kin$dim[2]))

# }
# NOT RUN {


# }