gg.overlay: Plot output from 'kin' functions
In ckenaley/trackter: Automated Kinematic Analysis of Image Data

Description Usage Arguments Details Value See Also Examples

Plots data output from one of trackter's kin functions using ggplot2. Useful for quickly visualizing results from kin functions. Data and geometries include body-contour polygons with midline points, head or fin points, both midline and head points, or none or all of these. Optionally builds and saves an animation of data with reference to frame from kin data.

gg.overlay(
  kin = NULL,
  frames = NULL,
  under = "cont",
  over = "midline",
  zoom = FALSE,
  animate = FALSE,
  shadow = TRUE,
  alpha = 0.1,
  fps = 10,
  save = FALSE,
  filename = NULL,
  out.dir = NULL,
  ...
)

`kin`	a list of data returned from `kin` functions. See Details.
`frames`	integer, a vector for frames within the data (a column common to all `kin` functions' output). Will subset the data or, if NULL, will not. If more than one frame is specified, plot will be faceted by frame with `facet_wrap` or animated across frames.
`under`	character, the data to plot under `over`, the contour(s) from `kin` functions, i.e, 'cont' or 'cont.sm'. See Details.
`over`	character, the data to plot over the contour(s). Must be either 'kin.dat', 'midline', 'both', 'fin', 'fin.pt', 'all', or 'none'. See Details.
`zoom`	logical, should the plotted area zoom to the extents of the contours. See Detail.
`animate`	logical, should an animation be plotted to the graphics device with state changes reflected by `frame`.
`shadow`	logical,should `shadow_mark` be implemented to draw geometries in previous frames. Ignored if `animate=FALSE`.
`alpha`	numeric, the opacity of geometries in previous frames during animation. Ignored if `animate=FALSE`.
`fps`	integer, the play back speed of animation in frames per second. Ignored if `animate=FALSE`.
`save`	logical, should the animation be saved as a GIF. Ignored if `animate=FALSE`. See Details.
`filename`	character, the name given to the GIF file. Ignored if `animate=FALSE` or `save=FALSE`.
`out.dir`	character, the file path of the directory to which the GIF file is saved. Ignored if `animate=FALSE` or `save=FALSE`.
`...`	other arguments to be passed to midline and head point geometries, e.g. 'size', 'color'.

Simply plots 2D dimensional data over contours retrieved from kin functions. May be useful in quickly assesses their results. The under layer can be one of the named contour data tables in lists returned by the kin functions kin.search,kin.simple, kin.free, or fin.kin. The overlayed data layer specified by over are non-contour data from the kin functions.

If the list specified by 'kin' is from kin.search,kin.simple, or kin.free, 'over' must be 'cont' or 'cont.sm' and under one of 'midline','kin', 'none' or 'both'. 'midline' will produce the smoothed midline coordinates.

If the list specified by 'kin' is from fin.kin, 'over' must be 'cont' or 'comp' and under one of 'midline','fin', 'fin.pts', 'none' or 'all'.

Animations are produced with gganimate and optionally saved as a GIF with anim_save using the default gifski_renderer().

A ggplot printed to the graphics device, a gganimate object plotted to graphics device, or a GIF file saved to a local directory specified in out.dir.

geom_point, geom_polygon,gganimate, kin.free, kin.search, kin.simple,fin.kin

## Not run: 
#animate a ropefish swimming with its midline

#download example avi and place in subdirectory
f <- "https://github.com/ckenaley/exampledata/blob/master/ropefish.avi?raw=true"

download.file(f, paste0(tempdir(),"/ropefish.avi"))

dir.create(paste0(tempdir(),"/images"))

vid.to.images(paste0(tempdir(),"/ropefish.avi"), out.dir = paste0(tempdir(),"/images"))

kin <- kin.free(image.dir =paste0(tempdir(),"/images"),
par=TRUE,
      ml.smooth=list("spline",0.9),
      thr = "otsu",
      size.min=0.01,
      red=0.5
      )

gg.overlay(kin=kin,
frames=seq(20,320,20),
under="cont.sm",
over="midline",
size=1,
animate=TRUE,
col="red",
fps=10)

#clean up 
unlink(paste0(tempdir(),"/images"),recursive=TRUE)

## End(Not run)