fin.kin: Tracking of fin-like extensions of body contours
In trackter: Automated Kinematic Analysis of Image Data

Description Usage Arguments Details Value See Also Examples

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.

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

`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`

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).

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.

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

###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]))


## End(Not run)